feat: support multiple bases

Author: theobat

README.md

@@ -83,6 +83,77 @@ Loading this module through a script tag will make the ```Multibase``` obj avail
 
 You will need to use Node.js `Buffer` API compatible, if you are running inside the browser, you can access it by `multibase.Buffer` or you can load Feross's [Buffer](https://github.com/feross/buffer) module.
 
+## Architecture and Encoding/Decoding
+
+Multibase package defines all the supported bases and the location of their implementation in the constants.js file. A base is a class with a name, a code, an implementation and an alphabet.
+```js
+class Base {
+  constructor (name, code, implementation, alphabet) {
+    //...
+  }
+  // ...
+}
+```
+The ```implementation``` is an object where the encoding/decoding functions are implemented. It must take one argument, (the alphabet) following the [base-x module](https://github.com/cryptocoinjs/base-x) architecture.
+
+The ```alphabet``` is the **ordered** set of defined symbols for a given base.
+
+The idea behind this is that several bases may have implementations from different locations/modules so it's useful to have an object (and a summary) of all of them in one location (hence the constants.js).
+
+All the supported bases are currently using the npm [base-x](https://github.com/cryptocoinjs/base-x) module as their implementation. It is using bitwise maipulation to go from one base to another, so this module does not support padding at the moment.
+
+## Adding additional bases
+
+If the base you are looking for is not supported yet in js-multibase and you know a good encoding/decoding algorithm, you can add support for this base easily by editing the constants.js file
+(**you'll need to create an issue about that beforehand since a code and a canonical name have to be defined**):
+
+```js
+const baseX = require('base-x')
+//const newPackage = require('your-package-name')
+
+const constants = [
+  ['base1', '1', '', '1'],
+  ['base2', '0', baseX, '01'],
+  ['base8', '7', baseX, '01234567'],
+  // ... [ 'your-base-name', 'code-to-be-defined', newPackage, 'alphabet']
+]
+```
+The required package defines the implementation of the encoding/decoding process. **It must comply by these rules** :
+- `encode` and `decode` functions with to-be-encoded buffer as the only expected argument
+- the require call use the `alphabet` given as an argument for the encoding/decoding process
+
+*If no package is specified (such as for base1 in the above example, it means the base is not implemented yet)*
+
+Adding a new base requires the tests to be updated. Test files to be updated are :
+- constants.spec.js
+```js
+describe('constants', () => {
+  it('constants indexed by name', () => {
+    const names = constants.names
+    expect(Object.keys(names).length).to.equal(constants-count) // currently 12
+  })
+
+  it('constants indexed by code', () => {
+    const codes = constants.codes
+    expect(Object.keys(codes).length).to.equal(constants-count)
+  })
+})
+```
+
+- multibase.spec.js
+    - if the base is implemented
+    ```js
+    const supportedBases = [
+      ['base2', 'yes mani !', '01111001011001010111001100100000011011010110000101101110011010010010000000100001'],
+      ['base8', 'yes mani !', '7171312714403326055632220041'],
+      ['base10', 'yes mani !', '9573277761329450583662625'],
+      // ... ['your-base-name', 'what you want', 'expected output']
+    ```
+    - if the base is not implemented yet
+    ```js
+    const supportedBases = [
+      // ... ['your-base-name']
+    ```
 
 ## License
 

package.json

@@ -44,9 +44,10 @@
   },
   "homepage": "https://github.com/multiformats/js-multibase#readme",
   "dependencies": {
-    "bs58": "^3.0.0"
+    "base-x": "1.0.4"
   },
   "contributors": [
-    "David Dias <daviddias.p@gmail.com>"
+    "David Dias <daviddias.p@gmail.com>",
+    "theobat <theophile.batoz@gmail.com>"
   ]
-}
+}

src/Base.js

@@ -0,0 +1,27 @@
+'use strict'
+
+class Base {
+  constructor (name, code, implementation, alphabet) {
+    this.name = name
+    this.code = code
+    this.alphabet = alphabet
+    if (implementation && alphabet) {
+      this.engine = implementation(alphabet)
+    }
+  }
+
+  encode (stringOrBuffer) {
+    return this.engine.encode(stringOrBuffer)
+  }
+
+  decode (stringOrBuffer) {
+    return this.engine.decode(stringOrBuffer)
+  }
+
+  isImplemented () {
+    return this.engine
+  }
+
+}
+
+module.exports = Base

src/constants.js

@@ -1,24 +1,30 @@
 'use strict'
 
