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

Commit 03d31cd

Browse files
alanshawalanshaw
authored
docs: make constructor options linkable (#1486)
* docs: make constructor options linkable This PR changes the constructor options into headings so that people can link the relevant options. I have needed this multiple times but haven't been able to give people a link to the correct part of the page. License: MIT Signed-off-by: Alan Shaw <[email protected]> * Fix README typos and add links where we now can This also unifies the style in all the places where default values are different in various environments: use a comma between each environment. License: MIT Signed-off-by: Rob Brackett <[email protected]>
1 parent d0b671b commit 03d31cd

File tree

1 file changed

+105
-39
lines changed

1 file changed

+105
-39
lines changed

‎README.md‎

Lines changed: 105 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -202,56 +202,122 @@ const node = new IPFS([options])
202202

203203
Creates and returns an instance of an IPFS node. Use the `options` argument to specify advanced configuration. It is an object with any of these properties:
204204

205-
- `repo` (string or [`ipfs.Repo`](https://github.com/ipfs/js-ipfs-repo) instance): The file path at which to store the IPFS node’s data. Alternatively, you can set up a customized storage system by providing an [`ipfs.Repo`](https://github.com/ipfs/js-ipfs-repo) instance. (Default: `'~/.jsipfs'` in Node.js, `'ipfs'` in browsers.)
206205

207-
Example:
206+
##### `options.repo`
208207

209-
```js
210-
// Store data outside your user directory
211-
const node = new IPFS({ repo: '/var/ipfs/data' })
212-
```
208+
| Type | Default |
209+
|------|---------|
210+
| string or [`ipfs.Repo`](https://github.com/ipfs/js-ipfs-repo) instance | `'~/.jsipfs'` in Node.js, `'ipfs'` in browsers |
211+
212+
The file path at which to store the IPFS node’s data. Alternatively, you can set up a customized storage system by providing an [`ipfs.Repo`](https://github.com/ipfs/js-ipfs-repo) instance.
213+
214+
Example:
215+
216+
```js
217+
// Store data outside your user directory
218+
const node = new IPFS({ repo: '/var/ipfs/data' })
219+
```
220+
221+
##### `options.init`
222+
223+
| Type | Default |
224+
|------|---------|
225+
| boolean or object | `true` |
226+
227+
Initialize the repo when creating the IPFS node.
228+
229+
If you have already initialized a repo before creating your IPFS node (e.g. you are loading a repo that was saved to disk from a previous run of your program), you must make sure to set this to `false`. Note that *initializing* a repo is different from creating an instance of [`ipfs.Repo`](https://github.com/ipfs/js-ipfs-repo). The IPFS constructor sets many special properties when initializing a repo, so you should usually not try and call `repoInstance.init()` yourself.
230+
231+
Instead of a boolean, you may provide an object with custom initialization options. All properties are optional:
232+
233+
- `emptyRepo` (boolean) Whether to remove built-in assets, like the instructional tour and empty mutable file system, from the repo. (Default: `false`)
234+
- `bits` (number) Number of bits to use in the generated key pair. (Default: `2048`)
235+
- `pass` (string) A passphrase to encrypt keys. You should generally use the [top-level `pass` option](#optionspass) instead of the `init.pass` option (this one will take its value from the top-level option if not set).
236+
237+
##### `options.start`
238+
239+
| Type | Default |
240+
|------|---------|
241+
| boolean | `true` |
242+
243+
If `false`, do not automatically start the IPFS node. Instead, you’ll need to manually call [`node.start()`](#nodestartcallback) yourself.
244+
245+
##### `options.pass`
246+
247+
| Type | Default |
248+
|------|---------|
249+
| string | `null` |
250+
251+
A passphrase to encrypt/decrypt your keys.
252+
253+
##### `options.relay`
254+
255+
| Type | Default |
256+
|------|---------|
257+
| object | `{ enabled: false, hop: { enabled: false, active: false } }` |
258+
259+
Configure circuit relay (see the [circuit relay tutorial](https://github.com/ipfs/js-ipfs/tree/master/examples/circuit-relaying) to learn more).
260+
261+
- `enabled` (boolean): Enable circuit relay dialer and listener. (Default: `false`)
262+
- `hop` (object)
263+
- `enabled` (boolean): Make this node a relay (other nodes can connect *through* it). (Default: `false`)
264+
- `active` (boolean): Make this an *active* relay node. Active relay nodes will attempt to dial a destination peer even if that peer is not yet connected to the relay. (Default: `false`)
265+
266+
##### `options.preload`
267+
268+
| Type | Default |
269+
|------|---------|
270+
| object | `{ enabled: true, addresses: [...] }` |
271+
272+
Configure external nodes that will preload content added to this node.
273+
274+
- `enabled` (boolean): Enable content preloading (Default: `true`)
275+
- `addresses` (array): Multiaddr API addresses of nodes that should preload content. **NOTE:** nodes specified here should also be added to your node's bootstrap address list at [`config.Boostrap`](#optionsconfig).
276+
277+
##### `options.EXPERIMENTAL`
278+
279+
| Type | Default |
280+
|------|---------|
281+
| object | `{ pubsub: false, sharding: false, dht: false }` |
282+
283+
Enable and configure experimental features.
213284

214-
- `init` (boolean or object): Initialize the repo when creating the IPFS node. (Default: `true`)
285+
- `pubsub` (boolean): Enable libp2p pub-sub. (Default: `false`)
286+
- `sharding` (boolean): Enable directory sharding. Directories that have many child objects will be represented by multiple DAG nodes instead of just one. It can improve lookup performance when a directory has several thousand files or more. (Default: `false`)
287+
- `dht` (boolean): Enable KadDHT. **This is currently not interopable with `go-ipfs`.**
215288

216-
If you have already initialized a repo before creating your IPFS node (e.g. you are loading a repo that was saved to disk from a previous run of your program), you must make sure to set this to `false`. Note that *initializing* a repo is different from creating an instance of [`ipfs.Repo`](https://github.com/ipfs/js-ipfs-repo). The IPFS constructor sets many special properties when initializing a repo, so you should usually not try and call `repoInstance.init()` yourself.
289+
##### `options.config`
217290

218-
Instead of a boolean, you may provide an object with custom initialization options. All properties are optional:
291+
| Type | Default |
292+
|------|---------|
293+
| object | [`config-nodejs.js`](https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime/config-nodejs.js) in Node.js, [`config-browser.js`](https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime/config-browser.js) in browsers |
219294

220-
- `init.emptyRepo` (boolean) Whether to remove built-in assets, like the instructional tour and empty mutable file system, from the repo. (Default: `false`)
221-
- `init.bits` (number) Number of bits to use in the generated key pair. (Default: `2048`)
222-
- `init.pass` (string) A passphrase to encrypt keys. You should generally use the top-level `pass` option instead of the `init.pass` option (this one will take its value from the top-level option if not set).
295+
Modify the default IPFS node config. This object will be *merged* with the default config; it will not replace it.
223296

224-
- `start` (boolean): If `false`, do not automatically start the IPFS node. Instead, you’ll need to manually call `node.start()` yourself. (Default: `true`)
297+
##### `options.libp2p`
225298

226-
- `pass` (string): A passphrase to encrypt/decrypt your keys.
299+
| Type | Default |
300+
|------|---------|
301+
| object | [`libp2p-nodejs.js`](https://github.com/ipfs/js-ipfs/blob/master/src/core/runtime/libp2p-nodejs.js) in Node.js, [`libp2p-browser.js`](https://github.com/ipfs/js-ipfs/blob/master/src/core/runtime/libp2p-browser.js) in browsers |
227302

228-
- `relay` (object): Configure circuit relay (see the [circuit relay tutorial](https://github.com/ipfs/js-ipfs/tree/master/examples/circuit-relaying) to learn more).
229-
- `enabled` (boolean): Enable circuit relay dialer and listener. (Default: `false`)
230-
- `hop` (object)
231-
- `enabled` (boolean): Make this node a relay (other nodes can connect *through* it). (Default: `false`)
232-
- `active` (boolean): Make this an *active* relay node. Active relay nodes will attempt to dial a destination peer even if that peer is not yet connected to the relay. (Default: `false`)
303+
Add custom modules to the libp2p stack of your node.
233304

234-
- `preload` (object): Configure external nodes that will preload content added to this node
235-
- `enabled` (boolean): Enable content preloading (Default: `true`)
236-
- `addresses` (array): Multiaddr API addresses of nodes that should preload content. NOTE: nodes specified here should also be added to your node's bootstrap address list at `config.Boostrap`
237-
- `EXPERIMENTAL` (object): Enable and configure experimental features.
238-
- `pubsub` (boolean): Enable libp2p pub-sub. (Default: `false`)
239-
- `sharding` (boolean): Enable directory sharding. Directories that have many child objects will be represented by multiple DAG nodes instead of just one. It can improve lookup performance when a directory has several thousand files or more. (Default: `false`)
240-
- `dht` (boolean): Enable KadDHT. **This is currently not interopable with `go-ipfs`.**
305+
- `modules` (object):
306+
- `transport` (Array<[libp2p.Transport](https://github.com/libp2p/interface-transport)>): An array of Libp2p transport classes/instances to use _instead_ of the defaults. See [libp2p/interface-transport](https://github.com/libp2p/interface-transport) for details.
307+
- `peerDiscovery` (Array<[libp2p.PeerDiscovery](https://github.com/libp2p/interface-peer-discovery)>): An array of Libp2p peer discovery classes/instances to use _instead_ of the defaults. See [libp2p/peer-discovery](https://github.com/libp2p/interface-peer-discovery) for details. If passing a class, configuration can be passed using the config section below under the key corresponding to you module's unique `tag` (a static property on the class)
308+
- `config` (object):
309+
- `peerDiscovery` (object):
310+
- `[PeerDiscovery.tag]` (object): configuration for a peer discovery module
311+
- `enabled` (boolean): whether this module is enabled or disabled
312+
- `[custom config]` (any): other keys are specific to the module
241313

242-
- `config` (object) Modify the default IPFS node config. Find the Node.js defaults at [`src/core/runtime/config-nodejs.js`](https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime/config-nodejs.js) and the browser defaults at [`src/core/runtime/config-browser.js`](https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime/config-browser.js). This object will be *merged* with the default config; it will not replace it.
314+
##### `options.connectionManager`
243315

244-
- `libp2p` (object) add custom modules to the libp2p stack of your node
245-
- `modules` (object):
246-
- `transport` (Array<[libp2p.Transport](https://github.com/libp2p/interface-transport)>): An array of Libp2p transport classes/instances to use _instead_ of the defaults. See [libp2p/interface-transport](https://github.com/libp2p/interface-transport) for details.
247-
- `peerDiscovery` (Array<[libp2p.PeerDiscovery](https://github.com/libp2p/interface-peer-discovery)>): An array of Libp2p peer discovery classes/instances to use _instead_ of the defaults. See [libp2p/peer-discovery](https://github.com/libp2p/interface-peer-discovery) for details. If passing a class, configuration can be passed using the config section below under the key corresponding to you module's unique `tag` (a static property on the class)
248-
- `config` (object):
249-
- `peerDiscovery` (object):
250-
- `[PeerDiscovery.tag]` (object): configuration for a peer discovery module
251-
- `enabled` (boolean): whether this module is enabled or disabled
252-
- `[custom config]` (any): other keys are specific to the module
316+
| Type | Default |
317+
|------|---------|
318+
| object | [defaults](https://github.com/libp2p/js-libp2p-connection-manager#create-a-connectionmanager) |
253319

254-
- `connectionManager` (object): Configure the libp2p connection manager, see the [documentation for available options](https://github.com/libp2p/js-libp2p-connection-manager#create-a-connectionmanager).
320+
Configure the libp2p connection manager.
255321

256322
#### Events
257323

@@ -363,10 +429,10 @@ The core API is grouped into several areas:
363429
- [`ipfs.files.addPullStream([options])`](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md#filesaddpullstream)
364430
- [`ipfs.files.addReadableStream([options])`](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md#filesaddreadablestream)
365431
- [`ipfs.files.cat(ipfsPath, [options], [callback])`](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md#filescat). Alias to `ipfs.cat`.
366-
- [`ipfs.files.catPullStream(ipfsPath, [options])`](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md#filescatpullstream)
432+
- [`ipfs.files.catPullStream(ipfsPath, [options])`](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md#filescatpullstream)
367433
- [`ipfs.files.catReadableStream(ipfsPath, [options])`](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md#filescatreadablestream)
368434
- [`ipfs.files.get(ipfsPath, [options], [callback])`](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md#filesget). Alias to `ipfs.get`.
369-
- [`ipfs.files.getPullStream(ipfsPath, [options])`](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md#filesgetpullstream)
435+
- [`ipfs.files.getPullStream(ipfsPath, [options])`](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md#filesgetpullstream)
370436
- [`ipfs.files.getReadableStream(ipfsPath, [options])`](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md#filesgetreadablestream)
371437
- [`ipfs.ls(ipfsPath, [callback])`](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md#ls)
372438
- [`ipfs.lsPullStream(ipfsPath)`](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md#lspullstream)

0 commit comments

Comments
 (0)