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';constvalue=true;constencoded=encode(value);// returns `Uint8Array [245]` (which is "F5" in hex)constdecoded=decode(encoded);// returns `true`

With replacer/reviver:

import{encode,decode,typeReplacer,typeReviver}from'@dfinity/cbor';constvalue={a: 1,b: 2};// Encoding with replacerconstreplacer: Replacer=val=>(typeofval==='number' ? val*2 : val);constresult=encode(value,replacer);decode(result);// { a: 2, b: 4 }// Decoding with reviverconstbytes=encode(value);constreviver: Reviver=val=>(typeofval==='number' ? val*2 : val);decode(bytes,reviver);// { a: 2, b: 4 }

API

🧰 Functions

• decode
• encode
• encodeWithSelfDescribedTag

⚙️ 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

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

Reviver

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

⚙️ 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

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

Replacer

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

⚙️ 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:

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

🔧 Constants

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

⚙️ 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

⚙️ CBOR_STOP_CODE

Constant	Type
CBOR_STOP_CODE	unique symbol

⚙️ TOKEN_VALUE_MAX

Constant	Type
TOKEN_VALUE_MAX	23

⚙️ ONE_BYTE_MAX

Constant	Type
ONE_BYTE_MAX	255

⚙️ TWO_BYTES_MAX

Constant	Type
TWO_BYTES_MAX	65535

⚙️ FOUR_BYTES_MAX

Constant	Type
FOUR_BYTES_MAX	4294967295

⚙️ EIGHT_BYTES_MAX

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

Constant	Type
EIGHT_BYTES_MAX	bigint

🏭 DecodingError

🏭 EncodingError

🔩 Enum

• CborSimpleType
• CborMajorType
• CborMinorType

⚙️ CborSimpleType

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

⚙️ CborMajorType

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

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