@dfinity/cbor

CBOR encoder/decoder

A small implementation of Concise Binary Object Representation (CBOR) in pure JavaScript.

Note: this package is not 100% compatible with the CBOR specification. See the Not implemented section for more details.

Installation

Using npm:

npm install @dfinity/cbor

Using pnpm:

pnpm add @dfinity/cbor

Using yarn:

yarn add @dfinity/cbor

Usage

Simple:

import { encode, decode } from '@dfinity/cbor';

const value = true;
const encoded = encode(value); // returns `Uint8Array [245]` (which is "F5" in hex)
const decoded = decode(encoded); // returns `true`

With replacer/reviver:

import { encode, decode, type Replacer, type Reviver } from '@dfinity/cbor';

const value = { a: 1, b: 2 };

// Encoding with replacer
const replacer: Replacer = val => (typeof val === 'number' ? val * 2 : val);
const result = encode(value, replacer);
decode(result); // { a: 2, b: 4 }

// Decoding with reviver
const bytes = encode(value);
const reviver: Reviver = val => (typeof val === 'number' ? val * 2 : val);
decode(bytes, reviver); // { a: 2, b: 4 }

API

:toolbox: Functions

• decode
• encode
• encodeWithSelfDescribedTag

:gear: decode

Decodes a CBOR byte array into a value. See {@link Reviver} for more information.

Function	Type
decode	<T extends unknown = any>(input: Uint8Array<ArrayBufferLike>, reviver?: Reviver<T> or undefined) => T

Parameters:

• input: - The CBOR byte array to decode.
• reviver: - A function that can be used to manipulate the decoded value.

Examples:

Simple

const value = true;
const encoded = encode(value); // returns `Uint8Array [245]` (which is "F5" in hex)
const decoded = decode(encoded); // returns `true`

Reviver

const bytes = ...; // Uint8Array corresponding to the CBOR encoding of `{ a: 1, b: 2 }`
const reviver: Reviver = val => (typeof val === 'number' ? val * 2 : val);
decode(bytes, reviver); // returns `{ a: 2, b: 4 }`

:gear: encode

Encodes a value into a CBOR byte array.

Function	Type
encode	<T = any>(value: CborValue<T>, replacer?: Replacer<T> or undefined) => Uint8Array<ArrayBufferLike>

Parameters:

• value: - The value to encode.
• replacer: - A function that can be used to manipulate the input before it is encoded.

Examples:

Simple

const value = true;
const encoded = encode(value); // returns `Uint8Array [245]` (which is "F5" in hex)

Replacer

const replacer: Replacer = val => (typeof val === 'number' ? val * 2 : val);
encode({ a: 1, b: 2 }, replacer); // returns the Uint8Array corresponding to the CBOR encoding of `{ a: 2, b: 4 }`

:gear: encodeWithSelfDescribedTag

Encodes a value into a CBOR byte array (same as {@link encode}), but prepends the self-described CBOR tag (55799).

Function	Type
encodeWithSelfDescribedTag	<T = any>(value: CborValue<T>, replacer?: Replacer<T> or undefined) => Uint8Array<ArrayBufferLike>

Parameters:

• value: - The value to encode.
• replacer: - A function that can be used to manipulate the input before it is encoded.

Examples:

const value = true;
const encoded = encodeWithSelfDescribedTag(value); // returns the Uint8Array [217, 217, 247, 245] (which is "D9D9F7F5" in hex)

:wrench: Constants

• CBOR_SELF_DESCRIBED_TAG
• CBOR_STOP_CODE
• TOKEN_VALUE_MAX
• ONE_BYTE_MAX
• TWO_BYTES_MAX
• FOUR_BYTES_MAX
• EIGHT_BYTES_MAX

:gear: CBOR_SELF_DESCRIBED_TAG

The tag number 55799, the self-described tag for CBOR. The serialization of this tag's head is 0xd9d9f7.

Constant	Type
CBOR_SELF_DESCRIBED_TAG	55799

:gear: CBOR_STOP_CODE

Constant	Type
CBOR_STOP_CODE	unique symbol

:gear: TOKEN_VALUE_MAX

Constant	Type
TOKEN_VALUE_MAX	23

:gear: ONE_BYTE_MAX

Constant	Type
ONE_BYTE_MAX	255

:gear: TWO_BYTES_MAX

Constant	Type
TWO_BYTES_MAX	65535

:gear: FOUR_BYTES_MAX

Constant	Type
FOUR_BYTES_MAX	4294967295

:gear: EIGHT_BYTES_MAX

The maximum value that can be encoded in 8 bytes: 18446744073709551615n.

Constant	Type
EIGHT_BYTES_MAX	bigint

:factory: DecodingError

:factory: EncodingError

:nut_and_bolt: Enum

• CborSimpleType
• CborMajorType
• CborMinorType

:gear: CborSimpleType

Property	Type	Description
False	0x14
True	0x15
Null	0x16
Undefined	0x17
Break	0x1f

:gear: CborMajorType

Property	Type	Description
UnsignedInteger	0
NegativeInteger	1
ByteString	2
TextString	3
Array	4
Map	5
Tag	6
Simple	7

:gear: CborMinorType

Property	Type	Description
Value	23
OneByte	24
TwoBytes	25
FourBytes	26
EightBytes	27
Indefinite	31

Not implemented

• Custom tag encoding/decoding.
  • Custom tags allow for encoding and decoding of custom types.
  • We currently don't use this custom tags (although we probably should).
  • Since we don't directly encode developer provided data (that's encoded by Candid) then we can safely say we don't need the feature.
• Unit tests for text/byte strings with a length that does not fit in four bytes or less.
  • The "length" of the text string can be encoded with up to 8 bytes, which means the largest possible string length is 18,446,744,073,709,551,615. The tests cover a string length that's encoded up to four 4 bytes, longer than this and the tests became extremely slow.
  • The largest number in 4 bytes is 2,147,483,647 which would represent the length of an ~2gb string, which is not possible to fit into a single IC message anyway.
• Indeterminite length encoding for text and byte strings
  • To encode a string length longer than the previously mentioned 8 byte limit, a string can be encoded with an "indeterminate" length.
  • Similar to the previous point, this would be impractical for the IC due to message limits.

Contributing

Check out the contribution guidelines.

Setup

• Install pnpm
• Install commitizen
• Install pre-commit
• Install dependencies:

  pnpm install
  

Running tests

pnpm test

Formatting

pnpm format

Generating documentation

We use tsdoc-markdown to generate the documentation.

To update the documentation in the README.md file, run:

pnpm tsdoc

License

This project is licensed under the Apache License 2.0.