0.41.0-rc.2Installable via npm install --save ipfs, it can also be used directly in the browser.
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')
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
Parses chunker string into options used by DAGBuilder in ipfs-unixfs-engine
(String)
Chunker algorithm supported formats:
"size-{size}"
"rabin"
"rabin-{avg}"
"rabin-{min}-{avg}-{max}"
Object:
Chunker options for DAGBuilder
Parses rabin chunker string
(String)
Chunker algorithm supported formats:
"rabin"
"rabin-{avg}"
"rabin-{min}-{avg}-{max}"
Object:
rabin chunker options
Protobuf interface from go-ipfs/pin/internal/pb/header.proto
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'] }
(String)
An ipfs-path
Object:
{ hash: base58 string, links:
[string]
, ?err: Error }
Returns a well-formed ipfs Path. The returned path will always be prefixed with /ipfs/ or /ipns/.
(String)
An ipfs-path, or ipns-path or a cid
String:
ipfs-path or ipns-path
Resolve various styles of an ipfs-path to the hash of the target node. Follows links in the path.
Accepts formats:
(Dag)
The IPFS dag api
(Object?)
Optional options passed directly to dag.resolve
Promise<Array<CID>>:
Change file mode
(String)
The path of the source to modify.
(Object)
The mode to set the path
(Object?)
Options for modification.
| Name | Description |
|---|---|
opts.recursive boolean
(default false)
|
Whether to change modes recursively. (default: false) |
opts.flush boolean
(default true)
|
Whether or not to immediately flush MFS changes to disk (default: true). |
opts.shardSplitThreshold number?
|
If the modified path has more than this many links it will be turned into a HAMT shard |
Promise<string>:
Copy files
(String)
The path of the destination to copy to.
(Object?)
Options for copy.
| Name | Description |
|---|---|
opts.parents boolean
(default false)
|
Whether or not to make the parent directories if they don't exist. (default: false) |
opts.format String
(default dag-pb)
|
Format of nodes to write any newly created directories as. (default: dag-pb) |
opts.hashAlg String
(default sha2-256)
|
Algorithm to use when creating CIDs for newly created directories. (default: sha2-256) The list of all possible values |
opts.flush boolean
(default true)
|
Whether or not to immediately flush MFS changes to disk (default: true). |
Promise<string>:
Make a directory
(String)
The path to the directory to make.
(Object?)
Options for mkdir.
| Name | Description |
|---|---|
opts.parents boolean
(default false)
|
Value to decide whether or not to make the parent directories if they don't exist. (default: false) |
opts.format String
(default dag-pb)
|
Format of nodes to write any newly created directories as. (default: dag-pb). |
opts.hashAlg String?
|
Algorithm to use when creating CIDs for newly created directories. (default: sha2-256) The list of all possible values |
opts.flush boolean
(default true)
|
Whether or not to immediately flush MFS changes to disk (default: true). |
Promise<void>:
Type: Object
(String)
: Output hash.
(number)
: File size in bytes.
(number)
: Integer with the size of the DAGNodes making up the file in Bytes.
(string)
: Output type either 'directory' or 'file'.
(number)
: If type is directory, this is the number of files in the directory. If it is file it is the number of blocks that make up the file.
(boolean)
: Indicate if locality information is present.
(boolean)
: Indicate if the queried dag is fully present locally.
(number)
: Integer indicating the cumulative size of the data present locally.
Get file or directory status.
(String)
Path to the file or directory to stat.
(Object?)
Options for stat.
| Name | Description |
|---|---|
opts.hash boolean
(default false)
|
Return only the hash. (default: false) |
opts.size boolean
(default false)
|
Return only the size. (default: false) |
opts.withLocal boolean
(default false)
|
Compute the amount of the dag that is local, and if possible the total size. (default: false) |
Promise<StatOutput>:
Remove a file or directory.
Promise<void>:
Type: Object
Read a file into a Buffer.
(string)
Path of the file to read and must point to a file (and not a directory).
(ReadOptions?)
Object for read.
AsyncIterable<Buffer>:
Update modification time
(String)
The path of the source to modify.
(number)
Time to use as the new modification time in seconds since (+ve) or before (-ve) the Unix Epoch
(Object?)
Options for touch.
| Name | Description |
|---|---|
opts.parents boolean
(default false)
|
Whether or not to make the parent directories if they don't exist. (default: false) |
opts.cidVersion number
(default 0)
|
CID version to use with the newly updated node |
opts.shardSplitThreshold number?
|
If the modified path has more than this many links it will be turned into a HAMT shard |
Promise<string>:
Write to a file.
(string)
Path of the file to write.
(Object)
Options for write.
| Name | Description |
|---|---|
opts.offset number
(default 0)
|
Integer with the byte offset to begin writing at. (default: 0) |
opts.create boolean
(default false)
|
Indicate to create the file if it doesn't exist. (default: false) |
opts.truncate boolean
(default false)
|
Indicate if the file should be truncated after writing all the bytes from content. (default: false) |
opts.parents boolena
(default false)
|
Value to decide whether or not to make the parent directories if they don't exist. (default: false) |
opts.length number?
|
Maximum number of bytes to read. (default: Read all bytes from content) |
opts.rawLeaves boolean
(default false)
|
If true, DAG leaves will contain raw file data and not be wrapped in a protobuf. (default: false) |
opts.cidVersion number
(default 0)
|
The CID version to use when storing the data (storage keys are based on the CID, including its version). (default: 0) |
Promise<void>:
If from has multiple values then to must be a directory.
If from has a single value and to exists and is a directory, from will be moved into to.
If from has a single value and to exists and is a file, from must be a file and the contents of to will be replaced with the contents of from otherwise an error will be returned.
If from is an IPFS path, and an MFS path exists with the same name, the IPFS path will be chosen.
All values of from will be removed after the operation is complete unless they are an IPFS path.
(string)
Path of the destination to move to.
(Object)
Options for mv.
| Name | Description |
|---|---|
opts.parents boolean
(default false)
|
Value to decide whether or not to make the parent directories if they don't exist. (default: false) |
opts.format String
(default dag-pb)
|
Format of nodes to write any newly created directories as. (default: dag-pb). |
opts.hashAlg String?
|
Algorithm to use when creating CIDs for newly created directories. (default: sha2-256) The list of all possible values |
opts.flush boolean
(default true)
|
Value to decide whether or not to immediately flush MFS changes to disk. (default: true) |
Promise<void>:
Flush a given path's data to the disk.
Promise<void>:
Type: Object
Type: Object
List directories in the local mutable namespace.
(string
= "/")
String to show listing for. (default: /)
(ListOptions?)
Options for list.
AsyncIterable<ListOutputFile>:
Time Aware Least Recent Used Cache
Set a key value pair
Clears the cache
Put a value to the local datastore indexed by the received key properly encoded.
(Buffer)
identifier of the value.
(Buffer)
value to be stored.
(function (Error))
void:
Get a value from the local datastore indexed by the received key properly encoded.
void:
(Object)
| Name | Description |
|---|---|
$0.ipns any
|
|
$0.dag any
|
|
$0.peerInfo any
|
|
$0.isOnline any
|
|
$0.keychain any
|
|
$0.options any
|
IPNS - Inter-Planetary Naming System
(IPFS)
| Name | Description |
|---|---|
self.ipns any
|
|
self.dag any
|
|
self.peerInfo any
|
|
self.isOnline any
|
|
self.keychain any
|
|
self.options any
|
Object:
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.
(String)
ipfs path of the object to be published.
(Object)
ipfs publish options.
| Name | Description |
|---|---|
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, as listed by 'ipfs key list -l'. |
(function (Error)?)
(Promise | void):
Cancel a name subscription.
Promise<{canceled: boolean}>:
Query the state of IPNS pubsub.
Promise<boolean>:
Put a value to the pubsub datastore indexed by the received key properly encoded.
(Buffer)
identifier of the value.
(Buffer)
value to be stored.
(function (Error))
void:
Get a value from the pubsub datastore indexed by the received key properly encoded. Also, the identifier topic is subscribed to and the pubsub datastore records will be updated once new publishes occur.
void:
Get pubsub subscriptions related to ipns.
Array<Object>:
Cancel pubsub subscriptions related to ipns.
void:
Show current name subscriptions.
(function (Error)?)
Promise<Array<string>>:
(Object)
| Name | Description |
|---|---|
$0.dns any
|
|
$0.ipns any
|
|
$0.peerInfo any
|
|
$0.isOnline any
|
|
$0.options any
|
IPNS - Inter-Planetary Naming System
(IPFS)
| Name | Description |
|---|---|
self.dns any
|
|
self.ipns any
|
|
self.peerInfo any
|
|
self.isOnline any
|
|
self.options any
|
Object:
Given a key, query the DHT for its best value.
(String)
ipns name to resolve. Defaults to your node's peerID.
(Object)
ipfs resolve options.
| Name | Description |
|---|---|
options.nocache boolean
|
do not use cached entries. |
options.recursive boolean
|
resolve until the result is not an IPNS name. |
(function (Error)?)
(Promise | void):
(Object)
| Name | Description |
|---|---|
$0.ipld any
|
|
$0.name any
|
IPFS Resolve factory
(Object)
| Name | Description |
|---|---|
config.ipld IPLD
|
An instance of IPLD |
config.name NameApi?
|
An IPFS core interface name API |
Resolve:
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).
String:
If the repo has been initialized, report the current version. Otherwise report the version that would be initialized.
number:
Type: Object