npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@xanthous/file-box

v0.8.27

Published

Pack a File into Box for easy move/transfer between servers no matter of where it is.(local path, remote url, or cloud storage)

Downloads

8

Readme

FILEBOX

NPM Version Build Status TypeScript Greenkeeper badge

FileBox is a virtual container for packing a file data into it for future read, and easily transport between servers with the least payload, no mater than where it is (local path, remote url, or cloud storage).

File Box

Currently the FileBox supports almost all kinds of the data input/output methods/formats:

| File Type | Pack Method | Unpack Method | Description | | :--- | :--- | :--- | :--- | | Local File | fromFile() | toFile() | Local file in file system | | Remote URL | fromUrl() | toUrl()(TBW) | Remote file in a HTTP/HTTPS URL | | Buffer | fromBuffer() | toBuffer() | JavaScript Buffer | | Stream | fromStream() | toStream() | JavaScript Stream | | Base64 | fromBase64() | toBase64() | Base64 data | | DataURL | fromDataURL() | toDataURL() | DataURL data | | JSON | fromJSON()(TBW) | toJSON()(TBW) | Serialize/Deserialize FileBox |

EXAMPLES

The following example demos:

  1. Save URL to File
  2. Convert Buffer to Stream
  3. Pack from Base64 then Unpack to DataURL
import { FileBox } from 'file-box'

/**
 * 1. Save URL to File
 */
const fileBox1 = FileBox.fromUrl(
  'https://huan.github.io/file-box/images/file-box-logo.jpg',
  'logo.jpg',
)
fileBox1.toFile('/tmp/file-box-logo.jpg')

/**
 * 2. Convert Buffer to Stream
 */
import * as fs from 'fs'
const fileBox2 = FileBox.fromBuffer(
  Buffer.from('world'),
  'hello.txt',
)
const writeStream = fs.createWriteStream('/tmp/hello.txt')
fileBox2.pipe(writeStream)

/**
 * 3. Pack Base64, Unpack to DataURL
 */
const fileBox3 = FileBox.fromBase64('d29ybGQK', 'hello.txt')
fileBox3.toDataURL()
        .then(console.log)
// Output: data:text/plain;base64,d29ybGQK

API REFERENCE

1. Load File in to Box

1.1 fromFile(filePath: string): FileBox

Alias: fromLocal()

const fileBox = FileBox.fromLocal('/tmp/test.txt')

1.2 fromUrl(url: string, name?: string, headers?: http.OutgoingHttpHeaders): FileBox

Alais: fromRemote()

const fileBox = FileBox.fromUrl(
  'https://huan.github.io/file-box/images/file-box-logo.jpg',
  'logo.jpg',
)

1.3 fromStream(stream: NoddeJS.ReadableStream, name: string): FileBox

const fileBox = FileBox.fromStream(res, '/tmp/download.zip')

1.4 fromBuffer(buffer: Buffer, name: string): FileBox

const fileBox = FileBox.fromBuffer(buf, '/tmp/download.zip')

1.5 FileBox.fromBase64(base64: string, name: string): FileBox

Decoded a base64 encoded file data.

const fileBox = FileBox.fromBase64('d29ybGQK', 'hello.txt')
fileBox.toFile()

1.6 FileBox.fromDataURL(dataUrl: string, name: string): FileBox

Decoded a DataURL data.

const fileBox = FileBox.fromDataURL('data:text/plain;base64,d29ybGQK', 'hello.txt')
fileBox.toFile()

1.7 FileBox.fromJSON()

Restore a FileBox.toJSON() text string back to a FileBox instance.

WIP: Not Implement Yet

const restoredFileBox = FileBox.fromJSON(jsonText)

2. Get File out from Box

2.1 toFile(name?: string): Promise<void>

Save file to current work path(cwd) of the local file system with the default name.

if name specified with a full path, then will use the speficied file name instead.

const fileBox = FileBox.fromRemote(
  'https://huan.github.io/file-box/images/file-box-logo.jpg',
)
await fileBox.toFile('/tmp/logo.jpg')

2.2 pipe(destination: Writable): Promise<void>

Pipe to a writable stream.

const fileBox = FileBox.fromRemote(
  'https://huan.github.io/file-box/images/file-box-logo.jpg',
)
const writableStream = fs.createWritable('/tmp/logo.jpg')
fileBox.pipe(writableStream)

2.3 toBase64(): Promise<string>

Get the base64 data of file.

const fileBox = FileBox.fromRemote(
  'https://huan.github.io/file-box/images/file-box-logo.jpg',
)
const base64Text = await fileBox.toBase64()
console.log(base64Text) // Output: the base64 encoded data of the file

2.4 toJSON(): string

Get the JSON.stringify-ed text.

Not Implement Yet: Working In Progress...

