feat: new IPLD Format API

BREAKING CHANGE: The API is now async/await based

There are numerous changes, the most significant one is that the API
is no longer callback based, but it using async/await.

For the full new API please see the [IPLD Formats spec].

[IPLD Formats spec]: https://github.com/ipld/interface-ipld-format

package.json

@@ -40,7 +40,8 @@
   "homepage": "https://github.com/ipld/js-ipld-raw#readme",
   "dependencies": {
     "cids": "~0.6.0",
-    "multihashing-async": "~0.6.0"
+    "multicodec": "~0.5.0",
+    "multihashing-async": "~0.7.0"
   },
   "devDependencies": {
     "aegir": "^18.2.0",

src/index.js

@@ -1,44 +1,68 @@
 'use strict'
 const CID = require('cids')
-const multihash = require('multihashing-async')
+const multihashing = require('multihashing-async')
+const multicodec = require('multicodec')
 
 // binary resolver
 module.exports = {
+  codec: multicodec.RAW,
+  defaultHashAlg: multicodec.SHA2_256,
   resolver: {
-    multicodec: 'raw',
-    defaultHashAlg: 'sha2-256',
-    resolve: (binaryBlob, path, callback) => {
-      callback(null, {
+    /**
+     * Resolves a path within a Raw block.
+     *
+     * Always returns the raw data as value without any remainderPath.
+     *
+     * @param {Buffer} binaryBlob - Binary representation of a PB block
+     * @param {string} [path='/'] - Path that should be resolved (that value is ignored)
+     * @returns {Object} result - Result of the path it it was resolved successfully
+     * @returns {*} result.value - The raw data
+     * @returns {string} result.remainderPath - An empty string
+     */
+    resolve: (binaryBlob, path) => {
+      return {
         value: binaryBlob,
         remainderPath: ''
-      })
+      }
     },
-    tree: (binaryBlob, options, callback) => {
-      if (typeof options === 'function') {
-        callback = options
+    /**
+     * Return all available paths of a block.
+     *
+     * @generator
+     * @param {Buffer} binaryBlob - The raw data
+     * @returns {Object} - Finished generator with `done: true`
+     */
+    tree: (binaryBlob) => {
+      return {
+        done: true
       }
-      callback(null, [])
     }
   },
   util: {
-    deserialize: (data, cb) => {
-      cb(null, data)
+    deserialize: (data) => {
+      return data
     },
-    serialize: (data, cb) => {
-      cb(null, data)
+    serialize: (data) => {
+      return data
     },
-    cid: (data, options, cb) => {
-      if (typeof options === 'function') {
-        cb = options
-        options = {}
-      }
-      options = options || {}
-      const hashAlg = options.hashAlg || 'sha2-256'
-      const version = typeof options.version === 'undefined' ? 1 : options.version
-      multihash(data, hashAlg, (err, mh) => {
-        if (err) return cb(err)
-        cb(null, new CID(version, 'raw', mh))
-      })
+    /**
+     * Calculate the CID of the binary blob.
+     *
+     * @param {Object} binaryBlob - Encoded IPLD Node
+     * @param {Object} [userOptions] - Options to create the CID
+     * @param {number} [userOptions.cidVersion=1] - CID version number
+     * @param {string} [UserOptions.hashAlg] - Defaults to the defaultHashAlg of the format
+     * @returns {Promise.<CID>}
+     */
+    cid: async (binaryBlob, userOptions) => {
+      const defaultOptions = { cidVersion: 1, hashAlg: module.exports.defaultHashAlg }
+      const options = Object.assign(defaultOptions, userOptions)
+
+      const multihash = await multihashing(binaryBlob, options.hashAlg)
+      const codecName = multicodec.print[module.exports.codec]
+      const cid = new CID(options.cidVersion, codecName, multihash)
+
+      return cid
     }
   }
 }

test/index.spec.js

@@ -8,92 +8,61 @@ chai.use(dirtyChai)
 const ipldRaw = require('../src/index')
 const resolver = ipldRaw.resolver
 const multihash = require('multihashes')
+const multicodec = require('multicodec')
 
 describe('raw codec', () => {
   let testData = Buffer.from('test data')
-  let testBlob
-
-  before((done) => {
-    ipldRaw.util.serialize(testData, (err, result) => {
-      expect(err).to.not.exist()
-      testBlob = result
-      done()
-    })
-  })
+  let testBlob = ipldRaw.util.serialize(testData)
 
   it('multicodec is raw', () => {
-    expect(resolver.multicodec).to.equal('raw')
+    expect(ipldRaw.codec).to.equal(multicodec.RAW)
   })
 
   it('defaultHashAlg is sha2-256', () => {
-    expect(resolver.defaultHashAlg).to.equal('sha2-256')
+    expect(ipldRaw.defaultHashAlg).to.equal(multicodec.SHA2_256)
   })
 
   it('resolver.resolve', () => {
-    resolver.resolve(testBlob, 'a/b/c/d', (err, result) => {
-      expect(err).to.not.exist()
-      expect(result.value.toString('hex')).to.equal(testData.toString('hex'))
-      expect(result.remainderPath).to.equal('')
-    })
+    const result = resolver.resolve(testBlob, 'a/b/c/d')
+    expect(result.value.toString('hex')).to.equal(testData.toString('hex'))
+    expect(result.remainderPath).to.equal('')
   })
 
   it('resolver.tree', () => {
-    resolver.tree(testBlob, {}, (err, paths) => {
-      expect(err).to.not.exist()
-      expect(Array.isArray(paths)).to.eql(true)
-      expect(paths.length).to.eql(0)
-    })
-  })
-
-  it('resolver.tree option parameter can be ignored', () => {
-    resolver.tree(testBlob, (err, paths) => {
-      expect(err).to.not.exist()
-      expect(Array.isArray(paths)).to.eql(true)
-      expect(paths.length).to.eql(0)
-    })
+    const paths = resolver.tree(testBlob)
+    expect(paths.value).to.be.undefined()
+    expect(paths.done).to.be.true()
   })
 })
 
 describe('raw util', () => {
-  let rawData = Buffer.from('some raw data')
+  const rawData = Buffer.from('some raw data')
 
-  it('serialize is noop', (done) => {
-    ipldRaw.util.serialize(rawData, (err, result) => {
-      expect(err).to.not.exist()
-      expect(result).to.equal(rawData)
-      done()
-    })
+  it('serialize is noop', () => {
+    const result = ipldRaw.util.serialize(rawData)
+    expect(result).to.equal(rawData)
   })
 
-  it('deserialize is noop', (done) => {
-    ipldRaw.util.deserialize(rawData, (err, result) => {
-      expect(err).to.not.exist()
-      expect(result).to.equal(rawData)
-      done()
-    })
+  it('deserialize is noop', () => {
+    const result = ipldRaw.util.deserialize(rawData)
+    expect(result).to.equal(rawData)
   })
 
-  it('create cid', (done) => {
-    ipldRaw.util.cid(rawData, (err, cid) => {
-      expect(err).to.not.exist()
-      expect(cid.version).to.equal(1)
-      expect(cid.codec).to.equal('raw')
-      expect(cid.multihash).to.exist()
-      const mh = multihash.decode(cid.multihash)
-      expect(mh.name).to.equal('sha2-256')
-      done()
-    })
+  it('create cid', async () => {
+    const cid = await ipldRaw.util.cid(rawData)
+    expect(cid.version).to.equal(1)
+    expect(cid.codec).to.equal('raw')
+    expect(cid.multihash).to.exist()
+    const mh = multihash.decode(cid.multihash)
+    expect(mh.name).to.equal('sha2-256')
   })
 
-  it('create cid with hashAlg', (done) => {
-    ipldRaw.util.cid(rawData, { hashAlg: 'sha2-512' }, (err, cid) => {
-      expect(err).to.not.exist()
-      expect(cid.version).to.equal(1)
-      expect(cid.codec).to.equal('raw')
-      expect(cid.multihash).to.exist()
-      const mh = multihash.decode(cid.multihash)
-      expect(mh.name).to.equal('sha2-512')
-      done()
-    })
+  it('create cid with hashAlg', async () => {
+    const cid = await ipldRaw.util.cid(rawData, { hashAlg: 'sha2-512' })
+    expect(cid.version).to.equal(1)
+    expect(cid.codec).to.equal('raw')
+    expect(cid.multihash).to.exist()
+    const mh = multihash.decode(cid.multihash)
+    expect(mh.name).to.equal('sha2-512')
   })
 })