chore: update examples in docs to async/await

README.md

@@ -71,20 +71,21 @@ Install `interface-ipfs-core` as one of the dependencies of your project and as
 
 ```js
 const tests = require('interface-ipfs-core')
+const nodes = []
 
 // Create common setup and teardown
 const createCommon = () => ({
   // Do some setup common to all tests
-  setup (cb) {
-    // Must call back with an "IPFS factory", an object with a `spawnNode` method
-    cb(null, {
-      // Use ipfsd-ctl or other to spawn an IPFS node for testing
-      spawnNode (cb) { /* ... */ }
-    })
+  setup: async () => {
+    // Use ipfsd-ctl or other to spawn an IPFS node for testing
+    const node = await spawnNode()
+    nodes.push(node)
+
+    return node.api
   },
   // Dispose of nodes created by the IPFS factory and any other teardown
-  teardown (cb) {
-    cb()
+  teardown: () => {
+    return Promise.all(nodes.map(n => n.stop()))
   }
 })
 

SPEC/BITSWAP.md

@@ -3,40 +3,55 @@
 * [bitswap.wantlist](#bitswapwantlist)
 * [bitswap.stat](#bitswapstat)
 
+### ⚠️ Note
+Although not listed in the documentation, all the following APIs that actually return a **promise** can also accept a **final callback** parameter.
+
 ### `bitswap.wantlist`
 
 > Returns the wantlist, optionally filtered by peer ID
 
-#### `ipfs.bitswap.wantlist([peerId], [callback])`
+#### `ipfs.bitswap.wantlist([peerId])`
+
+**Returns**
+
+| Type | Description |
+| -------- | -------- |
+| `Promise<Object>` | An object representing the wantlist |
 
-`callback` must follow `function (err, list) {}` signature, where `err` is an error if the operation was not successful. `list` is an Object containing the following keys:
+the returned object contains the following keys:
 
 - `Keys` An array of objects containing the following keys:
     - `/` A string multihash
 
-If no `callback` is passed, a promise is returned.
-
 **Example:**
 
 ```JavaScript
-ipfs.bitswap.wantlist((err, list) => console.log(list))
-
+const list = await ipfs.bitswap.wantlist()
+console.log(list)
 // { Keys: [{ '/': 'QmHash' }] }
 
-ipfs.bitswap.wantlist(peerId, (err, list) => console.log(list))
-
+const list2 = await ipfs.bitswap.wantlist(peerId)
+console.log(list2)
 // { Keys: [{ '/': 'QmHash' }] }
 ```
 
+A great source of [examples][] can be found in the tests for this API.
+
 #### `bitswap.stat`
 
 > Show diagnostic information on the bitswap agent.
 
-##### `ipfs.bitswap.stat([callback])`
+##### `ipfs.bitswap.stat()`
 
 Note: `bitswap.stat` and `stats.bitswap` can be used interchangeably.
 
-`callback` must follow `function (err, stats) {}` signature, where `err` is an error if the operation was not successful. `stats` is an Object containing the following keys:
+**Returns**
+
+| Type | Description |
+| -------- | -------- |
+| `Promise<Object>` | An object that contains information about the bitswap agent |
+
+the returned object contains the following keys:
 
 - `provideBufLen` is an integer.
 - `wantlist` (array of CIDs)
@@ -48,14 +63,13 @@ Note: `bitswap.stat` and `stats.bitswap` can be used interchangeably.
 - `dupBlksReceived` is a [BigNumber Int][1]
 - `dupDataReceived` is a [BigNumber Int][1]
 
-If no `callback` is passed, a promise is returned.
-
 **Example:**
 
 ```JavaScript
-ipfs.bitswap.stat((err, stats) => console.log(stats))
-
-// { provideBufLen: 0,
+const stats = await ipfs.bitswap.stat()
+console.log(stats)
+// {
+//   provideBufLen: 0,
 //   wantlist: [ { '/': 'QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM' } ],
 //   peers:
 //    [ 'QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM',
@@ -66,7 +80,11 @@ ipfs.bitswap.stat((err, stats) => console.log(stats))
 //   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

SPEC/BLOCK.md

