chore: add code type info

Author: Gozala

src/bases/base.js

@@ -136,7 +136,7 @@ class ComposedDecoder {
     /** @type {Object<string, UnibaseDecoder<Prefix>>} */
     this.decoders = decoders
     // so that we can distinguish between unibase and multibase
-    /** @type {void} */
+    /** @type {null} */
     this.prefix = null
   }
 

src/block.js

@@ -3,13 +3,14 @@
 import CID from './cid.js'
 
 /**
+ * @template {number} Code
  * @template T
  * @class
  */
 export default class Block {
   /**
    * @param {CID|null} cid
-   * @param {number} code
+   * @param {Code} code
    * @param {T} data
    * @param {Uint8Array} bytes
    * @param {BlockConfig} config
@@ -56,30 +57,33 @@ export default class Block {
   }
 
   /**
+   * @template {number} Code
    * @template T
-   * @param {Encoder<T>} codec
+   * @param {Encoder<Code, T>} codec
    * @param {BlockConfig} options
    */
   static encoder (codec, options) {
     return new BlockEncoder(codec, options)
   }
 
   /**
+   * @template {number} Code
    * @template T
-   * @param {Decoder<T>} codec
+   * @param {Decoder<Code, T>} codec
    * @param {BlockConfig} options
    */
   static decoder (codec, options) {
     return new BlockDecoder(codec, options)
   }
 
   /**
+   * @template {number} Code
    * @template T
    * @param {Object} codec
-   * @param {Encoder<T>} codec.encoder
-   * @param {Decoder<T>} codec.decoder
-   * @param {Object} [options]
-   * @returns {BlockCodec<T>}
+   * @param {Encoder<Code, T>} codec.encoder
+   * @param {Decoder<Code, T>} codec.decoder
+   * @param {BlockConfig} options
+   * @returns {BlockCodec<Code, T>}
    */
 
   static codec ({ encoder, decoder }, options) {
@@ -178,12 +182,13 @@ const createCID = async (hasher, bytes, code) => {
 }
 
 /**
+ * @template {number} Code
  * @template T
  */
 class BlockCodec {
   /**
-   * @param {Encoder<T>} encoder
-   * @param {Decoder<T>} decoder
+   * @param {Encoder<Code, T>} encoder
+   * @param {Decoder<Code, T>} decoder
    * @param {BlockConfig} config
    */
 
@@ -195,17 +200,17 @@ class BlockCodec {
 
   /**
    * @param {Uint8Array} bytes
-   * @param {BlockConfig} [options]
-   * @returns {Block<T>}
+   * @param {Partial<BlockConfig>} [options]
+   * @returns {Block<Code, T>}
    */
   decode (bytes, options) {
     return this.decoder.decode(bytes, { ...this.config, ...options })
   }
 
   /**
    * @param {T} data
-   * @param {BlockConfig} [options]
-   * @returns {Block<T>}
+   * @param {Partial<BlockConfig>} [options]
+   * @returns {Block<Code, T>}
    */
   encode (data, options) {
     return this.encoder.encode(data, { ...this.config, ...options })
@@ -214,11 +219,12 @@ class BlockCodec {
 
 /**
  * @class
+ * @template {number} Code
  * @template T
  */
 class BlockEncoder {
   /**
-   * @param {Encoder<T>} codec
+   * @param {Encoder<Code, T>} codec
    * @param {BlockConfig} config
    */
   constructor (codec, config) {
@@ -228,8 +234,8 @@ class BlockEncoder {
 
   /**
    * @param {T} data
-   * @param {BlockConfig} [options]
-   * @returns {Block}
+   * @param {Partial<BlockConfig>} [options]
+   * @returns {Block<Code, T>}
    */
   encode (data, options) {
     const { codec } = this
@@ -240,11 +246,12 @@ class BlockEncoder {
 
 /**
  * @class
+ * @template {number} Code
  * @template T
  */
 class BlockDecoder {
   /**
-   * @param {Decoder<T>} codec
+   * @param {Decoder<Code, T>} codec
    * @param {BlockConfig} config
    */
   constructor (codec, config) {
@@ -255,7 +262,7 @@ class BlockDecoder {
   /**
    * @param {Uint8Array} bytes
    * @param {Partial<BlockConfig>} [options]
-   * @returns {Block}
+   * @returns {Block<Code, T>}
    */
   decode (bytes, options) {
     const data = this.codec.decode(bytes)
@@ -283,16 +290,19 @@ class BlockDecoder {
  */
 
 /**
+ * @template {number} Code
  * @template T
- * @typedef {import('./codecs/interface').BlockEncoder<T>} Encoder
+ * @typedef {import('./codecs/interface').BlockEncoder<Code, T>} Encoder
  */
 
 /**
+ * @template {number} Code
  * @template T
- * @typedef {import('./codecs/interface').BlockDecoder} Decoder
+ * @typedef {import('./codecs/interface').BlockDecoder<Code, T>} Decoder
  */
 
 /**
+ * @template {number} Code
  * @template T
- * @typedef {import('./codecs/interface').BlockCodec} Codec
+ * @typedef {import('./codecs/interface').BlockCodec<Code, T>} Codec
  */

src/codecs/codec.js

@@ -15,16 +15,17 @@ export const codec = ({ name, code, decode, encode }) =>
   new Codec(name, code, encode, decode)
 
 /**
+ * @template {number} Code
  * @template T
- * @typedef {import('./interface').BlockEncoder<T>} BlockEncoder
+ * @typedef {import('./interface').BlockEncoder<Code, T>} BlockEncoder
  */
 
 /**
  * @class
  * @template T
  * @template {string} Name
  * @template {number} Code
- * @implements {BlockEncoder<T>}
+ * @implements {BlockEncoder<Code, T>}
  */
 export class Encoder {
   /**
@@ -40,36 +41,42 @@ export class Encoder {
 }
 
 /**
+ * @template {number} Code
  * @template T
- * @typedef {import('./interface').BlockDecoder<T>} BlockDecoder
+ * @typedef {import('./interface').BlockDecoder<Code, T>} BlockDecoder
  */
 
 /**
  * @class
+ * @template {number} Code
  * @template T
- * @implements {BlockDecoder<T>}
+ * @implements {BlockDecoder<Code, T>}
  */
 export class Decoder {
   /**
+   * @param {string} name
+   * @param {Code} code
    * @param {(bytes:Uint8Array) => T} decode
    */
-  constructor (code, decode) {
+  constructor (name, code, decode) {
+    this.name = name
     this.code = code
     this.decode = decode
   }
 }
 
 /**
+ * @template {number} Code
  * @template T
- * @typedef {import('./interface').BlockCodec<T>} BlockCodec
+ * @typedef {import('./interface').BlockCodec<Code, T>} BlockCodec
  */
 
 /**
  * @class
  * @template {string} Name
  * @template {number} Code
  * @template T
- * @implements {BlockCodec<T>}
+ * @implements {BlockCodec<Code, T>}
  */
 export class Codec {
   /**
@@ -86,8 +93,8 @@ export class Codec {
   }
 
   get decoder () {
-    const { name, decode } = this
-    const decoder = new Decoder(name, decode)
+    const { name, code, decode } = this
+    const decoder = new Decoder(name, code, decode)
     Object.defineProperty(this, 'decoder', { value: decoder })
     return decoder
   }

src/codecs/interface.ts

@@ -1,24 +1,31 @@
 /**
  * IPLD encoder part of the codec.
  */
-export interface BlockEncoder<T> {
+export interface BlockEncoder<Code extends number, T> {
   name: string
-  code: number
-  encode(data: T): Uint8Array
+  code: Code
+  encode(data: T): ByteView<T>
 }
 
 /**
  * IPLD decoder part of the codec.
  */
-export interface BlockDecoder<T> {
-  code: number
-  decode(bytes: Uint8Array): T
+export interface BlockDecoder<Code extends number, T> {
+  code: Code
+  decode(bytes: ByteView<T>): T
 }
 
 /**
  * IPLD codec that is just Encoder + Decoder however it is
  * separate those capabilties as sender requires encoder and receiver
  * requires decoder.
  */
-export interface BlockCodec<T> extends BlockEncoder<T>, BlockDecoder<T> { }
+export interface BlockCodec<Code extends number, T> extends BlockEncoder<Code, T>, BlockDecoder<Code, T> { }
 
+
+// This just a hack to retain type information abouth the data that
+// is incoded `T`  Because it's a union `data` field is never going
+// to be usable anyway.
+type ByteView<T> =
+  | Uint8Array
+  | Uint8Array & { data: T }

src/legacy.js

@@ -27,6 +27,7 @@ const legacy = (codec, { hashes }) => {
     }
 
     if (bytes.isBinary(obj)) {
+      // @ts-ignore
       return Buffer.from(obj)
     }
 
@@ -93,7 +94,7 @@ const legacy = (codec, { hashes }) => {
     let value = codec.decode(buff)
     const entries = path.split('/').filter(x => x)
     while (entries.length) {
-      value = value[entries.shift()]
+      value = value[/** @type {string} */(entries.shift())]
       if (typeof value === 'undefined') throw new Error('Not found')
       if (OldCID.isCID(value)) {
         return { value, remainderPath: entries.join('/') }