@btoon/js 0.0.0-stage → 0.1.0

package/dist/esm/values.d.ts

@@ -0,0 +1,58 @@
+/** True for a Uint8Array from any realm (including Node.js Buffers). */
+export declare function isUint8Array(v: unknown): v is Uint8Array;
+/**
+ * A generic MessagePack extension value: a signed 8-bit type id and an opaque payload.
+ *
+ * Decoding returns `Ext` for every extension id BTOON does not define (application ids
+ * 0…127 and the reserved negative ids). Encoding writes it verbatim with the smallest
+ * header. An `Ext` may also carry one of the ids BTOON defines (-1…-6, -10) — this is how
+ * to emit a `date` (-2) or `datetime` (-3) value, which have no JavaScript type of their
+ * own — but its payload must then be well-formed for that type, or encoding fails with
+ * `invalid_argument`.
+ */
+export declare class Ext {
+    /** Extension type id, an integer in [-128, 127]. */
+    readonly type: number;
+    /** The payload bytes (not copied by the constructor). */
+    readonly data: Uint8Array;
+    constructor(type: number, data: Uint8Array);
+}
+/**
+ * A BTOON timestamp (extension -1): an instant with nanosecond precision and an optional
+ * UTC offset.
+ *
+ * `seconds` and `nanoseconds` always describe the instant in UTC. `offsetMinutes` is
+ * presentation metadata ("local time is UTC + offset") and is encoded only when present.
+ * Decoding returns `Timestamp` objects when `timestamps: 'object'` is set, and for
+ * instants outside the range of `Date`.
+ */
+export declare class Timestamp {
+    /** Whole seconds since the Unix epoch (UTC), in the int64 range. */
+    readonly seconds: bigint;
+    /** Nanoseconds within the second, in [0, 999 999 999]. */
+    readonly nanoseconds: number;
+    /** UTC offset in minutes, in [-1080, 1080], or `undefined` for a plain UTC timestamp. */
+    readonly offsetMinutes?: number;
+    /**
+     * @param seconds Seconds since the Unix epoch; a `bigint`, or a `number` that is a safe integer.
+     * @param nanoseconds Nanoseconds within the second, an integer in [0, 1e9).
+     * @param offsetMinutes Optional UTC offset in minutes, an integer in [-1080, 1080].
+     * @throws {BtoonError} `invalid_argument` if a field is out of range.
+     */
+    constructor(seconds: bigint | number, nanoseconds: number, offsetMinutes?: number);
+    /**
+     * The instant as a `Date`. Sub-millisecond nanoseconds are truncated toward the past and
+     * the offset is dropped (a `Date` has no offset).
+     * @throws {BtoonError} `invalid_argument` if the instant is outside the range of `Date`.
+     */
+    toDate(): Date;
+    /**
+     * The UTC timestamp of a `Date` (millisecond precision, no offset).
+     * @throws {BtoonError} `invalid_argument` for an invalid `Date`.
+     */
+    static fromDate(date: Date): Timestamp;
+}
+/** Milliseconds of a Date (from any realm); throws for an invalid Date. */
+export declare function dateTime(date: unknown): number;
+export declare function isExt(v: object): v is Ext;
+export declare function isTimestamp(v: object): v is Timestamp;

package/dist/esm/values.js

