ipfs-unixfs-exporter

Exports UnixFS and other DAGs from IPFS

Lead Maintainer

Alex Potsides

Table of Contents

• ipfs-unixfs-exporter
  • Lead Maintainer
  • Table of Contents
  • Install
  • Usage
    • Example
      • API
    • exporter(cid, ipld, options)
      • UnixFSEntry
      • Raw entries
      • CBOR entries
      • entry.content({ offset, length })
    • walkPath(cid, ipld)
    • recursive(cid, ipld)
  • Contribute
  • License

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: new Uint8Array([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 size = entry.unixfs.fileSize()
const bytes = new Uint8Array(size)
let offset = 0

for await (const buf of entry.content()) {
  bytes.set(buf, offset)
  offset += chunk.length
}

console.info(bytes) // 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 a UnixFSEntry.

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

UnixFSEntry

{
  type: 'file' // or 'directory'
  name: 'foo.txt',
  path: 'Qmbar/foo.txt',
  cid: CID, // see https://github.com/multiformats/js-cid
  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 Uint8Arrays containing the file content:

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

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

if (entry.type === '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: Uint8Array,
  content: function // returns an async iterator that yields a single 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 length = 5
const data = new Uint8Array(length)
let offset = 0

for await (const chunk of entry.content({
  offset: 0,
  length
})) {
  data.set(chunk, offset)
  offset += chunk.length
}

// `data` contains the first 5 bytes of the file
return data

If entry is a directory, 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

walkPath(cid, ipld)

walkPath will return an async iterator that yields entries for all segments in a path:

const { walkPath } = require('ipfs-unixfs-exporter')

const entries = []

for await (const entry of walkPath('Qmfoo/foo/bar/baz.txt', ipld)) {
  entries.push(entry)
}

// entries contains 4x `entry` objects

recursive(cid, ipld)

recursive will return an async iterator that yields all entries beneath a given CID or IPFS path, as well as the containing directory.

const { recursive } = require('ipfs-unixfs-exporter')

const entries = []

for await (const child of 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