multibase - npm Package Compare versions

Comparing version 0.2.0 to 0.3.0

package.json

 {
   "name": "multibase",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "JavaScript implementation of the multibase specification",
-  "main": "lib/index.js",
-  "jsnext:main": "src/index.js",
+  "main": "src/index.js",
   "scripts": {
@@ -13,5 +12,6 @@ "test:node": "aegir-test node",
     "test": "aegir-test",
-    "release": "aegir-release",
-    "release-minor": "aegir-release --type minor",
-    "release-major": "aegir-release --type major",
+    "docs": "aegir-docs",
+    "release": "aegir-release --docs",
+    "release-minor": "aegir-release --type minor --docs",
+    "release-major": "aegir-release --type major --docs",
     "coverage": "aegir-coverage",
@@ -37,5 +37,5 @@ "coverage-publish": "aegir-coverage publish"
   "devDependencies": {
-    "aegir": "^6.0.1",
+    "aegir": "^9.3.0",
     "chai": "^3.5.0",
-    "pre-commit": "^1.1.3"
+    "pre-commit": "^1.2.2"
   },
@@ -49,7 +49,11 @@ "author": "David Dias <[e-mail]>",
   "dependencies": {
-    "bs58": "^3.0.0"
+    "base-x": "2.0.2"
   },
   "contributors": [
-    "David Dias <[e-mail]>"
+    "David Dias <[e-mail]>",
+    "Friedel Ziegelmayer <[e-mail]>",
+    "Richard Littauer <[e-mail]>",
+    "npm-to-cdn-bot (by Forbes Lindesay) <[e-mail]>",
+    "theobat <[e-mail]>"
   ]
 }

README.md

@@ -5,13 +5,67 @@ js-multibase
 [![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://ipn.io)
-[![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23ipfs)
+[![](https://img.shields.io/badge/project-multiformats-blue.svg?style=flat-square)](https://github.com/multiformats/multiformats)
+[![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](https://webchat.freenode.net/?channels=%23ipfs)
 [![Coverage Status](https://coveralls.io/repos/github/multiformats/js-multibase/badge.svg?branch=master)](https://coveralls.io/github/multiformats/js-multibase?branch=master)
-[![Travis CI](https://travis-ci.org/multiformats/js-multibase.svg?branch=master)](https://travis-ci.org/multiformats/js-multibase)
+[![Travis CI](https://img.shields.io/travis/multiformats/js-multibase.svg?style=flat-square&branch=master)](https://travis-ci.org/multiformats/js-multibase)
 [![Circle CI](https://circleci.com/gh/multiformats/js-multibase.svg?style=svg)](https://circleci.com/gh/multiformats/js-multibase)
 [![Dependency Status](https://david-dm.org/multiformats/js-multibase.svg?style=flat-square)](https://david-dm.org/multiformats/js-multibase)
 [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/feross/standard)
+[![](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
 
-> JavaScript Implementation of the [multibase](https://github.com/multiformats/multibase) specification
+> JavaScript implementation of the [multibase](https://github.com/multiformats/multibase) specification
 
-## Example
+## Table of Contents
 
+- [Install](#install)
+  - [In Node.js through npm](#in-nodejs-through-npm)
+  - [Browser: Browserify, Webpack, other bundlers](#browser-browserify-webpack-other-bundlers)
+  - [In the Browser through `<script>` tag](#in-the-browser-through-script-tag)
+    - [Gotchas](#gotchas)
+- [Usage](#usage)
+  - [Example](#example)
+- [API](#api)
+  - [`multibase` - Prefixes an encoded buffer with its multibase code](#multibase---prefixes-an-encoded-buffer-with-its-multibase-code)
+  - [`multibase.encode` - Encodes a buffer into one of the supported encodings, prefixing it with the multibase code](#multibaseencode---encodes-a-buffer-into-one-of-the-supported-encodings-prefixing-it-with-the-multibase-code)
+  - [`multibase.decode` - Decodes a buffer or string](#multibasedecode---decodes-a-buffer-or-string)
+  - [`multibase.isEncoded` - Checks if buffer or string is encoded](#multibaseisencoded---checks-if-buffer-or-string-is-encoded)
+  - [Supported Encodings, see `src/constants.js`](#supported-encodings-see-srcconstantsjs)
+- [Architecture and Encoding/Decoding](#architecture-and-encodingdecoding)
+- [Adding additional bases](#adding-additional-bases)
+- [License](#license)
+
+## Install
+
+### In Node.js through npm
+
+```bash
+> npm install --save multibase
+```
+
+### Browser: Browserify, Webpack, other bundlers
+
+The code published to npm that gets loaded on require is in fact an ES5 transpiled version with the right shims added. This means that you can require it and use with your favourite bundler without having to adjust asset management process.
+
+```js
+const multibase = require('multiubase')
+```
+
+
+### In the Browser through `<script>` tag
+
+Loading this module through a script tag will make the ```Multibase``` obj available in the global namespace.
+
+```html
+<script src="https://unpkg.com/multibase/dist/index.min.js"></script>
+<!-- OR -->
+<script src="https://unpkg.com/multibase/dist/index.js"></script>
+```
+
+#### Gotchas
+
+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.
+
+## Usage
+
+### Example
+
 ```JavaScript
@@ -56,36 +110,88 @@ const multibase = require('multibase')
 
-## Installation
+## Architecture and Encoding/Decoding
 
-### In Node.js through npm
-
-```bash
-> npm install --save multibase
+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.
 
-### Browser: Browserify, Webpack, other bundlers
+The ```alphabet``` is the **ordered** set of defined symbols for a given base.
 
-The code published to npm that gets loaded on require is in fact an ES5 transpiled version with the right shims added. This means that you can require it and use with your favourite bundler without having to adjust asset management process.
+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 multibase = require('multiubase')
+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)*
 
-### In the Browser through `<script>` tag
+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
+  })
 
-Loading this module through a script tag will make the ```Multibase``` obj available in the global namespace.
-
-```html
-<script src="https://npmcdn.com/multibase/dist/index.min.js"></script>
-<!-- OR -->
-<script src="https://npmcdn.com/multibase/dist/index.js"></script>
+  it('constants indexed by code', () => {
+    const codes = constants.codes
+    expect(Object.keys(codes).length).to.equal(constants-count)
+  })
+})
 ```
 
-#### Gotchas
+- 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']
+    ```
 
-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.
+## Maintainers
 
+Captain: [@diasdavid](https://github.com/diasdavid)
 
+## Contribute
+
+Contributions welcome. Please check out [the issues](https://github.com/multiformats/js-multibase/issues).
+
+Check out our [contributing document](https://github.com/multiformats/multiformats/blob/master/contributing.md) for more information on how we work, and about contributing in general. Please be aware that all interactions related to multiformats are subject to the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).
+
+Small note: If editing the README, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification.
+
 ## License
 
-[MIT] © Protocol Labs Inc.
+[MIT](LICENSE) © 2016 Protocol Labs Inc.

src/constants.js

 '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
@@ -21,3 +28,3 @@ }, {})
 const codes = constants.reduce((prev, tupple) => {
-  prev[tupple[1]] = tupple[0]
+  prev[tupple[1]] = names[tupple[0]]
   return prev
@@ -24,0 +31,0 @@ }, {})

src/index.js

@@ -0,3 +1,136 @@
+/**
+ * Implementation of the [multibase](https://github.com/multiformats/multibase) specification.
+ * @module Multibase
+ */
 'use strict'
 
-exports = module.exports = require('./multibase')
+const constants = require('./constants')
+
+exports = module.exports = multibase
+exports.encode = encode
+exports.decode = decode
+exports.isEncoded = isEncoded
+
+const errNotSupported = new Error('Unsupported encoding')
+
+/**
+ * Create a new buffer with the multibase varint+code.
+ *
+ * @param {string|number} nameOrCode - The multibase name or code number.
+ * @param {Buffer} buf - The data to be prefixed with multibase.
+ * @memberof Multibase
+ * @returns {Buffer}
+ */
+function multibase (nameOrCode, buf) {
+  if (!buf) {
+    throw new Error('requires an encoded buffer')
+  }
+  const base = getBase(nameOrCode)
+  const codeBuf = new Buffer(base.code)
+
+  const name = base.name
+  validEncode(name, buf)
+  return Buffer.concat([codeBuf, buf])
+}
+
+/**
+ * Encode data with the specified base and add the multibase prefix.
+ *
+ * @param {string|number} nameOrCode - The multibase name or code number.
+ * @param {Buffer} buf - The data to be encoded.
+ * @returns {Buffer}
+ * @memberof Multibase
+ */
+function encode (nameOrCode, buf) {
+  const base = getBase(nameOrCode)
+  const name = base.name
+
+  return multibase(name, new Buffer(base.encode(buf)))
+}
+
+/**
+ *
+ * Takes 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
+ *
+ * @param {Buffer|string} bufOrString
+ * @returns {Object} result
+ * @returns {string} result.base
+ * @returns {Buffer} result.data
+ * @memberof Multibase
+ *
+ */
+function decode (bufOrString) {
+  if (Buffer.isBuffer(bufOrString)) {
+    bufOrString = bufOrString.toString()
+  }
+
+  const code = bufOrString.substring(0, 1)
+  bufOrString = bufOrString.substring(1, bufOrString.length)
+
+  if (typeof bufOrString === 'string') {
+    bufOrString = new Buffer(bufOrString)
+  }
+
+  const base = getBase(code)
+
+  const decodeObject = {
+    base: base.name,
+    data: new Buffer(base.decode(bufOrString.toString()))
+  }
+  return decodeObject.data
+}
+
+/**
+ * Is the given data multibase encoded?
+ *
+ * @param {Buffer|string} bufOrString
+ * @returns {boolean}
+ * @memberof Multibase
+ */
+function isEncoded (bufOrString) {
+  if (Buffer.isBuffer(bufOrString)) {
+    bufOrString = bufOrString.toString()
+  }
+
+  const code = bufOrString.substring(0, 1)
+  try {
+    const base = getBase(code)
+    return base.name
+  } catch (err) {
+    return false
+  }
+}
+
+/**
+ * @param {string} name
+ * @param {Buffer} buf
+ * @private
+ * @returns {undefined}
+ */
+function validEncode (name, buf) {
+  const base = getBase(name)
+  base.decode(buf.toString())
+}
+
+function getBase (nameOrCode) {
+  let base
+
+  if (constants.names[nameOrCode]) {
+    base = constants.names[nameOrCode]
+  } else if (constants.codes[nameOrCode]) {
+    base = constants.codes[nameOrCode]
+  } else {
+    throw errNotSupported
+  }
+
+  if (!base.isImplemented()) {
+    throw new Error('Base ' + nameOrCode + ' is not implemented yet')
+  }
+
+  return base
+}

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Number of lines in readme file

196

increased by117.78%

Worsened metrics

Total package byte prevSize

202152

decreased by-78.43%

Number of package files

13

decreased by-13.33%

Lines of code

2363

decreased by-76.83%

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Addedbase-x@2.0.2

• + Addedbase-x@2.0.2(transitive)

• - Removedbs58@^3.0.0

• - Removedbase-x@1.1.0(transitive)

• - Removedbs58@3.1.0(transitive)