Skip to content
This repository was archived by the owner on Mar 10, 2020. It is now read-only.

Commit 1a568c9

Browse files
author
Alan Shaw
committed
refactor: async iterables
1 parent e51d27c commit 1a568c9

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

98 files changed

+1300
-3409
lines changed

‎SPEC/BITSWAP.md

-3
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,6 @@
33
* [bitswap.wantlist](#bitswapwantlist)
44
* [bitswap.stat](#bitswapstat)
55

6-
### ⚠️ Note
7-
Although not listed in the documentation, all the following APIs that actually return a **promise** can also accept a **final callback** parameter.
8-
96
### `bitswap.wantlist`
107

118
> Returns the wantlist, optionally filtered by peer ID

‎SPEC/BLOCK.md

+16-9
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,6 @@
55
* [block.rm](#blockrm)
66
* [block.stat](#blockstat)
77

8-
### ⚠️ Note
9-
Although not listed in the documentation, all the following APIs that actually return a **promise** can also accept a **final callback** parameter.
10-
118
#### `block.get`
129

1310
> Get a raw IPFS block.
@@ -114,22 +111,32 @@ A great source of [examples][] can be found in the tests for this API.
114111

115112
`options` is an Object that can contain the following properties:
116113

117-
- force (boolean): Ignores nonexistent blocks.
118-
- quiet (boolean): write minimal output
114+
- `force` (boolean): Ignores nonexistent blocks.
115+
- `quiet` (boolean): write minimal output
119116

120117
**Returns**
121118

122119
| Type | Description |
123120
| -------- | -------- |
124-
| `Promise<Array>` | An array of objects containing hash and (potentially) error strings |
121+
| `AsyncIterable<Object>` | An async iterable that yields objects containing hash and (potentially) error strings |
125122

126-
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.
123+
Each object yielded is of the form:
124+
125+
```js
126+
{
127+
hash: string,
128+
error: string
129+
}
130+
```
131+
132+
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.
127133

128134
**Example:**
129135

130136
```JavaScript
131-
const result = await ipfs.block.rm(cid)
132-
console.log(result[0].hash)
137+
for await (const result of ipfs.block.rm(cid)) {
138+
console.log(result.hash)
139+
}
133140
```
134141

135142
A great source of [examples][] can be found in the tests for this API.

‎SPEC/BOOTSTRAP.md

+1-4
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,12 @@
44
the addresses of the bootstrap nodes. These are the trusted peers from
55
which to learn about other peers in the network.
66

7-
> Only edit this list if you understand the risks of adding or removing nodes from this list.
7+
> Only edit this list if you understand the risks of adding or removing nodes
88
99
* [bootstrap.add](#bootstrapadd)
1010
* [bootstrap.list](#bootstraplist)
1111
* [bootstrap.rm](#bootstraprm)
1212

13-
### ⚠️ Note
14-
Although not listed in the documentation, all the following APIs that actually return a **promise** can also accept a **final callback** parameter.
15-
1613
#### `bootstrap.add`
1714

1815
> Add a peer address to the bootstrap list

‎SPEC/CONFIG.md

-3
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,6 @@
66
* [config.profiles.list](#configprofileslist)
77
* [config.profiles.apply](#configprofilesapply)
88

9-
### ⚠️ Note
10-
Although not listed in the documentation, all the following APIs that actually return a **promise** can also accept a **final callback** parameter.
11-
129
#### `config.get`
1310

1411
> Returns the currently being used config. If the daemon is off, it returns the stored config.

‎SPEC/DAG.md

-3
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,6 @@ _Explore the DAG API through interactive coding challenges in our ProtoSchool tu
1010
- _[P2P data links with content addressing](https://proto.school/#/basics/) (beginner)_
1111
- _[Blogging on the Decentralized Web](https://proto.school/#/blog/) (intermediate)_
1212

13-
### ⚠️ Note
14-
Although not listed in the documentation, all the following APIs that actually return a **promise** can also accept a **final callback** parameter.
15-
1613
#### `dag.put`
1714

1815
> Store an IPLD format node

‎SPEC/DHT.md

+139-50
Original file line numberDiff line numberDiff line change
@@ -7,79 +7,80 @@
77
* [dht.put](#dhtput)
88
* [dht.query](#dhtquery)
99

10-
### ⚠️ Note
11-
Although not listed in the documentation, all the following APIs that actually return a **promise** can also accept a **final callback** parameter.
12-
1310
#### `dht.findPeer`
1411

15-
> Retrieve the Peer Info of a reachable node in the network.
12+
> Find the multiaddresses associated with a Peer ID
1613
1714
##### `ipfs.dht.findPeer(peerId)`
1815

19-
Where `peerId` is a IPFS/libp2p Id from [PeerId](https://github.com/libp2p/js-peer-id) type.
16+
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.
2017

2118
**Returns**
2219

2320
| Type | Description |
2421
| -------- | -------- |
25-
| `Promise<PeerInfo>` | An object type [`PeerInfo`](https://github.com/libp2p/js-peer-info) |
22+
| `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. |
2623

2724
**Example:**
2825

2926
```JavaScript
30-
var id = PeerId.create()
31-
32-
const peerInfo = await ipfs.dht.findPeer(id)
33-
// peerInfo will contain the multiaddrs of that peer
34-
const id = peerInfo.id
35-
const addrs = peerInfo.multiaddrs
27+
const info = await ipfs.dht.findPeer('QmcZf59bWwK5XFi76CZX8cbJ4BhTzzA3gU1ZjYZcYW3dwt')
28+
29+
console.log(info.id.toString())
30+
/*
31+
QmcZf59bWwK5XFi76CZX8cbJ4BhTzzA3gU1ZjYZcYW3dwt
32+
*/
33+
34+
info.addrs.forEach(addr => console.log(addr.toString()))
35+
/*
36+
/ip4/147.75.94.115/udp/4001/quic
37+
/ip6/2604:1380:3000:1f00::1/udp/4001/quic
38+
/dnsaddr/bootstrap.libp2p.io
39+
/ip6/2604:1380:3000:1f00::1/tcp/4001
40+
/ip4/147.75.94.115/tcp/4001
41+
*/
3642
```
3743

3844
A great source of [examples][] can be found in the tests for this API.
3945

4046
#### `dht.findProvs`
4147

42-
> Retrieve the providers for content that is addressed by an hash.
48+
> Find peers that can provide a specific value, given a CID.
4349
44-
##### `ipfs.dht.findProvs(hash, [options])`
50+
##### `ipfs.dht.findProvs(cid, [options])`
4551

46-
Where `hash` is a multihash.
52+
Where `cid` is a CID as a `String`, `Buffer` or [`CID`](https://github.com/multiformats/js-cid) instance.
4753

48-
`options` an optional object with the following properties
49-
- `timeout` - a maximum timeout in milliseconds
50-
- `maxNumProviders` - a maximum number of providers to find
54+
`options` an optional object with the following properties:
55+
- `numProviders` - the number of providers to find. Default: 20
56+
57+
Note that if `options.numProviders` are not found an error will be thrown.
5158

5259
**Returns**
5360

5461
| Type | Description |
5562
| -------- | -------- |
56-
| `Promise<Array>` | An array of type [`PeerInfo`](https://github.com/libp2p/js-peer-info) |
57-
58-
each entry of the returned array is composed by the peerId, as well as an array with its adresses.
63+
| `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. |
5964

6065
**Example:**
6166

6267
```JavaScript
63-
const provs = await ipfs.dht.findProvs(multihash)
64-
provs.forEach(prov => {
65-
console.log(prov.id.toB58String())
66-
})
67-
68-
const provs2 = await ipfs.dht.findProvs(multihash, { timeout: 4000 })
69-
provs2.forEach(prov => {
70-
console.log(prov.id.toB58String())
71-
})
68+
const providers = ipfs.dht.findProvs('QmdPAhQRxrDKqkGPvQzBvjYe3kU8kiEEAd2J6ETEamKAD9')
69+
70+
for await (const provider of providers) {
71+
console.log(provider.id.toString())
72+
}
7273
```
7374

7475
A great source of [examples][] can be found in the tests for this API.
7576

7677
#### `dht.get`
7778

78-
> Retrieve a value from DHT
79+
> Given a key, query the routing system for its best value.
7980
8081
##### `ipfs.dht.get(key)`
8182

82-
Where `key` is a Buffer.
83+
Where `key` is a `Buffer`.
8384

8485
**Returns**
8586

@@ -99,70 +100,158 @@ A great source of [examples][] can be found in the tests for this API.
99100

100101
> Announce to the network that you are providing given values.
101102
102-
##### `ipfs.dht.provide(cid)`
103+
##### `ipfs.dht.provide(cid, [options])`
104+
105+
Where `cid` is a CID or array of CIDs as a `String`, `Buffer` or [`CID`](https://github.com/multiformats/js-cid) instance.
103106

104-
Where `cid` is a CID or array of CIDs.
107+
`options` an optional object with the following properties:
108+
- `recursive` - boolean, set to `true` to recursively provide the entire graph. Default `false`.
105109

106110
**Returns**
107111

108112
| Type | Description |
109113
| -------- | -------- |
110-
| `Promise<void>` | If action is successfully completed. Otherwise an error will be thrown |
114+
| `AsyncIterable<Object>` | DHT query messages. See example below for structure. |
115+
116+
Note: You must consume the iterable to completion to complete the provide operation.
111117

112118
**Example:**
113119

114120
```JavaScript
115-
await ipfs.dht.provide(cid)
121+
for await (const message of ipfs.dht.provide('QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR')) {
122+
console.log(message)
123+
}
124+
125+
/*
126+
Prints objects like:
127+
128+
{
129+
extra: 'dial backoff',
130+
id: CID(QmWtewmnzJiQevJPSmG9s8aC7yRfK2WXTCdRc1pCbDFu6z),
131+
responses: [
132+
{
133+
addrs: [
134+
Multiaddr(/ip4/127.0.0.1/tcp/4001),
135+
Multiaddr(/ip4/172.20.0.3/tcp/4001),
136+
Multiaddr(/ip4/35.178.190.196/tcp/1024)
137+
],
138+
id: CID(QmRz5Nth4jTFuJJKcjyb6uwvrhxWbruRvamKY2PJxwJKw8)
139+
}
140+
],
141+
type: 1
142+
}
143+
144+
For message `type` values, see:
145+
https://github.com/libp2p/go-libp2p-core/blob/6e566d10f4a5447317a66d64c7459954b969bdab/routing/query.go#L15-L24
146+
*/
147+
```
148+
149+
Alternatively you can simply "consume" the iterable:
150+
151+
```js
152+
const { consume } = require('streaming-iterables')
153+
await consume(ipfs.dht.provide('QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR'))
116154
```
117155

118156
A great source of [examples][] can be found in the tests for this API.
119157

120158
#### `dht.put`
121159

122-
> Store a value on the DHT
160+
> Write a key/value pair to the routing system.
123161
124162
##### `ipfs.dht.put(key, value)`
125163

126-
Where `key` is a Buffer and `value` is a Buffer.
164+
Where `key` is a `Buffer` and `value` is a `Buffer`.
127165

128166
**Returns**
129167

130168
| Type | Description |
131169
| -------- | -------- |
132-
| `Promise<void>` | If action is successfully completed. Otherwise an error will be thrown |
170+
| `AsyncIterable<Object>` | DHT query messages. See example below for structure. |
133171

134172
**Example:**
135173

136174
```JavaScript
137-
await ipfs.dht.put(key, value)
175+
for await (const message of ipfs.dht.put(key, value)) {
176+
console.log(message)
177+
}
178+
179+
/*
180+
Prints objects like:
181+
182+
{
183+
extra: 'dial backoff',
184+
id: CID(QmWtewmnzJiQevJPSmG9s8aC7yRfK2WXTCdRc1pCbDFu6z),
185+
responses: [
186+
{
187+
addrs: [
188+
Multiaddr(/ip4/127.0.0.1/tcp/4001),
189+
Multiaddr(/ip4/172.20.0.3/tcp/4001),
190+
Multiaddr(/ip4/35.178.190.196/tcp/1024)
191+
],
192+
id: CID(QmRz5Nth4jTFuJJKcjyb6uwvrhxWbruRvamKY2PJxwJKw8)
193+
}
194+
],
195+
type: 1
196+
}
197+
198+
For message `type` values, see:
199+
https://github.com/libp2p/go-libp2p-core/blob/6e566d10f4a5447317a66d64c7459954b969bdab/routing/query.go#L15-L24
200+
*/
201+
```
202+
203+
Alternatively you can simply "consume" the iterable:
204+
205+
```js
206+
const { consume } = require('streaming-iterables')
207+
await consume(ipfs.dht.put(key, value))
138208
```
139209

140210
A great source of [examples][] can be found in the tests for this API.
141211

142212
#### `dht.query`
143213

144-
> Queries the network for the 'closest peers' to a given key. 'closest' is defined by the rules of the underlying Peer Routing mechanism.
214+
> Find the closest Peer IDs to a given Peer ID by querying the DHT.
145215
146216
##### `ipfs.dht.query(peerId)`
147217

148-
Where `peerId` is a IPFS/libp2p Id of type [PeerId](https://github.com/libp2p/js-peer-id).
218+
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.
149219

150220
**Returns**
151221

152222
| Type | Description |
153223
| -------- | -------- |
154-
| `Promise<Array>` | An array of objects of type [PeerInfo](https://github.com/libp2p/js-peer-info) |
224+
| `AsyncIterable<Object>` | DHT query messages. See example below for structure. |
155225

156226
**Example:**
157227

158228
```JavaScript
159-
const id = PeerId.create()
160-
161-
const peerInfos = await ipfs.dht.query(id)
162-
163-
peerInfos.forEach(p => {
164-
console.log(p.id.toB58String())
165-
})
229+
for await (const info of ipfs.dht.query('QmcZf59bWwK5XFi76CZX8cbJ4BhTzzA3gU1ZjYZcYW3dwt')) {
230+
console.log(info)
231+
}
232+
233+
/*
234+
Prints objects like:
235+
236+
{
237+
extra: 'dial backoff',
238+
id: CID(QmWtewmnzJiQevJPSmG9s8aC7yRfK2WXTCdRc1pCbDFu6z),
239+
responses: [
240+
{
241+
addrs: [
242+
Multiaddr(/ip4/127.0.0.1/tcp/4001),
243+
Multiaddr(/ip4/172.20.0.3/tcp/4001),
244+
Multiaddr(/ip4/35.178.190.196/tcp/1024)
245+
],
246+
id: CID(QmRz5Nth4jTFuJJKcjyb6uwvrhxWbruRvamKY2PJxwJKw8)
247+
}
248+
],
249+
type: 1
250+
}
251+
252+
For message `type` values, see:
253+
https://github.com/libp2p/go-libp2p-core/blob/6e566d10f4a5447317a66d64c7459954b969bdab/routing/query.go#L15-L24
254+
*/
166255
```
167256

168257
A great source of [examples][] can be found in the tests for this API.

0 commit comments

Comments
 (0)