@@ -0,0 +1,120 @@
+import { EXT_BRAND, MAX_DATE_MS, MAX_OFFSET_MINUTES, NANOS_PER_SECOND, TIMESTAMP_BRAND, } from './constants.js';
+import { fail } from './errors.js';
+const INT64_MIN = -(1n << 63n);
+const INT64_MAX = (1n << 63n) - 1n;
+/** True for a Uint8Array from any realm (including Node.js Buffers). */
+export function isUint8Array(v) {
+    return ArrayBuffer.isView(v) && v[Symbol.toStringTag] === 'Uint8Array';
+}
+/**
+ * A generic MessagePack extension value: a signed 8-bit type id and an opaque payload.
+ *
+ * Decoding returns `Ext` for every extension id BTOON does not define (application ids
+ * 0…127 and the reserved negative ids). Encoding writes it verbatim with the smallest
+ * header. An `Ext` may also carry one of the ids BTOON defines (-1…-6, -10) — this is how
+ * to emit a `date` (-2) or `datetime` (-3) value, which have no JavaScript type of their
+ * own — but its payload must then be well-formed for that type, or encoding fails with
+ * `invalid_argument`.
+ */
+export class Ext {
+    constructor(type, data) {
+        if (typeof type !== 'number' || !Number.isInteger(type) || type < -128 || type > 127) {
+            throw fail('invalid_argument', `Ext type must be an integer in [-128, 127], got ${String(type)}`);
+        }
+        if (!isUint8Array(data)) {
+            throw fail('invalid_argument', 'Ext data must be a Uint8Array');
+        }
+        this.type = type;
+        this.data = data;
+    }
+}
+Object.defineProperty(Ext.prototype, EXT_BRAND, { value: true });
+/**
+ * A BTOON timestamp (extension -1): an instant with nanosecond precision and an optional
+ * UTC offset.
+ *
+ * `seconds` and `nanoseconds` always describe the instant in UTC. `offsetMinutes` is
+ * presentation metadata ("local time is UTC + offset") and is encoded only when present.
+ * Decoding returns `Timestamp` objects when `timestamps: 'object'` is set, and for
+ * instants outside the range of `Date`.
+ */
+export class Timestamp {
+    /**
+     * @param seconds Seconds since the Unix epoch; a `bigint`, or a `number` that is a safe integer.
+     * @param nanoseconds Nanoseconds within the second, an integer in [0, 1e9).
+     * @param offsetMinutes Optional UTC offset in minutes, an integer in [-1080, 1080].
+     * @throws {BtoonError} `invalid_argument` if a field is out of range.
+     */
+    constructor(seconds, nanoseconds, offsetMinutes) {
+        let s;
+        if (typeof seconds === 'bigint') {
+            s = seconds;
+        }
+        else if (typeof seconds === 'number' && Number.isSafeInteger(seconds)) {
+            s = BigInt(seconds);
+        }
+        else {
+            throw fail('invalid_argument', 'Timestamp seconds must be a bigint or a safe integer');
+        }
+        if (s < INT64_MIN || s > INT64_MAX) {
+            throw fail('invalid_argument', 'Timestamp seconds must fit in a signed 64-bit integer');
+        }
+        if (typeof nanoseconds !== 'number' ||
+            !Number.isInteger(nanoseconds) ||
+            nanoseconds < 0 ||
+            nanoseconds >= NANOS_PER_SECOND) {
+            throw fail('invalid_argument', 'Timestamp nanoseconds must be an integer in [0, 999999999]');
+        }
+        if (offsetMinutes !== undefined &&
+            (typeof offsetMinutes !== 'number' ||
+                !Number.isInteger(offsetMinutes) ||
+                offsetMinutes < -MAX_OFFSET_MINUTES ||
+                offsetMinutes > MAX_OFFSET_MINUTES)) {
+            throw fail('invalid_argument', 'Timestamp offsetMinutes must be an integer in [-1080, 1080]');
+        }
+        this.seconds = s;
+        this.nanoseconds = nanoseconds;
+        this.offsetMinutes = offsetMinutes;
+    }
+    /**
+     * The instant as a `Date`. Sub-millisecond nanoseconds are truncated toward the past and
+     * the offset is dropped (a `Date` has no offset).
+     * @throws {BtoonError} `invalid_argument` if the instant is outside the range of `Date`.
+     */
+    toDate() {
+        const ms = this.seconds * 1000n + BigInt(Math.floor(this.nanoseconds / 1e6));
+        if (ms > BigInt(MAX_DATE_MS) || ms < -BigInt(MAX_DATE_MS)) {
+            throw fail('invalid_argument', 'Timestamp is outside the range of Date');
+        }
+        return new Date(Number(ms));
+    }
+    /**
+     * The UTC timestamp of a `Date` (millisecond precision, no offset).
+     * @throws {BtoonError} `invalid_argument` for an invalid `Date`.
+     */
+    static fromDate(date) {
+        const ms = dateTime(date);
+        const seconds = Math.floor(ms / 1000);
+        return new Timestamp(BigInt(seconds), (ms - seconds * 1000) * 1e6);
+    }
+}
+Object.defineProperty(Timestamp.prototype, TIMESTAMP_BRAND, { value: true });
+/** Milliseconds of a Date (from any realm); throws for an invalid Date. */
+export function dateTime(date) {
+    let ms;
+    try {
+        ms = Date.prototype.getTime.call(date);
+    }
+    catch {
+        throw fail('invalid_argument', 'expected a Date');
+    }
+    if (!Number.isFinite(ms))
+        throw fail('invalid_argument', 'cannot encode an invalid Date');
+    return ms;
+}
+export function isExt(v) {
+    return v[EXT_BRAND] === true;
+}
+export function isTimestamp(v) {
+    return v[TIMESTAMP_BRAND] === true;
+}

package/dist/esm/web.d.ts

