refactor: async iterables (#567)

* refactor: async iterables

* fix: browser check not work for http client

Author: Alan Shaw

SPEC/BITSWAP.md

@@ -3,9 +3,6 @@
 * [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
@@ -16,23 +13,18 @@ Although not listed in the documentation, all the following APIs that actually r
 
 | 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.
@@ -51,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]
@@ -70,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/BLOCK.md

@@ -5,9 +5,6 @@
 * [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.
@@ -114,22 +111,32 @@ A great source of [examples][] can be found in the tests for this API.
 
 `options` is an Object that can contain the following properties:
 
-- force (boolean): Ignores nonexistent blocks.
-- quiet (boolean): write minimal output
+- `force` (boolean): Ignores nonexistent blocks.
+- `quiet` (boolean): write minimal output
 
 **Returns**
 
 | Type | Description |
 | -------- | -------- |
-| `Promise<Array>` | An array of objects containing hash and (potentially) error strings |
+| `AsyncIterable<Object>` | An async iterable that yields objects containing hash and (potentially) error strings |
 
-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.
+Each object yielded is of the form:
+
+```js
+{
+  hash: string,
+  error: string
+}
+```
+
+Note: If an error string is present for a given object, 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
-const result = await ipfs.block.rm(cid)
-console.log(result[0].hash)
+for await (const result of ipfs.block.rm(cid)) {
+  console.log(result.hash)
+}
 ```
 
 A great source of [examples][] can be found in the tests for this API.

SPEC/BOOTSTRAP.md

@@ -4,15 +4,12 @@
   the addresses of the bootstrap nodes. These are the trusted peers from
   which to learn about other peers in the network.
 
-> Only edit this list if you understand the risks of adding or removing nodes from this list.
+> Only edit this list if you understand the risks of adding or removing nodes
 
 * [bootstrap.add](#bootstrapadd)
 * [bootstrap.list](#bootstraplist)
 * [bootstrap.rm](#bootstraprm)
 
-### ⚠️ Note
-Although not listed in the documentation, all the following APIs that actually return a **promise** can also accept a **final callback** parameter.
-
 #### `bootstrap.add`
 
 > Add a peer address to the bootstrap list

SPEC/CONFIG.md

@@ -6,9 +6,6 @@
 * [config.profiles.list](#configprofileslist)
 * [config.profiles.apply](#configprofilesapply)
 
-### ⚠️ Note
-Although not listed in the documentation, all the following APIs that actually return a **promise** can also accept a **final callback** parameter.
-
 #### `config.get`
 
 > Returns the currently being used config. If the daemon is off, it returns the stored config.

SPEC/DAG.md

@@ -10,9 +10,6 @@ _Explore the DAG API through interactive coding challenges in our ProtoSchool tu
 - _[P2P data links with content addressing](https://proto.school/#/basics/) (beginner)_
 - _[Blogging on the Decentralized Web](https://proto.school/#/blog/) (intermediate)_
 
-### ⚠️ Note
-Although not listed in the documentation, all the following APIs that actually return a **promise** can also accept a **final callback** parameter.
-
 #### `dag.put`
 
 > Store an IPLD format node