ipfs
0.36.3

- Intro
- put
- get
- getSubscriptions
- cancel
- version
- put
- get
- parseIpfsPath
- normalizePath
- resolvePath
- pin.proto
- glob-source
- parseChunkerString
- parseRabinString
- get
- put
- findProvs
- findPeer
- provide
- query
- cidToString
- publish
- resolve
- state
- cancel
- subs

# Intro

Installable via `npm install --save ipfs`, it can also be used directly in the browser.

## Download

The source is available for download from GitHub. Alternatively, you can install using npm:

    $ npm install --save ipfs

You can then `require()` ipfs as normal:

    const ipfs = require('ipfs')

## In the Browser

Ipfs should work in any ES2015 environment out of the box.

Usage:

    <script type="text/javascript" src="index.js"></script>

The portable versions of ipfs, including `index.js` and `index.min.js`, are included in the `/dist` folder. Ipfs can also be found on unpkg.com under

- https://unpkg.com/ipfs/dist/index.min.js
- https://unpkg.com/ipfs/dist/index.js

# put

Put a value to the pubsub datastore indexed by the received key properly encoded.

#### Parameters

1. `key: Buffer`:
   identifier of the value.
2. `value: Buffer`:
   value to be stored.
3. `callback: function (Error)`:

#### Returns

`void`

# get

Get a value from the pubsub datastore indexed by the received key properly encoded. Moreover, the identifier topic is subscribed and the pubsub datastore records will be updated once new publishes occur.

#### Parameters

1. `key: Buffer`:
   identifier of the value to be obtained.
2. `callback: function (Error, Buffer)`:

#### Returns

`void`

# getSubscriptions

Get pubsub subscriptions related to ipns.

#### Parameters

1. `callback: function (Error, Object)`:

#### Returns

`void`

# cancel

Cancel pubsub subscriptions related to ipns.

#### Parameters

1. `name: String`:
   ipns path to cancel the pubsub subscription.
2. `callback: function (Error, Object)`:

#### Returns

`void`

# version

If the repo has been initialized, report the current version. Otherwise report the version that would be initialized.

#### Parameters

1. `callback: function (Error, Number)?`:

#### Returns

`undefined`

# put

Put a value to the local datastore indexed by the received key properly encoded.

#### Parameters

1. `key: Buffer`:
   identifier of the value.
2. `value: Buffer`:
   value to be stored.
3. `callback: function (Error)`:

#### Returns

`void`

# get

Get a value from the local datastore indexed by the received key properly encoded.

#### Parameters

1. `key: Buffer`:
   identifier of the value to be obtained.
2. `callback: function (Error, Buffer)`:

#### Returns

`void`

# parseIpfsPath

Break an ipfs-path down into it's hash and an array of links.

examples: b58Hash -> { hash: 'b58Hash', links: [] } b58Hash/mercury/venus -> { hash: 'b58Hash', links: ['mercury', 'venus']} /ipfs/b58Hash/links/by/name -> { hash: 'b58Hash', links: ['links', 'by', 'name'] }

#### Parameters

1. `ipfsPath: String`:
   An ipfs-path

#### Returns

`Object` { hash: base58 string, links: [string] , ?err: Error }

#### Throws

`any` on an invalid @param ipfsPath

# normalizePath

Returns a well-formed ipfs Path. The returned path will always be prefixed with /ipfs/ or /ipns/. If the received string is not a valid ipfs path, an error will be returned examples: b58Hash -> { hash: 'b58Hash', links: [] } b58Hash/mercury/venus -> { hash: 'b58Hash', links: ['mercury', 'venus']} /ipfs/b58Hash/links/by/name -> { hash: 'b58Hash', links: ['links', 'by', 'name'] }

#### Parameters

1. `pathStr: String`:
   An ipfs-path, or ipns-path or a cid

#### Returns

`String` ipfs-path or ipns-path

#### Throws

`any` on an invalid @param ipfsPath

# resolvePath

Resolve various styles of an ipfs-path to the hash of the target node. Follows links in the path.

Accepts formats:

- /link/to/venus
- /ipfs//link/to/pluto
- multihash Buffer
- Arrays of the above

#### Parameters

1. `objectAPI: IPFS`:
   The IPFS object api
2. `callback: Function<err, res>`:
   res is Array<Buffer(hash)> if no callback is passed, returns a Promise

#### Returns

`(Promise | void)`

# pin.proto

Protobuf interface from go-ipfs/pin/internal/pb/header.proto

# glob-source

Create a pull stream source that can be piped to ipfs.addPullStream for the provided file paths.

#### Parameters

1. `args: ...any`:
2. `options: Object?`:
   Optional options
3. `options.recursive: Boolean?`:
   Recursively glob all paths in directories
4. `options.hidden: Boolean?`:
   Include .dot files in matched paths
5. `options.ignore: Array<String>?`:
   Glob paths to ignore
6. `options.followSymlinks: Boolean?`:
   follow symlinks

#### Returns

`Function` pull stream source

# parseChunkerString

