ipfs-unixfs-exporter
JavaScript implementation of the exporter used by IPFS to handle Files
Lead Maintainer
Table of Contents
Install
> npm install ipfs-unixfs-exporter
Usage
Example
// import a file and export it againconst importer = const exporter = const files = for await const file of files console // Qmbaz const entry = await console // Qmquxconsole // Qmbaz/foo/bar.txtconsole // bar.txtconsole // 4 // stream content from unixfs nodeconst bytes = for await const buf of entrycontent offset: 0 // optional offset length: 4 // optional length bytes const content = Buffer console // 0, 1, 2, 3
API
const exporter =
exporter(cid, ipld)
Uses the given [js-ipld instance][] to fetch an IPFS node by it's CID.
Returns a Promise which resolves to an entry
.
UnixFS V1 entries
Entries with a dag-pb
codec CID
return UnixFS V1 entries:
name: 'foo.txt' path: 'Qmbar/foo.txt' cid: CID // see https://github.com/multiformats/js-cid node: DAGNode // see https://github.com/ipld/js-ipld-dag-pb
If the entry is a file, entry.content()
returns an async iterator that yields one or more buffers containing the file content:
if entryunixfstype === 'file' for await const chunk of entrycontent // chunk is a Buffer
If the entry is a directory or hamt shard, entry.content()
returns further entry
objects:
if entryunixfstype // can be 'directory' or 'hamt-sharded-directory' for await const entry of dircontent console
Raw entries
Entries with a raw
codec CID
return raw entries:
name: 'foo.txt' path: 'Qmbar/foo.txt' cid: CID // see https://github.com/multiformats/js-cid node: Buffer // see https://nodejs.org/api/buffer.html
entry.content()
returns an async iterator that yields a buffer containing the node content:
for await const chunk of entrycontent // chunk is a Buffer
Unless you an options object containing offset
and length
keys as an argument to entry.content()
, chunk
will be equal to entry.node
.
CBOR entries
Entries with a dag-cbor
codec CID
return JavaScript object entries:
name: 'foo.txt' path: 'Qmbar/foo.txt' cid: CID // see https://github.com/multiformats/js-cid node: Object // see https://github.com/ipld/js-ipld-dag-cbor
There is no content
function for a CBOR
node.
entry.content({ offset, length })
When entry
is a file or a raw
node, offset
and/or length
arguments can be passed to entry.content()
to return slices of data:
const bufs = for await const chunk of entrycontent offset: 0 length: 5 bufs // `data` contains the first 5 bytes of the fileconst data = Buffer
If entry
is a directory or hamt shard, passing offset
and/or length
to entry.content()
will limit the number of files returned from the directory.
const entries = for await const entry of dircontent offset: 0 length: 5 entries // `entries` contains the first 5 files/directories in the directory
exporter.path(cid, ipld)
exporter.path
will return an async iterator that yields entries for all segments in a path:
const entries = for await const entry of exporter entries // entries contains 4x `entry` objects
exporter.recursive(cid, ipld)
exporter.recursive
will return an async iterator that yields all entries beneath a given CID or IPFS path, as well as the containing directory.
const entries = for await const child of exporter entries // entries contains all children of the `Qmfoo/foo/bar` directory and it's children
Contribute
Feel free to join in. All welcome. Open an issue!
This repository falls under the IPFS Code of Conduct.