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

Commit 3ed1e1b

Browse files
author
Pedro Santos
committed
chore: update examples in docs to async/await
1 parent 5d8a483 commit 3ed1e1b

18 files changed

+1107
-839
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: 31 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -7,36 +7,48 @@
77

88
> Returns the wantlist, optionally filtered by peer ID
99
10-
#### `ipfs.bitswap.wantlist([peerId], [callback])`
10+
#### `ipfs.bitswap.wantlist([peerId])`
1111

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:
12+
**Returns**
13+
14+
| Type | Description |
15+
| -------- | -------- |
16+
| `Promise<Object>` | An object representing the wantlist |
17+
18+
the returned object contains the following keys:
1319

1420
- `Keys` An array of objects containing the following keys:
1521
- `/` A string multihash
1622

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

2125
```JavaScript
22-
ipfs.bitswap.wantlist((err, list) => console.log(list))
23-
26+
const list = await ipfs.bitswap.wantlist()
27+
console.log(list)
2428
// { Keys: [{ '/': 'QmHash' }] }
2529

26-
ipfs.bitswap.wantlist(peerId, (err, list) => console.log(list))
27-
30+
const list2 = await ipfs.bitswap.wantlist(peerId)
31+
console.log(list2)
2832
// { Keys: [{ '/': 'QmHash' }] }
2933
```
3034

35+
A great source of [examples][] can be found in the tests for this API.
36+
3137
#### `bitswap.stat`
3238

3339
> Show diagnostic information on the bitswap agent.
3440
35-
##### `ipfs.bitswap.stat([callback])`
41+
##### `ipfs.bitswap.stat()`
3642

3743
Note: `bitswap.stat` and `stats.bitswap` can be used interchangeably.
3844

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:
45+
**Returns**
46+
47+
| Type | Description |
48+
| -------- | -------- |
49+
| `Promise<Object>` | An object that contains information about the bitswap agent |
50+
51+
the returned object contains the following keys:
4052

4153
- `provideBufLen` is an integer.
4254
- `wantlist` (array of CIDs)
@@ -48,14 +60,13 @@ Note: `bitswap.stat` and `stats.bitswap` can be used interchangeably.
4860
- `dupBlksReceived` is a [BigNumber Int][1]
4961
- `dupDataReceived` is a [BigNumber Int][1]
5062

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

5565
```JavaScript
56-
ipfs.bitswap.stat((err, stats) => console.log(stats))
57-
58-
// { provideBufLen: 0,
66+
const stats = await ipfs.bitswap.stat()
67+
console.log(stats)
68+
// {
69+
// provideBufLen: 0,
5970
// wantlist: [ { '/': 'QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM' } ],
6071
// peers:
6172
// [ 'QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM',
@@ -66,7 +77,11 @@ ipfs.bitswap.stat((err, stats) => console.log(stats))
6677
// blocksSent: 0,
6778
// dataSent: 0,
6879
// dupBlksReceived: 0,
69-
// dupDataReceived: 0 }
80+
// dupDataReceived: 0
81+
// }
7082
```
7183

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

‎SPEC/BLOCK.md

Lines changed: 50 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -9,32 +9,25 @@
99

1010
> Get a raw IPFS block.
1111
12-
##### `ipfs.block.get(cid, [options], [callback])`
12+
##### `ipfs.block.get(cid, [options])`
1313

1414
`cid` is a [cid][cid] which can be passed as:
1515

1616
- Buffer, the raw Buffer of the cid
1717
- CID, a CID instance
1818
- String, the base58 encoded version of the multihash
1919

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.
20+
**Returns**
2121

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

2426
**Example:**
2527

2628
```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-
})
29+
const block = await ipfs.block.get(cid)
30+
console.log(block.data)
3831
```
3932

4033
A great source of [examples][] can be found in the tests for this API.
@@ -43,7 +36,7 @@ A great source of [examples][] can be found in the tests for this API.
4336

4437
> Stores input as an IPFS block.
4538
46-
##### `ipfs.block.put(block, [options], [callback])`
39+
##### `ipfs.block.put(block, [options])`
4740

4841
Where `block` can be:
4942

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

6659
**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.
6760

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.
61+
**Returns**
6962

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

7267
**Example:**
7368

7469
```JavaScript
7570
// Defaults
7671
const buf = new Buffer('a serialized object')
7772

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

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-
})
75+
console.log(block.data.toString())
76+
// Logs:
77+
// a serialized object
78+
console.log(block.cid.toBaseEncodedString())
79+
// Logs:
80+
// the CID of the object
8981

9082
// With custom format and hashtype through CID
9183
const CID = require('cids')
9284
const buf = new Buffer('another serialized object')
9385
const cid = new CID(1, 'dag-pb', multihash)
9486

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-
})
87+
const block = await ipfs.block.put(blob, cid)
88+
89+
console.log(block.data.toString())
90+
// Logs:
91+
// a serialized object
92+
console.log(block.cid.toBaseEncodedString())
93+
// Logs:
94+
// the CID of the object
10695
```
10796

10897
A great source of [examples][] can be found in the tests for this API.
@@ -111,7 +100,7 @@ A great source of [examples][] can be found in the tests for this API.
111100

112101
> Remove one or more IPFS block(s).
113102
114-
##### `ipfs.block.rm(cid, [options], [callback])`
103+
##### `ipfs.block.rm(cid, [options])`
115104

116105
`cid` is a [cid][cid] which can be passed as:
117106

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

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.
117+
**Returns**
129118

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.
119+
| Type | Description |
120+
| -------- | -------- |
121+
| `Promise<Array>` | An array of objects containing hash and (potentially) error strings |
131122

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

134125
**Example:**
135126

136127
```JavaScript
137-
ipfs.block.rm(cid, function (err, result) {
138-
if (err) {
139-
throw err
140-
}
141-
console.log(result[0].hash)
142-
})
128+
const result = await ipfs.block.rm(cid)
129+
console.log(result[0].hash)
143130
```
144131

145132
A great source of [examples][] can be found in the tests for this API.
@@ -148,15 +135,21 @@ A great source of [examples][] can be found in the tests for this API.
148135

149136
> Print information of a raw IPFS block.
150137
151-
##### `ipfs.block.stat(cid, [callback])`
138+
##### `ipfs.block.stat(cid)`
152139

153140
`cid` is a [cid][cid] which can be passed as:
154141

155142
- `Buffer`, the raw Buffer of the multihash (or of and encoded version)
156143
- `String`, the toString version of the multihash (or of an encoded version)
157144
- CID, a CID instance
158145

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:`
146+
**Returns**
147+
148+
| Type | Description |
149+
| -------- | -------- |
150+
| `Promise<Object>` | An object containing the block's info |
151+
152+
the returned object has the following keys:
160153

161154
```JavaScript
162155
{
@@ -165,25 +158,19 @@ A great source of [examples][] can be found in the tests for this API.
165158
}
166159
```
167160

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

172163
```JavaScript
173164
const multihashStr = 'QmQULBtTjNcMwMr4VMNknnVv3RpytrLSdgpvMcTnfNhrBJ'
174165
const cid = new CID(multihashStr)
175166

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-
})
167+
const stats = await ipfs.block.stat(cid)
168+
console.log(stats)
169+
// Logs:
170+
// {
171+
// key: QmQULBtTjNcMwMr4VMNknnVv3RpytrLSdgpvMcTnfNhrBJ,
172+
// size: 3739
173+
// }
187174
```
188175

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

0 commit comments

Comments
 (0)