Parses chunker string into options used by DAGBuilder in ipfs-unixfs-engine

#### Parameters

1. `chunker: String`:
   Chunker algorithm supported formats: "size-{size}" "rabin" "rabin-{avg}" "rabin-{min}-{avg}-{max}"

#### Returns

`Object` Chunker options for DAGBuilder

# parseRabinString

Parses rabin chunker string

#### Parameters

1. `chunker: String`:
   Chunker algorithm supported formats: "rabin" "rabin-{avg}" "rabin-{min}-{avg}-{max}"

#### Returns

`Object` rabin chunker options

# get

Given a key, query the DHT for its best value.

#### Parameters

1. `key: Buffer`:
2. `options: Object`:
   get options
3. `options.timeout: number`:
   optional timeout
4. `callback: function (Error)?`:

#### Returns

`(Promise | void)`

# put

Write a key/value pair to the DHT.

Given a key of the form /foo/bar and a value of any form, this will write that value to the DHT with that key.

#### Parameters

1. `key: Buffer`:
2. `value: Buffer`:
3. `callback: function (Error)?`:

#### Returns

`(Promise | void)`

# findProvs

Find peers in the DHT that can provide a specific value, given a key.

#### Parameters

1. `key: CID`:
   They key to find providers for.
2. `options: Object`:
   findProviders options
3. `options.timeout: number`:
   how long the query should maximally run, in milliseconds (default: 60000)
4. `options.maxNumProviders: number`:
   maximum number of providers to find
5. `callback: function (Error, Array<PeerInfo>)?`:

#### Returns

`(Promise<PeerInfo> | void)`

# findPeer

Query the DHT for all multiaddresses associated with a `PeerId`.

#### Parameters

1. `peer: PeerId`:
   The id of the peer to search for.
2. `callback: function (Error, PeerInfo)?`:

#### Returns

`(Promise<PeerInfo> | void)`

# provide

Announce to the network that we are providing given values.

#### Parameters

1. `keys: (CID | Array<CID>)`:
   The keys that should be announced.
2. `options: Object`:
   provide options
3. `options.recursive: bool (=false)`:
   Provide not only the given object but also all objects linked from it.
4. `callback: function (Error)?`:

#### Returns

`(Promise | void)`

# query

Find the closest peers to a given `PeerId`, by querying the DHT.

#### Parameters

1. `peer: PeerId`:
   The `PeerId` to run the query agains.
2. `callback: function (Error, Array<PeerInfo>)?`:

#### Returns

`(Promise<Array<PeerInfo>> | void)`

# cidToString

Stringify a CID encoded in the requested base, upgrading to v1 if necessary.

Setting upgrade to false will disable automatic CID upgrading from v0 to v1 which is necessary if the multibase is something other than base58btc. Note that it will also not apply the encoding (since v0 CIDs can only be encoded as base58btc).

#### Parameters

1. `cid: (CID | Buffer | String)`:
   The CID to encode
2. `options: Object?`:
   Optional options
3. `options.base: String?`:
   Name of multibase codec to encode the CID with
4. `options.upgrade: Boolean?`:
   Automatically upgrade v0 CIDs to v1 when necessary. Default: true.

#### Returns

`String`

# publish

IPNS is a PKI namespace, where names are the hashes of public keys, and the private key enables publishing new (signed) values. In both publish and resolve, the default name used is the node's own PeerID, which is the hash of its public key.

#### Parameters

1. `value: String`:
   ipfs path of the object to be published.
2. `options: Object`:
   ipfs publish options.
3. `options.resolve: boolean`:
   resolve given path before publishing.
4. `options.lifetime: String`:
   time duration that the record will be valid for. This accepts durations such as "300s", "1.5h" or "2h45m". Valid time units are "ns", "ms", "s", "m", "h". Default is 24h.
5. `options.ttl: String`:
   time duration this record should be cached for (NOT IMPLEMENTED YET). This accepts durations such as "300s", "1.5h" or "2h45m". Valid time units are "ns", "ms", "s", "m", "h" (caution: experimental).
6. `options.key: String`:
   name of the key to be used, as listed by 'ipfs key list -l'.
7. `callback: function (Error)?`:

#### Returns

`(Promise | void)`

# resolve

Given a key, query the DHT for its best value.

#### Parameters

1. `name: String`:
   ipns name to resolve. Defaults to your node's peerID.
2. `options: Object`:
   ipfs resolve options.
3. `options.nocache: boolean`:
   do not use cached entries.
4. `options.recursive: boolean`:
   resolve until the result is not an IPNS name.
5. `callback: function (Error)?`:

#### Returns

`(Promise | void)`

# state

Query the state of IPNS pubsub.

#### Returns

`(Promise | void)`

# cancel

Cancel a name subscription.

#### Parameters

1. `name: String`:
   subscription name.
2. `callback: function (Error)?`:

#### Returns

`(Promise | void)`

# subs

Show current name subscriptions.

#### Parameters

1. `callback: function (Error)?`:

#### Returns

`(Promise | void)`