ipld-dag-pb

js-ipld-dag-pb

JavaScript Implementation of the IPLD Format MerkleDAG Node in Protobuf. In addition to the IPLD Format methods, this module also provides an API for creating the nodes and manipulating them (adding and removing links, etc).

Lead Maintainer

Volker Mische

Table of Contents

• Install
• Usage
  • Examples
    • Create a DAGNode
    • Add and remove a Link
• API
  • DAGNode functions
    • DAGNode.create(data, links, callback)
    • addLink(node, link, callback)
    • rmLink(node, nameOrCid, callback)
    • clone(node, callback)
  • DAGNode instance methods and properties
    • node.data
    • node.links
    • node.size
    • node.toJSON()
    • node.toString()
  • DAGLink functions
    • DAGLink.create(name, size, cid, callback)
  • DAGLink instance methods and properties
    • link.name
    • link.size
    • link.cid
    • link.toJSON()
    • link.toString()
  • [IPLD Format Specifics - Local (node/block scope) resolver](#ipld-format-specificshttpsgithubcomipldinterface-ipld-format---local-nodeblock-scope-resolver)
    • dagPB.resolver.resolve
    • dagPB.resolver.tree
    • dagPB.resolver.patch
  • [IPLD Format Specifics - util](#ipld-format-specificshttpsgithubcomipldinterface-ipld-format---util)
  • dagPB.util.cid
  • dagPB.util.serialize
  • dagPB.util.deserialize
• Contribute
• License

Install

> npm install ipld-dag-pb --save

Usage

const dagPB = require('ipld-dag-pb')

dagPB.DAGNode.create  // create a DAGNode
dagPB.DAGNode.clone   // clone a DAGNode
dagPB.DAGNode.addLink // add a Link to a DAGNode, creating a new one
dagPB.DAGNode.rmLink  // remove a Link to a DAGNode, creating a new one
dagPB.DAGLink.create  // create a DAGLink

// IPLD Format specifics
dagPB.resolver
dagPB.util

Examples

Create a DAGNode

DAGNode.create(new Buffer('some data'), (err, node1) => {
  if (err) {
    throw error
  }
  // node1 is your DAGNode instance.
})

DAGNode.create('some data', (err, node2) => {
  // node2 will have the same data as node1.
})

Add and remove a Link

const link = {
  name: 'I am a link',
  cid: 'QmHash..',
  size: 42
}

DAGNode.addLink(node, link, (err, nodeA) => {
  if (err) {
    throw err
  }
  // node - DAGNode instance with the link
  console.log('with link', nodeA.toJSON())

  DAGNode.rmLink(nodeA, 'I am a link', (err, nodeB) => {
    if (err) {
      throw err
    }

  // node - DAGNode instance without the link, equal to just node
  console.log('without link', nodeB.toJSON())
  })
})

API

DAGNode functions

DAGNodes are immutable objects, in order to manipulate them you have to follow a function approach of applying function and getting new instances of the given DAGNode.

You can incude it in your project with:

const dagPB = require('ipld-dag-pb')
const DAGNode = dagPB.DAGNode

DAGNode.create(data, links, callback)

• data - type: Buffer
• links- type: Array of DAGLink instances or Array of DAGLink instances in its json format (link.toJSON)
• callback - type: function with signature function (err, node) {}

Create a DAGNode.

DAGNode.create('data', links, (err, dagNode) => {
  // ...
})

links can be a single or an array of DAGLinks instances or objects with the following pattern

{
  name: '<some name>',
  cid: '<some cid>',
  size: <sizeInBytes>
}

addLink(node, link, callback)

• node - type: DAGNode
• link - type: DAGLink or DAGLink in its json format
• callback - type: function with signature function (err, node) {}

Creates a link on node A to node B by using node B to get its CID. Returns a new instance of DAGNode without modifying the old one.

Creates a new DAGNode instance with the union of node.links plus the new link.

link can be:

• DAGLink instance
• DAGNode instance
• Object with the following properties:

{
  name: '<some string>', // optional
  size: <size in bytes>,
  cid: <cid> // can be a String CID, CID buffer or CID object
}

rmLink(node, nameOrCid, callback)

• node - type: DAGNode
• nameOrCid - type: String, CID object or CID buffer
• callback - type: function with signature function (err, node) {}

Removes a link from the node by name. Returns a new instance of DAGNode without modifying the old one.

DAGNode.rmLink(node, 'Link1' (err, dagNode) => ...)

clone(node, callback)

• node - type: DAGNode
• callback - type: function with signature function (err, node) {}

Creates a clone of the DAGNode instance passed

DAGNode.clone(node, (err, nodeClone) => {})

DAGNode instance methods and properties

You have the following methods and properties available in every DAGNode instance.

node.data

node.links

An array of DAGLinks

node.size

Size of the node, in bytes

node.toJSON()

node.toString()

DAGLink functions

Following the same pattern as DAGNode functions above, DAGLink also offers a function for its creation.

You can incude it in your project with:

const dagPB = require('ipld-dag-pb')
const DAGLink = dagPB.DAGLink

DAGLink.create(name, size, cid, callback)

DAGLink.create(
  'link-to-file',  // name of the link (can be empty)
  10,              // size in bytes
  'QmSomeHash...', // can be CID object, CID buffer or string
  (err, link) => {
    if (err) {
      throw err
    }
   // link is a DAGLink instance
})

Note: DAGLinks are simpler objects and can be instantiated directly:

const link = new DAGLink(name, size, cid)

DAGLink instance methods and properties

link.name

link.size

link.cid

link.toJSON()

link.toString()

IPLD Format Specifics - Local (node/block scope) resolver

See: https://github.com/ipld/interface-ipld-format#local-resolver-methods

dagPB.resolver.resolve

dagPB.resolver.tree

dagPB.resolver.patch

IPLD Format Specifics - util

See: https://github.com/ipld/interface-ipld-format#ipld-format-utils

dagPB.util.cid

dagPB.util.serialize

dagPB.util.deserialize

Contribute

Please contribute! Look at the issues!

Check out our contributing document for more information on how we work, and about contributing in general. Please be aware that all interactions related to IPLD are subject to the IPFS Code of Conduct.

Small note: If editing the README, please conform to the standard-readme specification.

License

ISC © 2016 Protocol Labs Inc.

Changelog

0.15.3 (2019-03-13)

Bug Fixes

• add a return to callback (eb73e70)
• package: update is-ipfs to version 0.6.0 (0935e53)

<a name="0.15.2"></a>