IF Commons GitHub

cbor

Written to: 1 requirement: 0 proved, 0 partly, 0 failing, 1 with no test recorded. 0001-formats FR-014

CBOR (RFC 8949), read and written with no outside package (commons 0014-webauthn FR-001): what WebAuthn's attestation objects and COSE keys are made of. The reader takes the definite-length forms of every major type (unsigned and negative integers, byte and text strings, arrays, maps, tags, the simple values false, true, null and undefined, and half, single and double floats) and returns a Result whose error says what and at which byte: an indefinite length, a reserved additional value, text that is not UTF-8, a map key that is neither an integer nor a text string, a key given twice, nesting deeper than 64 levels, or bytes left over. An integer beyond Number.MAX_SAFE_INTEGER is a bigint. The writer gives the core deterministic encoding (RFC 8949 §4.2.1): the shortest heads, definite lengths and map keys sorted by their encoded bytes, so the same value is the same bytes every time.

import { type CborValue, decodeCbor, encodeCbor } from "./cbor.ts";
const bytes = encodeCbor(new Map<number | string, CborValue>([[1, 2], ["a", [true, null]]]));
decodeCbor(bytes); // { kind: "ok", value: Map { 1 => 2, "a" => [true, null] } }

Source: commons/formats/src/cbor.ts

6 of 24 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

cbornamespace
namespace cbor
cbor.CborKeytypeno test imports it
type CborKey = number | bigint | string;

A map key this module reads and writes: an integer or a text string.

cbor.CborTaggedtypeno test imports it
type CborTagged = { readonly tag: number | bigint; readonly value: CborValue };

A tagged value (major type 6): its tag number and the value it tags.

cbor.CborValuetypeno test imports it
type CborValue =
  number | bigint | string | Uint8Array | boolean | null | undefined | readonly CborValue[] | ReadonlyMap<CborKey, CborValue> | CborTagged;

A CBOR data item as a value: integers (a bigint beyond the safe range), floats, strings, bytes, arrays, maps, tags and simple values.

cbor.CborErrortypeno test imports it
type CborError = { readonly kind: "cbor"; readonly at: number; readonly message: string };

Why bytes are not CBOR this reader takes: what, and at which byte.

cbor.CborItemtypeno test imports it
type CborItem = { readonly value: CborValue; readonly end: number };

One data item read from a longer input: its value and the offset just after it.

cbor.MAX_DEPTHconstno test imports it
const MAX_DEPTH: 64

The deepest nesting of arrays, maps and tags read.

cbor.formatCborErrorfunctionno test imports it
function formatCborError(e: CborError): string

A CBOR error as one line.

cbor.isTaggedfunctionno test imports it
function isTagged(value: CborValue): value is CborTagged

Whether a value is a tagged value (rather than a map, an array or bytes).

cbor.isMapfunctionno test imports it
function isMap(value: CborValue): value is ReadonlyMap<CborKey, CborValue>

Whether a value is a map.

cbor.decodeCborItemfunctionno test imports it
function decodeCborItem(bytes: Uint8Array<ArrayBufferLike>, offset?: number): Result<CborItem, CborError>

The data item that starts at offset, and the offset just after it: for CBOR followed by more bytes (WebAuthn's authenticator data).

cbor.decodeCborfunctionno test imports it
function decodeCbor(bytes: Uint8Array<ArrayBufferLike>): Result<CborValue, CborError>

The one data item the bytes hold; bytes left after it are an error.

cbor.encodeCborfunctionno test imports it
function encodeCbor(value: CborValue): Uint8Array<ArrayBufferLike>

A value as CBOR, in the core deterministic encoding: integers (safe numbers or bigints) in their shortest head, other numbers as doubles, strings as UTF-8, Uint8Array as a byte string, arrays, maps with their keys sorted by their encoding, tags and the four simple values. A value no CBOR item can hold (an integer beyond 64 bits) is a programming error and throws a RangeError.

CborKeytype
type CborKey = number | bigint | string;

A map key this module reads and writes: an integer or a text string.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

CborTaggedtypeno test imports it
type CborTagged = { readonly tag: number | bigint; readonly value: CborValue };

A tagged value (major type 6): its tag number and the value it tags.

CborValuetype
type CborValue =
  number | bigint | string | Uint8Array | boolean | null | undefined | readonly CborValue[] | ReadonlyMap<CborKey, CborValue> | CborTagged;

A CBOR data item as a value: integers (a bigint beyond the safe range), floats, strings, bytes, arrays, maps, tags and simple values.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

CborErrortypeno test imports it
type CborError = { readonly kind: "cbor"; readonly at: number; readonly message: string };

Why bytes are not CBOR this reader takes: what, and at which byte.

CborItemtypeno test imports it
type CborItem = { readonly value: CborValue; readonly end: number };

One data item read from a longer input: its value and the offset just after it.

MAX_DEPTHconstno test imports it
const MAX_DEPTH: 64

The deepest nesting of arrays, maps and tags read.

formatCborErrorfunction
function formatCborError(e: CborError): string

A CBOR error as one line.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

isTaggedfunctionno test imports it
function isTagged(value: CborValue): value is CborTagged

Whether a value is a tagged value (rather than a map, an array or bytes).

isMapfunctionno test imports it
function isMap(value: CborValue): value is ReadonlyMap<CborKey, CborValue>

Whether a value is a map.

decodeCborItemfunction
function decodeCborItem(bytes: Uint8Array<ArrayBufferLike>, offset?: number): Result<CborItem, CborError>

The data item that starts at offset, and the offset just after it: for CBOR followed by more bytes (WebAuthn's authenticator data).

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

decodeCborfunction
function decodeCbor(bytes: Uint8Array<ArrayBufferLike>): Result<CborValue, CborError>

The one data item the bytes hold; bytes left after it are an error.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

encodeCborfunction
function encodeCbor(value: CborValue): Uint8Array<ArrayBufferLike>

A value as CBOR, in the core deterministic encoding: integers (safe numbers or bigints) in their shortest head, other numbers as doubles, strings as UTF-8, Uint8Array as a byte string, arrays, maps with their keys sorted by their encoding, tags and the four simple values. A value no CBOR item can hold (an integer beyond 64 bits) is a programming error and throws a RangeError.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.