+const Base = require('./Base.js')
+const baseX = require('base-x')
+// name, code, implementation, alphabet
 const constants = [
-  ['base1', '1'],
-  ['base2', '0'],
-  ['base8', '7'],
-  ['base10', '9'],
-  ['base16', 'f'],
-  ['base58flickr', 'Z'],
-  ['base58btc', 'z'],
-  ['base64', 'y'],
-  ['base64url', 'Y']
+  ['base1', '1', '', '1'],
+  ['base2', '0', baseX, '01'],
+  ['base8', '7', baseX, '01234567'],
+  ['base10', '9', baseX, '0123456789'],
+  ['base16', 'f', baseX, '0123456789abcdef'],
+  ['base32hex', 'v', baseX, '0123456789abcdefghijklmnopqrstuv'],
+  ['base32', 'b', baseX, 'abcdefghijklmnopqrstuvwxyz234567'],
+  ['base32z', 'h', baseX, 'ybndrfg8ejkmcpqxot1uwisza345h769'],
+  ['base58flickr', 'Z', baseX, '123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ'],
+  ['base58btc', 'z', baseX, '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'],
+  ['base64', 'm', baseX, 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'],
+  ['base64url', 'u', baseX, 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_']
 ]
 
 const names = constants.reduce((prev, tupple) => {
-  prev[tupple[0]] = tupple[1]
+  prev[tupple[0]] = new Base(tupple[0], tupple[1], tupple[2], tupple[3])
   return prev
 }, {})
 
 const codes = constants.reduce((prev, tupple) => {
-  prev[tupple[1]] = tupple[0]
+  prev[tupple[1]] = names[tupple[0]]
   return prev
 }, {})
 

src/multibase.js

@@ -1,7 +1,6 @@
 'use strict'
 
 const constants = require('./constants')
-const bs58 = require('bs58')
 
 exports = module.exports = multibase
 exports.encode = encode
@@ -15,32 +14,27 @@ function multibase (nameOrCode, buf) {
   if (!buf) {
     throw new Error('requires an encoded buffer')
   }
-  const code = getCode(nameOrCode)
-  const codeBuf = new Buffer(code)
+  const base = getBase(nameOrCode)
+  const codeBuf = new Buffer(base.code)
 
-  const name = getName(nameOrCode)
+  const name = base.name
   validEncode(name, buf)
   return Buffer.concat([codeBuf, buf])
 }
 
 function encode (nameOrCode, buf) {
-  const name = getName(nameOrCode)
+  const base = getBase(nameOrCode)
+  const name = base.name
 
-  let encode
-
-  switch (name) {
-    case 'base58btc': {
-      encode = (buf) => { return new Buffer(bs58.encode(buf)) }
-    } break
-    default: throw errNotSupported
-  }
-
-  return multibase(name, encode(buf))
+  return multibase(name, new Buffer(base.encode(buf)))
 }
 
 // receives a buffer or string encoded with multibase header
 // decodes it and returns an object with the decoded buffer
 // and the encoded type { base: <name>, data: <buffer> }
+
+// from @theobat : This is not what the multibase.spec.js test is waiting for,
+// hence the return decodeObject.data
 function decode (bufOrString) {
   if (Buffer.isBuffer(bufOrString)) {
     bufOrString = bufOrString.toString()
@@ -53,16 +47,13 @@ function decode (bufOrString) {
     bufOrString = new Buffer(bufOrString)
   }
 
-  let decode
+  const base = getBase(code)
 
-  switch (code) {
-    case 'z': {
-      decode = (buf) => { return new Buffer(bs58.decode(buf.toString())) }
-    } break
-    default: throw errNotSupported
+  const decodeObject = {
+    base: base.name,
+    data: new Buffer(base.decode(bufOrString.toString()))
   }
-
-  return decode(bufOrString)
+  return decodeObject.data
 }
 
 function isEncoded (bufOrString) {
@@ -72,56 +63,32 @@ function isEncoded (bufOrString) {
 
   const code = bufOrString.substring(0, 1)
   try {
-    const name = getName(code)
-    return name
+    const base = getBase(code)
+    return base.name
   } catch (err) {
     return false
   }
 }
 
-function validNameOrCode (nameOrCode) {
-  const err = new Error('Unsupported encoding')
-
-  if (!constants.names[nameOrCode] &&
-      !constants.codes[nameOrCode]) {
-    throw err
-  }
-}
-
 function validEncode (name, buf) {
-  let decode
-
-  switch (name) {
-    case 'base58btc': {
-      decode = bs58.decode
-      buf = buf.toString() // bs58 only operates in strings bs58 strings
-    } break
-    default: throw errNotSupported
-  }
-
-  decode(buf)
+  const base = getBase(name)
+  base.decode(buf.toString())
 }
 
-function getCode (nameOrCode) {
-  validNameOrCode(nameOrCode)
-
-  let code = nameOrCode
+function getBase (nameOrCode) {
+  let base
 
   if (constants.names[nameOrCode]) {
-    code = constants.names[nameOrCode]
+    base = constants.names[nameOrCode]
+  } else if (constants.codes[nameOrCode]) {
+    base = constants.codes[nameOrCode]
+  } else {
+    throw errNotSupported
   }
 
-  return code
-}
-
-function getName (nameOrCode) {
-  validNameOrCode(nameOrCode)
-
-  let name = nameOrCode
-
-  if (constants.codes[nameOrCode]) {
-    name = constants.codes[nameOrCode]
+  if (!base.isImplemented()) {
+    throw new Error('Base ' + nameOrCode + ' is not implemented yet')
   }
 
-  return name
+  return base
 }

test/constants.spec.js

@@ -7,11 +7,11 @@ const constants = require('../src/constants.js')
 describe('constants', () => {
   it('constants indexed by name', () => {
     const names = constants.names
-    expect(Object.keys(names).length).to.equal(9)
+    expect(Object.keys(names).length).to.equal(12)
   })
 
   it('constants indexed by code', () => {
     const codes = constants.codes
-    expect(Object.keys(codes).length).to.equal(9)
+    expect(Object.keys(codes).length).to.equal(12)
   })
 })