Skip to content
This repository has been archived by the owner on Feb 12, 2024. It is now read-only.

Commit

Permalink
fix: optional arguments go in the options object (#3118)
Browse files Browse the repository at this point in the history 
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 <hugomrdias@gmail.com>
  • Loading branch information
@achingbrain @hugomrdias
achingbrain and hugomrdias committed Jul 2, 2020
1 parent 65f8b23 commit 8cb8c73
Show file tree
Hide file tree
Showing 86 changed files with 1,088 additions and 502 deletions.
54 changes: 44 additions & 10 deletions docs/core-api/BITSWAP.md
View file
Original file line number Diff line number Diff line change
@@ -1,30 +1,33 @@
# Bitswap API <!-- omit in toc -->

- [`ipfs.bitswap.wantlist([peerId,] [options])`](#ipfsbitswapwantlistpeerid-options)
- [`ipfs.bitswap.wantlist([options])`](#ipfsbitswapwantlistoptions)
- [Parameters](#parameters)
- [Options](#options)
- [Returns](#returns)
- [Example](#example)
- [`ipfs.bitswap.unwant(cids, [options])`](#ipfsbitswapunwantcids-options)
- [`ipfs.bitswap.wantlistForPeer(peerId, [options])`](#ipfsbitswapwantlistforpeerpeerid-options)
- [Parameters](#parameters-1)
- [Options](#options-1)
- [Returns](#returns-1)
- [Example](#example-1)
- [`ipfs.bitswap.stat([options])`](#ipfsbitswapstatoptions)
- [`ipfs.bitswap.unwant(cids, [options])`](#ipfsbitswapunwantcids-options)
- [Parameters](#parameters-2)
- [Options](#options-2)
- [Returns](#returns-2)
- [Example](#example-2)
- [`ipfs.bitswap.stat([options])`](#ipfsbitswapstatoptions)
- [Parameters](#parameters-3)
- [Options](#options-3)
- [Returns](#returns-3)
- [Example](#example-3)

## `ipfs.bitswap.wantlist([peerId,] [options])`
## `ipfs.bitswap.wantlist([options])`

> Returns the wantlist, optionally filtered by peer ID
> Returns the wantlist for your node
### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| peerId | [PeerId][], [CID][], `String` or `Buffer` | An optional peer ID to return the wantlist for |
None

### Options

Expand All @@ -47,9 +50,40 @@ An optional object which may have the following keys:
const list = await ipfs.bitswap.wantlist()
console.log(list)
// [ CID('QmHash') ]
```

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

## `ipfs.bitswap.wantlistForPeer(peerId, [options])`

> Returns the wantlist for a connected peer
### Parameters

| Name | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| peerId | [PeerId][], [CID][], `String` or `Buffer` | A peer ID to return the wantlist for |

### 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<CID[]>` | An array of [CID][]s currently in the wantlist |

const list2 = await ipfs.bitswap.wantlist(peerId)
console.log(list2)
### Example

```JavaScript
const list = await ipfs.bitswap.wantlistForPeer(peerId)
console.log(list)
// [ CID('QmHash') ]
```

Expand Down
116 changes: 101 additions & 15 deletions docs/core-api/BOOTSTRAP.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -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<{ Peers: Array<MultiAddr> }>` | 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
Expand Down Expand Up @@ -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<{ Peers: Array<MultiAddr> }>` | 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

Expand All @@ -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, ...]
Expand Down
26 changes: 13 additions & 13 deletions docs/core-api/DAG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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 |
Expand Down Expand Up @@ -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
Expand All @@ -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 |
Expand Down
Loading

0 comments on commit 8cb8c73

Please sign in to comment.