Skip to content
The JavaScript Implementation of IPLD
JavaScript
Branch: master
Clone or download
greenkeeper and vmx chore(package): update ipfs-repo to version 0.27.1
Update to latest ipld-in-memory.
Latest commit 8933c25 Aug 21, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
test chore(package): update ipld-dag-pb to version 0.18.1 Aug 20, 2019
.gitattributes
.gitignore feat: raw ipld resolver (#90) Oct 7, 2017
.npmignore
.travis.yml chore: enable Travis for CI Mar 4, 2019
CHANGELOG.md chore: release version v0.25.0 Aug 1, 2019
CONTRIBUTING.md docs: Lead maintainer (#127) May 6, 2018
ISSUE_TEMPLATE.md Fix contributing guide link in issue template May 8, 2019
LICENSE
OKR.md docs: update OKR document Oct 26, 2018
README.md chore: fix typo in README (#231) Aug 14, 2019
clip
package-list.json docs: update package table in readme to swap jenkins for travis Mar 18, 2019
package.json chore(package): update ipfs-repo to version 0.27.1 Aug 21, 2019

README.md

IPLD hex logo

The JavaScript implementation of the IPLD

Travis CI Coverage Status Dependency Status js-standard-style Greenkeeper badge

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.

Throughput Graph

Weekly Core Dev Calls

Tech Lead

Volker Mische

Lead Maintainer

Volker Mische

Table of Contents

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/ipfsrepo', (err, ipld) => {
  // Do something with the `ipld`, e.g. `ipld.get(…)`
})

API

The IPLD API works strictly with CIDs and deserialized IPLD Nodes. Interacting with the binary data happens on lower levels. To access the binary data directly, use the Block API.

All methods that return an async iterator return one that got extended with convenience methods:

  • iter.first(): Return the first item only
  • iter.last(): Return the last item only
  • iter.all(): Return all items as array

Example:

const result = ipld.getMany([cid1, cid2])
const node1 = await result.first()

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)
Type Default
async Function null

Function to dynamically load an IPLD Format. It is passed a codec, the multicodec code of the IPLD format to load and returns an IPLD Format implementation. For example:

const multicodec = require('multicodec')
const ipld = new Ipld({
  async loadFormat (codec) {
    if (codec === multicodec.GIT_RAW) {
      return require('ipld-git')
    } else {
      throw new Error('unable to load format ' + multicodec.print[codec])
    }
  }
})

.put(node, format, options)

Stores the given IPLD Node of a recognized IPLD Format.

  • node (Object): the deserialized IPLD node that should be inserted.
  • format (multicodec, required): the multicodec of the format that IPLD Node should be encoded in.
  • options is an object with the following properties:
    • hashAlg (multicodec, default: hash algorithm of the given multicodec): the hashing algorithm that is used to calculate the CID.
    • cidVersion (number, default: 1): the CID version to use.
    • onlyHash (boolean, default: false): if true the serialized form of the IPLD Node will not be passed to the underlying block store.

Returns a Promise with the CID of the serialized IPLD Node.

.putMany(nodes, format, options)

Stores the given IPLD Nodes of a recognized IPLD Format.

  • nodes (AsyncIterable<Object>): deserialized IPLD nodes that should be inserted.
  • format (multicodec, required): the multicodec of the format that IPLD Node should be encoded in.
  • options is applied to any of the nodes and is an object with the following properties:
    • hashAlg (multicodec, default: hash algorithm of the given multicodec): the hashing algorithm that is used to calculate the CID.
    • cidVersion (number, default: 1): the CID version to use.
    • onlyHash (boolean, default: false): if true the serialized form of the IPLD Node will not be passed to the underlying block store.

Returns an async iterator with the CIDs of the serialized IPLD Nodes. The iterator will throw an exception on the first error that occurs.

.resolve(cid, path)

Retrieves IPLD Nodes along the path that is rooted at cid.

  • cid (CID, required): the CID the resolving starts.
  • path (IPLD Path, required): the path that should be resolved.

Returns an async iterator of all the IPLD Nodes that were traversed during the path resolving. Every element is an object with these fields:

  • remainderPath (string): the part of the path that wasn’t resolved yet.
  • value (*): the value where the resolved path points to. If further traversing is possible, then the value is a CID object linking to another IPLD Node. If it was possible to fully resolve the path, value is the value the path points to. So if you need the CID of the IPLD Node you’re currently at, just take the value of the previously returned IPLD Node.

.get(cid)

Retrieve an IPLD Node.

  • cid (CID): the CID of the IPLD Node that should be retrieved.

Returns a Promise with the IPLD Node that correspond to the given cid.

Throws an error if the IPLD Node can’t be retrieved.

.getMany(cids)

Retrieve several IPLD Nodes at once.

  • cids (AsyncIterable<CID>): the CIDs of the IPLD Nodes that should be retrieved.

Returns an async iterator with the IPLD Nodes that correspond to the given cids.

Throws an error if a IPLD Node can’t be retrieved.

.remove(cid)

Remove an IPLD Node by the given cid

  • cid (CID): the CIDs of the IPLD Node that should be removed.

Throws an error if the IPLD Node can’t be removed.

.removeMany(cids)

Remove IPLD Nodes by the given cids

  • cids (AsyncIterable<CID>): the CIDs of the IPLD Nodes that should be removed.

Throws an error if any of the Blocks can’t be removed. This operation is not atomic, some Blocks might have already been removed.

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

Returns all the paths that can be resolved into.

  • cid (CID, required): the CID to get the paths from.
  • path (IPLD Path, default: ''): the path to start to retrieve the other paths from.
  • options:
    • recursive (bool, default: false): whether to get the paths recursively or not. false resolves only the paths of the given CID.

Returns an async iterator of all the paths (as Strings) you could resolve into.

.addFormat(ipldFormatImplementation)

Add support for an IPLD Format

  • ipldFormatImplementation (IPLD Format, required): the implementation of an IPLD Format.

Returns the IPLD instance. This way you can chain addFormat() calls.

.removeFormat(codec)

Remove support for an IPLD Format

  • codec (multicodec, required): the codec of the IPLD Format to remove.

Returns the IPLD instance. This way you can chain removeFormat() calls.

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 npm Deps Travis CI codecov Volker Mische
ipld-dag-cbor npm Deps Travis CI codecov Volker Mische
ipld-dag-pb npm Deps Travis CI codecov Volker Mische
ipld-ethereum npm Deps Travis CI codecov Volker Mische
ipld-git npm Deps Travis CI codecov Volker Mische
ipld-raw npm Deps Travis CI codecov Volker Mische
ipld-zcash npm Deps Travis CI codecov Volker Mische
Data Types (non IPLD specific)
multihashes npm Deps Travis CI codecov David Dias
ipfs-block npm Deps Travis CI codecov Volker Mische
Storage
ipfs-repo npm Deps Travis CI codecov Jacob Heun
interface-datastore npm Deps Travis CI codecov Pedro Teixeira
ipfs-block-service npm Deps Travis CI codecov Volker Mische

Contribute

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

This repository falls under the IPFS Code of Conduct.

License

MIT

You can’t perform that action at this time.