refactor: return CIDs from core

Author: Alan Shaw

SPEC/BITSWAP.md

@@ -13,23 +13,18 @@
 
 | Type | Description |
 | -------- | -------- |
-| `Promise<Object>` | An object representing the wantlist |
-
-the returned object contains the following keys:
-
-- `Keys` An array of objects containing the following keys:
-    - `/` A string multihash
+| `Promise<CID[]>` | An array of [CID][cid]s currently in the wantlist |
 
 **Example:**
 
 ```JavaScript
 const list = await ipfs.bitswap.wantlist()
 console.log(list)
-// { Keys: [{ '/': 'QmHash' }] }
+// [ CID('QmHash') ]
 
 const list2 = await ipfs.bitswap.wantlist(peerId)
 console.log(list2)
-// { Keys: [{ '/': 'QmHash' }] }
+// [ CID('QmHash') ]
 ```
 
 A great source of [examples][] can be found in the tests for this API.
@@ -48,11 +43,11 @@ Note: `bitswap.stat` and `stats.bitswap` can be used interchangeably.
 | -------- | -------- |
 | `Promise<Object>` | An object that contains information about the bitswap agent |
 
-the returned object contains the following keys:
+The returned object contains the following keys:
 
 - `provideBufLen` is an integer.
-- `wantlist` (array of CIDs)
-- `peers` (array of peer IDs)
+- `wantlist` (array of [CID][cid]s)
+- `peers` (array of peer IDs as [CID][cid] instances)
 - `blocksReceived` is a [BigNumber Int][1]
 - `dataReceived` is a [BigNumber Int][1]
 - `blocksSent` is a [BigNumber Int][1]
@@ -67,21 +62,22 @@ const stats = await ipfs.bitswap.stat()
 console.log(stats)
 // {
 //   provideBufLen: 0,
-//   wantlist: [ { '/': 'QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM' } ],
+//   wantlist: [ CID('QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM') ],
 //   peers:
-//    [ 'QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM',
-//      'QmSoLSafTMBsPKadTEgaXctDQVcqN88CNLHXMkTNwMKPnu',
-//      'QmSoLer265NRgSp2LA3dPaeykiS1J6DifTC88f5uVQKNAd' ],
+//    [ CID('QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM'),
+//      CID('QmSoLSafTMBsPKadTEgaXctDQVcqN88CNLHXMkTNwMKPnu'),
+//      CID('QmSoLer265NRgSp2LA3dPaeykiS1J6DifTC88f5uVQKNAd') ],
 //   blocksReceived: 0,
 //   dataReceived: 0,
 //   blocksSent: 0,
 //   dataSent: 0,
 //   dupBlksReceived: 0,
-//  dupDataReceived: 0
+//   dupDataReceived: 0
 // }
 ```
 
 A great source of [examples][] can be found in the tests for this API.
 
 [1]: https://github.com/MikeMcl/bignumber.js/
 [examples]: https://github.com/ipfs/interface-ipfs-core/blob/master/src/bitswap
+[cid]: https://www.npmjs.com/package/cids

SPEC/PIN.md

@@ -14,19 +14,19 @@ Where:
 
 - `hash` is an IPFS multihash.
 - `options` is an object that can contain the following keys
-  - 'recursive' - Recursively pin the object linked. Type: bool. Default: `true`
+  - `recursive` - Recursively pin the object linked. Type: bool. Default: `true`
 
 **Returns**
 
 | Type | Description |
 | -------- | -------- |
-| `Promise<Array>` | An array of objects that represent the files that were pinned |
+| `Promise<{ cid: CID }>` | An array of objects that represent the files that were pinned |
 
 an array of objects is returned, each of the form:
 
 ```JavaScript
 {
-  hash: 'QmHash'
+  cid: CID('QmHash')
 }
 ```
 
@@ -36,7 +36,7 @@ an array of objects is returned, each of the form:
 const pinset = await ipfs.pin.add('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u')
 console.log(pinset)
 // Logs:
-// [ { hash: 'QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u' } ]
+// [ { cid: CID('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u') } ]
 ```
 
 A great source of [examples][] can be found in the tests for this API.
@@ -57,17 +57,17 @@ Where:
 
 | Type | Description |
 | -------- | -------- |
