feat: update DAGLink and DAGNode to have an immutable API

README.md

@@ -14,7 +14,7 @@
 
 [![Sauce Test Status](https://saucelabs.com/browser-matrix/ipld-js-dag-pb.svg)](https://saucelabs.com/u/ipld-js-dag-pb)
 
-> JavaScript Implementation of the IPLD Format MerkleDAG Node in Protobuf.
+> 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).
 
 ## Table of Contents
 
@@ -28,89 +28,193 @@
 ## Install
 
 ```bash
-> npm i ipld-dag-pb
+> npm install ipld-dag-pb --save
 ```
 
 ## Usage
 
-```js
+```JavaScript
 const dagPB = require('ipld-dag-pb')
 
-// then, to access each of the components
-dagPB.DAGNode
+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.rmLinkq // 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
+
+```JavaScript
+// TODO
+```
+
+#### Add and remove a Link
+
+```JavaScript
+// TODO
 ```
 
 ## API
 
-### DAGNode Class
+### 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:
+
+```JavaScript
+const dagPB = require('ipld-dag-pb')
+const DAGNode = dagPB.DAGNode
+```
+
+#### DAGNode.create(data, links, hashAlg, callback)
+
+Create a DAGNode.
+
+```JavaScript
+DAGNode.create("data", links, (err, dagNode) => {
+})
+```
+
+links can be a single or an array of DAGLinks instances or objects with the following pattern
+
+```JavaScript
+{
+  name: '<some name>',
+  hash: '<some multihash>', // can also be `multihash: <some multihash>`
+  size: <sizeInBytes>
+}
+```
+
+#### addLink(node, link, callback)
+
+Creates a link on node A to node B by using node B to get its multihash. Returns a *new* instance of DAGNode without modifying the old one.
 
-Create a new DAGNode
+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:
 
 ```JavaScript
-var node = new dagPB.DAGNode([<data>, <[links]>])
+{
+  name: '<some string>', // optional
+  size: <size in bytes>,
+  multihash: <multihash> // can be a String multihash or multihash buffer
+}
 ```
 
-#### `addNodeLink`
 
-> creates a link on node A to node B by using node B to get its multihash
+#### rmLink(node, nameOrMultihash, callback)
 
-#### `addRawLink`
+Removes a link from the node by name. Returns a *new* instance of DAGNode without modifying the old one.
 
-> creates a link on node A to node B by using directly node B multihash
+```JavaScript
+DAGNode.rmLink(node, "Link1" (err, dagNode) => ...) 
+```
 
-#### `updateNodeLink`
+#### clone(node, callback)
 
-> updates a link on the node. *caution* this method returns a copy of the MerkleDAG node
+Creates a clone of the DAGNode instance passed
 
-#### `removeNodeLink`
+```JavaScript
+DAGNode.clone(node, (err, nodeClone) => {})
+```
 
-> removes a link from the node by name
+### DAGNode instance methods and properties
 
-#### `removeNodeLinkByHash`
+You have the following methods and properties available in every DAGNode instance.
 
-> removes a link from the node by the hash of the linked node
+#### `node.data`
 
+#### `node.links`
 
-#### `clone`
+An array of `DAGLinks`
 
-> creates a clone of the MerkleDAG Node
+#### `node.size`
 
-#### `size`
+Size of the node, in bytes
 
-> (property) size of the node, in bytes
+#### `node.multihash`
 
-#### `links`
+#### `node.serialized`
 
-> (property) an array of `DAGLink`s belonging to the node
+#### `node.toJSON()`
 
-#### `multihash(callback)`
+#### `node.toString()`
 
-> returns the multihash (default: sha2-256)
 
-#### `getPBNode`
+### DAGLink functions
 
-> used internally
+Following the same pattern as [`DAGNode functions`]() above, DAGLink also offers a function for its creation. 
 
-#### `makeLink`
+You can incude it in your project with:
 
-> used internally
+```JavaScript
+const dagPB = require('ipld-dag-pb')
+const DAGLink = dagPB.DAGLink
+```
 
-### DAGLink Class
+#### DAGLink.create(name, size, multihash, callback)
+
+```JavaScript
+DAGLink.create('link-to-file',  // name of the link (can be empty)
+               10,              // size in bytes
+               'QmSomeHash...', // can be multihash buffer or string
+               (err, link) => {
+                 if (err) {
+                   throw err
+                 }
+                 // link is a DAGLink instance
+})
+```
 
-Create a new DAGLink
+Note: DAGLinks are simpler objects and can be instantiated directly:
 
 ```JavaScript
-var link = new dagPB.DAGLink(<name>, <size>, <hash>)
+const link = new DAGLink(name, size, multihash)
 ```
 
-### Local Resolver (to be used by the IPLD Resolver)
+### DAGLink instance methods and properties
+
+#### `link.name`
+
+#### `link.size`
+
+#### `link.multihash`
+
+#### `link.toJSON()`
+
+#### `link.toString()`
+
+### [IPLD Format Specifics](https://github.com/ipld/interface-ipld-format) - 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](https://github.com/ipld/interface-ipld-format) - util
+
+> See: https://github.com/ipld/interface-ipld-format#ipld-format-utils
 
-#### `resolver.resolve`
+### `dagPB.util.cid`
 
-#### `resolver.tree`
+### `dagPB.util.serialize`
 
-#### `resolver.patch`
+### `dagPB.util.deserialize`
 
 ## License
 

package.json

@@ -34,33 +34,35 @@
     "url": "https://github.com/ipld/js-ipld-dag-pb.git"
   },
   "engines": {
-    "node": ">=4.0.0"
+    "node": ">=4.0.0",
+    "npm": ">=3.0.0"
   },
   "dependencies": {
     "async": "^2.1.2",
+    "buffer-loader": "0.0.1",
     "cids": "^0.2.0",
     "ipfs-block": "^0.5.0",
     "is-ipfs": "^0.2.1",
     "multihashes": "^0.2.2",
     "multihashing-async": "^0.2.0",
-    "protocol-buffers": "^3.1.6",
+    "protocol-buffers": "^3.1.8",
     "pull-stream": "^3.5.0",
     "pull-traverse": "^1.0.3",
     "stable": "^0.1.5"
   },
   "devDependencies": {
-    "aegir": "^9.1.0",
+    "aegir": "^9.1.2",
     "bs58": "^3.0.0",
     "buffer-loader": "0.0.1",
     "chai": "^3.5.0",
     "chai-checkmark": "^1.0.1",
     "fs-pull-blob-store": "^0.4.1",
     "idb-pull-blob-store": "^0.5.1",
-    "ipfs-block-service": "^0.6.0",
-    "ipfs-repo": "^0.11.0",
-    "lodash": "^4.16.6",
+    "ipfs-block-service": "^0.7.0",
+    "ipfs-repo": "^0.11.1",
+    "lodash": "^4.17.0",
     "ncp": "^2.0.0",
     "pre-commit": "^1.1.3",
     "rimraf": "^2.5.4"
   }
