{"id":19032559,"url":"https://github.com/storacha/pail","last_synced_at":"2025-04-23T16:41:06.999Z","repository":{"id":65496414,"uuid":"580788054","full_name":"storacha/pail","owner":"storacha","description":"🪣 DAG based key value store.","archived":false,"fork":false,"pushed_at":"2025-04-04T11:18:00.000Z","size":163,"stargazers_count":46,"open_issues_count":5,"forks_count":12,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-18T01:48:14.065Z","etag":null,"topics":["bucket","crdt","dag","ipfs","ipld","kv","kv-store","merkle-crdt","merkle-dag","shard"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"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/storacha.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2022-12-21T13:00:12.000Z","updated_at":"2025-04-06T14:43:42.000Z","dependencies_parsed_at":"2024-03-19T10:47:01.551Z","dependency_job_id":"02ea8251-80b6-4ae2-a2c1-017f9d59fc92","html_url":"https://github.com/storacha/pail","commit_stats":{"total_commits":70,"total_committers":2,"mean_commits":35.0,"dds":"0.014285714285714235","last_synced_commit":"586fd06596b129405c06275d47c7f124e6527b0c"},"previous_names":["web3-storage/pail","alanshaw/pail","storacha-network/pail","storacha/pail"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/storacha%2Fpail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/storacha%2Fpail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/storacha%2Fpail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/storacha%2Fpail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/storacha","download_url":"https://codeload.github.com/storacha/pail/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250472024,"owners_count":21436067,"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":["bucket","crdt","dag","ipfs","ipld","kv","kv-store","merkle-crdt","merkle-dag","shard"],"created_at":"2024-11-08T21:29:15.647Z","updated_at":"2025-04-23T16:41:06.979Z","avatar_url":"https://github.com/storacha.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pail\n\n[![Test](https://github.com/web3-storage/pail/actions/workflows/ci.yml/badge.svg)](https://github.com/web3-storage/pail/actions/workflows/ci.yml)\n[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)\n\nDAG based key value store. Sharded DAG that minimises traversals and work to build shards.\n\n* 📖 [Read the SPEC](https://github.com/web3-storage/specs/blob/4163e28d7e6a7c44cff68db9d9bffb9b37707dc6/pail.md).\n* 🎬 [Watch the Presentation](https://youtu.be/f-BrtpYKZfg).\n\n## Install\n\n```\nnpm install @web3-storage/pail\n```\n\n## Usage\n\n```js\nimport { put, get, del } from '@web3-storage/pail'\nimport { ShardBlock } from '@web3-storage/pail/shard'\nimport { MemoryBlockstore } from '@web3-storage/pail/block'\n\n// Initialize a new bucket\nconst blocks = new MemoryBlockstore()\nconst init = await ShardBlock.create() // empty root shard\nawait blocks.put(init.cid, init.bytes)\n\n// Add a key and value to the bucket\nconst { root, additions, removals } = await put(blocks, init.cid, 'path/to/data0', dataCID0)\n\nconsole.log(`new root: ${root}`)\n\n// Process the diff\nfor (const block of additions) {\n  await blocks.put(block.cid, block.bytes)\n}\nfor (const block of removals) {\n  await blocks.delete(block.cid)\n}\n```\n\n### Batch operations\n\nIf adding many multiple items to the pail together, it is faster to batch them together.\n\n```js\nimport { put, get, del } from '@web3-storage/pail'\nimport { ShardBlock } from '@web3-storage/pail/shard'\nimport { MemoryBlockstore } from '@web3-storage/pail/block'\nimport * as Batch from '@web3-storage/pail/batch'\n\n// Initialize a new bucket\nconst blocks = new MemoryBlockstore()\nconst init = await ShardBlock.create() // empty root shard\nawait blocks.put(init.cid, init.bytes)\n\nconst batch = await Batch.create(blocks, init.cid)\n\n// items is an array of `{ key: string, value: CID }` - the items to add to the pail\nfor (const item of items) {\n  await batch.put(item.key, item.value)\n}\n\nconst { root, additions, removals } = await batch.commit()\n\nconsole.log(`new root: ${root}`)\n\n// Process the diff\nfor (const block of additions) {\n  await blocks.put(block.cid, block.bytes)\n}\nfor (const block of removals) {\n  await blocks.delete(block.cid)\n}\n```\n\n## Contributing\n\nFeel free to join in. All welcome. [Open an issue](https://github.com/web3-storage/pail/issues)!\n\n## License\n\nDual-licensed under [MIT or Apache 2.0](https://github.com/web3-storage/pail/blob/main/LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstoracha%2Fpail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstoracha%2Fpail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstoracha%2Fpail/lists"}