chore: add types (#139)

Updates deps, adds types and fixes all compiler warnings

Author: achingbrain

package.json

@@ -4,7 +4,9 @@
   "description": "JavaScript implementation of the IPLD (InterpPlanetary Linked Data)",
   "leadMaintainer": "Volker Mische <[email protected]>",
   "main": "src/index.js",
+  "types": "./dist/src/index.d.ts",
   "scripts": {
+    "prepare": "aegir build",
     "test": "aegir test",
     "test:browser": "aegir test --target browser",
     "test:node": "aegir test --target node",
@@ -37,12 +39,14 @@
   "dependencies": {
     "borc": "^2.1.2",
     "cids": "^1.0.0",
+    "interface-ipld-format": "^1.0.0",
     "is-circular": "^1.0.2",
     "multicodec": "^3.0.1",
     "multihashing-async": "^2.0.0",
     "uint8arrays": "^2.1.3"
   },
   "devDependencies": {
+    "@types/detect-node": "^2.0.0",
     "aegir": "^31.0.1",
     "detect-node": "^2.0.4",
     "garbage": "0.0.0",

src/index.js

@@ -1,6 +1,18 @@
 'use strict'
 
-exports.util = require('./util.js')
-exports.resolver = require('./resolver.js')
-exports.codec = exports.util.codec
-exports.defaultHashAlg = exports.util.defaultHashAlg
+const util = require('./util.js')
+const resolver = require('./resolver.js')
+
+/**
+ * @typedef {import('interface-ipld-format').Format<object>} ObjectFormat
+ */
+
+/**
+ * @type {ObjectFormat}
+ */
+module.exports = {
+  util,
+  resolver,
+  codec: util.codec,
+  defaultHashAlg: util.defaultHashAlg
+}

src/resolver.js

@@ -12,13 +12,13 @@ const util = require('./util')
  * @param {Uint8Array} binaryBlob - Binary representation of a CBOR block
  * @param {string} [path='/'] - Path that should be resolved
  */
-exports.resolve = (binaryBlob, path) => {
+exports.resolve = (binaryBlob, path = '') => {
   let node = util.deserialize(binaryBlob)
 
   const parts = path.split('/').filter(Boolean)
   while (parts.length) {
     const key = parts.shift()
-    if (node[key] === undefined) {
+    if (!key || !(key in node)) {
       throw new Error(`Object has no property '${key}'`)
     }
 
@@ -37,17 +37,25 @@ exports.resolve = (binaryBlob, path) => {
   }
 }
 
+/**
+ * @param {any} node
+ * @param {string} [path]
+ * @returns {Generator<string, void, undefined>}
+ */
 const traverse = function * (node, path) {
   // Traverse only objects and arrays
-  if (node instanceof Uint8Array || CID.isCID(node) || typeof node === 'string' ||
-      node === null) {
+  if (node instanceof Uint8Array || CID.isCID(node) || typeof node === 'string' || node === null) {
     return
   }
+
   for (const item of Object.keys(node)) {
     const nextpath = path === undefined ? item : path + '/' + item
     yield nextpath
     yield * traverse(node[item], nextpath)
   }
+
+  // to stop eslint and tsc fighting
+  return undefined
 }
 
 /**

src/util.js

@@ -1,29 +1,47 @@
 'use strict'
 
+// @ts-ignore TODO: switch to cborg
 const cbor = require('borc')
 const multicodec = require('multicodec')
 const multihashing = require('multihashing-async')
+const { multihash } = multihashing
 const CID = require('cids')
+// @ts-ignore
 const isCircular = require('is-circular')
 const uint8ArrayConcat = require('uint8arrays/concat')
 const uint8ArrayFromString = require('uint8arrays/from-string')
 
+/**
+ * @typedef {import('cids').CIDVersion} CIDVersion
+ * @typedef {import('multihashing-async').multihash.HashCode} HashCode
+ */
+
 // https://github.com/ipfs/go-ipfs/issues/3570#issuecomment-273931692
 const CID_CBOR_TAG = 42
 
+/**
+ * @param {CID | string} cid
+ */
 function tagCID (cid) {
+  let buf
+
   if (typeof cid === 'string') {
-    cid = new CID(cid).bytes
+    buf = new CID(cid).bytes
   } else if (CID.isCID(cid)) {
-    cid = cid.bytes
+    buf = cid.bytes
+  } else {
+    throw new Error('Could not tag CID - was not string or CID')
   }
 
   return new cbor.Tagged(CID_CBOR_TAG, uint8ArrayConcat([
     uint8ArrayFromString('00', 'base16'), // thanks jdag
-    cid
-  ], 1 + cid.length))
+    buf
+  ], 1 + buf.length))
 }
 
+/**
+ * @param {any} dagNode
+ */
 function replaceCIDbyTAG (dagNode) {
   let circular
   try {
@@ -35,6 +53,10 @@ function replaceCIDbyTAG (dagNode) {
     throw new Error('The object passed has circular references')
   }
 
+  /**
+   * @param {any} obj
+   * @returns {any}
+   */
   function transform (obj) {
     if (!obj || obj instanceof Uint8Array || typeof obj === 'string') {
       return obj
@@ -52,6 +74,7 @@ function replaceCIDbyTAG (dagNode) {
 
     if (keys.length > 0) {
       // Recursive transform
+      /** @type {Record<string, any>} */
       const out = {}
       keys.forEach((key) => {
         if (typeof obj[key] === 'object') {
@@ -70,9 +93,12 @@ function replaceCIDbyTAG (dagNode) {
 }
 
 const codec = multicodec.DAG_CBOR
-const defaultHashAlg = multicodec.SHA2_256
+const defaultHashAlg = multihash.names['sha2-256']
 
 const defaultTags = {
+  /**
+   * @param {Uint8Array} val
+   */
   [CID_CBOR_TAG]: (val) => {
     // remove that 0
     val = val.slice(1)
@@ -83,7 +109,8 @@ const defaultSize = 64 * 1024 // current decoder heap size, 64 Kb
 let currentSize = defaultSize
 const defaultMaxSize = 64 * 1024 * 1024 // max heap size when auto-growing, 64 Mb
 let maxSize = defaultMaxSize
-let decoder = null
+/** @type {cbor.Decoder} */
+let decoder
 
 /**
  * Configure the underlying CBOR decoder.
@@ -141,7 +168,7 @@ function serialize (node) {
  * Deserialize CBOR block into the internal representation.
  *
  * @param {Uint8Array} data - Binary representation of a CBOR block
- * @returns {Object} - An object that conforms to the IPLD Data Model
+ * @returns {any} - An object that conforms to the IPLD Data Model
  */
 function deserialize (data) {
   if (data.length > currentSize && data.length <= maxSize) {
@@ -165,19 +192,21 @@ function deserialize (data) {
 /**
  * Calculate the CID of the binary blob.
  *
- * @param {Object} binaryBlob - Encoded IPLD Node
+ * @param {Uint8Array} 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>}
+ * @param {CIDVersion} [userOptions.cidVersion=1] - CID version number
+ * @param {HashCode} [userOptions.hashAlg=multihash.names['sha2-256']] - Defaults to the defaultHashAlg of the format
  */
-async function cid (binaryBlob, userOptions) {
-  const defaultOptions = { cidVersion: 1, hashAlg: defaultHashAlg }
-  const options = Object.assign(defaultOptions, userOptions)
+async function cid (binaryBlob, userOptions = {}) {
+  const options = {
+    cidVersion: userOptions.cidVersion == null ? 1 : userOptions.cidVersion,
+    hashAlg: userOptions.hashAlg == null ? module.exports.defaultHashAlg : userOptions.hashAlg
+  }
 
-  const multihash = await multihashing(binaryBlob, options.hashAlg)
-  const codecName = multicodec.getNameFromCode(codec)
-  const cid = new CID(options.cidVersion, codecName, multihash)
+  const hashName = multihash.codes[options.hashAlg]
+  const hash = await multihashing(binaryBlob, hashName)
+  const codecName = multicodec.getNameFromCode(module.exports.codec)
+  const cid = new CID(options.cidVersion, codecName, hash)
 
   return cid
 }

test/resolver.spec.js

@@ -74,6 +74,7 @@ describe('IPLD format resolver (local)', () => {
       })
 
       it('should resolve falsy values for path within scope', () => {
+        /** @type {{ [key: string]: any }} */
         const falsyNode = {
           nu11: null,
           f4lse: false,

test/util.spec.js

@@ -2,12 +2,17 @@
 'use strict'
 
 const { expect } = require('aegir/utils/chai')
+// @ts-ignore
 const garbage = require('garbage')
 const dagCBOR = require('../src')
 const multihash = require('multihashes')
 const CID = require('cids')
 const uint8ArrayFromString = require('uint8arrays/from-string')
+const uint8ArrayToString = require('uint8arrays/to-string')
 const uint8ArrayConcat = require('uint8arrays/concat')
+const {
+  configureDecoder
+} = require('../src/util')
 
 describe('util', () => {
   const obj = {
@@ -30,7 +35,7 @@ describe('util', () => {
     // Check for the tag 42
     // d8 = tag, 2a = 42
     expect(
-      serializedObj.toString('hex').match(/d82a/g)
+      uint8ArrayToString(serializedObj, 'base16').match(/d82a/g)
     ).to.have.length(4)
 
     const deserializedObj = dagCBOR.util.deserialize(serializedObj)
@@ -48,22 +53,22 @@ describe('util', () => {
     const deserialized = dagCBOR.util.deserialize(serialized)
     expect(largeObj).to.eql(deserialized)
     // reset decoder to default
-    dagCBOR.util.configureDecoder()
+    configureDecoder()
   })
 
   it('.deserialize fail on large objects beyond maxSize', () => {
     // larger than the default borc heap size, should bust the heap if we turn off auto-grow
     const dataSize = (128 * 1024) + 1
     const largeObj = { someKey: [].slice.call(new Uint8Array(dataSize)) }
 
-    dagCBOR.util.configureDecoder({ size: 64 * 1024, maxSize: 128 * 1024 }) // 64 Kb start, 128 Kb max
+    configureDecoder({ size: 64 * 1024, maxSize: 128 * 1024 }) // 64 Kb start, 128 Kb max
     const serialized = dagCBOR.util.serialize(largeObj)
     expect(serialized).to.be.a('Uint8Array')
 
     expect(() => dagCBOR.util.deserialize(serialized)).to.throw(
       'Data is too large to deserialize with current decoder')
     // reset decoder to default
-    dagCBOR.util.configureDecoder()
+    configureDecoder()
   })
 
   it('.serialize and .deserialize object with slash as property', () => {
@@ -90,7 +95,7 @@ describe('util', () => {
   })
 
   it('.cid with hashAlg', async () => {
-    const cid = await dagCBOR.util.cid(serializedObj, { hashAlg: 'sha2-512' })
+    const cid = await dagCBOR.util.cid(serializedObj, { hashAlg: multihash.names['sha2-512'] })
     expect(cid.version).to.equal(1)
     expect(cid.codec).to.equal('dag-cbor')
     expect(cid.multihash).to.exist()

tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./node_modules/aegir/src/config/tsconfig.aegir.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": [
+    "src",
+    "test"
+  ]
+}