ipld

The JavaScript implementation of the IPLD

The JavaScript implementation of the IPLD, InterPlanetary Linked-Data

Project Status

We've come a long way, but this project is still in Alpha, lots of development is happening, API might change, beware of the Dragons 🐉.

Want to get started? Check our examples folder. You can check the development status at the js-ipld Waffle Board.

Weekly Core Dev Calls

Tech Lead

Volker Mische

Lead Maintainer

Volker Mische

Table of Contents

• Install
• Usage
• API
  • IPLD Resolver
    • Constructor
    • .put(node, options, callback)
    • .get(cid [, path] [, options], callback)
    • .getStream(cid [, path] [, options])
    • .treeStream(cid [, path] [, options])
    • .remove(cid, callback)
    • .support.add(multicodec, formatResolver, formatUtil)
    • .support.rm(multicodec)
    • Properties
      • defaultOptions
• Packages
• Contribute
• License

Install

> npm install --save ipld

Usage

const Ipld = require('ipld')
const IpfsRepo = require('ipfs-repo')
const IpfsBlockService = require('ipfs-block-service')

const initIpld = (ipfsRepoPath, callback) => {
  const repo = new IpfsRepo(ipfsRepoPath)
  repo.init({}, (err) => {
    if (err) {
      return callback(err)
    }
    repo.open((err) => {
      if (err) {
        return callback(err)
      }
      const blockService = new IpfsBlockService(repo)
      const ipld = new Ipld({blockService: blockService})
      return callback(null, ipld)
    })
  })
}

initIpld('/tmp/ifpsrepo', (err, ipld) => {
  // Do something with the `ipld`, e.g. `ipld.get(…)`
})

API

IPLD constructor

Creates and returns an instance of IPLD.

const ipld = new Ipld(options)

The options is an object with any of these properties:

options.blockService

Type	Default
ipfs.BlockService instance	Required (no default)

Example:

const blockService = new IpfsBlockService(repo)
const ipld = new Ipld({blockService: blockService})

options.formats

Type	Default
Array of IPLD Format implementations	[require('ipld-dag-cbor'), require('ipld-dag-pb'), require('ipld-raw')]

By default only the dag-cbor), dag-pb) and raw) IPLD Formats are supported. Other formats need to be added manually. Here is an example if you want to have support for ipld-git only:

const ipldGit = require('ipld-git')

const ipld = new Ipld({
  formats: [ipldGit],
  …
})

options.loadFormat(codec, callback)

Type	Default
Function	null

Function to dynamically load an IPLD Format. It is passed a string codec, the multicodec of the IPLD format to load and a callback function to call when the format has been loaded. e.g.

const ipld = new Ipld({
  loadFormat (codec, callback) {
    if (codec === 'git-raw') {
      callback(null, require('ipld-git'))
    } else {
      callback(new Error('unable to load format ' + codec))
    }
  }
})

.put(node, options, callback)

Store the given node of a recognized IPLD Format.

options is an object that must contain one of the following combinations:

• cid - the CID of the node
• [hashAlg], [version] and format - the hashAlg, version and the format that should be used to create the CID of the node. The hashAlg and version defaults to the default values for the format.

It may contain any of the following:

• onlyHash - If true the serialized form of the node will not be passed to the underlying block store but the passed callback will be invoked as if it had been

callback is a function that should have the signature as following: function (err, cid) {}, where err is an Error object in case of error and cid is the cid of the stored object.

.get(cid [, path] [, options], callback)

Retrieve a node by the given cid or cid + path

options is an optional object containing:

• localResolve: bool - if true, get will only attempt to resolve the path locally

callback should be a function with the signature function (err, result), the result being an object with:

• value - the value that resulted from the get
• remainderPath - If it didn't manage to successfully resolve the whole path through or if simply the localResolve option was passed.
• cid - Where the graph traversal finished - if remainderPath has a value, this will be where it has its root

.getMany(cids, callback)

Retrieve several nodes at once

callback should be a function with the signature function (err, result), the result is an array with the nodes corresponding to the CIDs.

.getStream(cid [, path] [, options])

Same as get, but returns a source pull-stream that is used to pass the fetched node.

.treeStream(cid [, path] [, options])

Returns all the paths under a cid + path through a pull-stream. Accepts the following options:

• recursive - bool - traverse through links to complete the graph.

.remove(cid, callback)

Remove a node by the given cid

.support.add(multicodec, formatResolver, formatUtil)

Add support to another IPLD Format

.support.rm(multicodec)

Removes support of an IPLD Format

Properties

defaultOptions

Default options for IPLD.

Packages

Listing of dependencies from the IPLD ecosystem.

This table is generated using the module package-table with package-table --data=package-list.json.

Package	Version	Deps	CI	Coverage	Lead Maintainer
IPLD Formats
ipld-bitcoin					Volker Mische
ipld-dag-cbor					Volker Mische
ipld-dag-pb					Volker Mische
ipld-ethereum					kumavis
ipld-git					Volker Mische
ipld-raw					Volker Mische
ipld-zcash					Volker Mische
Data Types (non IPLD specific)
multihashes					David Dias
ipfs-block					Volker Mische
Storage
ipfs-repo					Jacob Heun
interface-datastore			N/A		Pedro Teixeira
ipfs-block-service					Volker Mische

Contribute

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

This repository falls under the IPFS Code of Conduct.

License

MIT

Changelog

0.21.1 (2019-01-25)

<a name="0.21.0"></a>