cids - npm Package Compare versions

Comparing version 0.5.8 to 0.6.0

CHANGELOG.md

@@ -0,1 +1,31 @@
+<a name="0.6.0"></a>
+# [0.6.0](https://github.com/multiformats/js-cid/compare/v0.5.8...v0.6.0) (2019-04-08)
+
+
+### Features
+
+* add flow typedefs ([1cf9740](https://github.com/multiformats/js-cid/commit/1cf9740))
+* cache string represntation ([537f604](https://github.com/multiformats/js-cid/commit/537f604))
+* preserve base when constructed from a string ([2e597b9](https://github.com/multiformats/js-cid/commit/2e597b9))
+
+
+### BREAKING CHANGES
+
+* previously base was not preserved and all CIDs would
+be normalised to base58btc when asking for their string representation.
+
+The default will change to base32 in https://github.com/multiformats/js-cid/pull/73/files
+
+The idea behind this change is that we shouldnt lose information when
+the user passes us a base encoded string, but keep it and use it as
+the default base so toString returns the same string they provided.
+
+I'd like this as a fix for ipld explorer, which currently forces all
+CIDs into base58btc, seee: https://github.com/ipfs-shipyard/ipfs-webui/issues/999
+
+License: MIT
+Signed-off-by: Oli Evans <[e-mail]>
+
+
+
 <a name="0.5.8"></a>
@@ -2,0 +32,0 @@ ## [0.5.8](https://github.com/multiformats/js-cid/compare/v0.5.7...v0.5.8) (2019-03-14)

package.json

 {
   "name": "cids",
-  "version": "0.5.8",
+  "version": "0.6.0",
   "description": "CID Implementation in JavaScript",
@@ -59,4 +59,6 @@ "leadMaintainer": "Volker Mische <[e-mail]>",
     "Friedel Ziegelmayer <[e-mail]>",
+    "Irakli Gozalishvili <[e-mail]>",
     "Mikeal Rogers <[e-mail]>",
     "Mitar <[e-mail]>",
+    "Oli Evans <[e-mail]>",
     "Real Harry <[e-mail]>",
@@ -63,0 +65,0 @@ "Richard Littauer <[e-mail]>",

README.md

@@ -57,3 +57,3 @@ # js-cid
 
-Basic usage is quite simple.
+You can create an instance from a CID string or CID Buffer
 
@@ -63,12 +63,42 @@ ```js
 
-const cid = new CID(1, 'dag-pb', multihash)
+const cid = new CID('zdj7WkRPAX9o9nb9zPbXzwG7JEs78uyhwbUs8JSUayB98DWWY')
+
+cid.version       // 1
+cid.codec         // 'dag-pb'
+cid.multibaseName // 'base58btc'
+cid.toString()
+// 'zdj7WkRPAX9o9nb9zPbXzwG7JEs78uyhwbUs8JSUayB98DWWY'
 ```
 
-If you have a base encoded string for a multihash you can also create
-an instance from the encoded string.
+or by specifying the [cid version](https://github.com/multiformats/cid#versions), [multicodec name](https://github.com/multiformats/multicodec/blob/master/table.csv) and [multihash](https://github.com/multiformats/multihash):
 
 ```js
-const cid = new CID(base58Multihash)
+const CID = require('cids')
+const multihashing = require('multihashing-async')
+
+multihashing(Buffer.from('OMG!'), 'sha2-256', (err, hash) => {
+  const cid = new CID(1, 'dag-pb', hash)
+  console.log(cid.toString())
+  // zdj7WkRPAX9o9nb9zPbXzwG7JEs78uyhwbUs8JSUayB98DWWY
+})
 ```
 
+The string form of CIDs currently defaults to `base58btc` flavour. (This is [soon to change to `base32`](https://github.com/ipfs/ipfs/issues/337). When creating a new instance you can optionally specify the default multibase to use when calling `toBaseEncodedString()` or `toString()`
+
+
+```js
+const cid = new CID(1, 'raw', hash, 'base32')
+console.log(cid.toString())
+// bafybeig6xv5nwphfmvcnektpnojts33jqcuam7bmye2pb54adnrtccjlsu
+```
+
+If you construct an instance from a valid CID string, the base you provided will be preserved as the default.
+
+```js
+const cid = new CID('bafkreigh2akiscaildcqabsyg3dfr6chu3fgpregiymsck7e7aqa4s52zy')
+cid.toString()
+// bafkreigh2akiscaildcqabsyg3dfr6chu3fgpregiymsck7e7aqa4s52zy
+```
+
+
 ## API
@@ -85,8 +115,8 @@
 
-Validates the different components (version, codec, multihash) of the CID
+Validates the different components (version, codec, multihash, multibaseName) of the CID
 instance. Returns true if valid, false if not valid.
 
-### new CID(version, codec, multihash)
+### new CID(version, codec, multihash, [multibaseName])
 
-`version` must be either 0 or 1.
+`version` must be [either 0 or 1](https://github.com/multiformats/cid#versions).
 
@@ -97,2 +127,4 @@ `codec` must be a string of a valid [registered codec](https://github.com/multiformats/multicodec/blob/master/table.csv).
 
+`multibaseName` optional string. Must be a valid [multibase](https://github.com/multiformats/multibase/blob/master/multibase.csv) name. Default is `base58btc`.
+
 ### new CID(baseEncodedString)
@@ -119,2 +151,6 @@
 
+#### cid.multibaseName
+
+Property containing the default base to use when calling `.toString`
+
 #### cid.buffer
@@ -139,6 +175,10 @@
 
-#### cid.toBaseEncodedString(base='base58btc')
+#### cid.toBaseEncodedString(base=this.multibaseName)
 
-Returns a base encodec string of the CID. Defaults to `base58btc`.
+Returns a base encodec string of the CID. Defaults to the base encoding in `this.multibaseName`
 
+#### cid.toString(base=this.multibaseName)
+
+Shorthand for `cid.toBaseEncodedString` described above.
+
 #### cid.equals(cid)
@@ -145,0 +185,0 @@

src/cid-util.js

@@ -27,2 +27,11 @@ 'use strict'
 
+    if (other.version === 0) {
+      if (other.codec !== 'dag-pb') {
+        return `codec must be 'dag-pb' for CIDv0`
+      }
+      if (other.multibaseName !== 'base58btc') {
+        return `multibaseName must be 'base58btc' for CIDv0`
+      }
+    }
+
     if (!Buffer.isBuffer(other.multihash)) {
@@ -29,0 +38,0 @@ return 'multihash must be a Buffer'

src/index.js

@@ -15,3 +15,2 @@ 'use strict'
  * @param {Buffer} multihash
- *
  */
@@ -39,12 +38,12 @@
    * ```
-   * if (str)
+   * if (cid)
+   *   -> create a copy
+   * else if (str)
    *   if (1st char is on multibase table) -> CID String
    *   else -> bs58 encoded multihash
    * else if (Buffer)
-   *   if (0 or 1) -> CID
+   *   if (1st byte is 0 or 1) -> CID
    *   else -> multihash
    * else if (Number)
    *   -> construct CID by parts
-   *
-   * ..if only JS had traits..
    * ```
@@ -55,6 +54,6 @@ *
    * @param {Buffer} [multihash]
+   * @param {string} [multibaseName]
    *
    * @example
-   *
-   * new CID(<version>, <codec>, <multihash>)
+   * new CID(<version>, <codec>, <multihash>, <multibaseName>)
    * new CID(<cidStr>)
@@ -65,42 +64,58 @@ * new CID(<cid.buffer>)
    * new CID(<cid>)
-   *
    */
-  constructor (version, codec, multihash) {
+  constructor (version, codec, multihash, multibaseName = 'base58btc') {
     if (module.exports.isCID(version)) {
-      let cid = version
+      // version is an exising CID instance
+      const cid = version
       this.version = cid.version
       this.codec = cid.codec
       this.multihash = Buffer.from(cid.multihash)
+      this.multibaseName = cid.multibaseName
       return
     }
+
     if (typeof version === 'string') {
-      if (multibase.isEncoded(version)) { // CID String (encoded with multibase)
+      // e.g. 'base32' or false
+      const baseName = multibase.isEncoded(version)
+      if (baseName) {
+        // version is a CID String encoded with multibase, so v1
         const cid = multibase.decode(version)
-        version = parseInt(cid.slice(0, 1).toString('hex'), 16)
-        codec = multicodec.getCodec(cid.slice(1))
-        multihash = multicodec.rmPrefix(cid.slice(1))
-      } else { // bs58 string encoded multihash
-        codec = 'dag-pb'
-        multihash = mh.fromB58String(version)
-        version = 0
+        this.version = parseInt(cid.slice(0, 1).toString('hex'), 16)
+        this.codec = multicodec.getCodec(cid.slice(1))
+        this.multihash = multicodec.rmPrefix(cid.slice(1))
+        this.multibaseName = baseName
+      } else {
+        // version is a base58btc string multihash, so v0
+        this.version = 0
+        this.codec = 'dag-pb'
+        this.multihash = mh.fromB58String(version)
+        this.multibaseName = 'base58btc'
       }
-    } else if (Buffer.isBuffer(version)) {
+      CID.validateCID(this)
+      Object.defineProperty(this, 'string', { value: version })
+      return
+    }
+
+    if (Buffer.isBuffer(version)) {
       const firstByte = version.slice(0, 1)
       const v = parseInt(firstByte.toString('hex'), 16)
-      if (v === 0 || v === 1) { // CID
+      if (v === 0 || v === 1) {
+        // version is a CID buffer
         const cid = version
-        version = v
-        codec = multicodec.getCodec(cid.slice(1))
-        multihash = multicodec.rmPrefix(cid.slice(1))
-      } else { // multihash
-        codec = 'dag-pb'
-        multihash = version
-        version = 0
+        this.version = v
+        this.codec = multicodec.getCodec(cid.slice(1))
+        this.multihash = multicodec.rmPrefix(cid.slice(1))
+        this.multibaseName = (v === 0) ? 'base58btc' : multibaseName
+      } else {
+        // version is a raw multihash buffer, so v0
+        this.version = 0
+        this.codec = 'dag-pb'
+        this.multihash = version
+        this.multibaseName = 'base58btc'
       }
+      CID.validateCID(this)
+      return
     }
 
-    /**
-     * @type {string}
-     */
-    this.codec = codec
+    // otherwise, assemble the CID from the parameters
 
@@ -113,2 +128,7 @@ /**
     /**
+     * @type {string}
+     */
+    this.codec = codec
+
+    /**
      * @type {Buffer}
@@ -118,2 +138,7 @@ */
 
+    /**
+     * @type {string}
+     */
+    this.multibaseName = multibaseName
+
     CID.validateCID(this)
@@ -202,20 +227,25 @@ }
    *
-   * @param {string} [base='base58btc'] - Base encoding to use.
+   * @param {string} [base=this.multibaseName] - Base encoding to use.
    * @returns {string}
    */
-  toBaseEncodedString (base) {
-    base = base || 'base58btc'
-
-    switch (this.version) {
-      case 0: {
-        if (base !== 'base58btc') {
-          throw new Error('not supported with CIDv0, to support different bases, please migrate the instance do CIDv1, you can do that through cid.toV1()')
-        }
-        return mh.toB58String(this.multihash)
+  toBaseEncodedString (base = this.multibaseName) {
+    if (this.string && base === this.multibaseName) {
+      return this.string
+    }
+    let str = null
+    if (this.version === 0) {
+      if (base !== 'base58btc') {
+        throw new Error('not supported with CIDv0, to support different bases, please migrate the instance do CIDv1, you can do that through cid.toV1()')
       }
-      case 1:
-        return multibase.encode(base, this.buffer).toString()
-      default:
-        throw new Error('Unsupported version')
+      str = mh.toB58String(this.multihash)
+    } else if (this.version === 1) {
+      str = multibase.encode(base, this.buffer).toString()
+    } else {
+      throw new Error('unsupported version')
     }
+    if (base === this.multibaseName) {
+      // cache the string value
+      Object.defineProperty(this, 'string', { value: str })
+    }
+    return str
   }
@@ -222,0 +252,0 @@

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

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

Total package byte prevSize

796927

increased by1.69%

Number of package files

15

increased by15.38%

Lines of code

6073

increased by1.23%

Number of lines in readme file

196

increased by25.64%

No dependency changes