`decoder`

(no submodules)

- half-float — Decodes 2 big-endian bytes representin…

half-float — Decodes 2 big-endian bytes representing IEEE 754 binary16 to a JavaScript number. The decoder is always available — n…
well-formed — isWellFormed(bytes) returns true iff bytes represent a single well-formed CBOR item per RFC 8949 §5.1. The functi…
half-float — Decodes 2 big-endian bytes representin…
half-float — Decodes 2 big-endian bytes representing IEEE 754 binary16 to a JavaScript number. The decoder is always available — n…
well-formed — isWellFormed(bytes) returns true iff bytes represent a single well-formed CBOR item per RFC 8949 §5.1. The functi…
half-float — Decodes 2 big-endian bytes representin…
half-float — Decodes 2 big-endian bytes representing IEEE 754 binary16 to a JavaScript number. The decoder is always available — n…
well-formed — isWellFormed(bytes) returns true iff bytes represent a single well-formed CBOR item per RFC 8949 §5.1. The functi…
half-float — Decodes 2 big-endian bytes representin…
half-float — Decodes 2 big-endian bytes representing IEEE 754 binary16 to a JavaScript number. The decoder is always available — n…
well-formed — isWellFormed(bytes) returns true iff bytes represent a single well-formed CBOR item per RFC 8949 §5.1. The functi…
half-float — Decodes 2 big-endian bytes representing IEEE 754 binary16 to a JavaScript number. The decoder is always available — n…
well-formed — isWellFormed(bytes) returns true iff bytes represent a single well-formed CBOR item per RFC 8949 §5.1. The functi…

Purpose

The CBOR decoder materialises an RFC 8949 byte sequence into a JavaScript value. It defaults to strict mode — every §5.1 well-formedness rule is enforced, including rejection of trailing bytes after the top-level item, truncation, malformed UTF-8, unmatched break stops, and reserved minor-type encodings. Lax mode applies §5.2 only and is provided for interop with producers that emit looser CBOR.

Features

All seven major types decode end-to-end, including indefinite-length byte/text strings and indefinite-length arrays/maps.
Half-float (binary16) decode — always available; never gated by an option.
BigInt fallback: u64 values exceeding Number.MAX_SAFE_INTEGER decode to bigint. Negative u64 values likewise.
Pluggable tag handling: callers pass a Map<number, TagHandler> and the decoder substitutes handler output for the inner value. Unknown tags return as Tagged per RFC 8949 §3.4.
Bounded recursion + bounded item count — maxDepth (default 64) and maxItems (default 1_000_000) caps prevent stack and memory blowups on adversarial inputs.
decodeOne returns the consumed byte count, enabling streaming and sequence decoders to advance their cursors precisely.

Usage: Basic Example

import { decode } from "@suaveplan/cbor/decoder";

const value = decode(bytes); // strict mode by default

Usage: Advanced Example

import { decode } from "@suaveplan/cbor/decoder";
import { defaultTagHandlers } from "@suaveplan/cbor/tags";

// Decode with the IANA built-in tag handlers (Date, URL, RegExp, ...)
const tags = defaultTagHandlers().snapshot();
const value = decode(bytes, { mode: "strict" }, tags);

API Reference

decode(bytes: Uint8Array, options?: DecoderOptions, tags?: ReadonlyMap<number, TagHandler>): DecodedValue
decodeOne(bytes, options?, tags?): { value: DecodedValue; consumed: number }
DecoderOptions:
- mode?: "strict" | "lax" — default "strict".
- tagHandling?: "registered" | "raw" — default "registered". "raw" yields Tagged instances even when a handler exists.
- maxDepth?: number, maxItems?: number, allowTrailingBytes?: boolean.

Throws CborError with codes MALFORMED, UNEXPECTED_TYPE, NESTED_TOO_DEEP, LENGTH_OVERFLOW, INDEFINITE_NOT_ALLOWED.

Implementation Notes

The decoder is single-pass and zero-copy where possible — subarray views into the input buffer back returned Uint8Array byte strings. Indefinite text/byte strings are reassembled chunk by chunk; nested indefinite chunks are explicitly rejected per §3.2. UTF-8 decoding uses a fatal-mode TextDecoder so invalid sequences raise MALFORMED rather than silently substituting U+FFFD. The decodeOne exit point exposes the cursor position so upstream sequence + streaming decoders can advance the input without re-tokenising.

4.7 KiB Raw Permalink Blame History

decoder