-| `AsyncIterable<{ hash: string, type: string }>` | An async iterable that yields currently pinned objects with `hash` and `type` properties. `hash` is a string CID of the pinned node, `type` is the pin type ("recursive", "direct" or "indirect") |
+| `AsyncIterable<{ cid: CID, type: string }>` | An async iterable that yields currently pinned objects with `cid` and `type` properties. `cid` is a [CID][cid] of the pinned node, `type` is the pin type ("recursive", "direct" or "indirect") |
 
 **Example:**
 
 ```JavaScript
-for await (const { hash, type } of ipfs.pin.ls()) {
-  console.log(pinset)
+for await (const { cid, type } of ipfs.pin.ls()) {
+  console.log({ cid, type })
 }
-// { hash: Qmc5XkteJdb337s7VwFBAGtiaoj2QCEzyxtNRy3iMudc3E, type: 'recursive' }
-// { hash: QmZbj5ruYneZb8FuR9wnLqJCpCXMQudhSdWhdhp5U1oPWJ, type: 'indirect' }
-// { hash: QmSo73bmN47gBxMNqbdV6rZ4KJiqaArqJ1nu5TvFhqqj1R, type: 'indirect' }
+// { cid: CID(Qmc5XkteJdb337s7VwFBAGtiaoj2QCEzyxtNRy3iMudc3E), type: 'recursive' }
+// { cid: CID(QmZbj5ruYneZb8FuR9wnLqJCpCXMQudhSdWhdhp5U1oPWJ), type: 'indirect' }
+// { cid: CID(QmSo73bmN47gBxMNqbdV6rZ4KJiqaArqJ1nu5TvFhqqj1R), type: 'indirect' }
 ```
 
 A great source of [examples][] can be found in the tests for this API.
@@ -87,14 +87,15 @@ Where:
 
 | Type | Description |
 | -------- | -------- |
-| `Promise<Array>` | An array of unpinned objects |
+| `Promise<{ cid: CID }>` | An array of unpinned objects |
 
 **Example:**
 
 ```JavaScript
-const pinset = await ipfs.pin.rm(hash)
+const pinset = await ipfs.pin.rm('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u')
 console.log(pinset)
 // prints the hashes that were unpinned
+// [ { cid: CID('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u') } ]
 ```
 
 A great source of [examples][] can be found in the tests for this API.

src/bitswap/utils.js

