@ipld/dag-cbor

What is @ipld/dag-cbor?

@ipld/dag-cbor is an npm package that provides tools for encoding and decoding data in the CBOR (Concise Binary Object Representation) format, specifically tailored for use with the InterPlanetary Linked Data (IPLD) system. It allows for efficient and compact serialization of data structures, making it suitable for use in distributed systems and blockchain technologies.

What are @ipld/dag-cbor's main functionalities?

Encoding Data

This feature allows you to encode a JavaScript object into CBOR format. The `serialize` method converts the object into a binary representation.

const dagCBOR = require('@ipld/dag-cbor');
const data = { hello: 'world' };
const encoded = dagCBOR.util.serialize(data);
console.log(encoded);

Decoding Data

This feature allows you to decode CBOR data back into a JavaScript object. The `deserialize` method takes a binary representation and converts it back into a readable object.

const dagCBOR = require('@ipld/dag-cbor');
const encoded = new Uint8Array([161, 101, 104, 101, 108, 108, 111, 101, 119, 111, 114, 108, 100]);
const decoded = dagCBOR.util.deserialize(encoded);
console.log(decoded);

CID Generation

This feature allows you to generate a Content Identifier (CID) for a given piece of data. The CID is a unique identifier used in IPLD to reference data objects.

const dagCBOR = require('@ipld/dag-cbor');
const CID = require('cids');
const data = { hello: 'world' };
const encoded = dagCBOR.util.serialize(data);
const cid = new CID(1, 'dag-cbor', dagCBOR.util.cid(encoded));
console.log(cid.toString());

Other packages similar to @ipld/dag-cbor

cbor

The `cbor` package is a general-purpose CBOR encoder/decoder for JavaScript. It provides similar functionality for encoding and decoding CBOR data but is not specifically tailored for IPLD. It is more versatile for general CBOR use cases.

borc

The `borc` package is another CBOR encoder/decoder that focuses on performance and compliance with the CBOR specification. Like `cbor`, it is not specialized for IPLD but offers efficient CBOR serialization and deserialization.

ipld

The `ipld` package provides a more comprehensive suite of tools for working with IPLD data structures, including support for multiple formats like DAG-CBOR, DAG-JSON, and more. It offers broader functionality compared to `@ipld/dag-cbor` but includes it as a part of its toolkit.

README

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

Changelog

9.1.0 (2024-01-30)

Features

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