CBOR encoder/decoder

!Libraries.io dependency status for latest release


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:

``bash
npm install @dfinity/cbor
`

Using pnpm:

`bash
pnpm add @dfinity/cbor
`

Using yarn:

`bash
yarn add @dfinity/cbor
`

Usage

Simple:

`ts
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:

`ts
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

$3

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

| Function | Type |
| -------- | ------------------------------------------------------------------------------------------------------- |
| decode | (input: Uint8Array, reviver?: Reviver 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

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

Reviver

`ts
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 }
`

$3

Encodes a value into a CBOR byte array.

| Function | Type |
| -------- | ---------------------------------------------------------------------------------------------------- |
| encode | (value: CborValue, replacer?: Replacer or undefined) => Uint8Array |

Parameters:

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

Examples:

Simple

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

Replacer

`ts
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 }
`

$3

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

| Function | Type |
| ---------------------------- | ---------------------------------------------------------------------------------------------------- |
| encodeWithSelfDescribedTag | (value: CborValue, replacer?: Replacer or undefined) => Uint8Array |

Parameters:

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

Examples:

`ts
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

$3

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 |

$3

| Constant | Type |
| ---------------- | --------------- |
| CBOR_STOP_CODE | unique symbol |

$3

| Constant | Type |
| ----------------- | ---- |
| TOKEN_VALUE_MAX | 23 |

$3

| Constant | Type |
| -------------- | ----- |
| ONE_BYTE_MAX | 255 |

$3

| Constant | Type |
| --------------- | ------- |
| TWO_BYTES_MAX | 65535 |

$3

| Constant | Type |
| ---------------- | ------------ |
| FOUR_BYTES_MAX | 4294967295 |

$3

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

$3

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

$3

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

$3

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

$3

- Install pnpm
- Install commitizen
- Install pre-commit
- Install dependencies:
`bash
pnpm install
`

$3

`bash
pnpm test
`

$3

`bash
pnpm format
`

$3

We use tsdoc-markdown to generate the documentation.

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

`bash
pnpm tsdoc
``

License

This project is licensed under the Apache License 2.0.