@@ -11,7 +11,7 @@ async function waitForWantlistKey (ipfs, key, opts = {}) {
   while (Date.now() < end) {
     const list = await ipfs.bitswap.wantlist(opts.peerId)
 
-    if (list && list.Keys && list.Keys.some(k => k['/'] === key)) {
+    if (list.some(cid => cid.toString() === key)) {
       return
     }
 

src/block/stat.js

@@ -27,10 +27,8 @@ module.exports = (common, options) => {
 
     it('should stat by CID', async () => {
       const cid = new CID(hash)
-
       const stats = await ipfs.block.stat(cid)
-
-      expect(stats).to.have.property('key')
+      expect(stats.cid.toString()).to.equal(cid.toString())
       expect(stats).to.have.property('size')
     })
 

src/cat.js

@@ -54,7 +54,7 @@ module.exports = (common, options) => {
 
       const res = await all(ipfs.add(input, { cidVersion: 0 }))
 
-      const cidv0 = new CID(res[0].hash)
+      const cidv0 = res[0].cid
       expect(cidv0.version).to.equal(0)
 
       const cidv1 = cidv0.toV1()
@@ -68,7 +68,7 @@ module.exports = (common, options) => {
 
       const res = await all(ipfs.add(input, { cidVersion: 1, rawLeaves: false }))
 
-      const cidv1 = new CID(res[0].hash)
+      const cidv1 = res[0].cid
       expect(cidv1.version).to.equal(1)
 
       const cidv0 = cidv1.toV0()
@@ -98,7 +98,7 @@ module.exports = (common, options) => {
       const file = await filesAdded.find((f) => f.path === 'a')
       expect(file).to.exist()
 
-      const data = await concat(ipfs.cat(`/ipfs/${file.hash}/testfile.txt`))
+      const data = await concat(ipfs.cat(`/ipfs/${file.cid}/testfile.txt`))
 
       expect(data.toString()).to.contain('Plz add me!')
     })
@@ -111,7 +111,7 @@ module.exports = (common, options) => {
       const file = filesAdded.find((f) => f.path === 'a')
       expect(file).to.exist()
 
-      const data = await concat(ipfs.cat(`/ipfs/${file.hash}/b/testfile.txt`))
+      const data = await concat(ipfs.cat(`/ipfs/${file.cid}/b/testfile.txt`))
       expect(data.toString()).to.contain('Plz add me!')
     })
 
@@ -142,7 +142,7 @@ module.exports = (common, options) => {
 
       const dir = files[0]
 
-      const err = await expect(concat(ipfs.cat(dir.hash))).to.be.rejected()
+      const err = await expect(concat(ipfs.cat(dir.cid))).to.be.rejected()
       expect(err.message).to.contain('this dag node is a directory')
     })
 

src/dag/get.js

@@ -5,7 +5,6 @@ const dagPB = require('ipld-dag-pb')
 const DAGNode = dagPB.DAGNode
 const dagCBOR = require('ipld-dag-cbor')
 const Unixfs = require('ipfs-unixfs')
-const CID = require('cids')
 const all = require('it-all')
 const { getDescribe, getIt, expect } = require('../utils/mocha')
 
@@ -157,7 +156,7 @@ module.exports = (common, options) => {
 
       const res = await all(ipfs.add(input, { cidVersion: 1, rawLeaves: false }))
 
-      const cidv1 = new CID(res[0].hash)
+      const cidv1 = res[0].cid
       expect(cidv1.version).to.equal(1)
 
       const cidv0 = cidv1.toV0()

src/dht/provide.js

@@ -30,7 +30,7 @@ module.exports = (common, options) => {
     it('should provide local CID', async () => {
       const res = await all(ipfs.add(Buffer.from('test')))
 
-      await all(ipfs.dht.provide(new CID(res[0].hash)))
+      await all(ipfs.dht.provide(res[0].cid))
     })
 
     it('should not provide if block not found locally', () => {
@@ -48,18 +48,12 @@ module.exports = (common, options) => {
         { content: Buffer.from('t1') }
       ]))
 
-      await all(ipfs.dht.provide([
-        new CID(res[0].hash),
-        new CID(res[1].hash)
-      ]))
+      await all(ipfs.dht.provide(res.map(f => f.cid)))
     })
 
     it('should provide a CIDv1', async () => {
       const res = await all(ipfs.add(Buffer.from('test'), { cidVersion: 1 }))
-
-      const cid = new CID(res[0].hash)
-
-      await all(ipfs.dht.provide(cid))
+      await all(ipfs.dht.provide(res[0].cid))
     })
 
     it('should error on non CID arg', () => {

src/files/cp.js

@@ -53,11 +53,9 @@ module.exports = (common, options) => {
     })
 
     it('should copy from outside of mfs', async () => {
-      const [{
-        hash
-      }] = await all(ipfs.add(fixtures.smallFile.data))
+      const [{ cid }] = await all(ipfs.add(fixtures.smallFile.data))
       const testFilePath = `/${hat()}`
-      await ipfs.files.cp(`/ipfs/${hash}`, testFilePath)
+      await ipfs.files.cp(`/ipfs/${cid}`, testFilePath)
       const testFileData = await concat(ipfs.files.read(testFilePath))
       expect(testFileData.slice()).to.eql(fixtures.smallFile.data)
     })

src/files/read.js

@@ -3,6 +3,7 @@
 
 const hat = require('hat')
 const concat = require('it-concat')
+const all = require('it-all')
 const { fixtures } = require('../utils')
 const { getDescribe, getIt, expect } = require('../utils/mocha')
 
@@ -45,10 +46,8 @@ module.exports = (common, options) => {
     })
 
     it('should read from outside of mfs', async () => {
-      const [{
-        hash
-      }] = await ipfs.add(fixtures.smallFile.data)
-      const testFileData = await concat(ipfs.files.read(`/ipfs/${hash}`))
+      const [{ cid }] = await all(ipfs.add(fixtures.smallFile.data))
+      const testFileData = await concat(ipfs.files.read(`/ipfs/${cid}`))
       expect(testFileData.slice()).to.eql(fixtures.smallFile.data)
     })
   })

src/get.js

@@ -50,7 +50,7 @@ module.exports = (common, options) => {
 
       const res = await all(ipfs.add(input, { cidVersion: 0 }))
 
-      const cidv0 = new CID(res[0].hash)
+      const cidv0 = res[0].cid
       expect(cidv0.version).to.equal(0)
 
       const cidv1 = cidv0.toV1()
@@ -64,7 +64,7 @@ module.exports = (common, options) => {
 
       const res = await all(ipfs.add(input, { cidVersion: 1, rawLeaves: false }))
 
-      const cidv1 = new CID(res[0].hash)
+      const cidv1 = res[0].cid
       expect(cidv1.version).to.equal(1)
 
       const cidv0 = cidv1.toV0()
@@ -105,7 +105,7 @@ module.exports = (common, options) => {
       const root = res[res.length - 1]
 
       expect(root.path).to.equal('test-folder')
-      expect(root.hash).to.equal(fixtures.directory.cid)
+      expect(root.cid.toString()).to.equal(fixtures.directory.cid)
 
       let files = await all((async function * () {
         for await (let { path, content } of ipfs.get(fixtures.directory.cid)) {
@@ -156,7 +156,7 @@ module.exports = (common, options) => {
 
       filesAdded.forEach(async (file) => {
         if (file.path === 'a') {
-          const files = await all(ipfs.get(`/ipfs/${file.hash}/testfile.txt`))
+          const files = await all(ipfs.get(`/ipfs/${file.cid}/testfile.txt`))
           expect(files).to.be.length(1)
           expect((await concat(files[0].content)).toString()).to.contain('Plz add me!')
         }
@@ -173,7 +173,7 @@ module.exports = (common, options) => {
 
       filesAdded.forEach(async (file) => {
         if (file.path === 'a') {
-          const files = await all(ipfs.get(`/ipfs/${file.hash}/testfile.txt`))
+          const files = await all(ipfs.get(`/ipfs/${file.cid}/testfile.txt`))
           expect(files).to.be.length(1)
           expect((await concat(files[0].content)).toString()).to.contain('Plz add me!')
         }

src/miscellaneous/resolve.js

@@ -30,27 +30,27 @@ module.exports = (common, options) => {
     it('should resolve an IPFS hash', async () => {
       const content = loadFixture('test/fixtures/testfile.txt', 'interface-ipfs-core')
 
-      const [{ hash }] = await all(ipfs.add(content))
-      const path = await ipfs.resolve(`/ipfs/${hash}`)
-      expect(path).to.equal(`/ipfs/${hash}`)
+      const [{ cid }] = await all(ipfs.add(content))
+      const path = await ipfs.resolve(`/ipfs/${cid}`)
+      expect(path).to.equal(`/ipfs/${cid}`)
     })
 
     it('should resolve an IPFS hash and return a base64url encoded CID in path', async () => {
-      const [{ hash }] = await all(ipfs.add(Buffer.from('base64url encoded')))
-      const path = await ipfs.resolve(`/ipfs/${hash}`, { cidBase: 'base64url' })
-      const [,, cid] = path.split('/')
+      const [{ cid }] = await all(ipfs.add(Buffer.from('base64url encoded')))
+      const path = await ipfs.resolve(`/ipfs/${cid}`, { cidBase: 'base64url' })
+      const [,, cidStr] = path.split('/')
 
-      expect(multibase.isEncoded(cid)).to.equal('base64url')
+      expect(multibase.isEncoded(cidStr)).to.equal('base64url')
     })
 
     // Test resolve turns /ipfs/QmRootHash/path/to/file into /ipfs/QmFileHash
     it('should resolve an IPFS path link', async () => {
       const path = 'path/to/testfile.txt'
       const content = loadFixture('test/fixtures/testfile.txt', 'interface-ipfs-core')
-      const [{ hash: fileHash }, , , { hash: rootHash }] = await all(ipfs.add([{ path, content }], { wrapWithDirectory: true }))
-      const resolve = await ipfs.resolve(`/ipfs/${rootHash}/${path}`)
+      const [{ cid: fileCid }, , , { cid: rootCid }] = await all(ipfs.add([{ path, content }], { wrapWithDirectory: true }))
+      const resolve = await ipfs.resolve(`/ipfs/${rootCid}/${path}`)
 
-      expect(resolve).to.equal(`/ipfs/${fileHash}`)
+      expect(resolve).to.equal(`/ipfs/${fileCid}`)
     })
 
     it('should resolve up to the last node', async () => {

src/object/get.js

@@ -138,7 +138,7 @@ module.exports = (common, options) => {
         content: data
       }))
 
-      const node = await ipfs.object.get(result[0].hash)
+      const node = await ipfs.object.get(result[0].cid)
       const meta = UnixFs.unmarshal(node.Data)
 
       expect(meta.fileSize()).to.equal(data.length)