feat: draft for #33 that incorporates feedback

README.md

@@ -13,31 +13,33 @@ This allows you to pass around an interface containing only the code you need
 which can greatly reduce dependencies and bundle size.
 
 ```js
-import { create } from 'multiformats'
-import sha2 from 'multiformats/hashes/sha2'
+import * as CID from 'multiformats/cid'
+import { sha256 } from 'multiformats/hashes/sha2'
 import dagcbor from '@ipld/dag-cbor'
-const { multihash, multicodec, CID } = create()
-multihash.add(sha2)
-multicodec.add(dagcbor)
+import { base32 } from 'multiformats/bases/base32'
+import { base58btc } from 'multiformats/bases/base58'
 
-const buffer = multicodec.encode({ hello, 'world' }, 'dag-cbor')
-const hash = await multihash.hash(buffer, 'sha2-256')
+const bytes = dagcbor.encode({ hello: 'world' })
+
+const hash = await sha256.digest(bytes)
 // raw codec is the only codec that is there by default
-const cid = new CID(1, 'raw', hash)
+const cid = CID.create(1, dagcbor.code, hash, {
+  base: base32,
+  base58btc
+})
 ```
 
 However, if you're doing this much you should probably use multiformats
 with the `Block` API.
 
 ```js
 // Import basics package with dep-free codecs, hashes, and base encodings
-import multiformats from 'multiformats/basics'
+import { block } from 'multiformats/basics'
 import dagcbor from '@ipld/dag-cbor'
-import { create } from '@ipld/block' // Yet to be released Block interface
-multiformats.multicodec.add(dagcbor)
-const Block = create(multiformats)
-const block = Block.encoder({ hello: world }, 'dag-cbor')
-const cid = await block.cid()
+
+const encoder = block.encoder(dagcbor)
+const hello = encoder.encode({ hello: 'world' })
+const cid = await hello.cid()
 ```
 
 # Plugins
@@ -83,35 +85,17 @@ Returns a new multiformats interface.
 
 Can optionally pass in a table of multiformat entries.
 
-# multihash
-
-## multihash.encode
-
-## multihash.decode
-
-## multihash.validate
-
-## multihash.add
-
-## multihash.hash
-
-# multicodec
-
-## multicodec.encode
-
-## multicodec.decode
-
-## multicodec.add
+## multiformats.configure
 
-# multibase
+## multiformats.varint
 
-## multibase.encode
+## multiformats.bytes
 
-## multibase.decode
+## multiformats.digest
 
-## multibase.add
+## multiformats.hasher
 
-# CID
+# multiformats.CID
 
 Changes from `cids`:
 

package.json