const fileBox = FileBox.fromRemote(
  'https://huan.github.io/file-box/images/file-box-logo.jpg',
)
const jsonText1 = fileBox.toJSON()
const jsonText2 = JSON.stringify(fileBox)
assert(jsonText1 === jsonText2)

console.log(jsonText1) // Output: the stringified data of the fileBox

const restoredFileBox = fileBox.fromJSON(jsonText1)
restoredFileBox.toFile('/tmp/file-box-logo.jpg')

2.5 toDataURL(): Promise<string>

Get the DataURL of the file.

const fileBox = FileBox.fromFile('tests/fixtures/hello.txt')
const dataUrl = await fileBox.toDataURL()
console.log(dataUrl) // Output: data:text/plain;base64,d29ybGQK'

2.6 toBuffer(): Promise<Buffer>

Get the Buffer of the file.

const fileBox = FileBox.fromFile('tests/fixtures/hello.txt')
const buffer = await fileBox.toBuffer()
console.log(buffer.toString()) // Output: world

3. Misc

3.1 name

File name of the file in the box

const fileBox = FileBox.fromRemote(
  'https://huan.github.io/file-box/images/file-box-logo.jpg',
)
console.log(fileBox.name) // Output: file-box-logo.jpg

3.2 metadata: Metadata { [key: string]: any }

Metadata for the file in the box. This value can only be assigned once, and will be immutable afterwards, all following assign or modify actions on metadata will throw errors

const fileBox = FileBox.fromRemote(
  'https://zixia.github.io/file-box/images/file-box-logo.jpg',
)
fileBox.metadata = {
  author      : 'zixia',
  githubRepo  : 'https://github.com/zixia/file-box',
}

console.log(fileBox.metadata)       // Output: { author: 'zixia', githubRepo: 'https://github.com/zixia/file-box' }
fileBox.metadata.author = 'Thanos'  // Will throw exception 

3.3 version(): string

Version of the FileBox

3.4 toJSON(): string

Serialize FileBox metadata to JSON.

To be implemented.

3.5 ready(): Promise<void>

Update the necessary internal data and make everything ready for use.

3.6 syncRemoteName(): Promise<void>

Sync the filename with the HTTP Response Header

HTTP Header Example:

Content-Disposition: attachment; filename="filename.ext"

FEATURES

  1. Present A File by Abstracting It's Meta Information that supports Reading & toJSON() API.
  2. Follow DOM File/BLOB Interface
  3. Present a file that could be: Local, Remote, Stream
  4. Lazy load
  5. Serializable
  6. Can be Transfered from server to server, server to browser.

SCHEMAS

Url

Node.js Documentation > URL Strings and URL Objects

┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│                                            href                                             │
├──────────┬──┬─────────────────────┬─────────────────────┬───────────────────────────┬───────┤
│ protocol │  │        auth         │        host         │           path            │ hash  │
│          │  │                     ├──────────────┬──────┼──────────┬────────────────┤       │
│          │  │                     │   hostname   │ port │ pathname │     search     │       │
│          │  │                     │              │      │          ├─┬──────────────┤       │
│          │  │                     │              │      │          │ │    query     │       │
"  https:   //    user   :   pass   @ sub.host.com : 8080   /p/a/t/h  ?  query=string   #hash "
│          │  │          │          │   hostname   │ port │          │                │       │
│          │  │          │          ├──────────────┴──────┤          │                │       │
│ protocol │  │ username │ password │        host         │          │                │       │
├──────────┴──┼──────────┴──────────┼─────────────────────┤          │                │       │
│   origin    │                     │       origin        │ pathname │     search     │ hash  │
├─────────────┴─────────────────────┴─────────────────────┴──────────┴────────────────┴───────┤
│                                            href                                             │
└─────────────────────────────────────────────────────────────────────────────────────────────┘

Path

Node.js Documentation > path.parse(path)

┌─────────────────────┬────────────┐
│          dir        │    base    │
├──────┬              ├──────┬─────┤
│ root │              │ name │ ext │
"  /    home/user/dir / file  .txt "
└──────┴──────────────┴──────┴─────┘

CHANGE LOG

v0.8 (master) (Jun 2018)

  1. Add two new factory methods: fromBase64(), fromDataURL()
  2. Add toBuffer(), toBase64() and toDataURL() to get the Buffer and BASE64 encoded file data
  3. Add metadata property to store additional informations. (#3)

v0.4 (May 2018)

  1. Add headers option for fromRemote() method

v0.2 (Apr 2018)

Initial version.

SEE ALSO

THANKS

This module is inspired by https://github.com/gulpjs/vinyl and https://github.com/DefinitelyTyped/DefinitelyTyped/pull/12368 when I need a virtual File module for my Chatie project.

AUTHOR

Huan LI <[email protected]>

COPYRIGHT & LICENSE

  • Docs released under Creative Commons
  • Code released under the Apache-2.0 License
  • Code & Docs © 2018 Huan LI <[email protected]>