ipfs-unixfs-importer

ipfs-unixfs-importer

JavaScript implementation of the UnixFs importer used by IPFS

Table of contents

• Install
  • Browser <script> tag
• Example
• API
  • const stream = importer(source, blockstore [, options])
  • const result = await importFile(content, blockstore [, options])
  • const result = await importDirectory(content, blockstore [, options])
  • const result = await importBytes(buf, blockstore [, options])
  • const result = await importByteStream(source, blockstore [, options])
• API Docs
• License
• Contribute

Install

$ npm i ipfs-unixfs-importer

Browser <script> tag

Loading this module through a script tag will make it's exports available as IpfsUnixfsImporter in the global namespace.

<script src="https://unpkg.com/ipfs-unixfs-importer/dist/index.min.js"></script>

Example

Let's create a little directory to import:

> cd /tmp
> mkdir foo
> echo 'hello' > foo/bar
> echo 'world' > foo/quux

And write the importing logic:

import { importer } from 'ipfs-unixfs-importer'
import { MemoryBlockstore } from 'blockstore-core/memory'
import * as fs from 'node:fs'

// Where the blocks will be stored
const blockstore = new MemoryBlockstore()

// Import path /tmp/foo/
const source = [{
  path: '/tmp/foo/bar',
  content: fs.createReadStream('/tmp/foo/bar')
}, {
  path: '/tmp/foo/quxx',
  content: fs.createReadStream('/tmp/foo/quux')
}]

for await (const entry of importer(source, blockstore)) {
  console.info(entry)
}

When run, metadata about DAGNodes in the created tree is printed until the root:

{
  cid: CID, // see https://github.com/multiformats/js-cid
  path: 'tmp/foo/bar',
  unixfs: UnixFS // see https://github.com/ipfs/js-ipfs-unixfs
}
{
  cid: CID, // see https://github.com/multiformats/js-cid
  path: 'tmp/foo/quxx',
  unixfs: UnixFS // see https://github.com/ipfs/js-ipfs-unixfs
}
{
  cid: CID, // see https://github.com/multiformats/js-cid
  path: 'tmp/foo',
  unixfs: UnixFS // see https://github.com/ipfs/js-ipfs-unixfs
}
{
  cid: CID, // see https://github.com/multiformats/js-cid
  path: 'tmp',
  unixfs: UnixFS // see https://github.com/ipfs/js-ipfs-unixfs
}

API

import { importer, importFile, importDir, importBytes, importByteStream } from 'ipfs-unixfs-importer'

const stream = importer(source, blockstore [, options])

The importer function returns an async iterator takes a source async iterator that yields objects of the form:

{
  path: 'a name',
  content: (Buffer or iterator emitting Buffers),
  mtime: (Number representing seconds since (positive) or before (negative) the Unix Epoch),
  mode: (Number representing ugo-rwx, setuid, setguid and sticky bit)
}

stream will output file info objects as files get stored in IPFS. When stats on a node are emitted they are guaranteed to have been written.

blockstore is an instance of a blockstore

The input's file paths and directory structure will be preserved in the dag-pb created nodes.

const result = await importFile(content, blockstore [, options])

A convenience function for importing a single file or directory.

const result = await importDirectory(content, blockstore [, options])

A convenience function for importing a directory - note this is non-recursive, to import recursively use the importer function.

const result = await importBytes(buf, blockstore [, options])

A convenience function for importing a single Uint8Array.

const result = await importByteStream(source, blockstore [, options])

A convenience function for importing a single stream of Uint8Arrays.

API Docs

• https://ipfs.github.io/js-ipfs-unixfs/modules/ipfs_unixfs_importer.html

License

Licensed under either of

• Apache 2.0, (LICENSE-APACHE / http://www.apache.org/licenses/LICENSE-2.0)
• MIT (LICENSE-MIT / http://opensource.org/licenses/MIT)

Contribute

Contributions welcome! Please check out the issues.

Also see our contributing document for more information on how we work, and about contributing in general.

Please be aware that all interactions related to this repo are subject to the IPFS Code of Conduct.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.