refactor: rename functions to explicit names

Breaking refactorings:
- Renamed getCodec to getNameFromData
- Renamed getName to getNameFromCode
- Renamed getNumber to getCodeFromName
- Renamed getCode to getCodeFromData
- Renamed getCodeVarint to getVarintFromName
- Renamed getVarint to getVarintFromCode
- getVarintFromCode returns Uint8Array instead of Array

For backwards compatibility, all old names were kept as alias,
and getVarint returns a regular Array as it did before. This does
not break compatibility. They are all marked as @deprecated.

License: MIT
Signed-off-by: Henrique Dias <[email protected]>

Author: hacdias

README.md

@@ -45,7 +45,7 @@ console.log(multicodec.DAG_CBOR)
 // 113
 
 // To get the string representation of a codec, e.g. for error messages:
-console.log(multicodec.print[113])
+console.log(multicodec.getNameFromCode(113))
 // dag-cbor
 ```
 

src/index.js

@@ -38,6 +38,7 @@ function addPrefix (multicodecStrOrCode, data) {
       throw new Error('multicodec not recognized')
     }
   }
+
   return uint8ArrayConcat([prefix, data], prefix.length + data.length)
 }
 
@@ -53,27 +54,27 @@ function rmPrefix (data) {
 }
 
 /**
- * Get the codec of the prefixed data.
+ * Get the codec name of the prefixed data.
  *
  * @param {Uint8Array} prefixedData
  * @returns {CodecName}
  */
-function getCodec (prefixedData) {
+function getNameFromData (prefixedData) {
   const code = varint.decode(prefixedData)
-  const codecName = codeToName[code]
-  if (codecName === undefined) {
-    throw new Error(`Code ${code} not found`)
+  const name = codeToName[code]
+  if (name === undefined) {
+    throw new Error(`Code "${code}" not found`)
   }
-  return codecName
+  return name
 }
 
 /**
- * Get the name of the codec (human friendly).
+ * Get the codec name from a code.
  *
  * @param {CodecCode} codec
- * @returns {CodecName|undefined}
+ * @returns {CodecName}
  */
-function getName (codec) {
+function getNameFromCode (codec) {
   return codeToName[codec]
 }
 
@@ -83,10 +84,10 @@ function getName (codec) {
  * @param {CodecName} name
  * @returns {CodecCode}
  */
-function getNumber (name) {
+function getCodeFromName (name) {
   const code = nameToCode[name]
   if (code === undefined) {
-    throw new Error('Codec `' + name + '` not found')
+    throw new Error(`Codec "${name}" not found`)
   }
   return code
 }
@@ -97,20 +98,20 @@ function getNumber (name) {
  * @param {Uint8Array} prefixedData
  * @returns {CodecCode}
  */
-function getCode (prefixedData) {
+function getCodeFromData (prefixedData) {
   return varint.decode(prefixedData)
 }
 
 /**
  * Get the code as varint of a codec name.
  *
- * @param {CodecName} codecName
+ * @param {CodecName} name
  * @returns {Uint8Array}
  */
-function getCodeVarint (codecName) {
-  const code = nameToVarint[codecName]
+function getVarintFromName (name) {
+  const code = nameToVarint[name]
   if (code === undefined) {
-    throw new Error('Codec `' + codecName + '` not found')
+    throw new Error(`Codec "${name}" not found`)
   }
   return code
 }
@@ -119,25 +120,96 @@ function getCodeVarint (codecName) {
  * Get the varint of a code.
  *
  * @param {CodecCode} code
+ * @returns {Uint8Array}
+ */
+function getVarintFromCode (code) {
+  return util.varintEncode(code)
+}
+
+/**
+ * Get the codec name of the prefixed data.
+ *
+ * @deprecated use getNameFromData instead.
+ * @param {Uint8Array} prefixedData
+ * @returns {CodecName}
+ */
+function getCodec (prefixedData) {
+  return getNameFromData(prefixedData)
+}
+
+/**
+ * Get the codec name from a code.
+ *
+ * @deprecated use getNameFromCode instead.
+ * @param {CodecCode} codec
+ * @returns {CodecName}
+ */
+function getName (codec) {
+  return getNameFromCode(codec)
+}
+
+/**
+ * Get the code of the codec
+ *
+ * @deprecated use getCodeFromName instead.
+ * @param {CodecName} name
+ * @returns {CodecCode}
+ */
+function getNumber (name) {
+  return getCodeFromName(name)
+}
+
+/**
+ * Get the code of the prefixed data.
+ *
+ * @deprecated use getCodeFromData instead.
+ * @param {Uint8Array} prefixedData
+ * @returns {CodecCode}
+ */
+function getCode (prefixedData) {
+  return getCodeFromData(prefixedData)
+}
+
+/**
+ * Get the code as varint of a codec name.
+ *
+ * @deprecated use getVarintFromName instead.
+ * @param {CodecName} name
+ * @returns {Uint8Array}
+ */
+function getCodeVarint (name) {
+  return getVarintFromName(name)
+}
+
+/**
+ * Get the varint of a code.
+ *
+ * @deprecated use getVarintFromCode instead.
+ * @param {CodecCode} code
  * @returns {Array.<number>}
  */
 function getVarint (code) {
-  return varint.encode(code)
+  return Array.from(getVarintFromCode(code))
 }
 
 module.exports = {
   addPrefix,
   rmPrefix,
+  getNameFromData,
+  getNameFromCode,
+  getCodeFromName,
+  getCodeFromData,
+  getVarintFromName,
+  getVarintFromCode,
+  // Deprecated
   getCodec,
   getName,
   getNumber,
   getCode,
   getCodeVarint,
   getVarint,
-
   // Make the constants top-level constants
   ...constantToCode,
-
   // Export the maps
   nameToVarint,
   nameToCode,

test/multicodec.spec.js

@@ -13,56 +13,56 @@ describe('multicodec', () => {
   it('add prefix through multicodec (string)', () => {
     const buf = uint8ArrayFromString('hey')
     const prefixedBuf = multicodec.addPrefix('protobuf', buf)
-    expect(multicodec.getCodec(prefixedBuf)).to.equal('protobuf')
+    expect(multicodec.getNameFromData(prefixedBuf)).to.equal('protobuf')
     expect(buf).to.eql(multicodec.rmPrefix(prefixedBuf))
   })
 
   it('add prefix through code (code)', () => {
     const buf = uint8ArrayFromString('hey')
     const prefixedBuf = multicodec.addPrefix(uint8ArrayFromString('70', 'base16'), buf)
-    expect(multicodec.getCodec(prefixedBuf)).to.equal('dag-pb')
+    expect(multicodec.getNameFromData(prefixedBuf)).to.equal('dag-pb')
     expect(buf).to.eql(multicodec.rmPrefix(prefixedBuf))
   })
 
   it('add multibyte varint prefix (eth-block) through multicodec (string)', () => {
     const buf = uint8ArrayFromString('hey')
     const prefixedBuf = multicodec.addPrefix('eth-block', buf)
-    expect(multicodec.getCodec(prefixedBuf)).to.equal('eth-block')
+    expect(multicodec.getNameFromData(prefixedBuf)).to.equal('eth-block')
     expect(buf).to.eql(multicodec.rmPrefix(prefixedBuf))
   })
 
   it('returns code via codec name', () => {
-    const code = multicodec.getCodeVarint('keccak-256')
+    const code = multicodec.getVarintFromName('keccak-256')
     expect(code).to.eql(uint8ArrayFromString('1b', 'base16'))
   })
 
   it('returns code from prefixed data', () => {
     const buf = uint8ArrayFromString('hey')
     const prefixedBuf = multicodec.addPrefix('dag-cbor', buf)
-    const code = multicodec.getCode(prefixedBuf)
+    const code = multicodec.getCodeFromData(prefixedBuf)
     expect(code).to.eql(multicodec.DAG_CBOR)
   })
 
   it('returns varint from code', () => {
-    const code = multicodec.getVarint(multicodec.KECCAK_256)
-    expect(code).to.eql([0x1b])
+    const code = multicodec.getVarintFromCode(multicodec.KECCAK_256)
+    expect(code).to.eql(Uint8Array.from([0x1b]))
   })
 
   it('returns the codec name from code', () => {
-    expect(multicodec.getName(144)).to.eql('eth-block')
-    expect(multicodec.getName(112)).to.eql('dag-pb')
-    expect(multicodec.getName(0xb201)).to.eql('blake2b-8')
+    expect(multicodec.getNameFromCode(144)).to.eql('eth-block')
+    expect(multicodec.getNameFromCode(112)).to.eql('dag-pb')
+    expect(multicodec.getNameFromCode(0xb201)).to.eql('blake2b-8')
   })
 
   it('returns the codec number from name', () => {
-    expect(multicodec.getNumber('eth-block')).to.eql(144)
-    expect(multicodec.getNumber('dag-pb')).to.eql(112)
-    expect(multicodec.getNumber('blake2b-8')).to.eql(0xb201)
+    expect(multicodec.getCodeFromName('eth-block')).to.eql(144)
+    expect(multicodec.getCodeFromName('dag-pb')).to.eql(112)
+    expect(multicodec.getCodeFromName('blake2b-8')).to.eql(0xb201)
   })
 
   it('returns all codec numbers from names', () => {
     for (const name in nameToCode) {
-      expect(multicodec.getNumber(/** @type {CodecName} */(name))).to.eql(nameToCode[name])
+      expect(multicodec.getCodeFromName(/** @type {CodecName} */(name))).to.eql(nameToCode[name])
     }
   })
 
@@ -73,40 +73,49 @@ describe('multicodec', () => {
   })
 
   it('returns the name from codec number', () => {
-    expect(multicodec.getName(144)).to.eql('eth-block')
-    expect(multicodec.getName(112)).to.eql('dag-pb')
-    expect(multicodec.getName(0x0111)).to.eql('udp')
-    expect(multicodec.getName(0xb201)).to.eql('blake2b-8')
-
-    expect(multicodec.getName(multicodec.ETH_BLOCK)).to.eql('eth-block')
-    expect(multicodec.getName(multicodec.DAG_PB)).to.eql('dag-pb')
-    expect(multicodec.getName(multicodec.UDP)).to.eql('udp')
-    expect(multicodec.getName(multicodec.BLAKE2B_8)).to.eql('blake2b-8')
+    expect(multicodec.getNameFromCode(144)).to.eql('eth-block')
+    expect(multicodec.getNameFromCode(112)).to.eql('dag-pb')
+    expect(multicodec.getNameFromCode(0x0111)).to.eql('udp')
+    expect(multicodec.getNameFromCode(0xb201)).to.eql('blake2b-8')
+
+    expect(multicodec.getNameFromCode(multicodec.ETH_BLOCK)).to.eql('eth-block')
+    expect(multicodec.getNameFromCode(multicodec.DAG_PB)).to.eql('dag-pb')
+    expect(multicodec.getNameFromCode(multicodec.UDP)).to.eql('udp')
+    expect(multicodec.getNameFromCode(multicodec.BLAKE2B_8)).to.eql('blake2b-8')
   })
 
   it('returns p2p when 0x01a5 is used', () => {
     // `ipfs` and `p2p` are assigned to `0x01a5`, `ipfs` is deprecated
-    expect(multicodec.getName(0x01a5)).to.eql('p2p')
+    expect(multicodec.getNameFromCode(0x01a5)).to.eql('p2p')
   })
 
-  it('throws error on unknown codec name when getting the code', () => {
+  it('throws error on unknown codec name when getting the varint from name', () => {
     expect(() => {
       // @ts-expect-error
-      multicodec.getCodeVarint('this-codec-doesnt-exist')
+      multicodec.getVarintFromName('this-codec-doesnt-exist')
     }).to.throw(
-      'Codec `this-codec-doesnt-exist` not found'
+      'Codec "this-codec-doesnt-exist" not found'
     )
   })
 
-  it('throws error on unknown codec name when getting the codec', () => {
+  it('throws error on unknown codec name when getting the code from name', () => {
+    expect(() => {
+      // @ts-expect-error
+      multicodec.getCodeFromName('this-codec-doesnt-exist')
+    }).to.throw(
+      'Codec "this-codec-doesnt-exist" not found'
+    )
+  })
+
+  it('throws error on unknown codec name when getting the name from the code', () => {
     const code = uint8ArrayFromString('ffee', 'base16')
 
     const buf = uint8ArrayFromString('hey')
     const prefixedBuf = multicodec.addPrefix(code, buf)
     expect(() => {
-      multicodec.getCodec(prefixedBuf)
+      multicodec.getNameFromData(prefixedBuf)
     }).to.throw(
-      'Code 65518 not found'
+      'Code "65518" not found'
     )
   })
 })