@@ -0,0 +1,25 @@
+import type { CompressionAlgorithm } from './options.js';
+/** The Compression Streams format name for `alg`, if this runtime supports it. */
+export declare function webFormat(alg: CompressionAlgorithm, kind: 'CompressionStream' | 'DecompressionStream'): string | undefined;
+export declare function webCompress(format: string, data: Uint8Array): Promise<Uint8Array>;
+/**
+ * Decompresses with a DecompressionStream, stopping as soon as the output exceeds
+ * `limit` (the declared size). For zlib it also checks that the payload ends with the
+ * Adler-32 of the output: older runtimes silently ignore bytes after the end of the
+ * stream, which a strict decoder must reject.
+ */
+export declare function webDecompress(alg: CompressionAlgorithm, format: string, data: Uint8Array, limit: number): Promise<Uint8Array>;
+type Subtle = {
+    importKey(format: 'raw', key: Uint8Array, alg: {
+        name: string;
+        hash: string;
+    }, extractable: boolean, usages: string[]): Promise<unknown>;
+    sign(alg: string, key: unknown, data: Uint8Array): Promise<ArrayBuffer>;
+    verify(alg: string, key: unknown, signature: Uint8Array, data: Uint8Array): Promise<boolean>;
+};
+/** WebCrypto's SubtleCrypto, if available (absent in Node 18 and on insecure origins). */
+export declare function subtle(): Subtle | undefined;
+export declare function webHmacSign(s: Subtle, key: Uint8Array, data: Uint8Array): Promise<Uint8Array>;
+/** Constant-time verification (crypto.subtle.verify compares internally). */
+export declare function webHmacVerify(s: Subtle, key: Uint8Array, mac: Uint8Array, data: Uint8Array): Promise<boolean>;
+export {};

package/dist/esm/web.js

@@ -0,0 +1,143 @@
+// Asynchronous implementations on top of web platform APIs: Compression Streams and
+// WebCrypto. Used by encodeAsync/decodeAsync wherever the runtime provides them.
+import { BtoonError, fail } from './errors.js';
+import { adler32 } from './inflate.js';
+const FORMATS = { zlib: 'deflate', brotli: 'brotli', zstd: 'zstd' };
+const CHUNK = 64 * 1024;
+const supported = new Map();
+function streamCtor(kind) {
+    const ctor = globalThis[kind];
+    return typeof ctor === 'function' ? ctor : undefined;
+}
+/** The Compression Streams format name for `alg`, if this runtime supports it. */
+export function webFormat(alg, kind) {
+    const format = FORMATS[alg];
+    const Ctor = streamCtor(kind);
+    if (format === undefined || Ctor === undefined)
+        return undefined;
+    const key = `${kind}:${format}`;
+    let ok = supported.get(key);
+    if (ok === undefined) {
+        try {
+            new Ctor(format);
+            ok = true;
+        }
+        catch {
+            ok = false;
+        }
+        supported.set(key, ok);
+    }
+    return ok ? format : undefined;
+}
+function concat(chunks, total) {
+    if (chunks.length === 1 && chunks[0].byteLength === total)
+        return chunks[0];
+    const out = new Uint8Array(total);
+    let p = 0;
+    for (const c of chunks) {
+        out.set(c, p);
+        p += c.byteLength;
+    }
+    return out;
+}
+async function readAll(reader, limit, alg) {
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > limit) {
+            reader.cancel().catch(() => undefined);
+            throw fail('invalid_envelope', `${alg} payload decompresses to more than the declared size`);
+        }
+        chunks.push(value);
+    }
+    return concat(chunks, total);
+}
+/** Feeds `data` in chunks, honouring backpressure, then closes the writer. */
+async function pump(writer, data) {
+    for (let i = 0; i < data.length; i += CHUNK) {
+        await writer.ready;
+        await writer.write(data.subarray(i, Math.min(i + CHUNK, data.length)));
+    }
+    await writer.close();
+}
+function messageOf(e) {
+    return e instanceof Error ? e.message || e.name : String(e);
+}
+export async function webCompress(format, data) {
+    const stream = new (streamCtor('CompressionStream'))(format);
+    const writer = stream.writable.getWriter();
+    const writing = pump(writer, data);
+    writing.catch(() => undefined);
+    const out = await readAll(stream.readable.getReader(), Infinity, format);
+    await writing;
+    return out;
+}
+/**
+ * Decompresses with a DecompressionStream, stopping as soon as the output exceeds
+ * `limit` (the declared size). For zlib it also checks that the payload ends with the
+ * Adler-32 of the output: older runtimes silently ignore bytes after the end of the
+ * stream, which a strict decoder must reject.
+ */
+export async function webDecompress(alg, format, data, limit) {
+    const stream = new (streamCtor('DecompressionStream'))(format);
+    const writer = stream.writable.getWriter();
+    const writing = pump(writer, data);
+    writing.catch(() => undefined);
+    let out;
+    try {
+        out = await readAll(stream.readable.getReader(), limit, alg);
+        await writing;
+    }
+    catch (e) {
+        writer.abort(e).catch(() => undefined);
+        if (e instanceof BtoonError)
+            throw e;
+        throw fail('invalid_envelope', `${alg} payload is corrupt: ${messageOf(e)}`, e);
+    }
+    if (alg === 'zlib') {
+        const n = data.length;
+        const trailer = n >= 4 ? ((data[n - 4] << 24) | (data[n - 3] << 16) | (data[n - 2] << 8) | data[n - 1]) >>> 0 : -1;
+        if (trailer !== adler32(out))
+            throw fail('invalid_envelope', 'zlib payload has trailing bytes');
+    }
+    return out;
+}
+/** WebCrypto's SubtleCrypto, if available (absent in Node 18 and on insecure origins). */
+export function subtle() {
+    const c = globalThis.crypto;
+    const s = c?.subtle;
+    return s && typeof s.importKey === 'function' && typeof s.sign === 'function' && typeof s.verify === 'function'
+        ? s
+        : undefined;
+}
+async function importKey(s, key, usage) {
+    try {
+        return await s.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, [usage]);
+    }
+    catch (e) {
+        throw fail('invalid_argument', `cannot use hmacKey with WebCrypto: ${messageOf(e)}`, e);
+    }
+}
+export async function webHmacSign(s, key, data) {
+    const k = await importKey(s, key, 'sign');
+    try {
+        return new Uint8Array(await s.sign('HMAC', k, data));
+    }
+    catch (e) {
+        throw fail('invalid_argument', `WebCrypto HMAC signing failed: ${messageOf(e)}`, e);
+    }
+}
+/** Constant-time verification (crypto.subtle.verify compares internally). */
+export async function webHmacVerify(s, key, mac, data) {
+    const k = await importKey(s, key, 'verify');
+    try {
+        return await s.verify('HMAC', k, mac, data);
+    }
+    catch (e) {
+        throw fail('authentication_failed', `WebCrypto HMAC verification failed: ${messageOf(e)}`, e);
+    }
+}

