{"id":18877557,"url":"https://github.com/nftstorage/ipfs-cluster","last_synced_at":"2025-04-14T18:31:48.558Z","repository":{"id":42370854,"uuid":"359798217","full_name":"nftstorage/ipfs-cluster","owner":"nftstorage","description":"***Notice: This repository is no longer maintained.*** A zero-dependency client to the IPFS Cluster HTTP API, built for the browser.","archived":false,"fork":false,"pushed_at":"2023-03-04T17:09:39.000Z","size":204,"stargazers_count":36,"open_issues_count":1,"forks_count":16,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-28T07:02:31.716Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nftstorage.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-20T11:55:34.000Z","updated_at":"2024-07-01T22:54:18.000Z","dependencies_parsed_at":"2024-06-18T21:16:02.039Z","dependency_job_id":"2be8a283-4f67-4783-88bd-23ce509345ea","html_url":"https://github.com/nftstorage/ipfs-cluster","commit_stats":{"total_commits":75,"total_committers":4,"mean_commits":18.75,"dds":"0.30666666666666664","last_synced_commit":"02a4c1d0f4cbe86557abd738be83bb2de25ccec0"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nftstorage%2Fipfs-cluster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nftstorage%2Fipfs-cluster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nftstorage%2Fipfs-cluster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nftstorage%2Fipfs-cluster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nftstorage","download_url":"https://codeload.github.com/nftstorage/ipfs-cluster/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248550620,"owners_count":21122934,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T06:20:01.722Z","updated_at":"2025-04-14T18:31:48.258Z","avatar_url":"https://github.com/nftstorage.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ipfs-cluster\n\n[![dependencies Status](https://status.david-dm.org/gh/nftstorage/ipfs-cluster.svg)](https://david-dm.org/nftstorage/ipfs-cluster)\n[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)\n[![minzip size](https://badgen.net/bundlephobia/minzip/@nftstorage/ipfs-cluster)](https://bundlephobia.com/result?p=@nftstorage/ipfs-cluster)\n\nA zero-dependency client to the [IPFS Cluster](https://cluster.ipfs.io/) HTTP API, built for the browser.\n\n## Install\n\nImport it from your favourite CDN (e.g. skypack.dev, unpkg.com, jsdelivr.com) or install directly from npm:\n\n```sh\nnpm i @nftstorage/ipfs-cluster\n```\n\n## Usage\n\nExample:\n\n```js\nimport { Cluster } from 'https://cdn.skypack.dev/@nftstorage/ipfs-cluster'\n\nconst cluster = new Cluster('https://your-cluster-domain.com')\n\nconst file = new File(['foo'], 'foo.txt')\nconst { cid } = await cluster.add(file)\nconsole.log(cid) // bafybeigpsl667todjswabhelaxvwmk7amgg3txsv5tkcpbpj5rtrf6g7mu\n```\n\n### Using in Node.js\n\nThis 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:\n\n```js\nimport fetch from '@web-std/fetch'\nimport { FormData } from '@web-std/form-data'\nimport { File, Blob } from '@web-std/file'\n\nObject.assign(global, { fetch, File, Blob, FormData })\n```\n\n## API\n\nThis library is **WIP** and not _all_ cluster HTTP API methods are available yet (PR's welcome!). Please see the [typescript types](https://github.com/nftstorage/ipfs-cluster/blob/main/src/interface.ts) for full parameter and return types.\n\nNote: all methods take an options object with a `signal` property - an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) from an [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) allowing the request to be aborted by the caller.\n\n- [Constructor](#constructor)\n- [`add`](#add)\n- [`addCAR`](#addcar)\n- [`addDirectory`](#adddirectory)\n- `alerts`\n- [`allocations`](#allocations)\n- `id`\n- `metrics`\n- [`metricNames`](#metricnames)\n- [`peerList`](#peerlist)\n- `peerAdd`\n- `peerRemove`\n- [`pin`](#pin)\n- `pinPath`\n- [`recover`](#recover)\n- `recoverAll`\n- `repoGC`\n- [`status`](#status)\n- [`statusAll`](#statusall)\n- `version`\n- [`unpin`](#unpin)\n- `unpinPath`\n\n### Constructor\n\nCreate a new instance of the cluster client.\n\n```js\nimport { Cluster } from '@nftstorage/ipfs-cluster'\nconst cluster = new Cluster('https://your-cluster-domain.com', {\n  // optional custom headers for e.g. auth\n  headers: { Authorization: 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' }\n})\n```\n\n### `add`\n\nImport a file to the cluster. First argument must be a `File` or `Blob`.\n\n```js\nconst file = new File(['foo'], 'foo.txt')\nconst { cid } = await cluster.add(file)\n```\n\nNote: by default this module uses v1 CIDs and raw leaves enabled.\n\n### `addCAR`\n\nAlternatively you can import data from a [CAR (Content Addressable aRchive)](https://github.com/ipld/specs/blob/master/block-layer/content-addressable-archives.md) file:\n\n```js\nconst car = new Blob(carFileData, { type: 'application/car' })\nconst { cid } = await cluster.addCAR(car)\n```\n\n[More information on reading and writing CAR files in JS](https://github.com/ipld/js-car#readme).\n\n### `addDirectory`\n\nImports multiple files to the cluster. First argument must be an array of `File` or `Blob`.\n\n```js\nconst files = [new File(['foo'], 'foo.txt'), new File(['bar'], 'bar.txt')]\nconst dir = await cluster.addDirectory(file)\n\nfor (const entry of dir) {\n  console.log(entry.cid)\n  // bafybeigpsl667todjswabhelaxvwmk7amgg3txsv5tkcpbpj5rtrf6g7mu\n  // bafybeidsnna57jpm2ttwaydwak25qpkxafrg4cnrjsfqipbcqxlsfobjje\n}\n```\n\nNote: by default this module uses v1 CIDs and raw leaves enabled.\n\n### `allocation`\n\nReturns the current allocation for a given CID.\n\n```js\nconst cid = 'bafybeigpsl667todjswabhelaxvwmk7amgg3txsv5tkcpbpj5rtrf6g7mu'\nconst allocation = await cluster.allocation(cid)\n```\n\n### `metricNames`\n\nGet a list of metric types known to the peer.\n\n```js\nconst names = await cluster.metricNames()\nconsole.log(names) // [ 'ping', 'freespace' ]\n```\n\n### `peerList`\n\nGet a list of Cluster peer info.\n\n```js\nconst peers = await cluster.peerList()\npeers.forEach((peer) =\u003e {\n  console.log(`${peer.id} | ${peer.peerName}`)\n  console.log('  \u003e Addresses:')\n  peer.addresses.forEach((addr) =\u003e console.log(`    - ${addr}`))\n  console.log(`  \u003e IPFS: ${peer.ipfs.id}`)\n  peer.ipfs.addresses.forEach((addr) =\u003e console.log(`    - ${addr}`))\n})\n```\n\n### `pin`\n\nTracks a CID with the given replication factor and a name for human-friendliness.\n\n```js\nconst cid = 'bafybeigpsl667todjswabhelaxvwmk7amgg3txsv5tkcpbpj5rtrf6g7mu'\nconst { cid } = await cluster.pin(cid)\n```\n\n### `recover`\n\nRe-triggers pin or unpin IPFS operations for a CID in error state.\n\n```js\nconst cid = 'bafybeigpsl667todjswabhelaxvwmk7amgg3txsv5tkcpbpj5rtrf6g7mu'\nconst { cid } = await cluster.recover(cid)\n```\n\n### `status`\n\nReturns the current IPFS state for a given CID.\n\n```js\nconst cid = 'bafybeigpsl667todjswabhelaxvwmk7amgg3txsv5tkcpbpj5rtrf6g7mu'\nconst status = await cluster.status(cid)\n\nfor (const [clusterPeerID, pinInfo] of Object.entries(status.peerMap)) {\n  console.log(`${clusterPeerID}: ${pinInfo.status}`)\n  // e.g.\n  // 12D3KooWAjKw14hMUo7wdyEu9KwogrUFCCMiQZApgZ4zMcvtcacj: pinned\n  // 12D3KooWKiebn7GqPvjqjKARnm47Xoez6f1civBEWxef3u5G6UdM: pinned\n  // 12D3KooWLKdPdFx5UpPNwoVmMXsLULCDegAqXZ7RAgpKuPSMKoSS: pinned\n}\n```\n\n### `statusAll`\n\nStatus of all tracked CIDs. Note: this is an expensive operation. Use the optional filters when possible.\n\n```js\nconst statuses = await cluster.statusAll()\nfor (const status of statuses) {\n  console.log(`${status.cid}:`)\n  for (const [clusterPeerID, pinInfo] of Object.entries(status.peerMap)) {\n    console.log(`    ${clusterPeerID}: ${pinInfo.status}`)\n  }\n}\n// e.g.\n// bafybeigpsl667todjswabhelaxvwmk7amgg3txsv5tkcpbpj5rtrf6g7mu:\n//     12D3KooWAjKw14hMUo7wdyEu9KwogrUFCCMiQZApgZ4zMcvtcacj: pinned\n//     12D3KooWKiebn7GqPvjqjKARnm47Xoez6f1civBEWxef3u5G6UdM: pinned\n//     12D3KooWLKdPdFx5UpPNwoVmMXsLULCDegAqXZ7RAgpKuPSMKoSS: pinned\n// bafkreibme22gw2h7y2h7tg2fhqotaqjucnbc24deqo72b6mkl2egezxhvy:\n//     12D3KooWAjKw14hMUo7wdyEu9KwogrUFCCMiQZApgZ4zMcvtcacj: queued\n//     12D3KooWKiebn7GqPvjqjKARnm47Xoez6f1civBEWxef3u5G6UdM: queued\n//     12D3KooWLKdPdFx5UpPNwoVmMXsLULCDegAqXZ7RAgpKuPSMKoSS: queued\n// ...etc.\n```\n\nNote: The method takes an options object that allows filtering by status or cid e.g.\n\n```js\n// retrieve only pinning and pinned items\nawait cluster.statusAll({ filter: ['pinning', 'pinned'] })\n\n// retrieve status for the passed list of CIDs (requires Cluster version \u003e= 0.14.5-rc1)\nawait cluster.statusAll({\n  cids: ['bafybeigpsl667todjswabhelaxvwmk7amgg3txsv5tkcpbpj5rtrf6g7mu']\n})\n```\n\n### `unpin`\n\nUntracks a CID from cluster.\n\n```js\nconst cid = 'bafybeigpsl667todjswabhelaxvwmk7amgg3txsv5tkcpbpj5rtrf6g7mu'\nawait cluster.unpin(cid)\n```\n\n## Contribute\n\nFeel free to dive in! [Open an issue](https://github.com/nftstorage/ipfs-cluster/issues/new) or submit PRs.\n\n## License\n\n[APACHE-2.0](LICENSE-APACHE) AND [MIT](LICENSE-MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnftstorage%2Fipfs-cluster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnftstorage%2Fipfs-cluster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnftstorage%2Fipfs-cluster/lists"}