ipfs-unixfs-exporter

JavaScript implementation of the exporter used by IPFS to handle Files

Lead Maintainer

Alex Potsides

Table of Contents

• Install
• Usage
  • Example
  • API
  • exporter(cid, ipld)
• Contribute
• License

Install

> npm install ipfs-unixfs-exporter

Usage

Example

// Create an export source pull-stream cid or ipfs path you want to export and a
// <dag or ipld-resolver instance> to fetch the file from
const exporter = require('ipfs-unixfs-exporter')
const pull = require('pull-stream/pull')
const { stdout } = require('pull-stdio')

const options = {}

pull(
  exporter(cid, ipld, options),
  collect((error, files) => {
    if (error) {
      // ...handle error
    }

    // Set up a pull stream that sends the file content to process.stdout
    pull(
      // files[0].content is a pull-stream that contains the bytes of the file
      files[0].content,
      stdout()
    )
  })
)

API

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

exporter(cid, ipld, options)

Uses the given dag API or an ipld-resolver instance to fetch an IPFS UnixFS object(s) by their CID.

Creates a new pull stream that outputs objects of the form

{
  path: 'a name',
  content: <pull stream>
}

offset and length

offset and length arguments can optionally be passed to the exporter function. These will cause the returned stream to only emit bytes starting at offset and with length of length.

See the tests for examples of using these arguments.

const exporter = require('ipfs-unixfs-exporter')
const pull = require('pull-stream')
const drain = require('pull-stream/sinks/drain')

pull(
  exporter(cid, ipld, {
    offset: 0,
    length: 10
  })
  drain((file) => {
    // file.content is a pull stream containing only the first 10 bytes of the file
  })
)

fullPath

If specified the exporter will emit an entry for every path component encountered.

const exporter = require('ipfs-unixfs-exporter')
const pull = require('pull-stream')
const collect = require('pull-stream/sinks/collect')

pull(
  exporter('QmFoo.../bar/baz.txt', ipld, {
    fullPath: true
  })
  collect((err, files) => {
    console.info(files)

    // [{
    //   depth: 0,
    //   name: 'QmFoo...',
    //   path: 'QmFoo...',
    //   size: ...
    //   hash: Buffer
    //   content: undefined
    //   type: 'dir'
    // }, {
    //   depth: 1,
    //   name: 'bar',
    //   path: 'QmFoo.../bar',
    //   size: ...
    //   hash: Buffer
    //   content: undefined
    //   type: 'dir'
    // }, {
    //   depth: 2,
    //   name: 'baz.txt',
    //   path: 'QmFoo.../bar/baz.txt',
    //   size: ...
    //   hash: Buffer
    //   content: <Pull stream>
    //   type: 'file'
    // }]
    //
  })
)

maxDepth

If specified the exporter will only emit entries up to the specified depth.

const exporter = require('ipfs-unixfs-exporter')
const pull = require('pull-stream')
const collect = require('pull-stream/sinks/collect')

pull(
  exporter('QmFoo.../bar/baz.txt', ipld, {
    fullPath: true,
    maxDepth: 1
  })
  collect((err, files) => {
    console.info(files)

    // [{
    //   depth: 0,
    //   name: 'QmFoo...',
    //   path: 'QmFoo...',
    //   size: ...
    //   hash: Buffer
    //   content: undefined
    //   type: 'dir'
    // }, {
    //   depth: 1,
    //   name: 'bar',
    //   path: 'QmFoo.../bar',
    //   size: ...
    //   hash: Buffer
    //   content: undefined
    //   type: 'dir'
    // }]
    //
  })
)

Contribute

Feel free to join in. All welcome. Open an issue!

This repository falls under the IPFS Code of Conduct.

License

MIT