node-ipfs-cluster-api
v0.0.1
Published
A client to the IPFS Cluster HTTP API, built for the browser.
Downloads
4
Maintainers
Readme
ipfs-cluster
A zero-dependency client to the IPFS Cluster HTTP API, built for the browser.
Install
Import it from your favourite CDN (e.g. skypack.dev, unpkg.com, jsdelivr.com) or install directly from npm:
npm i @nftstorage/ipfs-cluster
Usage
Example:
import { Cluster } from 'https://cdn.skypack.dev/@nftstorage/ipfs-cluster'
const cluster = new Cluster('https://your-cluster-domain.com')
const file = new File(['foo'], 'foo.txt')
const { cid } = await cluster.add(file)
console.log(cid) // bafybeigpsl667todjswabhelaxvwmk7amgg3txsv5tkcpbpj5rtrf6g7mu
Using in Node.js
This library is designed to run in the browser or in web workers but it can be run in Node.js if required web APIs are added to the global environment. For exmaple:
import fetch from '@web-std/fetch'
import { FormData } from '@web-std/form-data'
import { File, Blob } from '@web-std/file'
Object.assign(global, { fetch, File, Blob, FormData })
API
This library is WIP and not all cluster HTTP API methods are available yet (PR's welcome!). Please see the typescript types for full parameter and return types.
- Constructor
add
addDirectory
alerts
allocations
id
metrics
metricNames
peerList
peerAdd
peerRemove
pin
pinPath
recover
recoverAll
repoGC
status
statusAll
version
unpin
unpinPath
Constructor
Create a new instance of the cluster client.
import { Cluster } from '@nftstorage/ipfs-cluster'
const cluster = new Cluster('https://your-cluster-domain.com', {
// optional custom headers for e.g. auth
headers: { Authorization: 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' }
})
add
Import a file to the cluster. First argument must be a File
or Blob
.
const file = new File(['foo'], 'foo.txt')
const { cid } = await cluster.add(file)
Alternatively you can import data from a CAR (Content Addressable aRchive) file:
const car = new Blob(carFileData, { type: 'application/car' })
const { cid } = await cluster.add(car)
More information on reading and writing CAR files in JS.
addDirectory
Imports multiple files to the cluster. First argument must be an array of File
or Blob
.
const files = [
new File(['foo'], 'foo.txt'),
new File(['bar'], 'bar.txt'),
]
const dir = await cluster.addDirectory(file)
for (const entry of dir) {
console.log(entry.cid)
// bafybeigpsl667todjswabhelaxvwmk7amgg3txsv5tkcpbpj5rtrf6g7mu
// bafybeidsnna57jpm2ttwaydwak25qpkxafrg4cnrjsfqipbcqxlsfobjje
}
allocation
Returns the current allocation for a given CID.
const cid = 'bafybeigpsl667todjswabhelaxvwmk7amgg3txsv5tkcpbpj5rtrf6g7mu'
const allocation = await cluster.allocation(cid)
metricNames
Get a list of metric types known to the peer.
const names = await cluster.metricNames()
console.log(names) // [ 'ping', 'freespace' ]
pin
Tracks a CID with the given replication factor and a name for human-friendliness.
const cid = 'bafybeigpsl667todjswabhelaxvwmk7amgg3txsv5tkcpbpj5rtrf6g7mu'
const { cid } = await cluster.pin(cid)
recover
Re-triggers pin or unpin IPFS operations for a CID in error state.
const cid = 'bafybeigpsl667todjswabhelaxvwmk7amgg3txsv5tkcpbpj5rtrf6g7mu'
const { cid } = await cluster.recover(cid)
status
Returns the current IPFS state for a given CID.
const cid = 'bafybeigpsl667todjswabhelaxvwmk7amgg3txsv5tkcpbpj5rtrf6g7mu'
const status = await cluster.status(cid)
for (const [clusterPeerID, pinInfo] of Object.entries(status.peerMap)) {
console.log(`${clusterPeerID}: ${pinInfo.status}`)
// e.g.
// 12D3KooWAjKw14hMUo7wdyEu9KwogrUFCCMiQZApgZ4zMcvtcacj: pinned
// 12D3KooWKiebn7GqPvjqjKARnm47Xoez6f1civBEWxef3u5G6UdM: pinned
// 12D3KooWLKdPdFx5UpPNwoVmMXsLULCDegAqXZ7RAgpKuPSMKoSS: pinned
}
unpin
Untracks a CID from cluster.
const cid = 'bafybeigpsl667todjswabhelaxvwmk7amgg3txsv5tkcpbpj5rtrf6g7mu'
await cluster.unpin(cid)
Contribute
Feel free to dive in! Open an issue or submit PRs.
License
APACHE-2.0 AND MIT