@btoon/js 0.0.0-stage → 0.1.1

package/dist/esm/constants.js

@@ -0,0 +1,29 @@
+/** Version of this library. */
+export const VERSION = '0.1.1';
+/** Version of the BTOON specification this library implements. */
+export const SPEC_VERSION = '0.1';
+// Extension type ids (SPEC §5).
+export const EXT_TIMESTAMP = -1;
+export const EXT_DATE = -2;
+export const EXT_DATETIME = -3;
+export const EXT_BIGINT = -4;
+export const EXT_F32_VECTOR = -5;
+export const EXT_F64_VECTOR = -6;
+export const EXT_TABULAR = -10;
+export const TABULAR_VERSION = 1;
+export const MAX_OFFSET_MINUTES = 1080;
+export const NANOS_PER_SECOND = 1000000000;
+export const DEFAULT_MAX_DEPTH = 128;
+export const DEFAULT_MAX_DECOMPRESSED_SIZE = 256 * 1024 * 1024;
+/** Encoders SHOULD skip compression below this size (SPEC §6). */
+export const MIN_COMPRESSION_SIZE = 256;
+export const COMPRESSION_HEADER_SIZE = 16;
+export const SIGNED_HEADER_SIZE = 40;
+/** Compression algorithm ids of the envelope header (SPEC §6). */
+export const ALGORITHM_IDS = { zlib: 0, lz4: 1, zstd: 2, brotli: 3, snappy: 4 };
+export const ALGORITHM_NAMES = ['zlib', 'lz4', 'zstd', 'brotli', 'snappy'];
+/** Brands that identify {@link Ext} and {@link Timestamp} instances across module copies. */
+export const EXT_BRAND = Symbol.for('btoon.Ext');
+export const TIMESTAMP_BRAND = Symbol.for('btoon.Timestamp');
+/** Date's representable range is ±8.64e15 ms around the epoch. */
+export const MAX_DATE_MS = 8640000000000000;

package/dist/esm/core.d.ts

@@ -0,0 +1,15 @@
+import { type CompressionAlgorithm, type DecodeOptions, type EncodeOptions } from './options.js';
+/** Synchronous building blocks of one environment. */
+export interface Platform {
+    /** Decompressors; `size` is the declared uncompressed size (already checked against the limit). */
+    readonly decompress: Readonly<Partial<Record<CompressionAlgorithm, (data: Uint8Array, size: number) => Uint8Array>>>;
+    readonly compress: Readonly<Partial<Record<CompressionAlgorithm, (data: Uint8Array) => Uint8Array>>>;
+    hmac(key: Uint8Array, parts: readonly Uint8Array[]): Uint8Array;
+    equal(a: Uint8Array, b: Uint8Array): boolean;
+}
+/** Input accepted by `decode`. */
+export type BinaryInput = Uint8Array | ArrayBuffer | ArrayBufferView;
+export declare function encodeWith(value: unknown, options: EncodeOptions | undefined, platform: Platform): Uint8Array<ArrayBuffer>;
+export declare function decodeWith(data: BinaryInput, options: DecodeOptions | undefined, platform: Platform): unknown;
+export declare function encodeAsyncWith(value: unknown, options: EncodeOptions | undefined, platform: Platform): Promise<Uint8Array<ArrayBuffer>>;
+export declare function decodeAsyncWith(data: BinaryInput, options: DecodeOptions | undefined, platform: Platform): Promise<unknown>;

package/dist/esm/core.js

