⚠️ Object API is deprecated, use FILES and DAG APIs instead.
ipfs.object.new([options])ipfs.object.put(obj, [options])ipfs.object.get(cid, [options])ipfs.object.data(cid, [options])ipfs.object.links(cid, [options])ipfs.object.stat(cid, [options])ipfs.object.patch.addLink(cid, link, [options])ipfs.object.patch.rmLink(cid, link, [options])ipfs.object.patch.appendData(cid, data, [options])ipfs.object.patch.setData(multihash, data, [options])
Create a new MerkleDAG node, using a specific layout. Caveat: So far, only UnixFS object layouts are supported.
None.
An optional object which may have the following keys:
| Name | Type | Default | Description |
|---|---|---|---|
| template | String |
If defined, must be a string unixfs-dir and if that is passed, the created node will be an empty unixfs style directory |
|
| recursive | boolean |
false |
Resolve until the result is not an IPNS name |
| nocache | boolean |
cache |
Do not use cached entries |
| 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 |
| Type | Description |
|---|---|
Promise<CID> |
A CID instance |
const cid = await ipfs.object.new({
template: 'unixfs-dir'
})
console.log(cid.toString())
// Logs:
// QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3NnA great source of examples can be found in the tests for this API.
Store a MerkleDAG node.
| Name | Type | Description |
|---|---|---|
| obj | Object{ Data: <data>, Links: [] }, Uint8Array or DAGNode |
The MerkleDAG Node to be stored |
An optional object which may have the following keys:
| Name | Type | Default | Description |
|---|---|---|---|
| enc | String |
undefined |
The encoding of the Uint8Array (json, yml, etc), if passed a Uint8Array |
| 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 |
| Type | Description |
|---|---|
Promise<CID> |
A CID instance |
const obj = {
Data: new TextEncoder().encode('Some data'),
Links: []
}
const cid = await ipfs.object.put(obj)
console.log(cid.toString())
// Logs:
// QmPb5f92FxKPYdT3QNBd1GKiL4tZUXUrzF4Hkpdr3Gf1gKA great source of examples can be found in the tests for this API.
Fetch a MerkleDAG node
| Name | Type | Description |
|---|---|---|
| cid | CID | The returned DAGNode will correspond to this CID |
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 |
| Type | Description |
|---|---|
Promise<DAGNode> |
A MerkleDAG node of the type DAGNode |
const multihash = 'QmPb5f92FxKPYdT3QNBd1GKiL4tZUXUrzF4Hkpdr3Gf1gK'
const node = await ipfs.object.get(multihash)
console.log(node.Data)
// Logs:
// some dataA great source of examples can be found in the tests for this API.
Returns the Data field of an object
| Name | Type | Description |
|---|---|---|
| cid | CID | The returned data will be from the DAGNode that corresponds to this CID |
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 |
| Type | Description |
|---|---|
Promise<Uint8Array> |
An Promise that resolves to Uint8Array objects with the data that the MerkleDAG node contained |
const cid = 'QmPb5f92FxKPYdT3QNBd1GKiL4tZUXUrzF4Hkpdr3Gf1gK'
const data = await ipfs.object.data(cid)
console.log(data.toString())
// Logs:
// some dataA great source of examples can be found in the tests for this API.
Returns the Links field of an object
| Name | Type | Description |
|---|---|---|
| cid | CID | The returned DAGLinks will be from the DAGNode that corresponds to this CID |
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 |
| Type | Description |
|---|---|
Promise<Array> |
An Array of DAGLink objects |
const multihash = 'Qmc5XkteJdb337s7VwFBAGtiaoj2QCEzyxtNRy3iMudc3E'
const links = await ipfs.object.links(multihash)
const hashes = links.map((link) => link.Hash.toString())
console.log(hashes)
// Logs:
// [
// 'QmZbj5ruYneZb8FuR9wnLqJCpCXMQudhSdWhdhp5U1oPWJ',
// 'QmSo73bmN47gBxMNqbdV6rZ4KJiqaArqJ1nu5TvFhqqj1R'
// ]A great source of examples can be found in the tests for this API.
Returns stats about an Object
| Name | Type | Description |
|---|---|---|
| cid | CID | The returned stats will be from the DAGNode that corresponds to this CID |
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 |
| Type | Description |
|---|---|
Promise<Object> |
An object representing the stats of the Object |
the returned object has the following format:
{
Hash: 'QmPTkMuuL6PD8L2SwTwbcs1NPg14U8mRzerB1ZrrBrkSDD',
NumLinks: 0,
BlockSize: 10,
LinksSize: 2,
DataSize: 8,
CumulativeSize: 10
}const multihash = 'QmPTkMuuL6PD8L2SwTwbcs1NPg14U8mRzerB1ZrrBrkSDD'
const stats = await ipfs.object.stat(multihash, {timeout: '10s'})
console.log(stats)
// Logs:
// {
// Hash: 'QmPTkMuuL6PD8L2SwTwbcs1NPg14U8mRzerB1ZrrBrkSDD',
// NumLinks: 0,
// BlockSize: 10,
// LinksSize: 2,
// DataSize: 8,
// CumulativeSize: 10
// }A great source of examples can be found in the tests for this API.
Add a Link to an existing MerkleDAG Object
| Name | Type | Description |
|---|---|---|
| cid | CID | Add a link to the DAGNode that corresponds to this CID |
| link | DAGLink | The link to add |
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 |
| Type | Description |
|---|---|
Promise<CID> |
An instance of CID representing the new DAG node that was created due to the operation |
// cid is CID of the DAG node created by adding a link
const cid = await ipfs.object.patch.addLink(node, {
name: 'some-link',
size: 10,
cid: CID.parse('QmPTkMuuL6PD8L2SwTwbcs1NPg14U8mRzerB1ZrrBrkSDD')
})A great source of examples can be found in the tests for this API.
The DAGLink to be added can also be passed as an object containing: name, cid and size properties:
const link = {
name: 'Qmef7ScwzJUCg1zUSrCmPAz45m8uP5jU7SLgt2EffjBmbL',
size: 37,
cid: CID.parse('Qmef7ScwzJUCg1zUSrCmPAz45m8uP5jU7SLgt2EffjBmbL')
};or
const link = new DAGLink(name, size, multihash)Remove a Link from an existing MerkleDAG Object
| Name | Type | Description |
|---|---|---|
| cid | CID | Remove a link to the DAGNode that corresponds to this CID |
| link | DAGLink | The DAGLink to remove |
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 |
| Type | Description |
|---|---|
Promise<CID> |
An instance of CID representing the new DAG node that was created due to the operation |
// cid is CID of the DAG node created by removing a link
const cid = await ipfs.object.patch.rmLink(node, {
Name: 'some-link',
Tsize: 10,
Hash: CID.parse('QmPTkMuuL6PD8L2SwTwbcs1NPg14U8mRzerB1ZrrBrkSDD')
})A great source of examples can be found in the tests for this API.
link is the link to be removed on the node that is identified by the multihash, can be passed as:
-
DAGLinkconst link = new DAGLink(name, size, multihash)
-
Object containing a
namepropertyconst link = { name: 'Qmef7ScwzJUCg1zUSrCmPAz45m8uP5jU7SLgt2EffjBmbL' };
Append Data to the Data field of an existing node
| Name | Type | Description |
|---|---|---|
| cid | CID | Add data to the DAGNode that corresponds to this CID |
| data | Uint8Array |
The data to append to the .Data field of the node |
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 |
| Type | Description |
|---|---|
Promise<CID> |
An instance of CID representing the new DAG node that was created due to the operation |
const cid = await ipfs.object.patch.appendData(multihash, new TextEncoder().encode('more data'))A great source of examples can be found in the tests for this API.
Overwrite the Data field of a DAGNode with new Data
| Name | Type | Description |
|---|---|---|
| cid | CID | Replace data of the DAGNode that corresponds to this CID |
| data | Uint8Array |
The data to overwrite with |
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 |
| Type | Description |
|---|---|
Promise<CID> |
An instance of CID representing the new DAG node that was created due to the operation |
const cid = '/ipfs/Qmfoo'
const updatedCid = await ipfs.object.patch.setData(cid, new TextEncoder().encode('more data'))A great source of examples can be found in the tests for this API.