{"id":20642401,"url":"https://github.com/ipld/js-dag-pb","last_synced_at":"2026-05-11T06:31:43.939Z","repository":{"id":38041764,"uuid":"292135595","full_name":"ipld/js-dag-pb","owner":"ipld","description":"An implementation of the DAG-PB spec for JavaScript (for use with multiformats or @ipld/block)","archived":false,"fork":false,"pushed_at":"2025-03-28T13:16:04.000Z","size":87228,"stargazers_count":16,"open_issues_count":1,"forks_count":7,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-03-30T00:06:30.586Z","etag":null,"topics":[],"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/ipld.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2020-09-02T00:11:57.000Z","updated_at":"2025-03-28T13:07:35.000Z","dependencies_parsed_at":"2023-12-28T10:42:11.670Z","dependency_job_id":"db033007-71a1-4c88-9145-dcbf11112918","html_url":"https://github.com/ipld/js-dag-pb","commit_stats":{"total_commits":548,"total_committers":37,"mean_commits":14.81081081081081,"dds":0.6934306569343065,"last_synced_commit":"27ed1722e3d1788e40f03186a1dc9b1ba69fd1d2"},"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipld%2Fjs-dag-pb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipld%2Fjs-dag-pb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipld%2Fjs-dag-pb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipld%2Fjs-dag-pb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ipld","download_url":"https://codeload.github.com/ipld/js-dag-pb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247419860,"owners_count":20936012,"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-16T16:08:58.050Z","updated_at":"2026-03-02T20:35:25.497Z","avatar_url":"https://github.com/ipld.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @ipld/dag-pb \u003c!-- omit in toc --\u003e\n\n[![codecov](https://img.shields.io/codecov/c/github/ipld/js-dag-pb.svg?style=flat-square)](https://codecov.io/gh/ipld/js-dag-pb)\n[![CI](https://img.shields.io/github/actions/workflow/status/ipld/js-dag-pb/js-test-and-release.yml?branch=master\\\u0026style=flat-square)](https://github.com/ipld/js-dag-pb/actions/workflows/js-test-and-release.yml?query=branch%3Amaster)\n\n\u003e JS implementation of DAG-PB\n\n## Table of contents \u003c!-- omit in toc --\u003e\n\n- [Install](#install)\n  - [Browser `\u003cscript\u003e` tag](#browser-script-tag)\n- [Overview](#overview)\n- [Example](#example)\n- [Usage](#usage)\n  - [`prepare()`](#prepare)\n- [`createNode()` \\\u0026 `createLink()`](#createnode--createlink)\n- [API Docs](#api-docs)\n- [License](#license)\n- [Contribute](#contribute)\n\n## Install\n\n```console\n$ npm i @ipld/dag-pb\n```\n\n### Browser `\u003cscript\u003e` tag\n\nLoading this module through a script tag will make it's exports available as `IpldDagPb` in the global namespace.\n\n```html\n\u003cscript src=\"https://unpkg.com/@ipld/dag-pb/dist/index.min.js\"\u003e\u003c/script\u003e\n```\n\n## Overview\n\nAn implementation of the [DAG-PB spec](https://github.com/ipld/specs/blob/master/block-layer/codecs/dag-pb.md) for JavaScript designed for use with [multiformats](https://github.com/multiformats/js-multiformats) or via the higher-level `Block` abstraction in [@ipld/block](https://github.com/ipld/js-block).\n\n## Example\n\n```js\nimport { CID } from 'multiformats/cid'\nimport { sha256 } from 'multiformats/hashes/sha2'\nimport * as dagPB from '@ipld/dag-pb'\n\nasync function run () {\n  const bytes = dagPB.encode({\n    Data: new TextEncoder().encode('Some data as a string'),\n    Links: []\n  })\n\n  // also possible if you `import dagPB, { prepare } from '@ipld/dag-pb'`\n  // const bytes = dagPB.encode(prepare('Some data as a string'))\n  // const bytes = dagPB.encode(prepare(new TextEncoder().encode('Some data as a string')))\n\n  const hash = await sha256.digest(bytes)\n  const cid = CID.create(1, dagPB.code, hash)\n\n  console.log(cid, '=\u003e', Buffer.from(bytes).toString('hex'))\n\n  const decoded = dagPB.decode(bytes)\n\n  console.log(decoded)\n  console.log(`decoded \"Data\": ${new TextDecoder().decode(decoded.Data)}`)\n}\n\nrun().catch((err) =\u003e {\n  console.error(err)\n  process.exit(1)\n})\n```\n\n## Usage\n\n`@ipld/dag-pb` is designed to be used within multiformats but can be used separately. `encode()`, `decode()`, `validate()` and `prepare()` functions are available if you pass in a `multiformats` object to the default export function. Each of these can operate independently as required.\n\n### `prepare()`\n\nThe DAG-PB encoding is very strict about the Data Model forms that are passed in. The objects *must* exactly resemble what they would if they were to undergo a round-trip of encode \u0026 decode. Therefore, extraneous or mistyped properties are not acceptable and will be rejected. See the [DAG-PB spec](https://github.com/ipld/specs/blob/master/block-layer/codecs/dag-pb.md) for full details of the acceptable schema and additional constraints.\n\nDue to this strictness, a `prepare()` function is made available which simplifies construction and allows for more flexible input forms. Prior to encoding objects, call `prepare()` to receive a new object that strictly conforms to the schema.\n\n```js\nimport { CID } from 'multiformats/cid'\nimport { prepare } from '@ipld/dag-pb'\n\nconsole.log(prepare({ Data: 'some data' }))\n// -\u003e{ Data: Uint8Array(9) [115, 111, 109, 101, 32, 100,  97, 116, 97] }\nconsole.log(prepare({ Links: [CID.parse('bafkqabiaaebagba')] }))\n// -\u003e { Links: [ { Hash: CID(bafkqabiaaebagba) } ] }\n```\n\nSome features of `prepare()`:\n\n- Extraneous properties are omitted\n- String values for `Data` are converted\n- Strings are converted to `{ Data: bytes }` (as are `Uint8Array`s)\n- Multiple ways of finding CIDs in the `Links` array are attempted, including interpreting the whole link element as a CID, reading a `Uint8Array` as a CID\n- Ensuring that properties are of the correct type (link `Name` is a `string` and `Tsize` is a `number`)\n- `Links` array is always present, even if empty\n- `Links` array is properly sorted\n\n## `createNode()` \u0026 `createLink()`\n\nThese utility exports are available to make transition from the older [ipld-dag-pb](https://github.com/ipld/js-ipld-dag-pb) library which used `DAGNode` and `DAGLink` objects with constructors. `createNode()` mirrors the `new DAGNode()` API while `createLink()` mirrors `new DAGLink()` API.\n\n- `createNode(data: Uint8Array, links: PBLink[]|void): PBNode`: create a correctly formed `PBNode` object from a `Uint8Array` and an optional array of correctly formed `PBLink` objects. The returned object will be suitable for passing to `encode()` and using `prepare()` on it should result in a noop.\n- `createLink(name: string, size: number, cid: CID): PBLink`: create a correctly formed `PBLink` object from a name, size and CID. The returned object will be suitable for attaching to a `PBNode`'s `Links` array, or in an array for the second argument to `createNode()`.\n\n```js\nimport { CID, bytes } from 'multiformats'\nimport * as Block from 'multiformats/block'\nimport { sha256 as hasher } from 'multiformats/hashes/sha2'\nimport * as codec from '@ipld/dag-pb'\n\nconst { createLink, createNode } = codec\n\nasync function run () {\n  const cid1 = CID.parse('QmWDtUQj38YLW8v3q4A6LwPn4vYKEbuKWpgSm6bjKW6Xfe')\n  const cid2 = CID.parse('bafyreifepiu23okq5zuyvyhsoiazv2icw2van3s7ko6d3ixl5jx2yj2yhu')\n\n  const links = [createLink('link1', 100, cid1), createLink('link2', 200, cid2)]\n  const value = createNode(Uint8Array.from([0, 1, 2, 3, 4]), links)\n  console.log(value)\n\n  const block = await Block.encode({ value, codec, hasher })\n  console.log(block.cid)\n  console.log(`Encoded: ${bytes.toHex(block.bytes).replace(/(.{80})/g, '$1\\n         ')}`)\n}\n\nrun().catch((err) =\u003e console.error(err))\n```\n\nResults in:\n\n```\n    {\n      Data: Uint8Array(5) [ 0, 1, 2, 3, 4 ],\n      Links: [\n        {\n          Hash: CID(QmWDtUQj38YLW8v3q4A6LwPn4vYKEbuKWpgSm6bjKW6Xfe),\n          Name: 'link1',\n          Tsize: 100\n        },\n        {\n          Hash: CID(bafyreifepiu23okq5zuyvyhsoiazv2icw2van3s7ko6d3ixl5jx2yj2yhu),\n          Name: 'link2',\n          Tsize: 200\n        }\n      ]\n    }\n    CID(bafybeihsp53wkzsaif76mjv564cawzqyjwianosamlvf6sht2m25ttyxiy)\n    Encoded: 122d0a2212207521fe19c374a97759226dc5c0c8e674e73950e81b211f7dd3b6b30883a08a511205\n             6c696e6b31186412300a2401711220a47a29adb950ee698ae0f272019ae902b6aa06ee5f53bc3da2\n             ebea6fac27583d12056c696e6b3218c8010a050001020304\n```\n\n## API Docs\n\n- \u003chttps://ipld.github.io/js-dag-pb\u003e\n\n## License\n\nLicensed under either of\n\n- Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / \u003chttp://www.apache.org/licenses/LICENSE-2.0\u003e)\n- MIT ([LICENSE-MIT](LICENSE-MIT) / \u003chttp://opensource.org/licenses/MIT\u003e)\n\n## Contribute\n\nUnless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipld%2Fjs-dag-pb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fipld%2Fjs-dag-pb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipld%2Fjs-dag-pb/lists"}