@@ -1,11 +1,12 @@
 {
   "name": "multiformats",
   "version": "0.0.0-dev",
-  "description": "Interface for multihash, multicodec, multibase and CID.",
+  "description": "Interface for multihash, multicodec, multibase and CID",
   "main": "index.js",
   "type": "module",
   "scripts": {
     "build": "npm_config_yes=true npx ipjs@latest build --tests",
+    "build:vendor": "npx brrp -x varint > vendor/varint.js",
     "publish": "npm_config_yes=true npx ipjs@latest publish",
     "lint": "standard",
     "test:cjs": "npm run build && mocha dist/cjs/node-test/test-*.js && npm run test:cjs:browser",
@@ -71,8 +72,7 @@
   "dependencies": {
     "base-x": "^3.0.8",
     "buffer": "^5.6.0",
-    "cids": "^1.0.0",
-    "varint": "^5.0.0"
+    "cids": "^1.0.0"
   },
   "directories": {
     "test": "test"

src/bases/base.js

@@ -0,0 +1,205 @@
+// @ts-check
+
+/**
+ * @typedef {import('./interface').BaseEncoder} BaseEncoder
+ * @typedef {import('./interface').BaseDecoder} BaseDecoder
+ * @typedef {import('./interface').BaseCodec} BaseCodec
+ */
+
+/**
+ * @template T
+ * @typedef {import('./interface').Multibase<T>} Multibase
+ */
+/**
+ * @template T
+ * @typedef {import('./interface').MultibaseEncoder<T>} MultibaseEncoder
+ */
+
+/**
+ * Class represents both BaseEncoder and MultibaseEncoder meaning it
+ * can be used to encode to multibase or base encode without multibase
+ * prefix.
+ * @class
+ * @template {string} Base
+ * @template {string} Prefix
+ * @implements {MultibaseEncoder<Prefix>}
+ * @implements {BaseEncoder}
+ */
+class Encoder {
+  /**
+   * @param {Base} name
+   * @param {Prefix} prefix
+   * @param {(bytes:Uint8Array) => string} baseEncode
+   */
+  constructor (name, prefix, baseEncode) {
+    this.name = name
+    this.prefix = prefix
+    this.baseEncode = baseEncode
+  }
+
+  /**
+   * @param {Uint8Array} bytes
+   * @returns {Multibase<Prefix>}
+   */
+  encode (bytes) {
+    // @ts-ignore
+    return `${this.prefix}${this.baseEncode(bytes)}`
+  }
+}
+
+/**
+ * @template T
+ * @typedef {import('./interface').MultibaseDecoder<T>} MultibaseDecoder
+ */
+
+/**
+ * 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 {BaseDecoder}
+ */
+class Decoder {
+  /**
+   * @param {Base} name
+   * @param {Prefix} prefix
+   * @param {(text:string) => Uint8Array} baseDecode
+   */
+  constructor (name, prefix, baseDecode) {
+    this.name = name
+    this.prefix = prefix
+    this.baseDecode = baseDecode
+  }
+
+  /**
+   * @param {string} text
+   */
+  decode (text) {
+    switch (text[0]) {
+      case this.prefix: {
+        return this.baseDecode(text.slice(1))
+      }
+      default: {
+        throw Error(`${this.name} expects input starting with ${this.prefix} and can not decode "${text}"`)
+      }
+    }
+  }
+}
+
+/**
+ * @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}
+ */
+export class Codec {
+  /**
+   * @param {Base} name
+   * @param {Prefix} prefix
+   * @param {(bytes:Uint8Array) => string} baseEncode
+   * @param {(text:string) => Uint8Array} baseDecode
+   */
+  constructor (name, prefix, baseEncode, baseDecode) {
+    this.name = name
+    this.prefix = prefix
+    this.baseEncode = baseEncode
+    this.baseDecode = baseDecode
+    this.encoder = new Encoder(name, prefix, baseEncode)
+    this.decoder = new Decoder(name, prefix, baseDecode)
+  }
+
+  /**
+   * @param {Uint8Array} input
+   */
+  encode (input) {
+    return this.encoder.encode(input)
+  }
+
+  decode (input) {
+    return this.decoder.decode(input)
+  }
+}
+
+/**
+ * @template {string} Base
+ * @template {string} Prefix
+ * @param {Object} options
+ * @param {Base} options.name
+ * @param {Prefix} options.prefix
+ * @param {string} options.alphabet
+ * @param {(input:Uint8Array, alphabet:string) => string} options.encode
+ * @param {(input:string, alphabet:string) => Uint8Array} options.decode
+ */
+export const withAlphabet = ({ name, prefix, encode, decode, alphabet }) =>
+  from({
+    name,
+    prefix,
+    encode: input => encode(input, alphabet),
+    decode: input => {
+      for (const char of input) {
+        if (alphabet.indexOf(char) < 0) {
+          throw new Error(`invalid ${name} character`)
+        }
+      }
+      return decode(input, alphabet)
+    }
+  })
+
+/**
+ * @template {string} Base
+ * @template {string} Prefix
+ * @template Settings
+ *
+ * @param {Object} options
+ * @param {Base} options.name
+ * @param {Prefix} options.prefix
+ * @param {Settings} options.settings
+ * @param {(input:Uint8Array, settings:Settings) => string} options.encode
+ * @param {(input:string, settings:Settings) => Uint8Array} options.decode
+ */
+
+export const withSettings = ({ name, prefix, settings, encode, decode }) =>
+  from({
+    name,
+    prefix,
+    encode: (input) => encode(input, settings),
+    decode: (input) => decode(input, settings)
+  })
+
+/**
+ * @template {string} Base
+ * @template {string} Prefix
+ * @param {Object} options
+ * @param {Base} options.name
+ * @param {Prefix} options.prefix
+ * @param {(bytes:Uint8Array) => string} options.encode
+ * @param {(input:string) => Uint8Array} options.decode
+ * @returns {Codec<Base, Prefix>}
+ */
+export const from = ({ name, prefix, encode, decode }) =>
+  new Codec(name, prefix, encode, decode)
+
+export const notImplemented = ({ name, prefix }) =>
+  from({
+    name,
+    prefix,
+    encode: _ => {
+      throw Error(`No ${name} encoder implementation was provided`)
+    },
+    decode: _ => {
+      throw Error(`No ${name} decoder implemnetation was provided`)
+    }
+  })

src/bases/base16.js

@@ -1,17 +1,12 @@
-import { fromHex, toHex } from '../bytes.js'
+// @ts-check
 
-const create = function base16 (alphabet) {
-  return {
-    encode: input => toHex(input),
-    decode (input) {
-      for (const char of input) {
-        if (alphabet.indexOf(char) < 0) {
-          throw new Error('invalid base16 character')
-        }
-      }
-      return fromHex(input)
-    }
-  }
-}
+import { fromHex, toHex } from '../bytes.js'
+import { withAlphabet } from './base.js'
 
-export default { prefix: 'f', name: 'base16', ...create('0123456789abcdef') }
+export const base16 = withAlphabet({
+  prefix: 'f',
+  name: 'base16',
+  alphabet: '0123456789abcdef',
+  encode: toHex,
+  decode: fromHex
+})