refactor: async iterables

ipfs-inactive · Dec 17, 2019 · 186d007 · 186d007
1 parent d8b65ef
commit 186d007
Show file tree

Hide file tree

Showing 97 changed files with 1,243 additions and 3,366 deletions.
diff --git a/SPEC/BITSWAP.md b/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

diff --git a/SPEC/BLOCK.md b/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.

diff --git a/SPEC/BOOTSTRAP.md b/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

diff --git a/SPEC/CONFIG.md b/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.

diff --git a/SPEC/DAG.md b/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

diff --git a/SPEC/DHT.md b/SPEC/DHT.md
@@ -7,79 +7,80 @@
 * [dht.put](#dhtput)
 * [dht.query](#dhtquery)
 
-### ⚠️ Note
-Although not listed in the documentation, all the following APIs that actually return a **promise** can also accept a **final callback** parameter.
-
 #### `dht.findPeer`
 
-> Retrieve the Peer Info of a reachable node in the network.
+> Find the multiaddresses associated with a Peer ID
 
 ##### `ipfs.dht.findPeer(peerId)`
 
-Where `peerId` is a IPFS/libp2p Id from [PeerId](https://github.com/libp2p/js-peer-id) type.
+Where `peerId` is a Peer ID in `String`, [`CID`](https://github.com/multiformats/js-cid) or [`PeerId`](https://github.com/libp2p/js-peer-id) format.
 
 **Returns**
 
 | Type | Description |
 | -------- | -------- |
-| `Promise<PeerInfo>` | An object type [`PeerInfo`](https://github.com/libp2p/js-peer-info) |
+| `Promise<{ id: CID, addrs: Multiaddr[] }>` | A promise that resolves to an object with `id` and `addrs`. `id` is a [`CID`](https://github.com/multiformats/js-cid) - the peer's ID and `addrs` is an array of [Multiaddr](https://github.com/multiformats/js-multiaddr/) - addresses for the peer. |
 
 **Example:**
 
 ```JavaScript
-var id = PeerId.create()
-
-const peerInfo = await ipfs.dht.findPeer(id)
-// peerInfo will contain the multiaddrs of that peer
-const id = peerInfo.id
-const addrs = peerInfo.multiaddrs
+const info = await ipfs.dht.findPeer('QmcZf59bWwK5XFi76CZX8cbJ4BhTzzA3gU1ZjYZcYW3dwt')
+
+console.log(info.id.toString())
+/*
+QmcZf59bWwK5XFi76CZX8cbJ4BhTzzA3gU1ZjYZcYW3dwt
+*/
+
+info.addrs.forEach(addr => console.log(addr.toString()))
+/*
+/ip4/147.75.94.115/udp/4001/quic
+/ip6/2604:1380:3000:1f00::1/udp/4001/quic
+/dnsaddr/bootstrap.libp2p.io
+/ip6/2604:1380:3000:1f00::1/tcp/4001
+/ip4/147.75.94.115/tcp/4001
+*/
 ```
 
 A great source of [examples][] can be found in the tests for this API.
 
 #### `dht.findProvs`
 
-> Retrieve the providers for content that is addressed by an hash.
+> Find peers that can provide a specific value, given a CID.
 
-##### `ipfs.dht.findProvs(hash, [options])`
+##### `ipfs.dht.findProvs(cid, [options])`
 
-Where `hash` is a multihash.
+Where `cid` is a CID as a `String`, `Buffer` or [`CID`](https://github.com/multiformats/js-cid) instance.
 
-`options` an optional object with the following properties
-  - `timeout` - a maximum timeout in milliseconds
-  - `maxNumProviders` - a maximum number of providers to find
+`options` an optional object with the following properties:
+  - `numProviders` - the number of providers to find. Default: 20
+
+Note that if `options.numProviders` are not found an error will be thrown.
 
 **Returns**
 
 | Type | Description |
 | -------- | -------- |
-| `Promise<Array>` | An array of type [`PeerInfo`](https://github.com/libp2p/js-peer-info) |
-
-each entry of the returned array is composed by the peerId, as well as an array with its adresses.
+| `AsyncIterable<{ id: CID, addrs: Multiaddr[] }>` | A async iterable that yields objects with `id` and `addrs`. `id` is a [`CID`](https://github.com/multiformats/js-cid) - the peer's ID and `addrs` is an array of [Multiaddr](https://github.com/multiformats/js-multiaddr/) - addresses for the peer. |
 
 **Example:**
 
 ```JavaScript
-const provs = await ipfs.dht.findProvs(multihash)
-provs.forEach(prov => {
-  console.log(prov.id.toB58String())
-})
-
-const provs2 = await ipfs.dht.findProvs(multihash, { timeout: 4000 })
-provs2.forEach(prov => {
-  console.log(prov.id.toB58String())
-})
+const providers = ipfs.dht.findProvs('QmdPAhQRxrDKqkGPvQzBvjYe3kU8kiEEAd2J6ETEamKAD9')
+
+for await (const provider of providers) {
+  console.log(provider.id.toString())
+}
 ```
 
 A great source of [examples][] can be found in the tests for this API.
 
 #### `dht.get`
 
-> Retrieve a value from DHT
+> Given a key, query the routing system for its best value.
 
 ##### `ipfs.dht.get(key)`
 
-Where `key` is a Buffer.
+Where `key` is a `Buffer`.
 
 **Returns**
 
@@ -99,70 +100,158 @@ A great source of [examples][] can be found in the tests for this API.
 
 > Announce to the network that you are providing given values.
 
-##### `ipfs.dht.provide(cid)`
+##### `ipfs.dht.provide(cid, [options])`
+
+Where `cid` is a CID or array of CIDs as a `String`, `Buffer` or [`CID`](https://github.com/multiformats/js-cid) instance.
 
-Where `cid` is a CID or array of CIDs.
+`options` an optional object with the following properties:
+  - `recursive` - boolean, set to `true` to recursively provide the entire graph. Default `false`.
 
 **Returns**
 
 | Type | Description |
 | -------- | -------- |
-| `Promise<void>` | If action is successfully completed. Otherwise an error will be thrown |
+| `AsyncIterable<Object>` | DHT query messages. See example below for structure. |
+
+Note: You must consume the iterable to completion to complete the provide operation.
 
 **Example:**
 
 ```JavaScript
-await ipfs.dht.provide(cid)
+for await (const message of ipfs.dht.provide('QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR')) {
+  console.log(message)
+}
+
+/*
+Prints objects like:
+
+{
+  extra: 'dial backoff',
+  id: CID(QmWtewmnzJiQevJPSmG9s8aC7yRfK2WXTCdRc1pCbDFu6z),
+  responses: [
+    {
+      addrs: [
+        Multiaddr(/ip4/127.0.0.1/tcp/4001),
+        Multiaddr(/ip4/172.20.0.3/tcp/4001),
+        Multiaddr(/ip4/35.178.190.196/tcp/1024)
+      ],
+      id: CID(QmRz5Nth4jTFuJJKcjyb6uwvrhxWbruRvamKY2PJxwJKw8)
+    }
+  ],
+  type: 1
+}
+
+For message `type` values, see:
+https://github.com/libp2p/go-libp2p-core/blob/6e566d10f4a5447317a66d64c7459954b969bdab/routing/query.go#L15-L24
+*/
+```
+
+Alternatively you can simply "consume" the iterable:
+
+```js
+const { consume } = require('streaming-iterables')
+await consume(ipfs.dht.provide('QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR'))
 ```
 
 A great source of [examples][] can be found in the tests for this API.
 
 #### `dht.put`
 
-> Store a value on the DHT
+> Write a key/value pair to the routing system.
 
 ##### `ipfs.dht.put(key, value)`
 
-Where `key` is a Buffer and `value` is a Buffer.
+Where `key` is a `Buffer` and `value` is a `Buffer`.
 
 **Returns**
 
 | Type | Description |
 | -------- | -------- |
-| `Promise<void>` | If action is successfully completed. Otherwise an error will be thrown |
+| `AsyncIterable<Object>` | DHT query messages. See example below for structure. |
 
 **Example:**
 
 ```JavaScript
-await ipfs.dht.put(key, value)
+for await (const message of ipfs.dht.put(key, value)) {
+  console.log(message)
+}
+
+/*
+Prints objects like:
+
+{
+  extra: 'dial backoff',
+  id: CID(QmWtewmnzJiQevJPSmG9s8aC7yRfK2WXTCdRc1pCbDFu6z),
+  responses: [
+    {
+      addrs: [
+        Multiaddr(/ip4/127.0.0.1/tcp/4001),
+        Multiaddr(/ip4/172.20.0.3/tcp/4001),
+        Multiaddr(/ip4/35.178.190.196/tcp/1024)
+      ],
+      id: CID(QmRz5Nth4jTFuJJKcjyb6uwvrhxWbruRvamKY2PJxwJKw8)
+    }
+  ],
+  type: 1
+}
+
+For message `type` values, see:
+https://github.com/libp2p/go-libp2p-core/blob/6e566d10f4a5447317a66d64c7459954b969bdab/routing/query.go#L15-L24
+*/
+```
+
+Alternatively you can simply "consume" the iterable:
+
+```js
+const { consume } = require('streaming-iterables')
+await consume(ipfs.dht.put(key, value))
 ```
 
 A great source of [examples][] can be found in the tests for this API.
 
 #### `dht.query`
 
-> Queries the network for the 'closest peers' to a given key. 'closest' is defined by the rules of the underlying Peer Routing mechanism.
+> Find the closest Peer IDs to a given Peer ID by querying the DHT.
 
 ##### `ipfs.dht.query(peerId)`
 
-Where `peerId` is a IPFS/libp2p Id of type [PeerId](https://github.com/libp2p/js-peer-id).
+Where `peerId` is a Peer ID in `String`, [`CID`](https://github.com/multiformats/js-cid) or [`PeerId`](https://github.com/libp2p/js-peer-id) format.
 
 **Returns**
 
 | Type | Description |
 | -------- | -------- |
-| `Promise<Array>` | An array of objects of type [PeerInfo](https://github.com/libp2p/js-peer-info) |
+| `AsyncIterable<Object>` | DHT query messages. See example below for structure. |
 
 **Example:**
 
 ```JavaScript
-const id = PeerId.create()
-
-const peerInfos = await ipfs.dht.query(id)
-
-peerInfos.forEach(p => {
-  console.log(p.id.toB58String())
-})
+for await (const info of ipfs.dht.query('QmcZf59bWwK5XFi76CZX8cbJ4BhTzzA3gU1ZjYZcYW3dwt')) {
+  console.log(info)
+}
+
+/*
+Prints objects like:
+
+{
+  extra: 'dial backoff',
+  id: CID(QmWtewmnzJiQevJPSmG9s8aC7yRfK2WXTCdRc1pCbDFu6z),
+  responses: [
+    {
+      addrs: [
+        Multiaddr(/ip4/127.0.0.1/tcp/4001),
+        Multiaddr(/ip4/172.20.0.3/tcp/4001),
+        Multiaddr(/ip4/35.178.190.196/tcp/1024)
+      ],
+      id: CID(QmRz5Nth4jTFuJJKcjyb6uwvrhxWbruRvamKY2PJxwJKw8)
+    }
+  ],
+  type: 1
+}
+
+For message `type` values, see:
+https://github.com/libp2p/go-libp2p-core/blob/6e566d10f4a5447317a66d64c7459954b969bdab/routing/query.go#L15-L24
+*/
 ```
 
 A great source of [examples][] can be found in the tests for this API.