feat: add sync multihash hasher (#160)

Author: Gozala

.gitignore

@@ -8,3 +8,4 @@ node_modules
 yarn.lock
 types
 test/ts-use/tsconfig.tsbuildinfo
+test/tsconfig.tsbuildinfo

src/hashes/hasher.js

@@ -17,7 +17,7 @@ export const from = ({ name, code, encode }) => new Hasher(name, code, encode)
  * @template {string} Name
  * @template {number} Code
  * @class
- * @implements {MultihashHasher}
+ * @implements {MultihashHasher<Code>}
  */
 export class Hasher {
   /**
@@ -34,12 +34,15 @@ export class Hasher {
 
   /**
    * @param {Uint8Array} input
-   * @returns {Promise<Digest.Digest<Code, number>>}
+   * @returns {Await<Digest.Digest<Code, number>>}
    */
-  async digest (input) {
+  digest (input) {
     if (input instanceof Uint8Array) {
-      const digest = await this.encode(input)
-      return Digest.create(this.code, digest)
+      const result = this.encode(input)
+      return result instanceof Uint8Array
+        ? Digest.create(this.code, result)
+        /* c8 ignore next 1 */
+        : result.then(digest => Digest.create(this.code, digest))
     } else {
       throw Error('Unknown type, must be binary type')
       /* c8 ignore next 1 */
@@ -48,6 +51,7 @@ export class Hasher {
 }
 
 /**
+ * @template {number} Alg
  * @typedef {import('./interface').MultihashHasher} MultihashHasher
  */
 

src/hashes/identity.js

@@ -1,10 +1,14 @@
-// @ts-check
-
-import { from } from './hasher.js'
 import { coerce } from '../bytes.js'
+import * as Digest from './digest.js'
+
+export const code = 0x0
+export const name = 'identity'
+
+/**
+ * @param {Uint8Array} input
+ * @returns {Digest.Digest<typeof code, number>}
+ */
+export const digest = (input) => Digest.create(code, coerce(input))
 
-export const identity = from({
-  name: 'identity',
-  code: 0x0,
-  encode: (input) => coerce(input)
-})
+/** @type {import('./interface').SyncMultihashHasher<typeof code>} */
+export const identity = { code, name, digest }

src/hashes/interface.ts

@@ -9,11 +9,11 @@
 // a bunch of places that parse it to extract (code, digest, size). By creating
 // this first class representation we avoid reparsing and things generally fit
 // really nicely.
-export interface MultihashDigest {
+export interface MultihashDigest<Code extends number = number> {
   /**
    * Code of the multihash
    */
-  code: number
+  code: Code
 
   /**
    * Raw digest (without a hashing algorithm info)
@@ -35,20 +35,38 @@ export interface MultihashDigest {
  * Hasher represents a hashing algorithm implementation that produces as
  * `MultihashDigest`.
  */
-export interface MultihashHasher {
+export interface MultihashHasher<Code extends number = number> {
   /**
-   * Takes binary `input` and returns it (multi) hash digest.
+   * Takes binary `input` and returns it (multi) hash digest. Return value is
+   * either promise of a digest or a digest. This way general use can `await`
+   * while performance critical code may asses return value to decide whether
+   * await is needed.
+   *
    * @param {Uint8Array} input
    */
-  digest(input: Uint8Array): Promise<MultihashDigest>
+  digest(input: Uint8Array): Promise<MultihashDigest> | MultihashDigest
 
   /**
    * Name of the multihash
    */
-   name: string
+  name: string
 
   /**
    * Code of the multihash
    */
-  code: number
+  code: Code
+}
+
+/**
+ * Sync variant of `MultihashHasher` that refines return type of the `digest`
+ * to `MultihashDigest`. It is subtype of `MultihashHasher` so implementations
+ * of this interface can be passed anywhere `MultihashHasher` is expected,
+ * allowing consumer to either `await` or check the return type to decide
+ * whether to await or proceed with return value.
+ *
+ * `SyncMultihashHasher` is useful in certain APIs where async hashing would be
+ * impractical e.g. implementation of Hash Array Mapped Trie (HAMT).
+ */
+export interface SyncMultihashHasher<Code extends number = number> extends MultihashHasher<Code> {
+  digest(input: Uint8Array): MultihashDigest
 }

test/test-multihash.js

@@ -53,6 +53,22 @@ describe('multihash', () => {
       assert.deepStrictEqual(hash2.bytes, hash.bytes)
     })
 
+    if (typeof navigator === 'undefined') {
+      it('sync sha-256', () => {
+        const hash = sha256.digest(fromString('test'))
+        if (hash instanceof Promise) {
+          assert.fail('expected sync result')
+        } else {
+          assert.deepStrictEqual(hash.code, sha256.code)
+          assert.deepStrictEqual(hash.digest, slSha256(fromString('test')))
+
+          const hash2 = decodeDigest(hash.bytes)
+          assert.deepStrictEqual(hash2.code, sha256.code)
+          assert.deepStrictEqual(hash2.bytes, hash.bytes)
+        }
+      })
+    }
+
     it('hash sha2-512', async () => {
       const hash = await sha512.digest(fromString('test'))
       assert.deepStrictEqual(hash.code, sha512.code)
@@ -63,7 +79,7 @@ describe('multihash', () => {
       assert.deepStrictEqual(hash2.bytes, hash.bytes)
     })
 
-    it('hash identity', async () => {
+    it('hash identity async', async () => {
       const hash = await identity.digest(fromString('test'))
       assert.deepStrictEqual(hash.code, identity.code)
       assert.deepStrictEqual(identity.code, 0)
@@ -73,6 +89,17 @@ describe('multihash', () => {
       assert.deepStrictEqual(hash2.code, identity.code)
       assert.deepStrictEqual(hash2.bytes, hash.bytes)
     })
+
+    it('hash identity sync', () => {
+      const hash = identity.digest(fromString('test'))
+      assert.deepStrictEqual(hash.code, identity.code)
+      assert.deepStrictEqual(identity.code, 0)
+      assert.deepStrictEqual(hash.digest, fromString('test'))
+
+      const hash2 = decodeDigest(hash.bytes)
+      assert.deepStrictEqual(hash2.code, identity.code)
+      assert.deepStrictEqual(hash2.bytes, hash.bytes)
+    })
   })
   describe('decode', () => {
     for (const { encoding, hex, size } of valid) {
@@ -105,7 +132,11 @@ describe('multihash', () => {
   })
 
   it('throw on hashing non-buffer', async () => {
-    // @ts-expect-error - string is incompatible arg
-    await assert.isRejected(sha256.digest('asdf'), 'Unknown type, must be binary type')
+    try {
+      // @ts-expect-error - string is incompatible arg
+      await sha256.digest('asdf')
+    } catch (error) {
+      assert.match(String(error), /Unknown type, must be binary type/)
+    }
   })
 })

test/tsconfig.json

@@ -5,6 +5,7 @@
     }
   ],
   "compilerOptions": {
+    "composite": true,
     "allowJs": true,
     "checkJs": true,
     "forceConsistentCasingInFileNames": true,
@@ -28,13 +29,21 @@
     "skipLibCheck": true,
     "stripInternal": true,
     "resolveJsonModule": true,
-    "noEmit": true
+    "noEmit": true,
+    "paths": {
+      "multiformats": [
+        "../types/src/index"
+      ],
+      "multiformats/*": [
+        "../types/src/*"
+      ]
+    }
   },
   "include": [
-    "test/",
     "."
   ],
   "exclude": [
-    "ts-use/"
+    "ts-use/",
+    "node_modules"
   ]
 }