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

Latest commit

 

History

History
638 lines (457 loc) · 18.5 KB

PIN.md

File metadata and controls

638 lines (457 loc) · 18.5 KB
Raw

Pin API

ipfs.pin.add(ipfsPath, [options])

Adds an IPFS object to the pinset and also stores it to the IPFS repo. pinset is the set of hashes currently pinned (not gc'able)

Parameters

Name Type Description
source CID or string A CID or IPFS Path to pin in your repo

Options

An optional object which may have the following keys:

Name Type Default Description
recursive boolean true Recursively pin all links contained by the object
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

Returns

Type Description
CID The CID that was pinned

Example

const cid of ipfs.pin.add(CID.parse('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u'))
console.log(cid)
// Logs:
// CID('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u')

A great source of examples can be found in the tests for this API.

ipfs.pin.addAll(source, [options])

Adds multiple IPFS objects to the pinset and also stores it to the IPFS repo. pinset is the set of hashes currently pinned (not gc'able)

Parameters

Name Type Description
source AsyncIterable<{ cid: CID, path: string, recursive: boolean, comments: string }> One or more CIDs or IPFS Paths to pin in your repo

Options

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

Returns

Type Description
AsyncIterable<CID> An async iterable that yields the CIDs that were pinned

Each yielded object has the form:

{
  cid: CID('QmHash')
}

Example

for await (const cid of ipfs.pin.addAll(CID.parse('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u'))) {
  console.log(cid)
}
// Logs:
// CID('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u')

A great source of examples can be found in the tests for this API.

ipfs.pin.ls([options])

List all the objects pinned to local storage

Parameters

Name Type Description

Options

An optional object which may have the following keys:

Name Type Default Description
paths CID or Array<CID> or string or Array<string> CIDs or IPFS paths to search for in the pinset
type string undefined Filter by this type of pin ("recursive", "direct" or "indirect")
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

Returns

Type Description
AsyncIterable<{ cid: CID, type: string }> An async iterable that yields currently pinned objects with cid and type properties. cid is a CID of the pinned node, type is the pin type ("recursive", "direct" or "indirect")

Example

for await (const { cid, type } of ipfs.pin.ls()) {
  console.log({ cid, type })
}
// { cid: CID(Qmc5XkteJdb337s7VwFBAGtiaoj2QCEzyxtNRy3iMudc3E), type: 'recursive' }
// { cid: CID(QmZbj5ruYneZb8FuR9wnLqJCpCXMQudhSdWhdhp5U1oPWJ), type: 'indirect' }
// { cid: CID(QmSo73bmN47gBxMNqbdV6rZ4KJiqaArqJ1nu5TvFhqqj1R), type: 'indirect' }
for await (const { cid, type } of ipfs.pin.ls({
  paths: [ CID.parse('Qmc5..'), CID.parse('QmZb..'), CID.parse('QmSo..') ]
})) {
  console.log({ cid, type })
}
// { cid: CID(Qmc5XkteJdb337s7VwFBAGtiaoj2QCEzyxtNRy3iMudc3E), type: 'recursive' }
// { cid: CID(QmZbj5ruYneZb8FuR9wnLqJCpCXMQudhSdWhdhp5U1oPWJ), type: 'indirect' }
// { cid: CID(QmSo73bmN47gBxMNqbdV6rZ4KJiqaArqJ1nu5TvFhqqj1R), type: 'indirect' }

A great source of examples can be found in the tests for this API.

ipfs.pin.rm(ipfsPath, [options])

Unpin this block from your repo

Parameters

Name Type Description
ipfsPath CID of string Unpin this CID or IPFS Path

Options

An optional object which may have the following keys:

Name Type Default Description
recursive boolean true Recursively unpin the object linked
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

Returns

Type Description
CID The CIDs that was unpinned

Example

const cid of ipfs.pin.rm(CID.parse('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u'))
console.log(cid)
// prints the CID that was unpinned
// CID('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u')

A great source of examples can be found in the tests for this API.

ipfs.pin.rmAll(source, [options])

Unpin one or more blocks from your repo

Parameters

Name Type Description
source CID, string or AsyncIterable<{ cid: CID, path: string, recursive: boolean }> Unpin this CID

Options

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

Returns

Type Description
AsyncIterable<CID> An async iterable that yields the CIDs that were unpinned

Example

for await (const cid of ipfs.pin.rmAll(CID.parse('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u'))) {
  console.log(cid)
}
// prints the CIDs that were unpinned
// CID('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u')

A great source of examples can be found in the tests for this API.

ipfs.pin.remote.service.add(name, options)

Registers remote pinning service with a given name. Errors if service with the given name is already registered.

Parameters

Name Type Description
name string Service name

Options

An object which must contain following fields:

Name Type Description
endpoint string Service endpoint URL
key string Service key

An object may have the following optional fields:

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

Returns

Type Description
Promise Resolves if added successfully, or fails with error e.g. if service with such name is already registered

Example

await ipfs.pin.remote.service.add('pinata', {
  endpoint: new URL('https://api.pinata.cloud'),
  key: 'your-pinata-key'
})

A great source of examples can be found in the tests for this API.

ipfs.pin.remote.service.ls([options])

List registered remote pinning services.

Options

An object may have the following optional fields:

Name Type Default Description
stat boolean false If true will include service stats.
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

Returns

Type Description
Promise<RemotePinService[]> List of registered services

RemotePinService

Object contains following fields:

Name Type Description
service string Service name
endpoint URL Service endpoint URL
stat Stat Is included only when stat: true option was passed

Stat

If stats could not be fetched from service (e.g. endpoint was unreachable) object has following form:

Name Type Description
status 'invalid' Service status

If stats were fetched from service successfully object has following form:

Name Type Description
status 'valid' Service status
pinCount PinCount Pin counts

PinCount

Object has following fields:

Name Type Description
queued number Number of queued pins
pinning number Number of pins that are pinning
pinned number Number of pinned pins
failed number Number of faield pins

Example

await ipfs.pin.remote.service.ls()
// [{
//   service: 'pinata'
//   endpoint: new URL('https://api.pinata.cloud'),
// }]

await ipfs.pin.remote.service.ls({ stat: true })
// [{
//   service: 'pinata'
//   endpoint: new URL('https://api.pinata.cloud'),
//   stat: {
//      status: 'valid',
//      pinCount: {
//        queued: 0,
//        pinning: 0,
//        pinned: 1,
//        failed: 0,
//      }
//   }
// }]

A great source of examples can be found in the tests for this API.

ipfs.pin.remote.service.rm(name, [options])

Unregisteres remote pinning service with a given name (if service with such name is regisetered).

Parameters

Name Type Description
name string Service name

Options

An object may have the following optional fields:

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

Returns

Type Description
Promise Resolves on completion

Example

await ipfs.pin.remote.service.rm('pinata')

A great source of examples can be found in the tests for this API.

ipfs.pin.remote.add(cid, [options])

Pin a content with a given CID to a remote pinning service

Parameters

Name Type Description
cid CID A CID to pin on a remote pinning service

Options

An object which must contain following fields:

Name Type Description
service string Name of the remote pinning service to use

An object may have the following optional fields:

Name Type Default Description
name string undefined Name for pinned data; can be used for lookups later (max 255 characters)
origins Multiaddr[] undefined List of multiaddrs known to provide the data (max 20)
background boolean false If true, will add to the queue on the remote service and return immediately. If false or omitted will wait until pinned on the remote service
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

Returns

Type Description
Pin Pin Object

Pin

Object has following fields:

Type Description
Status Pin status
CID CID of the content
`string undefined`

Status

Status is one of the following string values:

'queued', 'pinning', 'pinned', 'failed'

Example

const cid = CID.parse('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u')
const pin = await ipfs.pin.remote.add(cid, {
  service: 'pinata',
  name: 'block-party'
})
console.log(pin)
// Logs:
// {
//    status: 'pinned',
//    cid: CID('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u'),
//    name: 'block-party'
// }

A great source of examples can be found in the tests for this API.

ipfs.pin.remote.ls(options)

Returns a list of matching pins on the remote pinning service.

Options

An object which must contain following fields:

Name Type Description
service string Name of the remote pinning service to use

An object may have the following optional fields:

Name Type Default Description
cid CID[] undefined If provided, will only include pin objects that have a CID from the given set.
name string undefined If passed, will only include pin objects with names that have this name (case-sensitive, exact match).
status Status[] ['pinned'] Return pin objects for pins that have one of the specified status values
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

Returns

Type Description
AysncIterable<Pin> Pin Objects

Example

for await (const pin of ipfs.pin.remote.ls({ service: 'pinata' })) {
  console.log(pin)
}
// Logs:
// {
//    status: 'pinned',
//    cid: CID('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u'),
//    name: 'block-party'
// }

A great source of examples can be found in the tests for this API.

ipfs.pin.remote.rm(options)

Removes a single matching pin object from the remote pinning service. Will error when multiple pins mtach, to remove all matches rmAll should be used instead.

Options

An object which must contain following fields:

Name Type Description
service string Name of the remote pinning service to use

An object may also contain following optional fields:

Name Type Default Description
cid CID[] undefined If provided, will match pin object(s) that have a CID from the given set.
name string undefined If provided, will match pin object(s) with exact (case-sensitive) name.
status Status[] ['pinned'] If provided, will match pin object(s) that have a status from the given set.
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

Returns

Type Description
Promise Succeeds on completion

Example

await ipfs.pin.remote.rm({
  service: 'pinata',
  name: 'block-party'
})

A great source of examples can be found in the tests for this API.

ipfs.pin.remote.rmAll(options)

Removes all the matching pin objects from the remote pinning service.

Options

An object which must contain following fields:

Name Type Description
service string Name of the remote pinning service to use

An object may also contain following optional fields:

Name Type Default Description
cid CID[] undefined If provided, will match pin object(s) that have a CID from the given set.
name string undefined If provided, will match pin object(s) with exact (case-sensitive) name.
status Status[] ['pinned'] If provided, will match pin object(s) that have a status from the given set.
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

Returns

Type Description
Promise Succeeds on completion

Example

// Delete all non 'pinned' pins
await ipfs.pin.remote.rmAll({
  service: 'pinata',
  status: ['queued', 'pinning', 'failed']
})

A great source of examples can be found in the tests for this API.