feat: define sync multihash hasher interface

Author: Gozala

.gitignore

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

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

@@ -63,7 +63,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 +73,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) {

test/tsconfig.json

@@ -28,13 +28,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"
   ]
 }