CID interface

.github/workflows/typecheck.yml

@@ -26,4 +26,4 @@ jobs:
       - name: Typecheck
         uses: gozala/[email protected]
         with:
-          project: test/tsconfig.json
+          project: tsconfig.json

package.json

@@ -98,6 +98,12 @@
     },
     "./codecs/raw": {
       "import": "./src/codecs/raw.js"
+    },
+    "./interface": {
+      "import": "./src/interface.js"
+    },
+    "./bytes": {
+      "import": "./src/bytes.js"
     }
   },
   "devDependencies": {

src/bases/base.js

@@ -1,20 +1,8 @@
 import basex from '../../vendor/base-x.js'
 import { coerce } from '../bytes.js'
-
-/**
- * @typedef {import('./interface').BaseEncoder} BaseEncoder
- * @typedef {import('./interface').BaseDecoder} BaseDecoder
- * @typedef {import('./interface').BaseCodec} BaseCodec
- */
-
-/**
- * @template {string} T
- * @typedef {import('./interface').Multibase<T>} Multibase
- */
-/**
- * @template {string} T
- * @typedef {import('./interface').MultibaseEncoder<T>} MultibaseEncoder
- */
+// Linter can't see that API is used in types.
+// eslint-disable-next-line
+import * as API from './interface.js'
 
 /**
  * Class represents both BaseEncoder and MultibaseEncoder meaning it
@@ -23,8 +11,8 @@ import { coerce } from '../bytes.js'
  * @class
  * @template {string} Base
  * @template {string} Prefix
- * @implements {MultibaseEncoder<Prefix>}
- * @implements {BaseEncoder}
+ * @implements {API.MultibaseEncoder<Prefix>}
+ * @implements {API.BaseEncoder}
  */
 class Encoder {
   /**
@@ -40,7 +28,7 @@ class Encoder {
 
   /**
    * @param {Uint8Array} bytes
-   * @returns {Multibase<Prefix>}
+   * @returns {API.Multibase<Prefix>}
    */
   encode (bytes) {
     if (bytes instanceof Uint8Array) {
@@ -51,29 +39,18 @@ class Encoder {
   }
 }
 
-/**
- * @template {string} Prefix
- * @typedef {import('./interface').MultibaseDecoder<Prefix>} MultibaseDecoder
- */
-
-/**
- * @template {string} Prefix
- * @typedef {import('./interface').UnibaseDecoder<Prefix>} UnibaseDecoder
- */
-
 /**
  * @template {string} Prefix
  */
 /**
  * Class represents both BaseDecoder and MultibaseDecoder so it could be used
  * to decode multibases (with matching prefix) or just base decode strings
  * with corresponding base encoding.
- * @class
  * @template {string} Base
  * @template {string} Prefix
- * @implements {MultibaseDecoder<Prefix>}
- * @implements {UnibaseDecoder<Prefix>}
- * @implements {BaseDecoder}
+ * @implements {API.MultibaseDecoder<Prefix>}
+ * @implements {API.UnibaseDecoder<Prefix>}
+ * @implements {API.BaseDecoder}
  */
 class Decoder {
   /**
@@ -107,7 +84,7 @@ class Decoder {
 
   /**
    * @template {string} OtherPrefix
-   * @param {UnibaseDecoder<OtherPrefix>|ComposedDecoder<OtherPrefix>} decoder
+   * @param {API.UnibaseDecoder<OtherPrefix>|ComposedDecoder<OtherPrefix>} decoder
    * @returns {ComposedDecoder<Prefix|OtherPrefix>}
    */
   or (decoder) {
@@ -117,30 +94,25 @@ class Decoder {
 
 /**
  * @template {string} Prefix
- * @typedef {import('./interface').CombobaseDecoder<Prefix>} CombobaseDecoder
- */
-
-/**
- * @template {string} Prefix
- * @typedef {Record<Prefix, UnibaseDecoder<Prefix>>} Decoders
+ * @typedef {Record<Prefix, API.UnibaseDecoder<Prefix>>} Decoders
  */
 
 /**
  * @template {string} Prefix
- * @implements {MultibaseDecoder<Prefix>}
- * @implements {CombobaseDecoder<Prefix>}
+ * @implements {API.MultibaseDecoder<Prefix>}
+ * @implements {API.CombobaseDecoder<Prefix>}
  */
 class ComposedDecoder {
   /**
-   * @param {Record<Prefix, UnibaseDecoder<Prefix>>} decoders
+   * @param {Decoders<Prefix>} decoders
    */
   constructor (decoders) {
     this.decoders = decoders
   }
 
   /**
    * @template {string} OtherPrefix
-   * @param {UnibaseDecoder<OtherPrefix>|ComposedDecoder<OtherPrefix>} decoder
+   * @param {API.UnibaseDecoder<OtherPrefix>|ComposedDecoder<OtherPrefix>} decoder
    * @returns {ComposedDecoder<Prefix|OtherPrefix>}
    */
   or (decoder) {
@@ -165,30 +137,25 @@ class ComposedDecoder {
 /**
  * @template {string} L
  * @template {string} R
- * @param {UnibaseDecoder<L>|CombobaseDecoder<L>} left
- * @param {UnibaseDecoder<R>|CombobaseDecoder<R>} right
+ * @param {API.UnibaseDecoder<L>|API.CombobaseDecoder<L>} left
+ * @param {API.UnibaseDecoder<R>|API.CombobaseDecoder<R>} right
  * @returns {ComposedDecoder<L|R>}
  */
 export const or = (left, right) => new ComposedDecoder(/** @type {Decoders<L|R>} */({
-  ...(left.decoders || { [/** @type UnibaseDecoder<L> */(left).prefix]: left }),
-  ...(right.decoders || { [/** @type UnibaseDecoder<R> */(right).prefix]: right })
+  ...(left.decoders || { [/** @type API.UnibaseDecoder<L> */(left).prefix]: left }),
+  ...(right.decoders || { [/** @type API.UnibaseDecoder<R> */(right).prefix]: right })
 }))
 
-/**
- * @template T
- * @typedef {import('./interface').MultibaseCodec<T>} MultibaseCodec
- */
-
 /**
  * @class
  * @template {string} Base
  * @template {string} Prefix
- * @implements {MultibaseCodec<Prefix>}
- * @implements {MultibaseEncoder<Prefix>}
- * @implements {MultibaseDecoder<Prefix>}
- * @implements {BaseCodec}
- * @implements {BaseEncoder}
- * @implements {BaseDecoder}
+ * @implements {API.MultibaseCodec<Prefix>}
+ * @implements {API.MultibaseEncoder<Prefix>}
+ * @implements {API.MultibaseDecoder<Prefix>}
+ * @implements {API.BaseCodec}
+ * @implements {API.BaseEncoder}
+ * @implements {API.BaseDecoder}
  */
 export class Codec {
   /**

src/bases/interface.js

@@ -0,0 +1 @@
+// this is dummy module overlayed by interface.ts

src/block.js

@@ -1,4 +1,7 @@
 import { bytes as binary, CID } from './index.js'
+// Linter can see that API is used in types.
+// eslint-disable-next-line
+import * as API from './interface.js'
 
 const readonly = ({ enumerable = true, configurable = false } = {}) => ({
   enumerable,
@@ -10,7 +13,7 @@ const readonly = ({ enumerable = true, configurable = false } = {}) => ({
  * @template T
  * @param {T} source
  * @param {Array<string|number>} base
- * @returns {Iterable<[string, CID]>}
+ * @returns {Iterable<[string, API.CIDView]>}
  */
 const links = function * (source, base) {
   if (source == null) return
@@ -71,6 +74,7 @@ const tree = function * (source, base) {
  * @template T
  * @param {T} source
  * @param {string[]} path
+ * @return {API.BlockCursorView<unknown>}
  */
 const get = (source, path) => {
   /** @type {Record<string, any>} */
@@ -89,17 +93,21 @@ const get = (source, path) => {
 }
 
 /**
- * @template T
+ * @template {unknown} T - Logical type of the data encoded in the block
+ * @template {number} C - multicodec code corresponding to codec used to encode the block
+ * @template {number} A - multicodec code corresponding to the hashing algorithm used in CID creation.
+ * @template {API.CIDVersion} V - CID version
+ * @implements {API.BlockView<T, C, A, V>}
  */
 class Block {
   /**
    * @param {Object} options
-   * @param {CID} options.cid
-   * @param {ByteView<T>} options.bytes
+   * @param {API.CIDView<C, A, V>} options.cid
+   * @param {API.ByteView<T>} options.bytes
    * @param {T} options.value
    */
   constructor ({ cid, bytes, value }) {
-    if (!cid || !bytes || typeof value === 'undefined') throw new Error('Missing required argument')
+    if (!cid || !bytes || typeof value === 'undefined') { throw new Error('Missing required argument') }
 
     this.cid = cid
     this.bytes = bytes
@@ -124,43 +132,48 @@ class Block {
   }
 
   /**
- * @param {string} [path]
- */
+   * @param {string} [path]
+   * @return {API.BlockCursorView<unknown>}
+   */
   get (path = '/') {
     return get(this.value, path.split('/').filter(Boolean))
   }
 }
 
 /**
- * @template T
- * @template {number} Code
- * @template {number} Algorithm
+ * @template {unknown} T - Logical type of the data encoded in the block
+ * @template {number} Code - multicodec code corresponding to codec used to encode the block
+ * @template {number} Alg - multicodec code corresponding to the hashing algorithm used in CID creation.
  * @param {Object} options
  * @param {T} options.value
- * @param {BlockEncoder<Code, T>} options.codec
- * @param {Hasher<Algorithm>} options.hasher
- * @returns {Promise<Block<T>>}
+ * @param {API.BlockEncoder<Code, T>} options.codec
+ * @param {API.MultihashHasher<Alg>} options.hasher
+ * @returns {Promise<API.BlockView<T, Code, Alg>>}
  */
 const encode = async ({ value, codec, hasher }) => {
   if (typeof value === 'undefined') throw new Error('Missing required argument "value"')
   if (!codec || !hasher) throw new Error('Missing required argument: codec or hasher')
 
   const bytes = codec.encode(value)
   const hash = await hasher.digest(bytes)
-  const cid = CID.create(1, codec.code, hash)
+  const cid = CID.create(
+    1,
+    codec.code,
+    hash
+  )
 
   return new Block({ value, bytes, cid })
 }
 
 /**
- * @template T
- * @template {number} Code
- * @template {number} Algorithm
+ * @template {unknown} T - Logical type of the data encoded in the block
+ * @template {number} Code - multicodec code corresponding to codec used to encode the block
+ * @template {number} Alg - multicodec code corresponding to the hashing algorithm used in CID creation.
  * @param {Object} options
- * @param {ByteView<T>} options.bytes
- * @param {BlockDecoder<Code, T>} options.codec
- * @param {Hasher<Algorithm>} options.hasher
- * @returns {Promise<Block<T>>}
+ * @param {API.ByteView<T>} options.bytes
+ * @param {API.BlockDecoder<Code, T>} options.codec
+ * @param {API.MultihashHasher<Alg>} options.hasher
+ * @returns {Promise<API.BlockView<T, Code, Alg>>}
  */
 const decode = async ({ bytes, codec, hasher }) => {
   if (!bytes) throw new Error('Missing required argument "bytes"')
@@ -175,14 +188,16 @@ const decode = async ({ bytes, codec, hasher }) => {
 
 /**
  * @typedef {Object} RequiredCreateOptions
- * @property {CID} options.cid
+ * @property {API.CID} options.cid
  */
 
 /**
- * @template T
- * @template {number} Code
- * @param {{ cid: CID, value:T, codec?: BlockDecoder<Code, T>, bytes: ByteView<T> }|{cid:CID, bytes:ByteView<T>, value?:void, codec:BlockDecoder<Code, T>}} options
- * @returns {Block<T>}
+ * @template {unknown} T - Logical type of the data encoded in the block
+ * @template {number} Code - multicodec code corresponding to codec used to encode the block
+ * @template {number} Alg - multicodec code corresponding to the hashing algorithm used in CID creation.
+ * @template {API.CIDVersion} V - CID version
+ * @param {{ cid: API.Link<T, Code, Alg, V>, value:T, codec?: API.BlockDecoder<Code, T>, bytes: API.ByteView<T> }|{cid:API.Link<T, Code, Alg, V>, bytes:API.ByteView<T>, value?:void, codec:API.BlockDecoder<Code, T>}} options
+ * @returns {API.BlockView<T, Code, Alg, V>}
  */
 const createUnsafe = ({ bytes, cid, value: maybeValue, codec }) => {
   const value = maybeValue !== undefined
@@ -191,19 +206,25 @@ const createUnsafe = ({ bytes, cid, value: maybeValue, codec }) => {
 
   if (value === undefined) throw new Error('Missing required argument, must either provide "value" or "codec"')
 
-  return new Block({ cid, bytes, value })
+  return new Block({
+    // eslint-disable-next-line object-shorthand
+    cid: /** @type {API.CIDView<Code, Alg, V>} */ (cid),
+    bytes,
+    value
+  })
 }
 
 /**
- * @template T
- * @template {number} Code
- * @template {number} Algorithm
+ * @template {unknown} T - Logical type of the data encoded in the block
+ * @template {number} Code - multicodec code corresponding to codec used to encode the block
+ * @template {number} Alg - multicodec code corresponding to the hashing algorithm used in CID creation.
+ * @template {API.CIDVersion} V - CID version
  * @param {Object} options
- * @param {CID} options.cid
- * @param {ByteView<T>} options.bytes
- * @param {BlockDecoder<Code, T>} options.codec
- * @param {Hasher<Algorithm>} options.hasher
- * @returns {Promise<Block<T>>}
+ * @param {API.CID<Code, Alg, V>} options.cid
+ * @param {API.ByteView<T>} options.bytes
+ * @param {API.BlockDecoder<Code, T>} options.codec
+ * @param {API.MultihashHasher<Alg>} options.hasher
+ * @returns {Promise<API.BlockView<T, Code, Alg, V>>}
  */
 const create = async ({ bytes, cid, hasher, codec }) => {
   if (!bytes) throw new Error('Missing required argument "bytes"')
@@ -214,29 +235,12 @@ const create = async ({ bytes, cid, hasher, codec }) => {
     throw new Error('CID hash does not match bytes')
   }
 
-  return createUnsafe({ bytes, cid, value, codec })
+  return createUnsafe({
+    bytes,
+    cid,
+    value,
+    codec
+  })
 }
 
 export { encode, decode, create, createUnsafe, Block }
-
-/**
- * @template T
- * @typedef {import('./codecs/interface').ByteView<T>} ByteView
- */
-
-/**
- * @template {number} Code
- * @template T
- * @typedef {import('./codecs/interface').BlockEncoder<Code, T>} BlockEncoder
- */
-
-/**
- * @template {number} Code
- * @template T
- * @typedef {import('./codecs/interface').BlockDecoder<Code, T>} BlockDecoder
- */
-
-/**
- * @template Algorithm
- * @typedef {import('./hashes/interface').MultihashHasher} Hasher
- */

src/block/interface.js

@@ -0,0 +1 @@
+// this is dummy module overlayed by interface.ts