@@ -5,36 +5,32 @@
 * [block.rm](#blockrm)
 * [block.stat](#blockstat)
 
+### ⚠️ Note
+Although not listed in the documentation, all the following APIs that actually return a **promise** can also accept a **final callback** parameter.
+
 #### `block.get`
 
 > Get a raw IPFS block.
 
-##### `ipfs.block.get(cid, [options], [callback])`
+##### `ipfs.block.get(cid, [options])`
 
 `cid` is a [cid][cid] which can be passed as:
 
 - Buffer, the raw Buffer of the cid
 - CID, a CID instance
 - String, the base58 encoded version of the multihash
 
-`callback` must follow `function (err, block) {}` signature, where `err` is an error if the operation was not successful and `block` is a [Block][block] type object, containing both the data and the hash of the block.
+**Returns**
 
-If no `callback` is passed, a promise is returned.
+| Type | Description |
+| -------- | -------- |
+| `Promise<Block>` | A [Block][block] type object, containing both the data and the hash of the block |
 
 **Example:**
 
 ```JavaScript
-ipfs.block.get(cid, function (err, block) {
-  if (err) {
-    throw err
-  }
-  block.key((err, key) => {
-    if (err) {
-      throw err
-    }
-    console.log(key, block.data)
-  })
-})
+const block = await ipfs.block.get(cid)
+console.log(block.data)
 ```
 
 A great source of [examples][] can be found in the tests for this API.
@@ -43,7 +39,7 @@ A great source of [examples][] can be found in the tests for this API.
 
 > Stores input as an IPFS block.
 
-##### `ipfs.block.put(block, [options], [callback])`
+##### `ipfs.block.put(block, [options])`
 
 Where `block` can be:
 
@@ -65,44 +61,40 @@ if no options are passed, it defaults to `{ format: 'dag-pb', mhtype: 'sha2-256'
 
 **Note:** If you pass a [`Block`][block] instance as the block parameter, you don't need to pass options, as the block instance will carry the CID value as a property.
 
-`callback` has the signature `function (err, block) {}`, where `err` is an error if the operation was not successful and `block` is a [Block][block] type object, containing both the data and the hash of the block.
+**Returns**
 
-If no `callback` is passed, a promise is returned.
+| Type | Description |
+| -------- | -------- |
+| `Promise<Block>` | A [Block][block] type object, containing both the data and the hash of the block |
 
 **Example:**
 
 ```JavaScript
 // Defaults
 const buf = new Buffer('a serialized object')
 
-ipfs.block.put(buf, (err, block) => {
-  if (err) { throw err }
-  // Block has been stored
+const block = await ipfs.block.put(buf)
 
-  console.log(block.data.toString())
-  // Logs:
-  // a serialized object
-  console.log(block.cid.toBaseEncodedString())
-  // Logs:
-  // the CID of the object
-})
+console.log(block.data.toString())
+// Logs:
+// a serialized object
+console.log(block.cid.toString())
+// Logs:
+// the CID of the object
 
 // With custom format and hashtype through CID
 const CID = require('cids')
 const buf = new Buffer('another serialized object')
 const cid = new CID(1, 'dag-pb', multihash)
 
-ipfs.block.put(blob, cid, (err, block) => {
-  if (err) { throw err }
-  // Block has been stored
-
-  console.log(block.data.toString())
-  // Logs:
-  // a serialized object
-  console.log(block.cid.toBaseEncodedString())
-  // Logs:
-  // the CID of the object
-})
+const block = await ipfs.block.put(blob, cid)
+
+console.log(block.data.toString())
+// Logs:
+// a serialized object
+console.log(block.cid.toString())
+// Logs:
+// the CID of the object
 ```
 
 A great source of [examples][] can be found in the tests for this API.
@@ -111,7 +103,7 @@ A great source of [examples][] can be found in the tests for this API.
 
 > Remove one or more IPFS block(s).
 
-##### `ipfs.block.rm(cid, [options], [callback])`
+##### `ipfs.block.rm(cid, [options])`
 
 `cid` is a [cid][cid] which can be passed as:
 
@@ -125,21 +117,19 @@ A great source of [examples][] can be found in the tests for this API.
 - force (boolean): Ignores nonexistent blocks.
 - quiet (boolean): write minimal output
 
-`callback` must follow `function (err, result) {}` signature, where `err` is an error if the operation was not successful and `result` is a list of objects, containing hash and (potentially) error strings.
+**Returns**
 
-If an error string is present for a given object in `result`, the block with that hash was not removed and the string will contain the reason why, for example if the block was pinned.
+| Type | Description |
+| -------- | -------- |
+| `Promise<Array>` | An array of objects containing hash and (potentially) error strings |
 
-If no `callback` is passed, a promise is returned.
+Note: If an error string is present for a given object in the returned array, the block with that hash was not removed and the string will contain the reason why, for example if the block was pinned.
 
 **Example:**
 
 ```JavaScript
-ipfs.block.rm(cid, function (err, result) {
-  if (err) {
-    throw err
-  }
-  console.log(result[0].hash)
-})
+const result = await ipfs.block.rm(cid)
+console.log(result[0].hash)
 ```
 
 A great source of [examples][] can be found in the tests for this API.
@@ -148,15 +138,21 @@ A great source of [examples][] can be found in the tests for this API.
 
 > Print information of a raw IPFS block.
 
-##### `ipfs.block.stat(cid, [callback])`
+##### `ipfs.block.stat(cid)`
 
 `cid` is a [cid][cid] which can be passed as:
 
 - `Buffer`, the raw Buffer of the multihash (or of and encoded version)
 - `String`, the toString version of the multihash (or of an encoded version)
 - CID, a CID instance
 
-`callback` must follow the signature `function (err, stats) {}`, where `err` is an error if the operation was not successful and `stats` is an object with the format:`
+**Returns**
+
+| Type | Description |
+| -------- | -------- |
+| `Promise<Object>` | An object containing the block's info |
+
+the returned object has the following keys:
 
 ```JavaScript
 {
@@ -165,25 +161,19 @@ A great source of [examples][] can be found in the tests for this API.
 }
 ```
 
-If no `callback` is passed, a promise is returned.
-
 **Example:**
 
 ```JavaScript
 const multihashStr = 'QmQULBtTjNcMwMr4VMNknnVv3RpytrLSdgpvMcTnfNhrBJ'
 const cid = new CID(multihashStr)
 
-ipfs.block.stat(cid, (err, stats) => {
-  if (err) {
-    throw err
-  }
-  console.log(stats)
-  // Logs:
-  // {
-  //   key: QmQULBtTjNcMwMr4VMNknnVv3RpytrLSdgpvMcTnfNhrBJ,
-  /    size: 3739
-  // }
-})
+const stats = await ipfs.block.stat(cid)
+console.log(stats)
+// Logs:
+// {
+//   key: QmQULBtTjNcMwMr4VMNknnVv3RpytrLSdgpvMcTnfNhrBJ,
+//    size: 3739
+// }
 ```
 
 A great source of [examples][] can be found in the tests for this API.