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,237 @@
 ## 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
+DAGNode.create(new Buffer('some data'), (err, node) => {
+  if (err) {
+    throw error
+  }
+  // node is your DAGNode instance
+})
+```
+
+#### Add and remove a Link
+
+```JavaScript
+const link = {
+  name: 'I am a link',
+  multihash: '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 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)
+
+- `data` - type: Buffer
+- `links`- type: Array of DAGLink instances or Array of DAGLink instances in its json format (link.toJSON)
+- `hashAlg` - type: String
+- `callback` - type: function with signature `function (err, node) {}`
+
+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)
 
-Create a new DAGNode
+- `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 multihash. 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:
 
 ```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)
+
+- `node` - type: DAGNode
+- `nameOrMultihash` - type: String or multihash 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.
+
+```JavaScript
+DAGNode.rmLink(node, 'Link1' (err, dagNode) => ...) 
+```
 
-#### `addRawLink`
+#### clone(node, callback)
 
-> creates a link on node A to node B by using directly node B multihash
+- `node` - type: DAGNode
+- `callback` - type: function with signature `function (err, node) {}`
 
-#### `updateNodeLink`
+Creates a clone of the DAGNode instance passed
 
-> updates a link on the node. *caution* this method returns a copy of the MerkleDAG node
+```JavaScript
+DAGNode.clone(node, (err, nodeClone) => {})
+```
 
-#### `removeNodeLink`
+### DAGNode instance methods and properties
 
-> removes a link from the node by name
+You have the following methods and properties available in every DAGNode instance.
 
-#### `removeNodeLinkByHash`
+#### `node.data`
 
-> removes a link from the node by the hash of the linked node
+#### `node.links`
 
+An array of `DAGLinks`
 
-#### `clone`
+#### `node.size`
 
-> creates a clone of the MerkleDAG Node
+Size of the node, in bytes
 
-#### `size`
+#### `node.multihash`
 
-> (property) size of the node, in bytes
+#### `node.serialized`
 
-#### `links`
+#### `node.toJSON()`
 
-> (property) an array of `DAGLink`s belonging to the node
+#### `node.toString()`
 
-#### `multihash(callback)`
 
-> returns the multihash (default: sha2-256)
+### DAGLink functions
 
-#### `getPBNode`
+Following the same pattern as [`DAGNode functions`]() above, DAGLink also offers a function for its creation. 
 
-> used internally
+You can incude it in your project with:
 
-#### `makeLink`
+```JavaScript
+const dagPB = require('ipld-dag-pb')
+const DAGLink = dagPB.DAGLink
+```
 
-> used internally
+#### DAGLink.create(name, size, multihash, callback)
 
-### DAGLink Class
+```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