Tiny CBOR

Encode and decode a useful subset of CBOR into simple JavaScript structures. Focused on clarity and portability.

#Install#

npm i @levischuck/tiny-cbor

pnpm add @levischuck/tiny-cbor

deno add jsr:@levischuck/tiny-cbor

bunx jsr add @levischuck/tiny-cbor

#Quick start#

1
import { encodeCBOR, decodeCBOR } from '@levischuck/tiny-cbor'
2
​
3
// Encode a simple structure
4
const value = new Map<string | number, any>([
5
  ['key', 'value'],
6
  [1, 'another value'],
7
])
8
const bytes: Uint8Array = encodeCBOR(value)
9
​
10
// Decode back to JS structures
11
const decoded = decodeCBOR(bytes) // Map<string | number, CBORType>

#Partial decoding#

When CBOR is embedded in a larger byte stream, use decodePartialCBOR to start from an index.

1
import { decodePartialCBOR } from '@levischuck/tiny-cbor'
2
​
3
const byteStream = new Uint8Array([1, 2, 245, 3, 4])
4
const [value, consumed] = decodePartialCBOR(byteStream, 2)
5
// value === true, consumed === 1

#Tags#

Wrap values with a CBOR tag without interpretation at decode-time.

1
import { CBORTag, encodeCBOR, decodeCBOR } from '@levischuck/tiny-cbor'
2
​
3
const tagged = new CBORTag(1234, 'hello')
4
const bytes = encodeCBOR(tagged)
5
const decoded = decodeCBOR(bytes) as CBORTag
6
decoded.tag // 1234
7
decoded.value // 'hello'

#API#

#encodeCBOR#

Encode a supported structure to a CBOR byte string.

• Signature: encodeCBOR(data: CBORType): Uint8Array
• Parameters: data – Data to encode
• Returns: A byte string as a Uint8Array
• Throws: Error if unsupported data is found during encoding

#decodeCBOR#

Decode CBOR data from a binary stream. The entire data stream from [0, length) will be consumed. If you require a partial decoding, see decodePartialCBOR.

• Signature: decodeCBOR(data: DataView | Uint8Array | ArrayBuffer | ArrayBufferLike): CBORType
• Parameters: data – a data stream, multiple types are supported
• Returns: Decoded CBORType value
• Throws: Error when the whole stream is not fully consumed

#decodePartialCBOR#

Like decodeCBOR, but the length of the data is unknown and there is likely more — possibly unrelated non-CBOR — data afterwards. Start decoding at a specific index and receive the value plus the number of bytes consumed.

• Signature: decodePartialCBOR(data: DataView | Uint8Array | ArrayBuffer | ArrayBufferLike, index: number): [CBORType, number]
• Parameters:
  • data – a data stream to read data from
  • index – where to start reading in the data stream
• Returns: a tuple of the value followed by bytes read
• Throws: Error when the data stream ends early or the CBOR data is not well formed

#CBORTag#

A value which is wrapped with a CBOR Tag. Several tags are registered with defined meanings like 0 for a date string. These meanings are not interpreted when decoded or encoded. This class is an immutable record. If the tag number or value needs to change, construct a new tag.

• Signature: class CBORTag(tag: number | bigint, value: CBORType)
• Getters: .tag – the tag number; .value – the wrapped value

#CBORType#

Supported types which are encodable and decodable with Tiny CBOR. Note that plain JavaScript objects are omitted. If you're looking to use JSON objects more easily, check out Tiny CBOR Schema.

number | bigint | string | Uint8Array | boolean | null | undefined | CBORType[] | CBORTag | Map<string | number, CBORType>

Source codeBack to Docs