You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Feb 12, 2024. It is now read-only.
fix: optional arguments go in the options object (#3118)
We have a few older APIs that take multiple optional arguments, which makes our code more complicated as it has to guess the users' intent, sometimes by inspecting properties on the passed args to see if they happen to correspond with properties on the actual options object.
The options object was recently added to all API calls and is the right place for optional arguments to go, so the change here is to move all optional arguments into the options object, except where the presence of an optional argument dramatically changes the behaviour of the call (`ipfs.bootstrap` I'm mostly looking at you), in which case the methods are split out into multiple versions that do distinct things.
Only the programatic API is affected, the CLI and HTTP APIs do not change.
BREAKING CHANGES:
- `ipfs.bitswap.wantlist([peer], [options])` is split into:
- `ipfs.bitswap.wantlist([options])`
- `ipfs.bitswap.wantlistForPeer(peer, [options])`
- `ipfs.bootstrap.add([addr], [options])` is split into:
- `ipfs.bootstrap.add(addr, [options])` - add a bootstrap node
- `ipfs.bootstrap.reset()` - restore the default list of bootstrap nodes
- `ipfs.bootstrap.rm([addr], [options])` is split into:
- `ipfs.bootstrap.rm(addr, [options])` - remove a bootstrap node
- `ipfs.bootstrap.clear([options])` - empty the bootstrap list
- `ipfs.dag.get(cid, [path], [options])` becomes `ipfs.dag.get(cid, [options])`
- `path` is moved into the `options` object
- `ipfs.dag.tree(cid, [path], [options])` becomes `ipfs.dag.tree(cid, [options])`
- `path` is moved into the `options` object
- `ipfs.dag.resolve(cid, [path], [options])` becomes `ipfs.dag.resolve(cid, [options])`
- `path` is moved into the `options` object
- `ipfs.files.flush([path], [options])` becomes `ipfs.files.flush(path, [options])`
- `ipfs.files.ls([path], [options])` becomes `ipfs.files.ls(path, [options])`
- `ipfs.object.new([template], [options])` becomes `ipfs.object.new([options])`
- `template` is moved into the `options` object
- `ipfs.pin.ls([paths], [options])` becomes `ipfs.pin.ls([options])`
- `paths` is moved into the `options` object
Co-authored-by: Hugo Dias <[email protected]>
Copy file name to clipboardExpand all lines: docs/core-api/BOOTSTRAP.md
+101-15
Original file line number
Diff line number
Diff line change
@@ -4,46 +4,53 @@
4
4
5
5
Warning: your node requires bootstrappers to join the network and find other peers.
6
6
7
-
If you edit this list, you may find you have reduced or no connectivity. If this is the case, please reset your node's bootstrapper list with `ipfs.bootstrap.add({ default: true })`.
7
+
If you edit this list, you may find you have reduced or no connectivity. If this is the case, please reset your node's bootstrapper list with `ipfs.bootstrap.reset()`.
| addr |[MultiAddr][]| The address of a network peer. If omitted the `default` option must be passed as `true`.|
43
+
| addr |[MultiAddr][]| The address of a network peer |
34
44
35
45
### Options
36
46
37
47
An optional object which may have the following keys:
38
48
39
49
| Name | Type | Default | Description |
40
50
| ---- | ---- | ------- | ----------- |
41
-
| default |`boolean`|`false`| If true, add the default peers to the list |
42
51
| timeout |`Number`|`undefined`| A timeout in ms |
43
52
| signal |[AbortSignal][]|`undefined`| Can be used to cancel any long running requests started as a result of this call |
44
53
45
-
Note: If passing the `default` option, `addr` is an optional parameter (may be `undefined`/`null`) and options may be passed as the first argument. i.e. `ipfs.bootstrap.add({ default: true })`
46
-
47
54
### Returns
48
55
49
56
| Type | Description |
@@ -71,6 +78,48 @@ console.log(res.Peers)
71
78
72
79
A great source of [examples][] can be found in the tests for this API.
73
80
81
+
## `ipfs.bootstrap.reset([options])`
82
+
83
+
> Reset the bootstrap list to contain only the default bootstrap nodes
84
+
85
+
### Parameters
86
+
87
+
None.
88
+
89
+
### Options
90
+
91
+
An optional object which may have the following keys:
92
+
93
+
| Name | Type | Default | Description |
94
+
| ---- | ---- | ------- | ----------- |
95
+
| timeout |`Number`|`undefined`| A timeout in ms |
96
+
| signal |[AbortSignal][]|`undefined`| Can be used to cancel any long running requests started as a result of this call |
97
+
98
+
### Returns
99
+
100
+
| Type | Description |
101
+
| -------- | -------- |
102
+
|`Promise<{ Peers: Array<MultiAddr> }>`| An object that contains an array with all the added addresses |
103
+
104
+
example of the returned object:
105
+
106
+
```JavaScript
107
+
{
108
+
Peers: [address1, address2, ...]
109
+
}
110
+
```
111
+
112
+
### Example
113
+
114
+
```JavaScript
115
+
constres=awaitipfs.bootstrap.reset()
116
+
console.log(res.Peers)
117
+
// Logs:
118
+
// ['/ip4/104....9z']
119
+
```
120
+
121
+
A great source of [examples][] can be found in the tests for this API.
122
+
74
123
## `ipfs.bootstrap.list([options])`
75
124
76
125
> List all peer addresses in the bootstrap list
@@ -113,27 +162,64 @@ console.log(res.Peers)
113
162
114
163
A great source of [examples][] can be found in the tests for this API.
115
164
116
-
## `ipfs.bootstrap.rm([addr,] [options])`
165
+
## `ipfs.bootstrap.rm(addr, [options])`
117
166
118
167
> Remove a peer address from the bootstrap list
119
168
120
169
### Parameters
121
170
122
171
| Name | Type | Description |
123
172
| ---- | ---- | ----------- |
124
-
| addr |[MultiAddr][]| The address of a network peer. If omitted the `all` option must be passed as `true`.|
173
+
| addr |[MultiAddr][]| The address of a network peer |
125
174
126
175
### Options
127
176
128
177
An optional object which may have the following keys:
129
178
130
179
| Name | Type | Default | Description |
131
180
| ---- | ---- | ------- | ----------- |
132
-
| all |`boolean`|`false`| If true, remove all peers from the bootstrap list |
133
181
| timeout |`Number`|`undefined`| A timeout in ms |
134
182
| signal |[AbortSignal][]|`undefined`| Can be used to cancel any long running requests started as a result of this call |
135
183
136
-
Note: If passing the `all` option, `addr` is an optional parameter (may be `undefined`/`null`) and options may be passed as the first argument. i.e. `ipfs.bootstrap.rm({ all: true })`
184
+
### Returns
185
+
186
+
| Type | Description |
187
+
| -------- | -------- |
188
+
|`Promise<{ Peers: Array<MultiAddr> }>`| An object that contains an array with all the removed addresses |
189
+
190
+
```JavaScript
191
+
{
192
+
Peers: [address1, address2, ...]
193
+
}
194
+
```
195
+
196
+
### Example
197
+
198
+
```JavaScript
199
+
constres=awaitipfs.bootstrap.rm('address1')
200
+
console.log(res.Peers)
201
+
// Logs:
202
+
// [address1, ...]
203
+
```
204
+
205
+
A great source of [examples][] can be found in the tests for this API.
206
+
207
+
## `ipfs.bootstrap.clear([options])`
208
+
209
+
> Remove all peer addresses from the bootstrap list
210
+
211
+
### Parameters
212
+
213
+
None.
214
+
215
+
### Options
216
+
217
+
An optional object which may have the following keys:
218
+
219
+
| Name | Type | Default | Description |
220
+
| ---- | ---- | ------- | ----------- |
221
+
| timeout |`Number`|`undefined`| A timeout in ms |
222
+
| signal |[AbortSignal][]|`undefined`| Can be used to cancel any long running requests started as a result of this call |
137
223
138
224
### Returns
139
225
@@ -150,7 +236,7 @@ Note: If passing the `all` option, `addr` is an optional parameter (may be `unde
0 commit comments