@ipld/dag-cbor

JS implementation of DAG-CBOR

Table of contents

• Install
• Spec
• License
• Contribute

Install

$ npm i @ipld/dag-cbor

This is the new interface meant for use by itself or with multiformats and @ipld/block. It is not used by js-ipld-format which is currently used in IPFS. That library is here.

Usage:

import { encode, decode } from '@ipld/dag-cbor'
import { CID } from 'multiformats'

const obj = {
  x: 1,
  /* CID instances are encoded as links */
  y: [2, 3, CID.parse('QmaozNR7DZHQK1ZcU9p7QdrshMvXqWK6gpu5rmrkPdT3L4')],
  z: {
    a: CID.parse('QmaozNR7DZHQK1ZcU9p7QdrshMvXqWK6gpu5rmrkPdT3L4'),
    b: null,
    c: 'string'
  }
}

let data = encode(obj)
let decoded = decode(data)
decoded.y[0] // 2
CID.asCID(decoded.z.a) // cid instance

// encode/decode options are exported for use with cborg's encodedLength and decodeFirst
import { encodeOptions, decodeOptions } from '@ipld/dag-cbor'
import { encodedLength } from 'cborg/length'
import { decodeFirst } from 'cborg'

// dag-cbor encoded length of obj in bytes
const byteLength = encodedLength(obj, encodeOptions)
byteLength // 104

// concatenate two dag-cbor encoded obj
const concatenatedData = new Uint8Array(data.length * 2)
concatenatedData.set(data)
concatenatedData.set(data, data.length)

// returns dag-cbor decoded obj at the beginning of the buffer as well as the remaining bytes
const [first, remainder] = decodeFirst(concatenatedData, decodeOptions)
assert.deepStrictEqual(first, obj)
assert.deepStrictEqual(remainder, data)

Spec

The dag-cbor specification is in the IPLD specs repo.

License

Licensed under either of

