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
put
Put a value to the pubsub datastore indexed by the received key properly encoded.
Parameters
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.
Returns
void
cancel
Cancel pubsub subscriptions related to ipns.
Parameters
name: String
:ipns path to cancel the pubsub subscription.
Returns
void
put
Put a value to the local datastore indexed by the received key properly encoded.
Parameters
Returns
void
version
If the repo has been initialized, report the current version. Otherwise report the version that would be initialized.
Returns
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
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
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
objectAPI: IPFS
:The IPFS object apicallback: Function<err, res>
:res is Array<Buffer(hash)> if no callback is passed, returns a Promise
Returns
(Promise | void)
glob-source
Create a pull stream source that can be piped to ipfs.addPullStream for the provided file paths.
Parameters
args: ...any
:
Returns
Function
pull stream source
parseChunkerString
Parses chunker string into options used by DAGBuilder in ipfs-unixfs-engine
Parameters
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
chunker: String
:Chunker algorithm supported formats: "rabin" "rabin-{avg}" "rabin-{min}-{avg}-{max}"
Returns
Object
rabin chunker options
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.
Returns
(Promise | void)
findprovs
Find peers in the DHT that can provide a specific value, given a key.
Returns
(Promise<PeerInfo> | void)
findpeer
Query the DHT for all multiaddresses associated with a PeerId
.
Parameters
peer: PeerId
:The id of the peer to search for.
provide
Announce to the network that we are providing given values.
Parameters
Returns
(Promise | void)
query
Find the closest peers to a given PeerId
, by querying the DHT.
Parameters
peer: PeerId
:ThePeerId
to run the query agains.
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
Returns
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
value: String
:ipfs path of the object to be published.options: Object
:ipfs publish options.options.resolve: boolean
:resolve given path before publishing.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.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).options.key: String
:name of the key to be used or a valid PeerID, as listed by 'ipfs key list -l'.callback: function (Error)?
:
Returns
(Promise | void)