Package Exports

ipfs-unixfs-exporter

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (ipfs-unixfs-exporter) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

ipfs-unixfs-exporter

Exports UnixFS and other DAGs from IPFS

Lead Maintainer

Alex Potsides

ipfs-unixfs-exporter

Install

> npm install ipfs-unixfs-exporter

Usage

Example

// import a file and export it again
const importer = require('ipfs-unixfs-importer')
const exporter = require('ipfs-unixfs-exporter')

const files = []

for await (const file of importer([{
  path: '/foo/bar.txt',
  content: Buffer.from(0, 1, 2, 3)
}], ipld)) {
  files.push(file)
}

console.info(files[0].cid) // Qmbaz

const entry = await exporter(files[0].cid, ipld)

console.info(entry.cid) // Qmqux
console.info(entry.path) // Qmbaz/foo/bar.txt
console.info(entry.name) // bar.txt
console.info(entry.unixfs.fileSize()) // 4

// stream content from unixfs node
const bytes = []

for await (const buf of entry.content({
  offset: 0, // optional offset
  length: 4 // optional length
})) {
  bytes.push(buf)
}

const content = Buffer.concat(bytes)

console.info(content) // 0, 1, 2, 3

API

const exporter = require('ipfs-unixfs-exporter')

`exporter(cid, ipld, options)`

Uses the given ipld instance to fetch an IPFS node by it's CID.

Returns a Promise which resolves to an entry.

options is an optional object argument that might include the following keys:

signal (AbortSignal): Used to cancel any network requests that are initiated as a result of this export

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
  content: function, // returns an async iterator
  unixfs: UnixFS // see https://github.com/ipfs/js-ipfs-unixfs
}

If the entry is a file, entry.content() returns an async iterator that yields one or more buffers containing the file content:

if (entry.unixfs.type === 'file') {
  for await (const chunk of entry.content()) {
    // chunk is a Buffer
  }
}

If the entry is a directory or hamt shard, entry.content() returns further entry objects:

if (entry.unixfs.type.includes('directory')) { // can be 'directory' or 'hamt-sharded-directory'
  for await (const entry of dir.content()) {
    console.info(entry.name)
  }
}

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
  content: function, // returns an async iterator
}

entry.content() returns an async iterator that yields a buffer containing the node content:

for await (const chunk of entry.content()) {
  // 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 entry.content({
  offset: 0,
  length: 5
})) {
  bufs.push(chunk)
}

// `data` contains the first 5 bytes of the file
const data = Buffer.concat(bufs)

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 dir.content({
  offset: 0,
  length: 5
})) {
  entries.push(entry)
}

// `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.path('Qmfoo/foo/bar/baz.txt', ipld)) {
  entries.push(entry)
}

// 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.recursive('Qmfoo/foo/bar', ipld)) {
  entries.push(entry)
}

// 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.

License

MIT