-}
+}

src/dag-link/create.js

@@ -0,0 +1,10 @@
+'use strict'
+
+const DAGLink = require('./index.js')
+
+function create (name, size, multihash, callback) {
+  const link = new DAGLink(name, size, multihash)
+  callback(null, link)
+}
+
+module.exports = create

src/dag-link/index.js

@@ -0,0 +1,61 @@
+'use strict'
+
+const mh = require('multihashes')
+const assert = require('assert')
+
+// Link represents an IPFS Merkle DAG Link between Nodes.
+class DAGLink {
+  constructor (name, size, multihash) {
+    assert(multihash, 'A link requires a multihash to point to')
+    assert(size, 'A link requires a size')
+
+    this._name = name
+    this._size = size
+
+    if (typeof multihash === 'string') {
+      this._multihash = mh.fromB58String(multihash)
+    } else if (Buffer.isBuffer(multihash)) {
+      this._multihash = multihash
+    }
+  }
+
+  toString () {
+    const mhStr = mh.toB58String(this.multihash)
+    return `DAGLink <${mhStr} - name: "${this.name}", size: ${this.size}>`
+  }
+
+  toJSON () {
+    return {
+      name: this.name,
+      size: this.size,
+      hash: this.multihash ? mh.toB58String(this.multihash) : undefined
+    }
+  }
+
+  get name () {
+    return this._name
+  }
+
+  set name (name) {
+    throw new Error("Can't set property: 'name' is immutable")
+  }
+
+  get size () {
+    return this._size
+  }
+
+  set size (size) {
+    throw new Error("Can't set property: 'size' is immutable")
+  }
+
+  get multihash () {
+    return this._multihash
+  }
+
+  set multihash (multihash) {
+    throw new Error("Can't set property: 'multihash' is immutable")
+  }
+}
+
+exports = module.exports = DAGLink
+exports.create = require('./create')