@@ -0,0 +1,269 @@
+// encode/decode with the compression (SPEC §6) and signed (SPEC §8) envelopes, layered as
+// sign(compress(encode(value))). The entry points bind these to a Platform: the set of
+// synchronous codecs available in that environment.
+import { ALGORITHM_IDS, ALGORITHM_NAMES, COMPRESSION_HEADER_SIZE, MIN_COMPRESSION_SIZE, SIGNED_HEADER_SIZE, } from './constants.js';
+import { decodeDocument, plainBytes } from './decode.js';
+import { encodeDocument } from './encode.js';
+import { BtoonError, fail } from './errors.js';
+import { decodeConfig, encodeConfig, } from './options.js';
+import { isUint8Array } from './values.js';
+import { subtle, webCompress, webDecompress, webFormat, webHmacSign, webHmacVerify } from './web.js';
+const COMPRESSED_MAGIC = [0x42, 0x54, 0x4f, 0x4e]; // "BTON"
+const SIGNED_MAGIC = [0x42, 0x54, 0x53, 0x47]; // "BTSG"
+const SIGNED_HEADER = new Uint8Array([0x42, 0x54, 0x53, 0x47, 1, 1, 0, 0]);
+const objectToString = Object.prototype.toString;
+function hasMagic(b, magic) {
+    return b.length >= 4 && b[0] === magic[0] && b[1] === magic[1] && b[2] === magic[2] && b[3] === magic[3];
+}
+function inputBytes(data) {
+    if (ArrayBuffer.isView(data))
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    const tag = objectToString.call(data);
+    if (tag === '[object ArrayBuffer]' || tag === '[object SharedArrayBuffer]')
+        return new Uint8Array(data);
+    throw fail('invalid_argument', 'decode() expects a Uint8Array, ArrayBuffer or other ArrayBufferView');
+}
+function isShared(b) {
+    return typeof SharedArrayBuffer !== 'undefined' && b.buffer instanceof SharedArrayBuffer;
+}
+function isThenable(v) {
+    return (typeof v === 'object' || typeof v === 'function') && v !== null && typeof v.then === 'function';
+}
+function messageOf(e) {
+    return e instanceof Error ? e.message || e.name : String(e);
+}
+// --- compression envelope -----------------------------------------------------------------
+function envelopeIfSmaller(raw, payload, alg) {
+    // SPEC §6: only when it saves at least 5%, i.e. 20 × envelope_size ≤ 19 × input_size.
+    if (20 * (COMPRESSION_HEADER_SIZE + payload.length) > 19 * raw.length)
+        return raw;
+    const out = new Uint8Array(COMPRESSION_HEADER_SIZE + payload.length);
+    out.set(COMPRESSED_MAGIC, 0);
+    out[4] = 1;
+    out[5] = ALGORITHM_IDS[alg];
+    const view = new DataView(out.buffer);
+    view.setUint32(8, payload.length);
+    view.setUint32(12, raw.length);
+    out.set(payload, COMPRESSION_HEADER_SIZE);
+    return out;
+}
+/** Checks the header of a compression envelope (before any decompression), or returns null. */
+function compressionEnvelope(b, cfg) {
+    if (b.length < COMPRESSION_HEADER_SIZE || !hasMagic(b, COMPRESSED_MAGIC))
+        return null;
+    if (!cfg.autoDecompress)
+        throw fail('invalid_envelope', 'input is compressed but autoDecompress is disabled');
+    const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    if (b[4] !== 1)
+        throw fail('invalid_envelope', `unsupported compression envelope version ${b[4]}`);
+    if (view.getUint16(6) !== 0)
+        throw fail('invalid_envelope', 'compression envelope reserved bytes must be zero');
+    if (view.getUint32(8) !== b.length - COMPRESSION_HEADER_SIZE) {
+        throw fail('invalid_envelope', 'compressed size does not match the envelope length');
+    }
+    const size = view.getUint32(12);
+    if (size > cfg.maxDecompressedSize) {
+        throw fail('size_limit', `declared uncompressed size ${size} exceeds maxDecompressedSize (${cfg.maxDecompressedSize})`);
+    }
+    const alg = ALGORITHM_NAMES[b[5]];
+    if (alg === undefined)
+        throw fail('unsupported_compression', `unknown compression algorithm id ${b[5]}`);
+    return { alg, payload: b.subarray(COMPRESSION_HEADER_SIZE), size };
+}
+function checkSize(out, size, alg) {
+    if (out.length !== size)
+        throw fail('invalid_envelope', `${alg} payload decompressed size does not match the header`);
+    return out;
+}
+function unavailable(alg, op, asyncWorks) {
+    const fn = op === 'compression' ? 'encodeAsync()' : 'decodeAsync()';
+    return fail('unsupported_compression', asyncWorks
+        ? `${alg} ${op} is not available synchronously in this environment; use ${fn} or pass options.codecs.${alg}`
+        : `${alg} ${op} is not available in this environment; pass options.codecs.${alg}`);
+}
+function codecResult(r, alg, fn) {
+    if (!isUint8Array(r))
+        throw fail('invalid_argument', `codecs.${alg}.${fn} must return a Uint8Array`);
+    return plainBytes(r);
+}
+function codecError(e, alg, fn) {
+    if (e instanceof BtoonError)
+        return e;
+    return fail(fn === 'decompress' ? 'invalid_envelope' : 'invalid_argument', `codecs.${alg}.${fn} failed: ${messageOf(e)}`, e);
+}
+function callCodecSync(codecs, alg, fn, args) {
+    const codec = codecs?.[alg];
+    const f = codec?.[fn];
+    if (f === undefined)
+        return undefined;
+    let r;
+    try {
+        r = f.apply(codec, args);
+    }
+    catch (e) {
+        throw codecError(e, alg, fn);
+    }
+    if (isThenable(r)) {
+        Promise.resolve(r).catch(() => undefined);
+        throw fail('invalid_argument', `codecs.${alg}.${fn} returned a Promise; use the async API (encodeAsync/decodeAsync)`);
+    }
+    return codecResult(r, alg, fn);
+}
+async function callCodecAsync(codecs, alg, fn, args) {
+    const codec = codecs?.[alg];
+    const f = codec?.[fn];
+    if (f === undefined)
+        return undefined;
+    let r;
+    try {
+        r = await f.apply(codec, args);
+    }
+    catch (e) {
+        throw codecError(e, alg, fn);
+    }
+    return codecResult(r, alg, fn);
+}
+function hasCodec(codecs, alg, fn) {
+    return typeof codecs?.[alg]?.[fn] === 'function';
+}
+function signedEnvelope(b) {
+    if (!hasMagic(b, SIGNED_MAGIC))
+        throw fail('authentication_failed', 'input is not a signed envelope');
+    if (b.length < SIGNED_HEADER_SIZE)
+        throw fail('invalid_envelope', 'signed envelope is truncated');
+    if (b[4] !== 1 || b[5] !== 1 || b[6] !== 0 || b[7] !== 0) {
+        throw fail('invalid_envelope', 'unsupported signed envelope version or algorithm');
+    }
+    return { header: b.subarray(0, 8), mac: b.subarray(8, SIGNED_HEADER_SIZE), payload: b.subarray(SIGNED_HEADER_SIZE) };
+}
+function rejectUnexpectedSignature(b) {
+    if (b.length >= SIGNED_HEADER_SIZE && hasMagic(b, SIGNED_MAGIC)) {
+        throw fail('authentication_failed', 'input is signed but no hmacKey was provided');
+    }
+}
+function assembleSigned(mac, payload) {
+    const out = new Uint8Array(SIGNED_HEADER_SIZE + payload.length);
+    out.set(SIGNED_HEADER, 0);
+    out.set(mac, 8);
+    out.set(payload, SIGNED_HEADER_SIZE);
+    return out;
+}
+function concat2(a, b) {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+}
+// --- synchronous API ------------------------------------------------------------------------
+export function encodeWith(value, options, platform) {
+    const cfg = encodeConfig(options);
+    let out = encodeDocument(value, cfg.maxDepth, cfg.autoTabular);
+    if (cfg.compress) {
+        const alg = cfg.algorithm;
+        const builtin = platform.compress[alg];
+        // Fail fast, even for documents too small to compress, so a missing codec shows up in testing.
+        if (!hasCodec(cfg.codecs, alg, 'compress') && builtin === undefined) {
+            throw unavailable(alg, 'compression', webFormat(alg, 'CompressionStream') !== undefined);
+        }
+        if (out.length >= MIN_COMPRESSION_SIZE) {
+            if (out.length > 0xffffffff)
+                throw fail('size_limit', 'document too large to compress');
+            const payload = callCodecSync(cfg.codecs, alg, 'compress', [out]) ?? builtin(out);
+            out = envelopeIfSmaller(out, payload, alg);
+        }
+    }
+    if (cfg.hmacKey !== undefined)
+        out = assembleSigned(platform.hmac(cfg.hmacKey, [SIGNED_HEADER, out]), out);
+    return out;
+}
+export function decodeWith(data, options, platform) {
+    const cfg = decodeConfig(options);
+    let bytes = inputBytes(data);
+    if (cfg.hmacKey !== undefined) {
+        if (isShared(bytes))
+            bytes = bytes.slice(); // verify and parse the same bytes
+        const env = signedEnvelope(bytes);
+        const expected = platform.hmac(cfg.hmacKey, [env.header, env.payload]);
+        if (!platform.equal(expected, env.mac))
+            throw fail('authentication_failed', 'HMAC verification failed');
+        bytes = env.payload;
+    }
+    else {
+        rejectUnexpectedSignature(bytes);
+    }
+    const env = compressionEnvelope(bytes, cfg);
+    if (env !== null) {
+        const { alg, payload, size } = env;
+        let out = callCodecSync(cfg.codecs, alg, 'decompress', [payload, size]);
+        if (out === undefined) {
+            const builtin = platform.decompress[alg];
+            if (builtin === undefined)
+                throw unavailable(alg, 'decompression', webFormat(alg, 'DecompressionStream') !== undefined);
+            out = builtin(payload, size);
+        }
+        bytes = checkSize(out, size, alg);
+    }
+    return decodeDocument(bytes, cfg);
+}
+// --- asynchronous API -------------------------------------------------------------------------
+export async function encodeAsyncWith(value, options, platform) {
+    const cfg = encodeConfig(options);
+    let out = encodeDocument(value, cfg.maxDepth, cfg.autoTabular);
+    if (cfg.compress) {
+        const alg = cfg.algorithm;
+        const builtin = platform.compress[alg];
+        const format = webFormat(alg, 'CompressionStream');
+        if (!hasCodec(cfg.codecs, alg, 'compress') && format === undefined && builtin === undefined) {
+            throw unavailable(alg, 'compression', false);
+        }
+        if (out.length >= MIN_COMPRESSION_SIZE) {
+            if (out.length > 0xffffffff)
+                throw fail('size_limit', 'document too large to compress');
+            let payload = await callCodecAsync(cfg.codecs, alg, 'compress', [out]);
+            if (payload === undefined)
+                payload = format !== undefined ? await webCompress(format, out) : builtin(out);
+            out = envelopeIfSmaller(out, payload, alg);
+        }
+    }
+    if (cfg.hmacKey !== undefined) {
+        const s = subtle();
+        const mac = s !== undefined ? await webHmacSign(s, cfg.hmacKey, concat2(SIGNED_HEADER, out)) : platform.hmac(cfg.hmacKey, [SIGNED_HEADER, out]);
+        out = assembleSigned(mac, out);
+    }
+    return out;
+}
+export async function decodeAsyncWith(data, options, platform) {
+    const cfg = decodeConfig(options);
+    // A private copy: the caller may reuse its buffer while we wait.
+    let bytes = inputBytes(data).slice();
+    if (cfg.hmacKey !== undefined) {
+        const env = signedEnvelope(bytes);
+        const s = subtle();
+        const ok = s !== undefined
+            ? await webHmacVerify(s, cfg.hmacKey, env.mac, concat2(env.header, env.payload))
+            : platform.equal(platform.hmac(cfg.hmacKey, [env.header, env.payload]), env.mac);
+        if (!ok)
+            throw fail('authentication_failed', 'HMAC verification failed');
+        bytes = env.payload;
+    }
+    else {
+        rejectUnexpectedSignature(bytes);
+    }
+    const env = compressionEnvelope(bytes, cfg);
+    if (env !== null) {
+        const { alg, payload, size } = env;
+        let out = await callCodecAsync(cfg.codecs, alg, 'decompress', [payload, size]);
+        if (out === undefined) {
+            const format = webFormat(alg, 'DecompressionStream');
+            const builtin = platform.decompress[alg];
+            if (format !== undefined)
+                out = await webDecompress(alg, format, payload, size);
+            else if (builtin !== undefined)
+                out = builtin(payload, size);
+            else
+                throw unavailable(alg, 'decompression', false);
+        }
+        bytes = checkSize(out, size, alg);
+    }
+    return decodeDocument(bytes, cfg);
+}

package/dist/esm/decode.d.ts

@@ -0,0 +1,10 @@
+import type { DecodeConfig } from './options.js';
+/** A plain Uint8Array view of the same bytes (Buffer.prototype.slice does not copy). */
+export declare function plainBytes(b: Uint8Array): Uint8Array;
+/** Decodes one bare BTOON document (no envelopes). */
+export declare function decodeDocument(bytes: Uint8Array, cfg: DecodeConfig): unknown;
+/**
+ * Used by the encoder: an `Ext` that carries a BTOON-defined id must hold a payload a
+ * strict decoder accepts, so the encoder never emits a document decoders reject.
+ */
+export declare function validateBtoonExt(type: number, data: Uint8Array, depth: number, maxDepth?: number): void;