package/package.json

@@ -1,6 +1,87 @@
 {
   "name": "@btoon/js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "BTOON (Binary TOON) for JavaScript and TypeScript: canonical, hardened MessagePack with a columnar encoding for tables. Pure TypeScript, zero dependencies; runs in browsers, Node.js, Deno, Bun and edge runtimes.",
+  "keywords": [
+    "btoon",
+    "messagepack",
+    "msgpack",
+    "binary",
+    "serialization",
+    "canonical",
+    "tabular",
+    "columnar",
+    "browser",
+    "deno",
+    "bun"
+  ],
+  "homepage": "https://btoon.net",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BTOON-project/btoon-javascript.git"
+  },
+  "bugs": "https://github.com/BTOON-project/btoon-javascript/issues",
+  "license": "MIT",
+  "author": "BTOON Contributors",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "exports": {
+    ".": {
+      "deno": {
+        "import": { "types": "./dist/esm/index.d.ts", "default": "./dist/esm/index.js" },
+        "require": { "types": "./dist/cjs/index.d.ts", "default": "./dist/cjs/index.js" }
+      },
+      "browser": {
+        "import": { "types": "./dist/esm/index.d.ts", "default": "./dist/esm/index.js" },
+        "require": { "types": "./dist/cjs/index.d.ts", "default": "./dist/cjs/index.js" }
+      },
+      "worker": {
+        "import": { "types": "./dist/esm/index.d.ts", "default": "./dist/esm/index.js" },
+        "require": { "types": "./dist/cjs/index.d.ts", "default": "./dist/cjs/index.js" }
+      },
+      "workerd": {
+        "import": { "types": "./dist/esm/index.d.ts", "default": "./dist/esm/index.js" },
+        "require": { "types": "./dist/cjs/index.d.ts", "default": "./dist/cjs/index.js" }
+      },
+      "edge-light": {
+        "import": { "types": "./dist/esm/index.d.ts", "default": "./dist/esm/index.js" },
+        "require": { "types": "./dist/cjs/index.d.ts", "default": "./dist/cjs/index.js" }
+      },
+      "react-native": {
+        "import": { "types": "./dist/esm/index.d.ts", "default": "./dist/esm/index.js" },
+        "require": { "types": "./dist/cjs/index.d.ts", "default": "./dist/cjs/index.js" }
+      },
+      "node": {
+        "import": { "types": "./dist/esm/node.d.ts", "default": "./dist/esm/node.js" },
+        "require": { "types": "./dist/cjs/node.d.ts", "default": "./dist/cjs/node.js" }
+      },
+      "import": { "types": "./dist/esm/index.d.ts", "default": "./dist/esm/index.js" },
+      "require": { "types": "./dist/cjs/index.d.ts", "default": "./dist/cjs/index.js" },
+      "default": "./dist/esm/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "node scripts/tsc.mjs -p tsconfig.json --noEmit",
+    "test": "node scripts/test.mjs",
+    "bench": "node bench/bench.mjs",
+    "vectors:sync": "node scripts/sync-vectors.mjs",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "typescript": "~5.9.3"
+  }
+}