• Apache 2.0, (LICENSE-APACHE / http://www.apache.org/licenses/LICENSE-2.0)
• MIT (LICENSE-MIT / http://opensource.org/licenses/MIT)

Contribute

Unless 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.

9.2.4 (2025-05-22)

Bug Fixes

• address lint errors (467d98c)

Trivial Changes

• omit lockfile from release commit (#126) (2013bda)
• remove package-lock (6445f53)

Dependencies

• dev: bump aegir from 46.0.5 to 47.0.10 (c0b2879)

9.2.3 (2025-05-08)

Dependencies

• dev: bump aegir from 45.2.1 to 46.0.0 (0c42027)

9.2.2 (2024-10-29)

Dependencies

• dev: bump aegir from 44.1.4 to 45.0.1 (4e3216c)

9.2.1 (2024-06-24)

Dependencies

• dev: bump aegir from 42.2.11 to 44.0.0 (f703384)

9.2.0 (2024-02-16)

Features

• support decoding ArrayBuffers (#114) (a10269d)

9.1.0 (2024-01-30)

Features

• export encode/decode options (#113) (d2094ca)

9.0.8 (2024-01-10)

Dependencies

• dev: bump aegir from 41.3.5 to 42.1.0 (c335c50)

9.0.7 (2023-12-30)

Dependencies

• bump multiformats from 12.1.3 to 13.0.0 (#109) (7033a31)

9.0.6 (2023-10-03)

Dependencies

• dev: bump aegir from 40.0.13 to 41.0.0 (b57fb02)

9.0.5 (2023-09-12)

Trivial Changes

• add or force update .github/workflows/js-test-and-release.yml (1ac562b)
• delete templates [skip ci] (#103) (683e127)

Dependencies

• bump cborg from 2.0.5 to 4.0.0 (2adc833)

9.0.4 (2023-08-08)

Dependencies

• dev: bump aegir from 39.0.13 to 40.0.8 (ca7b37e)

9.0.3 (2023-06-19)

Dependencies

• bump multiformats from 11.0.2 to 12.0.1 (ca10d92)

9.0.2 (2023-06-14)

Dependencies

• bump cborg from 1.10.2 to 2.0.1 (d5fd52a)

9.0.1 (2023-05-22)

Bug Fixes

• address linting problems (1e61b12)

Dependencies

• dev: bump aegir from 37.12.1 to 39.0.8 (45f01de)

9.0.0 (2023-01-06)

⚠ BREAKING CHANGES

• reject duplicate map keys

Bug Fixes

• reject duplicate map keys (2e90e34)

8.0.1 (2023-01-03)

Dependencies

• bump multiformats from 10.0.3 to 11.0.0 (6c918c0)

8.0.0 (2022-10-19)

⚠ BREAKING CHANGES

• publish as esm-only (#71)

Features

• publish as esm-only (#71) (807fdd4)

Trivial Changes

• no-release: bump actions/setup-node from 3.4.1 to 3.5.0 (#68) (4716850)
• no-release: bump actions/setup-node from 3.5.0 to 3.5.1 (#70) (14f9cdc)

7.0.3 (2022-08-27)

Trivial Changes

• deps-dev: bump typescript from 4.7.4 to 4.8.2 (#67) (3338761)
• no-release: bump actions/setup-node from 3.2.0 to 3.3.0 (#63) (c6249cb)
• no-release: bump actions/setup-node from 3.3.0 to 3.4.0 (#65) (ec1f3ef)
• no-release: bump actions/setup-node from 3.4.0 to 3.4.1 (#66) (e2e20cf)
• no-release: bump ipld-garbage from 4.0.10 to 5.0.0 (#64) (80f71cb)

7.0.2 (2022-05-25)

Trivial Changes

• deps-dev: bump typescript from 4.6.4 to 4.7.2 (a4e2e3b)
• no-release: bump actions/setup-node from 3.0.0 to 3.1.0 (#54) (bf33215)
• no-release: bump actions/setup-node from 3.1.0 to 3.1.1 (#55) (ba23a66)
• no-release: bump actions/setup-node from 3.1.1 to 3.2.0 (#61) (ac1f42e)
• no-release: bump mocha from 9.2.2 to 10.0.0 (#58) (c024006)
• no-release: bump polendina from 2.0.15 to 3.0.0 (#59) (929ff18)
• no-release: bump polendina from 3.0.0 to 3.1.0 (#60) (ce5616b)
• no-release: bump standard from 16.0.4 to 17.0.0 (#56) (0095b44)

7.0.1 (2022-03-02)

Trivial Changes

• deps-dev: bump typescript from 4.5.5 to 4.6.2 (#53) (dae80a2)
• no-release: bump actions/checkout from 2.4.0 to 3 (#52) (4dfdf4e)
• no-release: bump actions/setup-node from 2.5.0 to 2.5.1 (#49) (e3cd6e9)
• no-release: bump actions/setup-node from 2.5.1 to 3.0.0 (#51) (b0a94de)

7.0.0 (2021-12-13)

⚠ BREAKING CHANGES

• coerce undefined to null on decode

Features

• coerce undefined to null on decode (8145728)

6.0.15 (2021-12-09)

Bug Fixes

• update dep descriptors (22dd509)

Trivial Changes

• use semantic-release, update testing (e1f6252)

0.15.2 (2020-03-27)

Bug Fixes

• remove node globals (#124) (7acfeae)
• package: update cids to version 0.8.0 (bc6ac54)

0.15.1 (2020-01-13)

Bug Fixes

• package: update multicodec to version 1.0.0 (d1d78a0)
• package: update multihashing-async to version 0.8.0 (b8d4a55)

0.15.0 (2019-05-10)

Bug Fixes

• package: update cids to version 0.7.0 (2dc3378)

BREAKING CHANGES

• package: Returned v1 CIDs now default to base32 encoding

Previous versions returned a base58 encoded string when toString()/ toBaseEncodedString() was called on a CIDv1. It now returns a base32 encoded string.

0.14.0 (2019-05-08)

Bug Fixes

• make cbor Decoder configurable (#90) (dfb9137)
• remove console.log statement (a413cb2)
• typo in travis badge (94122f0)
• package: update cids to version 0.6.0 (1d507f7)
• package: update multihashing-async to version 0.6.0 (b328072)

Features

• allow decoder heap to grow dynamically (1f7b7f1), closes #73
• new IPLD Format API (cfc8519)

BREAKING CHANGES

• The API is now async/await based

There are numerous changes, the most significant one is that the API is no longer callback based, but it using async/await.

For the full new API please see the IPLD Formats spec.

0.13.1 (2019-01-08)

Bug Fixes

• reduce bundle size (#87) (ab637f3)

Features

• support the hashLen option of multihashing (#83) (9ffb5e2)

0.13.0 (2018-10-01)

Bug Fixes

• resolve falsy values (0a49705)

Features

• serialize and de-serialize CID instances (8585d65)

BREAKING CHANGES

• return values from de-serializer are now CID instances. Serializer still supports old link objects.

0.12.1 (2018-06-29)

Bug Fixes

• pass serialized blob to util.cid (#67) (1ec7744)

Features

• add defaultHashAlg (#65) (e095ef5)
• add util.cid options (#66) (1aed60e)

BREAKING CHANGES

• the first argument is now the serialized output NOT the dag node. See https://github.com/ipld/interface-ipld-format/issues/32

0.12.0 (2018-02-12)

Bug Fixes

• use binary blobs directly (5321d6a)

BREAKING CHANGES

• Everyone calling the functions of resolve need to pass in the binary data instead of an IPFS block.

So if your input is an IPFS block, the code changes from

resolver.resolve(block, path, (err, result) => {…}

to

resolver.resolve(block.data, path, (err, result) => {…}

0.12.0 (2018-02-12)

Bug Fixes

• use binary blobs directly (5321d6a)

BREAKING CHANGES

• Everyone calling the functions of resolve need to pass in the binary data instead of an IPFS block.

So if your input is an IPFS block, the code changes from

resolver.resolve(block, path, (err, result) => {…}

to

resolver.resolve(block.data, path, (err, result) => {…}

0.11.2 (2017-11-07)

Features

• next Aegir (fix tests in the middle) (#53) (02940a0)

0.11.1 (2017-04-04)

0.11.0 (2017-03-21)

Features

• use new block api (4ec9228)

0.10.1 (2017-03-16)

0.10.0 (2017-03-13)

0.9.1 (2017-02-09)

0.9.0 (2017-02-02)

0.8.6 (2017-01-31)

Features

• CBOR TAG (#38) (13323a2)

0.8.5 (2017-01-29)

0.8.4 (2017-01-29)

0.8.3 (2016-12-11)

Features

• switch to borc (#31) (3164a81), closes #23

0.8.2 (2016-12-01)

0.8.1 (2016-11-21)

0.8.0 (2016-11-03)

0.7.1 (2016-10-30)

0.7.0 (2016-10-26)

Bug Fixes

• add array handling to .tree (656ad84)
• complete migration to async API (2e91d7c)
• out of scope traversal for 2 or more levels deep (b7a565b)

Features

• add util.serialize, util.deserialize and util.cid (fcc2ab5)
• resolve out of scope (bea41ea)
• resolver.resolve within scope (1158fa4)
• resolver.tree and resolver.multicodec (21ddefc)
• use async interfaces (48eb863)

0.6.0 (2016-05-22)

Bug Fixes

• cbor: Typo in lodash.clonedeep (2f617b0)
• Add missing babel-runtime dep (5c11ce8)
• correct references in package.json (12f18ab)
• Ensure inputs are not modified (b20f90b)

Features

• upgrade to latest spec (7375f99)

0.4.0 (2016-03-22)

0.3.1 (2015-11-13)

0.3.0 (2015-11-13)

0.2.1 (2015-10-29)

0.2.0 (2015-09-14)

0.1.3 (2015-09-04)

0.1.2 (2015-09-04)

0.1.1 (2015-09-01)

0.1.0 (2015-09-01)