@btoon/js 0.0.0-stage → 0.1.0

package/dist/esm/errors.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Machine-readable error codes. All but `invalid_argument` are the decoder error codes
+ * of SPEC §7; `invalid_argument` reports a value or option the library cannot accept.
+ */
+export type BtoonErrorCode = 
+/** Input ends before a value is complete, or a length runs past the input. */
+'truncated'
+/** The reserved marker byte `0xc1`. */
+ | 'invalid_marker'
+/** Bytes remain after the top-level value (strict mode). */
+ | 'trailing_data'
+/** A string, map key or column name is not well-formed UTF-8 (or, when encoding, a string contains a lone surrogate). */
+ | 'invalid_utf8'
+/** A map key is not a string. */
+ | 'non_string_key'
+/** A map contains the same key twice (strict mode). */
+ | 'duplicate_key'
+/** Nesting deeper than `maxDepth`, or a cyclic value. */
+ | 'max_depth'
+/** A malformed BTOON extension payload (timestamp, date, datetime, bigint, vectors). */
+ | 'invalid_extension'
+/** A malformed tabular payload. */
+ | 'invalid_tabular'
+/** A malformed compression or signed envelope, or a corrupt compressed payload. */
+ | 'invalid_envelope'
+/** A size above a configured limit (for example `maxDecompressedSize`). */
+ | 'size_limit'
+/** A compression algorithm that is unknown or not available in this environment. */
+ | 'unsupported_compression'
+/** HMAC verification failed, a signature was required but missing, or a signed input arrived without a key. */
+ | 'authentication_failed'
+/** A value that cannot be encoded, or an invalid option. */
+ | 'invalid_argument';
+/**
+ * The only error type thrown by this library's `encode`/`decode` functions (and the only
+ * rejection reason of the async variants). Branch on {@link BtoonError.code}, which is
+ * stable across BTOON implementations; the message is for humans and may change.
+ */
+export declare class BtoonError extends Error {
+    /** Machine-readable error code (SPEC §7, plus `invalid_argument`). */
+    readonly code: BtoonErrorCode;
+    constructor(code: BtoonErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Shorthand used internally: `throw fail('truncated', '...')`. */
+export declare function fail(code: BtoonErrorCode, message: string, cause?: unknown): BtoonError;
+/**
+ * True for the engine's "too much recursion" error. Raising `maxDepth` far above the
+ * default can exhaust the JavaScript call stack before the depth limit triggers; that
+ * case is reported as `max_depth` instead of leaking a RangeError.
+ */
+export declare function isStackOverflow(e: unknown): boolean;

package/dist/esm/errors.js

@@ -0,0 +1,39 @@
+/**
+ * The only error type thrown by this library's `encode`/`decode` functions (and the only
+ * rejection reason of the async variants). Branch on {@link BtoonError.code}, which is
+ * stable across BTOON implementations; the message is for humans and may change.
+ */
+export class BtoonError extends Error {
+    constructor(code, message, options) {
+        super(message);
+        this.name = 'BtoonError';
+        this.code = code;
+        if (options !== undefined && 'cause' in options) {
+            Object.defineProperty(this, 'cause', {
+                value: options.cause,
+                writable: true,
+                enumerable: false,
+                configurable: true,
+            });
+        }
+    }
+}
+/** Shorthand used internally: `throw fail('truncated', '...')`. */
+export function fail(code, message, cause) {
+    return cause === undefined ? new BtoonError(code, message) : new BtoonError(code, message, { cause });
+}
+/**
+ * True for the engine's "too much recursion" error. Raising `maxDepth` far above the
+ * default can exhaust the JavaScript call stack before the depth limit triggers; that
+ * case is reported as `max_depth` instead of leaking a RangeError.
+ */
+export function isStackOverflow(e) {
+    if (e instanceof BtoonError)
+        return false;
+    if (typeof e !== 'object' || e === null)
+        return false;
+    const err = e;
+    if (err.name !== 'RangeError' && err.name !== 'InternalError')
+        return false;
+    return typeof err.message === 'string' && /call stack|recursion/i.test(err.message);
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * BTOON for JavaScript and TypeScript — portable entry point (browsers, Deno, Bun-for-web,
+ * Cloudflare Workers and other edge runtimes). It imports no `node:` modules.
+ *
+ * Synchronous `decode` handles zlib compression envelopes (pure-JS inflate) and signed
+ * envelopes (pure-JS HMAC-SHA256) everywhere; synchronous compression needs a codec from
+ * `options.codecs`, while `encodeAsync` uses `CompressionStream`. Node.js resolves the
+ * package to a sibling entry with the same API that uses `node:zlib` and `node:crypto`.
+ *
+ * @packageDocumentation
+ */
+import { type BinaryInput } from './core.js';
+import type { DecodeOptions, EncodeOptions } from './options.js';
+export { SPEC_VERSION, VERSION } from './constants.js';
+export type { BinaryInput } from './core.js';
+export { BtoonError, type BtoonErrorCode } from './errors.js';
+export type { Codec, CodecRegistry, CompressionAlgorithm, DecodeOptions, EncodeOptions } from './options.js';
+export { Ext, Timestamp } from './values.js';
+/**
+ * Encodes a value as canonical BTOON (SPEC §4): identical values produce identical bytes
+ * in every conforming implementation.
+ *
+ * Accepted values: `null`/`undefined` (nil), booleans, numbers (safe integers as integers,
+ * everything else — including `-0`, `NaN` and integral values beyond ±2^53 — as float64),
+ * `bigint`, strings (must not contain lone surrogates), `Uint8Array`/`ArrayBuffer`/other
+ * typed arrays and `DataView` (binary), `Float32Array`/`Float64Array` (float vectors),
+ * arrays, plain objects and `Map`s with string keys (maps, keys sorted by UTF-8 bytes),
+ * `Date` and {@link Timestamp} (timestamps), and {@link Ext}. Any other object is encoded
+ * the way `JSON.stringify` sees it: the result of its `toJSON()` method if it has one
+ * (called once), otherwise a map of its own enumerable string-keyed properties; `Number`,
+ * `String`, `Boolean` and `BigInt` wrapper objects are unwrapped. Functions and symbols are
+ * rejected. Arrays of uniform objects use the tabular encoding when it is smaller.
+ *
+ * With `compress` or `hmacKey`, the document is wrapped in a compression and/or signed
+ * envelope, layered as sign(compress(document)).
+ *
+ * @throws {BtoonError} `invalid_argument` for functions, symbols or invalid options, `max_depth`
+ *   for values nested deeper than `maxDepth` (including cycles), `invalid_utf8` for strings
+ *   with lone surrogates, `unsupported_compression` if the algorithm has no synchronous
+ *   implementation here (see `encodeAsync` and `options.codecs`).
+ */
+export declare function encode(value: unknown, options?: EncodeOptions): Uint8Array<ArrayBuffer>;
+/**
+ * Decodes one BTOON document, enforcing SPEC §7: bounds-checked reads, a nesting limit,
+ * no allocation beyond what the input justifies, strict UTF-8, unique map keys and no
+ * trailing bytes. Compression envelopes are decompressed (with the output capped at the
+ * declared size and `maxDecompressedSize`); with `hmacKey` the signature is verified before
+ * anything is parsed.
+ *
+ * Maps decode to plain objects. A `"__proto__"` key becomes an own property (as with
+ * `JSON.parse`); it never changes an object's prototype.
+ *
+ * @throws {BtoonError} with the SPEC §7 error code describing the problem.
+ */
+export declare function decode(data: BinaryInput, options?: DecodeOptions): unknown;
+/**
+ * Like {@link encode}, but compresses with `CompressionStream` (when the runtime supports
+ * the algorithm) and signs with WebCrypto, falling back to the synchronous implementations.
+ * Rejects with a {@link BtoonError}.
+ */
+export declare function encodeAsync(value: unknown, options?: EncodeOptions): Promise<Uint8Array<ArrayBuffer>>;
+/**
+ * Like {@link decode}, but decompresses with `DecompressionStream` (when the runtime
+ * supports the algorithm) and verifies signatures with `crypto.subtle.verify`, falling back
+ * to the synchronous implementations. The input is copied first, so the caller may reuse
+ * its buffer immediately. Rejects with a {@link BtoonError}.
+ */
+export declare function decodeAsync(data: BinaryInput, options?: DecodeOptions): Promise<unknown>;

package/dist/esm/index.js

@@ -0,0 +1,74 @@
+/**
+ * BTOON for JavaScript and TypeScript — portable entry point (browsers, Deno, Bun-for-web,
+ * Cloudflare Workers and other edge runtimes). It imports no `node:` modules.
+ *
+ * Synchronous `decode` handles zlib compression envelopes (pure-JS inflate) and signed
+ * envelopes (pure-JS HMAC-SHA256) everywhere; synchronous compression needs a codec from
+ * `options.codecs`, while `encodeAsync` uses `CompressionStream`. Node.js resolves the
+ * package to a sibling entry with the same API that uses `node:zlib` and `node:crypto`.
+ *
+ * @packageDocumentation
+ */
+import { decodeAsyncWith, decodeWith, encodeAsyncWith, encodeWith } from './core.js';
+import { portablePlatform } from './platform-portable.js';
+export { SPEC_VERSION, VERSION } from './constants.js';
+export { BtoonError } from './errors.js';
+export { Ext, Timestamp } from './values.js';
+/**
+ * Encodes a value as canonical BTOON (SPEC §4): identical values produce identical bytes
+ * in every conforming implementation.
+ *
+ * Accepted values: `null`/`undefined` (nil), booleans, numbers (safe integers as integers,
+ * everything else — including `-0`, `NaN` and integral values beyond ±2^53 — as float64),
+ * `bigint`, strings (must not contain lone surrogates), `Uint8Array`/`ArrayBuffer`/other
+ * typed arrays and `DataView` (binary), `Float32Array`/`Float64Array` (float vectors),
+ * arrays, plain objects and `Map`s with string keys (maps, keys sorted by UTF-8 bytes),
+ * `Date` and {@link Timestamp} (timestamps), and {@link Ext}. Any other object is encoded
+ * the way `JSON.stringify` sees it: the result of its `toJSON()` method if it has one
+ * (called once), otherwise a map of its own enumerable string-keyed properties; `Number`,
+ * `String`, `Boolean` and `BigInt` wrapper objects are unwrapped. Functions and symbols are
+ * rejected. Arrays of uniform objects use the tabular encoding when it is smaller.
+ *
+ * With `compress` or `hmacKey`, the document is wrapped in a compression and/or signed
+ * envelope, layered as sign(compress(document)).
+ *
+ * @throws {BtoonError} `invalid_argument` for functions, symbols or invalid options, `max_depth`
+ *   for values nested deeper than `maxDepth` (including cycles), `invalid_utf8` for strings
+ *   with lone surrogates, `unsupported_compression` if the algorithm has no synchronous
+ *   implementation here (see `encodeAsync` and `options.codecs`).
+ */
+export function encode(value, options) {
+    return encodeWith(value, options, portablePlatform);
+}
+/**
+ * Decodes one BTOON document, enforcing SPEC §7: bounds-checked reads, a nesting limit,
+ * no allocation beyond what the input justifies, strict UTF-8, unique map keys and no
+ * trailing bytes. Compression envelopes are decompressed (with the output capped at the
+ * declared size and `maxDecompressedSize`); with `hmacKey` the signature is verified before
+ * anything is parsed.
+ *
+ * Maps decode to plain objects. A `"__proto__"` key becomes an own property (as with
+ * `JSON.parse`); it never changes an object's prototype.
+ *
+ * @throws {BtoonError} with the SPEC §7 error code describing the problem.
+ */
+export function decode(data, options) {
+    return decodeWith(data, options, portablePlatform);
+}
+/**
+ * Like {@link encode}, but compresses with `CompressionStream` (when the runtime supports
+ * the algorithm) and signs with WebCrypto, falling back to the synchronous implementations.
+ * Rejects with a {@link BtoonError}.
+ */
+export function encodeAsync(value, options) {
+    return encodeAsyncWith(value, options, portablePlatform);
+}
+/**
+ * Like {@link decode}, but decompresses with `DecompressionStream` (when the runtime
+ * supports the algorithm) and verifies signatures with `crypto.subtle.verify`, falling back
+ * to the synchronous implementations. The input is copied first, so the caller may reuse
+ * its buffer immediately. Rejects with a {@link BtoonError}.
+ */
+export function decodeAsync(data, options) {
+    return decodeAsyncWith(data, options, portablePlatform);
+}

package/dist/esm/inflate.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Decompresses an RFC 1950 zlib stream that must expand to at most `limit` bytes. Throws
+ * `invalid_envelope` for corrupt or truncated input, trailing bytes after the stream, or
+ * output beyond `limit`. The output buffer grows geometrically, so a lying size header
+ * cannot force a large allocation for a small input.
+ */
+export declare function inflateZlib(input: Uint8Array, limit: number): Uint8Array;
+/** Adler-32 checksum of `d[start, end)` (RFC 1950). */
+export declare function adler32(d: Uint8Array, start?: number, end?: number): number;

package/dist/esm/inflate.js

@@ -0,0 +1,349 @@
+// A small, bounded zlib (RFC 1950) / DEFLATE (RFC 1951) decoder for runtimes without a
+// synchronous native one (browsers, Deno, edge workers). It accepts exactly what zlib's
+// inflate accepts (same rules for incomplete and over-subscribed Huffman codes, distance
+// limits and the Adler-32 trailer), rejects trailing bytes after the stream, and never
+// writes past the declared output size. Work per input byte is bounded: Huffman tables
+// cost at most 512 entries to build, and longer codes are decoded bit by bit.
+import { fail } from './errors.js';
+const FAST_BITS = 9;
+const FAST_SIZE = 1 << FAST_BITS;
+const FAST_MASK = FAST_SIZE - 1;
+const LEN_BASE = [3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 15, 17, 19, 23, 27, 31, 35, 43, 51, 59, 67, 83, 99, 115, 131, 163, 195, 227, 258];
+const LEN_EXTRA = [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 0];
+const DIST_BASE = [
+    1, 2, 3, 4, 5, 7, 9, 13, 17, 25, 33, 49, 65, 97, 129, 193, 257, 385, 513, 769, 1025, 1537, 2049, 3073, 4097, 6145,
+    8193, 12289, 16385, 24577,
+];
+const DIST_EXTRA = [0, 0, 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9, 10, 10, 11, 11, 12, 12, 13, 13];
+const CL_ORDER = [16, 17, 18, 0, 8, 7, 9, 6, 10, 5, 11, 4, 12, 3, 13, 2, 14, 1, 15];
+function corrupt(what) {
+    return fail('invalid_envelope', `zlib payload ${what}`);
+}
+/** Canonical Huffman code: counts per length, symbols in canonical order, a 9-bit fast table. */
+class Huffman {
+    constructor(n) {
+        this.count = new Uint16Array(16);
+        /** Indexed by the next 9 input bits: (symbol << 4) | length, or 0 for "decode slowly". */
+        this.fast = new Uint16Array(FAST_SIZE);
+        /** Longest code length in use (0 = no codes). */
+        this.max = 0;
+        this.symbol = new Uint16Array(n);
+    }
+    /** Builds from `n` code lengths; returns unused code space (0 = complete, < 0 = over-subscribed). */
+    build(lengths, offset, n) {
+        const count = this.count;
+        count.fill(0);
+        for (let i = 0; i < n; i++)
+            count[lengths[offset + i]]++;
+        count[0] = 0;
+        let max = 0;
+        let left = 1;
+        for (let len = 1; len <= 15; len++) {
+            left <<= 1;
+            left -= count[len];
+            if (left < 0)
+                return left;
+            if (count[len])
+                max = len;
+        }
+        this.max = max;
+        const offs = new Uint16Array(16);
+        for (let len = 1; len < 15; len++)
+            offs[len + 1] = offs[len] + count[len];
+        for (let sym = 0; sym < n; sym++) {
+            const len = lengths[offset + sym];
+            if (len)
+                this.symbol[offs[len]++] = sym;
+        }
+        const fast = this.fast;
+        fast.fill(0);
+        let code = 0;
+        let idx = 0;
+        for (let len = 1; len <= FAST_BITS; len++) {
+            for (let k = count[len]; k > 0; k--) {
+                let rev = 0;
+                for (let b = 0; b < len; b++)
+                    rev |= ((code >> b) & 1) << (len - 1 - b);
+                const entry = (this.symbol[idx] << 4) | len;
+                for (let j = rev; j < FAST_SIZE; j += 1 << len)
+                    fast[j] = entry;
+                idx++;
+                code++;
+            }
+            code <<= 1;
+        }
+        return left;
+    }
+}
+let fixedLit = null;
+let fixedDist = null;
+function fixedTables() {
+    if (fixedLit === null || fixedDist === null) {
+        const l = new Uint8Array(288);
+        l.fill(8, 0, 144);
+        l.fill(9, 144, 256);
+        l.fill(7, 256, 280);
+        l.fill(8, 280, 288);
+        fixedLit = new Huffman(288);
+        fixedLit.build(l, 0, 288);
+        const d = new Uint8Array(30).fill(5);
+        fixedDist = new Huffman(30);
+        fixedDist.build(d, 0, 30); // incomplete (30 of 32 codes), as in zlib
+    }
+    return [fixedLit, fixedDist];
+}
+class Inflater {
+    constructor(input, limit) {
+        this.inPos = 0;
+        this.bitBuf = 0;
+        this.bitCnt = 0;
+        this.outPos = 0;
+        this.input = input;
+        this.limit = limit;
+        this.out = new Uint8Array(Math.min(limit, Math.max(64 * 1024, input.length * 4)));
+    }
+    bits(n) {
+        while (this.bitCnt < n) {
+            if (this.inPos >= this.input.length)
+                throw corrupt('is truncated');
+            this.bitBuf |= this.input[this.inPos++] << this.bitCnt;
+            this.bitCnt += 8;
+        }
+        const v = this.bitBuf & ((1 << n) - 1);
+        this.bitBuf >>>= n;
+        this.bitCnt -= n;
+        return v;
+    }
+    /** Next Huffman symbol, or -1 if the bits match no code. */
+    sym(h) {
+        while (this.bitCnt < FAST_BITS && this.inPos < this.input.length) {
+            this.bitBuf |= this.input[this.inPos++] << this.bitCnt;
+            this.bitCnt += 8;
+        }
+        const e = h.fast[this.bitBuf & FAST_MASK];
+        const len = e & 15;
+        if (len !== 0) {
+            if (len > this.bitCnt)
+                throw corrupt('is truncated');
+            this.bitBuf >>>= len;
+            this.bitCnt -= len;
+            return e >> 4;
+        }
+        // Longer code (or none): canonical decoding, one bit at a time.
+        const count = h.count;
+        let code = 0;
+        let first = 0;
+        let index = 0;
+        for (let l = 1; l <= 15; l++) {
+            code |= this.bits(1);
+            const c = count[l];
+            if (code - first < c)
+                return h.symbol[index + code - first];
+            index += c;
+            first = (first + c) << 1;
+            code <<= 1;
+        }
+        return -1;
+    }
+    room(n) {
+        const need = this.outPos + n;
+        if (need <= this.out.length)
+            return;
+        if (need > this.limit)
+            throw corrupt('decompresses to more than the declared size');
+        const next = new Uint8Array(Math.min(this.limit, Math.max(this.out.length * 2, need)));
+        next.set(this.out.subarray(0, this.outPos));
+        this.out = next;
+    }
+    /** Byte-aligns the bit reader and hands back whole bytes it had buffered. */
+    align() {
+        this.inPos -= this.bitCnt >> 3;
+        this.bitBuf = 0;
+        this.bitCnt = 0;
+    }
+    stored() {
+        this.align();
+        const inp = this.input;
+        const p = this.inPos;
+        if (p + 4 > inp.length)
+            throw corrupt('is truncated');
+        const len = inp[p] | (inp[p + 1] << 8);
+        const nlen = inp[p + 2] | (inp[p + 3] << 8);
+        if (len !== (~nlen & 0xffff))
+            throw corrupt('is corrupt (invalid stored block lengths)');
+        if (p + 4 + len > inp.length)
+            throw corrupt('is truncated');
+        this.room(len);
+        this.out.set(inp.subarray(p + 4, p + 4 + len), this.outPos);
+        this.outPos += len;
+        this.inPos = p + 4 + len;
+    }
+    dynamic(lit, dist, cl, lens) {
+        const nlen = this.bits(5) + 257;
+        const ndist = this.bits(5) + 1;
+        const ncode = this.bits(4) + 4;
+        if (nlen > 286 || ndist > 30)
+            throw corrupt('is corrupt (too many length or distance symbols)');
+        const clLens = new Uint8Array(19);
+        for (let i = 0; i < ncode; i++)
+            clLens[CL_ORDER[i]] = this.bits(3);
+        if (cl.build(clLens, 0, 19) !== 0)
+            throw corrupt('is corrupt (invalid code lengths set)');
+        const total = nlen + ndist;
+        let i = 0;
+        while (i < total) {
+            const s = this.sym(cl);
+            if (s < 16) {
+                if (s < 0)
+                    throw corrupt('is corrupt (invalid code lengths set)');
+                lens[i++] = s;
+                continue;
+            }
+            let rep;
+            let val = 0;
+            if (s === 16) {
+                if (i === 0)
+                    throw corrupt('is corrupt (invalid bit length repeat)');
+                val = lens[i - 1];
+                rep = 3 + this.bits(2);
+            }
+            else if (s === 17) {
+                rep = 3 + this.bits(3);
+            }
+            else {
+                rep = 11 + this.bits(7);
+            }
+            if (i + rep > total)
+                throw corrupt('is corrupt (invalid bit length repeat)');
+            while (rep-- > 0)
+                lens[i++] = val;
+        }
+        if (lens[256] === 0)
+            throw corrupt('is corrupt (missing end-of-block code)');
+        // Incomplete codes are allowed only when they consist of a single 1-bit code (zlib).
+        let left = lit.build(lens, 0, nlen);
+        if (left < 0 || (left > 0 && lit.max !== 1))
+            throw corrupt('is corrupt (invalid literal/lengths set)');
+        left = dist.build(lens, nlen, ndist);
+        if (left < 0 || (left > 0 && dist.max > 1))
+            throw corrupt('is corrupt (invalid distances set)');
+        this.codes(lit, dist);
+    }
+    codes(lit, dist) {
+        for (;;) {
+            let s = this.sym(lit);
+            if (s < 256) {
+                if (s < 0)
+                    throw corrupt('is corrupt (invalid literal/length code)');
+                if (this.outPos >= this.out.length)
+                    this.room(1);
+                this.out[this.outPos++] = s;
+                continue;
+            }
+            if (s === 256)
+                return;
+            s -= 257;
+            if (s >= 29)
+                throw corrupt('is corrupt (invalid literal/length code)');
+            const len = LEN_BASE[s] + this.bits(LEN_EXTRA[s]);
+            const ds = this.sym(dist);
+            if (ds < 0 || ds >= 30)
+                throw corrupt('is corrupt (invalid distance code)');
+            const d = DIST_BASE[ds] + this.bits(DIST_EXTRA[ds]);
+            if (d > this.outPos)
+                throw corrupt('is corrupt (invalid distance too far back)');
+            this.room(len);
+            const out = this.out;
+            let to = this.outPos;
+            let from = to - d;
+            if (d >= len && len > 16) {
+                out.copyWithin(to, from, from + len);
+                to += len;
+            }
+            else {
+                for (const end = to + len; to < end;)
+                    out[to++] = out[from++];
+            }
+            this.outPos = to;
+        }
+    }
+    run() {
+        const inp = this.input;
+        if (inp.length < 2)
+            throw corrupt('is truncated');
+        const cmf = inp[0];
+        const flg = inp[1];
+        if (((cmf << 8) | flg) % 31 !== 0)
+            throw corrupt('is corrupt (incorrect header check)');
+        if ((cmf & 0x0f) !== 8)
+            throw corrupt('is corrupt (unknown compression method)');
+        if (cmf >> 4 > 7)
+            throw corrupt('is corrupt (invalid window size)');
+        if (flg & 0x20)
+            throw corrupt('needs a preset dictionary, which BTOON does not support');
+        this.inPos = 2;
+        let lit = null;
+        let dist = null;
+        let cl = null;
+        let lens = null;
+        let last = 0;
+        while (!last) {
+            last = this.bits(1);
+            const type = this.bits(2);
+            if (type === 0) {
+                this.stored();
+            }
+            else if (type === 1) {
+                const [fl, fd] = fixedTables();
+                this.codes(fl, fd);
+            }
+            else if (type === 2) {
+                if (lit === null) {
+                    lit = new Huffman(286);
+                    dist = new Huffman(30);
+                    cl = new Huffman(19);
+                    lens = new Uint8Array(286 + 30);
+                }
+                this.dynamic(lit, dist, cl, lens);
+            }
+            else {
+                throw corrupt('is corrupt (invalid block type)');
+            }
+        }
+        this.align();
+        const p = this.inPos;
+        if (p + 4 > inp.length)
+            throw corrupt('is truncated');
+        const expected = ((inp[p] << 24) | (inp[p + 1] << 16) | (inp[p + 2] << 8) | inp[p + 3]) >>> 0;
+        if (adler32(this.out, 0, this.outPos) !== expected)
+            throw corrupt('is corrupt (incorrect data check)');
+        if (p + 4 !== inp.length)
+            throw corrupt('has trailing bytes');
+        return this.out.subarray(0, this.outPos);
+    }
+}
+/**
+ * Decompresses an RFC 1950 zlib stream that must expand to at most `limit` bytes. Throws
+ * `invalid_envelope` for corrupt or truncated input, trailing bytes after the stream, or
+ * output beyond `limit`. The output buffer grows geometrically, so a lying size header
+ * cannot force a large allocation for a small input.
+ */
+export function inflateZlib(input, limit) {
+    return new Inflater(input, limit).run();
+}
+/** Adler-32 checksum of `d[start, end)` (RFC 1950). */
+export function adler32(d, start = 0, end = d.length) {
+    let a = 1;
+    let b = 0;
+    let i = start;
+    while (i < end) {
+        const stop = Math.min(end, i + 3800); // keeps b below 2^31 between reductions
+        for (; i < stop; i++) {
+            a += d[i];
+            b += a;
+        }
+        a %= 65521;
+        b %= 65521;
+    }
+    return ((b << 16) | a) >>> 0;
+}

package/dist/esm/node.d.ts

@@ -0,0 +1,64 @@
+/**
+ * BTOON for JavaScript and TypeScript — Node.js entry point (also used by Bun). Same API
+ * as the portable entry; synchronous compression and signing use `node:zlib` (zlib,
+ * Brotli, and Zstandard where Node.js has it) and `node:crypto`.
+ *
+ * @packageDocumentation
+ */
+import { type BinaryInput } from './core.js';
+import type { DecodeOptions, EncodeOptions } from './options.js';
+export { SPEC_VERSION, VERSION } from './constants.js';
+export type { BinaryInput } from './core.js';
+export { BtoonError, type BtoonErrorCode } from './errors.js';
+export type { Codec, CodecRegistry, CompressionAlgorithm, DecodeOptions, EncodeOptions } from './options.js';
+export { Ext, Timestamp } from './values.js';
+/**
+ * Encodes a value as canonical BTOON (SPEC §4): identical values produce identical bytes
+ * in every conforming implementation.
+ *
+ * Accepted values: `null`/`undefined` (nil), booleans, numbers (safe integers as integers,
+ * everything else — including `-0`, `NaN` and integral values beyond ±2^53 — as float64),
+ * `bigint`, strings (must not contain lone surrogates), `Uint8Array`/`ArrayBuffer`/other
+ * typed arrays and `DataView` (binary), `Float32Array`/`Float64Array` (float vectors),
+ * arrays, plain objects and `Map`s with string keys (maps, keys sorted by UTF-8 bytes),
+ * `Date` and {@link Timestamp} (timestamps), and {@link Ext}. Any other object is encoded
+ * the way `JSON.stringify` sees it: the result of its `toJSON()` method if it has one
+ * (called once), otherwise a map of its own enumerable string-keyed properties; `Number`,
+ * `String`, `Boolean` and `BigInt` wrapper objects are unwrapped. Functions and symbols are
+ * rejected. Arrays of uniform objects use the tabular encoding when it is smaller.
+ *
+ * With `compress` or `hmacKey`, the document is wrapped in a compression and/or signed
+ * envelope, layered as sign(compress(document)).
+ *
+ * @throws {BtoonError} `invalid_argument` for functions, symbols or invalid options, `max_depth`
+ *   for values nested deeper than `maxDepth` (including cycles), `invalid_utf8` for strings
+ *   with lone surrogates, `unsupported_compression` if the algorithm has no synchronous
+ *   implementation here (see `encodeAsync` and `options.codecs`).
+ */
+export declare function encode(value: unknown, options?: EncodeOptions): Uint8Array<ArrayBuffer>;
+/**
+ * Decodes one BTOON document, enforcing SPEC §7: bounds-checked reads, a nesting limit,
+ * no allocation beyond what the input justifies, strict UTF-8, unique map keys and no
+ * trailing bytes. Compression envelopes are decompressed (with the output capped at the
+ * declared size and `maxDecompressedSize`); with `hmacKey` the signature is verified before
+ * anything is parsed.
+ *
+ * Maps decode to plain objects. A `"__proto__"` key becomes an own property (as with
+ * `JSON.parse`); it never changes an object's prototype.
+ *
+ * @throws {BtoonError} with the SPEC §7 error code describing the problem.
+ */
+export declare function decode(data: BinaryInput, options?: DecodeOptions): unknown;
+/**
+ * Like {@link encode}, but compresses with `CompressionStream` (when the runtime supports
+ * the algorithm) and signs with WebCrypto, falling back to the synchronous implementations.
+ * Rejects with a {@link BtoonError}.
+ */
+export declare function encodeAsync(value: unknown, options?: EncodeOptions): Promise<Uint8Array<ArrayBuffer>>;
+/**
+ * Like {@link decode}, but decompresses with `DecompressionStream` (when the runtime
+ * supports the algorithm) and verifies signatures with `crypto.subtle.verify`, falling back
+ * to the synchronous implementations. The input is copied first, so the caller may reuse
+ * its buffer immediately. Rejects with a {@link BtoonError}.
+ */
+export declare function decodeAsync(data: BinaryInput, options?: DecodeOptions): Promise<unknown>;