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

Commit b12f872

Browse files
PedroMiguelSSAlan Shaw
PedroMiguelSS
authored and
Alan Shaw
committed
docs: update examples in docs to async/await (#542)
* chore: update examples in docs to async/await * chore: code review changes
1 parent 5d8a483 commit b12f872

18 files changed

+1167
-844
lines changed

‎README.md

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -71,20 +71,21 @@ Install `interface-ipfs-core` as one of the dependencies of your project and as
7171

7272
```js
7373
const tests = require('interface-ipfs-core')
74+
const nodes = []
7475

7576
// Create common setup and teardown
7677
const createCommon = () => ({
7778
// Do some setup common to all tests
78-
setup (cb) {
79-
// Must call back with an "IPFS factory", an object with a `spawnNode` method
80-
cb(null, {
81-
// Use ipfsd-ctl or other to spawn an IPFS node for testing
82-
spawnNode (cb) { /* ... */ }
83-
})
79+
setup: async () => {
80+
// Use ipfsd-ctl or other to spawn an IPFS node for testing
81+
const node = await spawnNode()
82+
nodes.push(node)
83+
84+
return node.api
8485
},
8586
// Dispose of nodes created by the IPFS factory and any other teardown
86-
teardown (cb) {
87-
cb()
87+
teardown: () => {
88+
return Promise.all(nodes.map(n => n.stop()))
8889
}
8990
})
9091

‎SPEC/BITSWAP.md

Lines changed: 34 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -3,40 +3,55 @@
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+
69
### `bitswap.wantlist`
710

811
> Returns the wantlist, optionally filtered by peer ID
912
10-
#### `ipfs.bitswap.wantlist([peerId], [callback])`
13+
#### `ipfs.bitswap.wantlist([peerId])`
14+
15+
**Returns**
16+
17+
| Type | Description |
18+
| -------- | -------- |
19+
| `Promise<Object>` | An object representing the wantlist |
1120

12-
`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:
21+
the returned object contains the following keys:
1322

1423
- `Keys` An array of objects containing the following keys:
1524
- `/` A string multihash
1625

17-
If no `callback` is passed, a promise is returned.
18-
1926
**Example:**
2027

2128
```JavaScript
22-
ipfs.bitswap.wantlist((err, list) => console.log(list))
23-
29+
const list = await ipfs.bitswap.wantlist()
30+
console.log(list)
2431
// { Keys: [{ '/': 'QmHash' }] }
2532

26-
ipfs.bitswap.wantlist(peerId, (err, list) => console.log(list))
27-
33+
const list2 = await ipfs.bitswap.wantlist(peerId)
34+
console.log(list2)
2835
// { Keys: [{ '/': 'QmHash' }] }
2936
```
3037

38+
A great source of [examples][] can be found in the tests for this API.
39+
3140
#### `bitswap.stat`
3241

3342
> Show diagnostic information on the bitswap agent.
3443
35-
##### `ipfs.bitswap.stat([callback])`
44+
##### `ipfs.bitswap.stat()`
3645

3746
Note: `bitswap.stat` and `stats.bitswap` can be used interchangeably.
3847

39-
`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:
48+
**Returns**
49+
50+
| Type | Description |
51+
| -------- | -------- |
52+
| `Promise<Object>` | An object that contains information about the bitswap agent |
53+
54+
the returned object contains the following keys:
4055

4156
- `provideBufLen` is an integer.
4257
- `wantlist` (array of CIDs)
@@ -48,14 +63,13 @@ Note: `bitswap.stat` and `stats.bitswap` can be used interchangeably.
4863
- `dupBlksReceived` is a [BigNumber Int][1]
4964
- `dupDataReceived` is a [BigNumber Int][1]
5065

51-
If no `callback` is passed, a promise is returned.
52-
5366
**Example:**
5467

5568
```JavaScript
56-
ipfs.bitswap.stat((err, stats) => console.log(stats))
57-
58-
// { provideBufLen: 0,
69+
const stats = await ipfs.bitswap.stat()
70+
console.log(stats)
71+
// {
72+
// provideBufLen: 0,
5973
// wantlist: [ { '/': 'QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM' } ],
6074
// peers:
6175
// [ 'QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM',
@@ -66,7 +80,11 @@ ipfs.bitswap.stat((err, stats) => console.log(stats))
6680
// blocksSent: 0,
6781
// dataSent: 0,
6882
// dupBlksReceived: 0,
69-
// dupDataReceived: 0 }
83+
// dupDataReceived: 0
84+
// }
7085
```
7186

87+
A great source of [examples][] can be found in the tests for this API.
88+
7289
[1]: https://github.com/MikeMcl/bignumber.js/
90+
[examples]: https://github.com/ipfs/interface-ipfs-core/blob/master/src/bitswap

‎SPEC/BLOCK.md

Lines changed: 53 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -5,36 +5,32 @@
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+
811
#### `block.get`
912

1013
> Get a raw IPFS block.
1114
12-
##### `ipfs.block.get(cid, [options], [callback])`
15+
##### `ipfs.block.get(cid, [options])`
1316

1417
`cid` is a [cid][cid] which can be passed as:
1518

1619
- Buffer, the raw Buffer of the cid
1720
- CID, a CID instance
1821
- String, the base58 encoded version of the multihash
1922

20-
`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.
23+
**Returns**
2124

22-
If no `callback` is passed, a promise is returned.
25+
| Type | Description |
26+
| -------- | -------- |
27+
| `Promise<Block>` | A [Block][block] type object, containing both the data and the hash of the block |
2328

2429
**Example:**
2530

2631
```JavaScript
27-
ipfs.block.get(cid, function (err, block) {
28-
if (err) {
29-
throw err
30-
}
31-
block.key((err, key) => {
32-
if (err) {
33-
throw err
34-
}
35-
console.log(key, block.data)
36-
})
37-
})
32+
const block = await ipfs.block.get(cid)
33+
console.log(block.data)
3834
```
3935

4036
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.
4339

4440
> Stores input as an IPFS block.
4541
46-
##### `ipfs.block.put(block, [options], [callback])`
42+
##### `ipfs.block.put(block, [options])`
4743

4844
Where `block` can be:
4945

@@ -65,44 +61,40 @@ if no options are passed, it defaults to `{ format: 'dag-pb', mhtype: 'sha2-256'
6561

6662
**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.
6763

68-
`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.
64+
**Returns**
6965

70-
If no `callback` is passed, a promise is returned.
66+
| Type | Description |
67+
| -------- | -------- |
68+
| `Promise<Block>` | A [Block][block] type object, containing both the data and the hash of the block |
7169

7270
**Example:**
7371

7472
```JavaScript
7573
// Defaults
7674
const buf = new Buffer('a serialized object')
7775

78-
ipfs.block.put(buf, (err, block) => {
79-
if (err) { throw err }
80-
// Block has been stored
76+
const block = await ipfs.block.put(buf)
8177

82-
console.log(block.data.toString())
83-
// Logs:
84-
// a serialized object
85-
console.log(block.cid.toBaseEncodedString())
86-
// Logs:
87-
// the CID of the object
88-
})
78+
console.log(block.data.toString())
79+
// Logs:
80+
// a serialized object
81+
console.log(block.cid.toString())
82+
// Logs:
83+
// the CID of the object
8984

9085
// With custom format and hashtype through CID
9186
const CID = require('cids')
9287
const buf = new Buffer('another serialized object')
9388
const cid = new CID(1, 'dag-pb', multihash)
9489

95-
ipfs.block.put(blob, cid, (err, block) => {
96-
if (err) { throw err }
97-
// Block has been stored
98-
99-
console.log(block.data.toString())
100-
// Logs:
101-
// a serialized object
102-
console.log(block.cid.toBaseEncodedString())
103-
// Logs:
104-
// the CID of the object
105-
})
90+
const block = await ipfs.block.put(blob, cid)
91+
92+
console.log(block.data.toString())
93+
// Logs:
94+
// a serialized object
95+
console.log(block.cid.toString())
96+
// Logs:
97+
// the CID of the object
10698
```
10799

108100
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.
111103

112104
> Remove one or more IPFS block(s).
113105
114-
##### `ipfs.block.rm(cid, [options], [callback])`
106+
##### `ipfs.block.rm(cid, [options])`
115107

116108
`cid` is a [cid][cid] which can be passed as:
117109

@@ -125,21 +117,19 @@ A great source of [examples][] can be found in the tests for this API.
125117
- force (boolean): Ignores nonexistent blocks.
126118
- quiet (boolean): write minimal output
127119

128-
`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.
120+
**Returns**
129121

130-
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.
122+
| Type | Description |
123+
| -------- | -------- |
124+
| `Promise<Array>` | An array of objects containing hash and (potentially) error strings |
131125

132-
If no `callback` is passed, a promise is returned.
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.
133127

134128
**Example:**
135129

136130
```JavaScript
137-
ipfs.block.rm(cid, function (err, result) {
138-
if (err) {
139-
throw err
140-
}
141-
console.log(result[0].hash)
142-
})
131+
const result = await ipfs.block.rm(cid)
132+
console.log(result[0].hash)
143133
```
144134

145135
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.
148138

149139
> Print information of a raw IPFS block.
150140
151-
##### `ipfs.block.stat(cid, [callback])`
141+
##### `ipfs.block.stat(cid)`
152142

153143
`cid` is a [cid][cid] which can be passed as:
154144

155145
- `Buffer`, the raw Buffer of the multihash (or of and encoded version)
156146
- `String`, the toString version of the multihash (or of an encoded version)
157147
- CID, a CID instance
158148

159-
`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:`
149+
**Returns**
150+
151+
| Type | Description |
152+
| -------- | -------- |
153+
| `Promise<Object>` | An object containing the block's info |
154+
155+
the returned object has the following keys:
160156

161157
```JavaScript
162158
{
@@ -165,25 +161,19 @@ A great source of [examples][] can be found in the tests for this API.
165161
}
166162
```
167163

168-
If no `callback` is passed, a promise is returned.
169-
170164
**Example:**
171165

172166
```JavaScript
173167
const multihashStr = 'QmQULBtTjNcMwMr4VMNknnVv3RpytrLSdgpvMcTnfNhrBJ'
174168
const cid = new CID(multihashStr)
175169

176-
ipfs.block.stat(cid, (err, stats) => {
177-
if (err) {
178-
throw err
179-
}
180-
console.log(stats)
181-
// Logs:
182-
// {
183-
// key: QmQULBtTjNcMwMr4VMNknnVv3RpytrLSdgpvMcTnfNhrBJ,
184-
/ size: 3739
185-
// }
186-
})
170+
const stats = await ipfs.block.stat(cid)
171+
console.log(stats)
172+
// Logs:
173+
// {
174+
// key: QmQULBtTjNcMwMr4VMNknnVv3RpytrLSdgpvMcTnfNhrBJ,
175+
// size: 3739
176+
// }
187177
```
188178

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

0 commit comments

Comments
 (0)