fix: optional arguments go in the options object

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 paroperties 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])` becomes `ipfs.bitswap([options])` - `peer` is moved into the `options` object - `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
ipfs · Jul 1, 2020 · 52e04f6 · 52e04f6
1 parent 21dab48
commit 52e04f6
Show file tree

Hide file tree

Showing 79 changed files with 910 additions and 482 deletions.
diff --git a/docs/core-api/BITSWAP.md b/docs/core-api/BITSWAP.md
@@ -1,6 +1,6 @@
 # Bitswap API <!-- omit in toc -->
 
-- [`ipfs.bitswap.wantlist([peerId,] [options])`](#ipfsbitswapwantlistpeerid-options)
+- [`ipfs.bitswap.wantlist([options])`](#ipfsbitswapwantlistoptions)
  - [Parameters](#parameters)
  - [Options](#options)
  - [Returns](#returns)
@@ -16,22 +16,21 @@
  - [Returns](#returns-2)
  - [Example](#example-2)
 
-## `ipfs.bitswap.wantlist([peerId,] [options])`
+## `ipfs.bitswap.wantlist([options])`
 
-> Returns the wantlist, optionally filtered by peer ID
+> Returns the wantlist for your node or for a connected peer
 
 ### Parameters
 
-| Name | Type | Description |
-| ---- | ---- | ----------- |
-| peerId | [PeerId][], [CID][], `String` or `Buffer` | An optional peer ID to return the wantlist for |
+None
 
 ### Options
 
 An optional object which may have the following keys:
 
 | Name | Type | Default | Description |
 | ---- | ---- | ------- | ----------- |
+| peer | [PeerId][], [CID][], `String` or `Buffer` | A peer ID to return the wantlist for |
 | timeout | `Number` | `undefined` | A timeout in ms |
 | signal | [AbortSignal][] | `undefined` | Can be used to cancel any long running requests started as a result of this call |
 
@@ -48,7 +47,7 @@ const list = await ipfs.bitswap.wantlist()
 console.log(list)
 // [ CID('QmHash') ]
 
-const list2 = await ipfs.bitswap.wantlist(peerId)
+const list2 = await ipfs.bitswap.wantlist({ peer: peerId })
 console.log(list2)
 // [ CID('QmHash') ]
 ```

diff --git a/docs/core-api/BOOTSTRAP.md b/docs/core-api/BOOTSTRAP.md
@@ -4,46 +4,53 @@
 
 Warning: your node requires bootstrappers to join the network and find other peers.
 
-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 })`.
+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()`.
 
-- [`ipfs.bootstrap.add([addr,] [options])`](#ipfsbootstrapaddaddr-options)
+- [`ipfs.bootstrap.add(addr, [options])`](#ipfsbootstrapaddaddr-options)
  - [Parameters](#parameters)
  - [Options](#options)
  - [Returns](#returns)
  - [Example](#example)
-- [`ipfs.bootstrap.list([options])`](#ipfsbootstraplistoptions)
+- [`ipfs.bootstrap.reset([options])`](#ipfsbootstrapresetoptions)
  - [Parameters](#parameters-1)
  - [Options](#options-1)
  - [Returns](#returns-1)
  - [Example](#example-1)
-- [`ipfs.bootstrap.rm([addr,] [options])`](#ipfsbootstraprmaddr-options)
+- [`ipfs.bootstrap.list([options])`](#ipfsbootstraplistoptions)
  - [Parameters](#parameters-2)
  - [Options](#options-2)
  - [Returns](#returns-2)
  - [Example](#example-2)
-
-## `ipfs.bootstrap.add([addr,] [options])`
+- [`ipfs.bootstrap.rm(addr, [options])`](#ipfsbootstraprmaddr-options)
+ - [Parameters](#parameters-3)
+ - [Options](#options-3)
+ - [Returns](#returns-3)
+ - [Example](#example-3)
+- [`ipfs.bootstrap.clear([options])`](#ipfsbootstrapclearoptions)
+ - [Parameters](#parameters-4)
+ - [Options](#options-4)
+ - [Returns](#returns-4)
+ - [Example](#example-4)
+
+## `ipfs.bootstrap.add(addr, [options])`
 
 > Add a peer address to the bootstrap list
 
 ### Parameters
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| addr | [MultiAddr][] | The address of a network peer. If omitted the `default` option must be passed as `true`. |
+| addr | [MultiAddr][] | The address of a network peer |
 
 ### Options
 
 An optional object which may have the following keys:
 
 | Name | Type | Default | Description |
 | ---- | ---- | ------- | ----------- |
-| default | `boolean` | `false` | If true, add the default peers to the list |
 | timeout | `Number` | `undefined` | A timeout in ms |
 | signal | [AbortSignal][] | `undefined` | Can be used to cancel any long running requests started as a result of this call |
 
-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 })`
-
 ### Returns
 
 | Type | Description |
@@ -71,6 +78,48 @@ console.log(res.Peers)
 
 A great source of [examples][] can be found in the tests for this API.
 
+## `ipfs.bootstrap.reset([options])`
+
+> Reset the bootstrap list to contain only the default bootstrap nodes
+
+### Parameters
+
+None.
+
+### Options
+
+An optional object which may have the following keys:
+
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| timeout | `Number` | `undefined` | A timeout in ms |
+| signal | [AbortSignal][] | `undefined` | Can be used to cancel any long running requests started as a result of this call |
+
+### Returns
+
+| Type | Description |
+| -------- | -------- |
+| `Promise<Object>` | An object that contains an array with all the added addresses |
+
+example of the returned object:
+
+```JavaScript
+{
+ Peers: [address1, address2, ...]
+}
+```
+
+### Example
+
+```JavaScript
+const res = await ipfs.bootstrap.reset()
+console.log(res.Peers)
+// Logs:
+// ['/ip4/104....9z']
+```
+
+A great source of [examples][] can be found in the tests for this API.
+
 ## `ipfs.bootstrap.list([options])`
 
 > List all peer addresses in the bootstrap list
@@ -113,27 +162,64 @@ console.log(res.Peers)
 
 A great source of [examples][] can be found in the tests for this API.
 
-## `ipfs.bootstrap.rm([addr,] [options])`
+## `ipfs.bootstrap.rm(addr, [options])`
 
 > Remove a peer address from the bootstrap list
 
 ### Parameters
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| addr | [MultiAddr][] | The address of a network peer. If omitted the `all` option must be passed as `true`. |
+| addr | [MultiAddr][] | The address of a network peer |
 
 ### Options
 
 An optional object which may have the following keys:
 
 | Name | Type | Default | Description |
 | ---- | ---- | ------- | ----------- |
-| all | `boolean` | `false` | If true, remove all peers from the bootstrap list |
 | timeout | `Number` | `undefined` | A timeout in ms |
 | signal | [AbortSignal][] | `undefined` | Can be used to cancel any long running requests started as a result of this call |
 
-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 })`
+### Returns
+
+| Type | Description |
+| -------- | -------- |
+| `Promise<Object>` | An object that contains an array with all the removed addresses |
+
+```JavaScript
+{
+ Peers: [address1, address2, ...]
+}
+```
+
+### Example
+
+```JavaScript
+const res = await ipfs.bootstrap.rm('address1')
+console.log(res.Peers)
+// Logs:
+// [address1, ...]
+```
+
+A great source of [examples][] can be found in the tests for this API.
+
+## `ipfs.bootstrap.clear([options])`
+
+> Remove all peer addresses from the bootstrap list
+
+### Parameters
+
+None.
+
+### Options
+
+An optional object which may have the following keys:
+
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| timeout | `Number` | `undefined` | A timeout in ms |
+| signal | [AbortSignal][] | `undefined` | Can be used to cancel any long running requests started as a result of this call |
 
 ### Returns
 
@@ -150,7 +236,7 @@ Note: If passing the `all` option, `addr` is an optional parameter (may be `unde
 ### Example
 
 ```JavaScript
-const res = await ipfs.bootstrap.rm(null, { all: true })
+const res = await ipfs.bootstrap.clear()
 console.log(res.Peers)
 // Logs:
 // [address1, address2, ...]

diff --git a/docs/core-api/DAG.md b/docs/core-api/DAG.md
@@ -7,12 +7,12 @@
  - [Options](#options)
  - [Returns](#returns)
  - [Example](#example)
-- [`ipfs.dag.get(cid, [path], [options])`](#ipfsdaggetcid-path-options)
+- [`ipfs.dag.get(cid, [options])`](#ipfsdaggetcid-path-options)
  - [Parameters](#parameters-1)
  - [Options](#options-1)
  - [Returns](#returns-1)
  - [Example](#example-1)
-- [`ipfs.dag.tree(cid, [path,] [options])`](#ipfsdagtreecid-path-options)
+- [`ipfs.dag.tree(cid, [options])`](#ipfsdagtreecid-path-options)
  - [Parameters](#parameters-2)
  - [Options](#options-2)
  - [Returns](#returns-2)
@@ -65,23 +65,23 @@ console.log(cid.toString())
 
 A great source of [examples][] can be found in the tests for this API.
 
-## `ipfs.dag.get(cid, [path], [options])`
+## `ipfs.dag.get(cid, [options])`
 
 > Retrieve an IPLD format node
 
 ### Parameters
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| cid | [CID][] | A DAG node that follows one of the supported IPLD formats |
-| path | `String` | An optional path within the DAG to resolve |
+| cid | [CID][] | A CID that resolves to a node to get |
 
 ### Options
 
 An optional object which may have the following keys:
 
 | Name | Type | Default | Description |
 | ---- | ---- | ------- | ----------- |
+| path | `String` | An optional path within the DAG to resolve |
 | localResolve | `boolean` | `false` | If set to true, it will avoid resolving through different objects |
 | timeout | `Number` | `undefined` | A timeout in ms |
 | signal | [AbortSignal][] | `undefined` | Can be used to cancel any long running requests started as a result of this call |
@@ -114,34 +114,34 @@ const cid = await ipfs.dag.put(obj, { format: 'dag-cbor', hashAlg: 'sha2-256' })
 console.log(cid.toString())
 // zdpuAmtur968yprkhG9N5Zxn6MFVoqAWBbhUAkNLJs2UtkTq5
 
-async function getAndLog(cidPath) {
- const result = await ipfs.dag.get(cidPath)
+async function getAndLog(cid, path) {
+ const result = await ipfs.dag.get(cid, { path })
  console.log(result.value)
 }
 
-await getAndLog('zdpuAmtur968yprkhG9N5Zxn6MFVoqAWBbhUAkNLJs2UtkTq5/a')
+await getAndLog(cid, '/a')
 // Logs:
 // 1
 
-await getAndLog('zdpuAmtur968yprkhG9N5Zxn6MFVoqAWBbhUAkNLJs2UtkTq5/b')
+await getAndLog(cid, '/b')
 // Logs:
 // [1, 2, 3]
 
-await getAndLog('zdpuAmtur968yprkhG9N5Zxn6MFVoqAWBbhUAkNLJs2UtkTq5/c')
+await getAndLog(cid, '/c')
 // Logs:
 // {
 // ca: [5, 6, 7],
 // cb: 'foo'
 // }
 
-await getAndLog('zdpuAmtur968yprkhG9N5Zxn6MFVoqAWBbhUAkNLJs2UtkTq5/c/ca/1')
+await getAndLog(cid, '/c/ca/1')
 // Logs:
 // 6
 ```
 
 A great source of [examples][] can be found in the tests for this API.
 
-## `ipfs.dag.tree(cid, [path,] [options])`
+## `ipfs.dag.tree(cid, [options])`
 
 > Enumerate all the entries in a graph
 
@@ -150,14 +150,14 @@ A great source of [examples][] can be found in the tests for this API.
 | Name | Type | Description |
 | ---- | ---- | ----------- |
 | cid | [CID][] | A DAG node that follows one of the supported IPLD formats |
-| path | `String` | An optional path within the DAG to resolve |
 
 ### Options
 
 An optional object which may have the following keys:
 
 | Name | Type | Default | Description |
 | ---- | ---- | ------- | ----------- |
+| path | `String` | An optional path within the DAG to resolve |
 | recursive | `boolean` | `false` | If set to true, it will follow the links and continuously run tree on them, returning all the paths in the graph |
 | timeout | `Number` | `undefined` | A timeout in ms |
 | signal | [AbortSignal][] | `undefined` | Can be used to cancel any long running requests started as a result of this call |

diff --git a/docs/core-api/FILES.md b/docs/core-api/FILES.md
@@ -72,11 +72,11 @@ _Explore the Mutable File System through interactive coding challenges in our [P
  - [Options](#options-12)
  - [Returns](#returns-11)
  - [Example](#example-8)
- - [`ipfs.files.flush([path,] [options])`](#ipfsfilesflushpath-options)
+ - [`ipfs.files.flush(path, [options])`](#ipfsfilesflushpath-options)
  - [Parameters](#parameters-13)
  - [Options](#options-13)
  - [Returns](#returns-12)
- - [`ipfs.files.ls([path], [options])`](#ipfsfileslspath-options)
+ - [`ipfs.files.ls(path, [options])`](#ipfsfileslspath-options)
  - [Parameters](#parameters-14)
  - [Options](#options-14)
  - [Returns](#returns-13)
@@ -869,15 +869,15 @@ If `from` is an IPFS path and the content does not exist in your node's repo, on
 
 All values of `from` will be removed after the operation is complete unless they are an IPFS path.
 
-### `ipfs.files.flush([path,] [options])`
+### `ipfs.files.flush(path, [options])`
 
 > Flush a given path's data to the disk
 
 #### Parameters
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| path | `String` | Optional [MFS path][] to flush, defaults to `'/'` |
+| path | `String` | The [MFS path][] to flush |
 
 #### Options
 
@@ -900,15 +900,15 @@ An optional object which may have the following keys:
 const cid = await ipfs.files.flush('/')
 ```
 
-### `ipfs.files.ls([path], [options])`
+### `ipfs.files.ls(path, [options])`
 
 > List directories in the local mutable namespace
 
 #### Parameters
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| path | `String` | Optional [MFS path][] to list, defaults to `'/'` |
+| path | `String` | The [MFS path][] to list |
 
 #### Options