More DAG API goodness (#123)

* feat: update dag.put spec

* feat: update dag.get spec

* feat: tests for all permutations of dag.get

* feat: add dag.ls and dag.tree spec

* feat: update tree spec

* docs: add examples to put and get

* fix: examples links

* test: .tree tests everywhere

Author: daviddias

API/dag/README.md

@@ -13,14 +13,28 @@ dag API
 
 - `dagNode` - a DAG node that follows one of the supported IPLD formats.
 - `options` - a object that might contain the follwing values:
-  - `format` - The IPLD format multicodec.
-  - `hashAlg` - The hash algorithm to be used over the serialized dagNode.
-  - `cid` - the CID of the node passed.
+    - `format` - The IPLD format multicodec.
+    - `hashAlg` - The hash algorithm to be used over the serialized dagNode.
+  - or
+    - `cid` - the CID of the node passed.
   - **Note** - You should only pass the CID or the format + hashAlg pair and not both
-- `callback` must follow `function (err) {}` signature, where `err` is an error if the operation was not successful.
+- `callback` must follow `function (err, cid) {}` signature, where `err` is an error if the operation was not successful and CID is the CID generated through the process or the one that was passed
 
 If no `callback` is passed, a [promise][] is returned.
 
+**Example:**
+
+```JavaScript
+const obj = { simple: 'object' }
+
+ipfs.dag.put(obj, { format: 'dag-cbor', hashAlg: 'sha3-512' }, (err, cid) => {
+  console.log(cid.toBaseEncodedString())
+  // zdpuAzE1oAAMpsfdoexcJv6PmL9UhE8nddUYGU32R98tzV5fv
+})
+```
+
+A great source of [examples][] can be found in the tests for this API.
+
 #### `dag.get`
 
 > Retrieve an IPLD format node
@@ -29,7 +43,10 @@ If no `callback` is passed, a [promise][] is returned.
 
 ##### `JavaScript` - ipfs.dag.get(cid [, path, options], callback)
 
-- `cid` - a [CID][https://github.com/ipfs/js-cid] instance.
+- `cid` - can be one of the following:
+  - a [CID](https://github.com/ipfs/js-cid) instance.
+  - a CID in its String format (i.e: zdpuAkxd9KzGwJFGhymCZRkPCXtBmBW7mB2tTuEH11HLbES9Y)
+  - a CID in its String format concatenated with the path to be resolved
 - `path` - the path to be resolved. Optional.
 - `options` - a object that might contain the following values:
   - `localResolve` - bool - if set to true, it will avoid resolving through different objects.
@@ -38,3 +55,83 @@ If no `callback` is passed, a [promise][] is returned.
 
 - `value` - the value or node that was fetched during the get operation.
 - `remainderPath` - The remainder of the Path that the node was unable to resolve or what was left in a localResolve scenario.
+
+If no `callback` is passed, a [promise][] is returned.
+
+**Example:**
+
+```JavaScript
+// example obj
+const obj = {
+  a: 1,
+  b: [1, 2, 3],
+  c: {
+    ca: [5, 6, 7],
+    cb: 'foo"'
+  }
+}
+
+ipfs.dag.put(obj, { format: 'dag-cbor', hashAlg: 'sha2-256' }, (err, cid) => {
+  console.log(cid.toBaseEncodedString())
+  // zdpuAmtur968yprkhG9N5Zxn6MFVoqAWBbhUAkNLJs2UtkTq5
+})
+
+function errOrLog(err, result) {
+  if (err) {
+    console.error('error: ' + err)
+  } else {
+    console.log(result.value)
+  }
+}
+
+ipfs.dag.get('zdpuAmtur968yprkhG9N5Zxn6MFVoqAWBbhUAkNLJs2UtkTq5/a', errOrLog)
+// Returns:
+// 1
+
+ipfs.dag.get('zdpuAmtur968yprkhG9N5Zxn6MFVoqAWBbhUAkNLJs2UtkTq5/b', errOrLog)
+// Returns:
+// [1, 2, 3]
+
+ipfs.dag.get('zdpuAmtur968yprkhG9N5Zxn6MFVoqAWBbhUAkNLJs2UtkTq5/c', errOrLog)
+// Returns:
+// {
+//   ca: [5, 6, 7],
+//   cb: 'foo'
+// }
+
+ipfs.dag.get('zdpuAmtur968yprkhG9N5Zxn6MFVoqAWBbhUAkNLJs2UtkTq5/c/ca/1', errOrLog)
+// Returns:
+// 6
+```
+
+A great source of [examples][] can be found in the tests for this API.
+
+#### `dag.tree`
+
+> Enumerate all the entries in a graph
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.dag.tree(cid [, path, options], callback)
+
+- `cid` - can be one of the following:
+  - a [CID](https://github.com/ipfs/js-cid) instance.
+  - a CID in its String format (i.e: zdpuAkxd9KzGwJFGhymCZRkPCXtBmBW7mB2tTuEH11HLbES9Y)
+  - a CID in its String format concatenated with the path to be resolved
+- `path` - the path to be resolved. Optional.
+- `options` - a object that might contain the following values:
+  - `recursive` - bool - if set to true, it will follow the links and continuously run tree on them, returning all the paths in the graph.
+
+`callback` must follow `function (err, result) {}` signature, where `err` is an error if the operation was not successful and `result` is an Array with the paths passed.
+
+If no `callback` is passed, a [promise][] is returned.
+
+**Example:**
+
+```JavaScript
+```
+
+A great source of [examples][] can be found in the tests for this API.
+
+
+[examples]: https://github.com/ipfs/interface-ipfs-core/blob/master/src/dag.js

package.json

@@ -26,19 +26,20 @@
   },
   "homepage": "https://github.com/ipfs/interface-ipfs-core#readme",
   "dependencies": {
-    "async": "^2.1.4",
+    "async": "^2.1.5",
     "bl": "^1.2.0",
     "bs58": "^4.0.0",
     "chai": "^3.5.0",
+    "cids": "^0.4.1",
     "concat-stream": "^1.6.0",
     "detect-node": "^2.0.3",
-    "ipfs-block": "^0.5.4",
-    "ipld-dag-cbor": "^0.9.0",
-    "ipld-dag-pb": "^0.9.4",
-    "multiaddr": "^2.2.0",
-    "multihashes": "^0.3.2",
+    "ipfs-block": "^0.5.5",
+    "ipld-dag-cbor": "^0.9.1",
+    "ipld-dag-pb": "^0.9.5",
+    "multiaddr": "^2.2.1",
+    "multihashes": "^0.4.3",
     "pull-stream": "^3.5.0",
-    "readable-stream": "2.2.2"
+    "readable-stream": "1.1.14"
   },
   "devDependencies": {
     "aegir": "^10.0.0"
@@ -54,4 +55,4 @@
     "haad <[email protected]>",
     "nginnever <[email protected]>"
   ]
-}
+}