From 04657c8b72a2da3019f1ce2e7a91d059758872fe Mon Sep 17 00:00:00 2001
From: Volker Mische <volker.mische@gmail.com>
Date: Thu, 15 Mar 2018 15:38:57 +0100
Subject: [PATCH] feat: update the spec

This update of the spec is based on the feedback from
https://github.com/ipld/interface-ipld-format/pull/11

The changes are:

 - `util.cid()` no longer takes a DAG node, but a serialized node
   as input. It also gains optional options
 - `util.toJSON()` is added
 - `resolver.isLink()` is removed, it should be part of js-ipld
   instead.
---
 README.md | 43 +++++++++++++++++--------------------------
 1 file changed, 17 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index 855f4aa..8ce4b09 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,8 @@
   - [IPLD format utils](#ipld-format-utils)
     - [`util.serialize(dagNode, callback)`](#utilserializedagnode-callback)
     - [`util.deserialize(binaryBlob, callback)`](#utildeserializebinaryblob-callback)
-    - [`util.cid(dagNode, callback)`](#utilciddagnode-callback)
+    - [`util.cid(dagNode[, options], callback)`](#utilciddagnode-callback)
+    - [`util.toJSON(dagNode, callback)`](#utiltojsondagnode-callback)
   - [Local resolver methods](#local-resolver-methods)
     - [`resolver.resolve(binaryBlob, path, callback)`](#resolverresolvebinaryblob-path-callback)
     - [`resolver.tree(binaryBlob[, options], callback)`](#resolvertreebinaryblob-options-callback)
@@ -52,16 +53,6 @@ Include this badge in your readme if you make a new module that implements inter
 
 A valid (read: that follows this interface) IPLD format implementation the following API.
 
-**Table of contents:**
-
-- IPLD format utils - Necessary by the main resolver
-  - `util.serialize`
-  - `util.deserialize`
-  - `util.cid`
-- Local resolver methods - the block level resolver (knows how to resolve paths at the block scope)
-  - `resolver.resolve`
-  - `resolver.tree`
-
 ### IPLD format utils
 
 #### `util.serialize(dagNode, callback)`
@@ -76,11 +67,23 @@ A valid (read: that follows this interface) IPLD format implementation the follo
 
 `callback` must have the signature `function (err, dagNode)`, where `err` is an Error if the function fails and `dagNode` is the dagNode that got deserialized in the process.
 
-#### `util.cid(dagNode, callback)`
+#### `util.cid(binaryBlob[, options], callback)`
+
+> get the CID of the serialized dagNode
+
+Options include:
+  - version - the CID version to be used (defaults to 1)
+  - hashAlg - the hash algorithm to be used (default to the one set by the format)
+
+`callback` must have the signature `function (err, cid)`, where `err` is an Error if the function fails and `cid` is a CID instance of the serialized dagNode.
 
-> get the CID of the dagNode
+#### `util.toJSON(dagNode, callback)`
 
-`callback` must have the signature `function (err, cid)`, where `err` is an Error if the function fails and `cid` is a CID instance of the dagNode.
+> return a JSON representation of the dagNode
+
+`callback` must have the signature `function (err, nodeJson)`, where `err` is an Error is the function fails and `nodeJson` is a JSON representation of the dagNode.
+
+This method was introduced to add some convinience when dealing with formats that have a non practical structure. For formats like dag-cbor, you won't need to use it as the dagNode itself is already a JSON 1:1 mapping to the CBOR representation.
 
 ### Local resolver methods
 
@@ -103,18 +106,6 @@ Options include:
 
 `callback` must have the signature `function (err, result)`, where `err` is an Error if the function fails and `result` is an array depending on `options.value`. If it is `true` it is an array of objects containing `path:value` tuples, such as: `[ { '/foo': 'bar' } ...]`. If it is `false` it contains only the paths, such as `['/foo', '/bar', ...]`.
 
-#### `resolver.isLink(binaryBlob, path, callback)`
-
-> returns an IPLD Link of a given path, if it is a valid link, false otherwise.
-
-`callback` must have the signature `function (err, link)`, where `err` is an Error if the function fails and `link` is the CID that was in a given path. `link` follows the format:
-
-```JavaScript
-{
-  '/': <cid>
-}
-```
-
 ## Maintainers
 
 Captain: [@diasdavid](https://github.com/diasdavid).