@btoon/js 0.0.0-stage → 0.1.0

package/dist/cjs/decode.js

@@ -0,0 +1,554 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.plainBytes = plainBytes;
+exports.decodeDocument = decodeDocument;
+exports.validateBtoonExt = validateBtoonExt;
+// Hardened BTOON decoder (SPEC §7). Invariants:
+//  * every read is bounds-checked against `end` (no reads past the input);
+//  * containers are depth-limited (max_depth) — no unbounded recursion;
+//  * nothing is allocated beyond what the remaining input could encode.
+const constants_js_1 = require("./constants.js");
+const errors_js_1 = require("./errors.js");
+const utf8_js_1 = require("./utf8.js");
+const values_js_1 = require("./values.js");
+const TWO_32 = 4294967296;
+const LITTLE_ENDIAN = new Uint8Array(new Uint16Array([1]).buffer)[0] === 1;
+const MAX_DATE_SECONDS = constants_js_1.MAX_DATE_MS / 1000;
+const hasOwn = Object.prototype.hasOwnProperty;
+const fromCharCode = String.fromCharCode;
+// Map keys repeat across records, so short ASCII keys are cached. A hit is verified
+// byte-for-byte, so a collision only costs a miss; the cached strings are already
+// internalized, which also makes the property stores cheaper.
+const KEY_CACHE_SIZE = 4096;
+const KEY_CACHE_MAX_LEN = 16;
+const keyCache = new Array(KEY_CACHE_SIZE).fill(undefined);
+const HEX = [];
+for (let i = 0; i < 256; i++)
+    HEX.push((i < 16 ? '0' : '') + i.toString(16));
+/** Sets `obj[key] = value` as an own data property; `__proto__` never touches the prototype. */
+function setProperty(obj, key, value) {
+    if (key === '__proto__') {
+        Object.defineProperty(obj, key, { value, writable: true, enumerable: true, configurable: true });
+    }
+    else {
+        obj[key] = value;
+    }
+}
+function floorDiv(a, b) {
+    let q = a / b;
+    let r = a % b;
+    if (r < 0n) {
+        r += b;
+        q -= 1n;
+    }
+    return [q, r];
+}
+/** A plain Uint8Array view of the same bytes (Buffer.prototype.slice does not copy). */
+function plainBytes(b) {
+    return Object.getPrototypeOf(b) === Uint8Array.prototype ? b : new Uint8Array(b.buffer, b.byteOffset, b.byteLength);
+}
+class Decoder {
+    constructor(bytes, strict, maxDepth, tsObjects, bigAlways) {
+        this.pos = 0;
+        this.bytes = plainBytes(bytes);
+        this.view = new DataView(this.bytes.buffer, this.bytes.byteOffset, this.bytes.byteLength);
+        this.end = this.bytes.length;
+        this.strict = strict;
+        this.maxDepth = maxDepth;
+        this.tsObjects = tsObjects;
+        this.bigAlways = bigAlways;
+    }
+    err(code, message, at = this.pos) {
+        return (0, errors_js_1.fail)(code, `${message} (at byte ${at})`);
+    }
+    need(n) {
+        if (this.end - this.pos < n)
+            throw this.err('truncated', 'unexpected end of input');
+    }
+    u8() {
+        this.need(1);
+        return this.bytes[this.pos++];
+    }
+    u16() {
+        this.need(2);
+        const v = this.view.getUint16(this.pos);
+        this.pos += 2;
+        return v;
+    }
+    u32() {
+        this.need(4);
+        const v = this.view.getUint32(this.pos);
+        this.pos += 4;
+        return v;
+    }
+    value(depth) {
+        if (this.pos >= this.end)
+            throw this.err('truncated', 'unexpected end of input');
+        const m = this.bytes[this.pos++];
+        if (m < 0x80)
+            return m;
+        if (m >= 0xe0)
+            return m - 0x100;
+        if (m < 0x90)
+            return this.map(m & 0x0f, depth);
+        if (m < 0xa0)
+            return this.array(m & 0x0f, depth);
+        if (m < 0xc0)
+            return this.str(m & 0x1f);
+        const view = this.view;
+        let v;
+        switch (m) {
+            case 0xc0:
+                return null;
+            case 0xc2:
+                return false;
+            case 0xc3:
+                return true;
+            case 0xc4:
+                return this.bin(this.u8());
+            case 0xc5:
+                return this.bin(this.u16());
+            case 0xc6:
+                return this.bin(this.u32());
+            case 0xc7:
+                return this.ext(this.u8(), depth);
+            case 0xc8:
+                return this.ext(this.u16(), depth);
+            case 0xc9:
+                return this.ext(this.u32(), depth);
+            case 0xca:
+                this.need(4);
+                v = view.getFloat32(this.pos);
+                this.pos += 4;
+                return v;
+            case 0xcb:
+                this.need(8);
+                v = view.getFloat64(this.pos);
+                this.pos += 8;
+                return v;
+            case 0xcc:
+                return this.u8();
+            case 0xcd:
+                return this.u16();
+            case 0xce:
+                return this.u32();
+            case 0xcf:
+                return this.uint64();
+            case 0xd0:
+                this.need(1);
+                return view.getInt8(this.pos++);
+            case 0xd1:
+                this.need(2);
+                v = view.getInt16(this.pos);
+                this.pos += 2;
+                return v;
+            case 0xd2:
+                this.need(4);
+                v = view.getInt32(this.pos);
+                this.pos += 4;
+                return v;
+            case 0xd3:
+                return this.int64();
+            case 0xd4:
+                return this.ext(1, depth);
+            case 0xd5:
+                return this.ext(2, depth);
+            case 0xd6:
+                return this.ext(4, depth);
+            case 0xd7:
+                return this.ext(8, depth);
+            case 0xd8:
+                return this.ext(16, depth);
+            case 0xd9:
+                return this.str(this.u8());
+            case 0xda:
+                return this.str(this.u16());
+            case 0xdb:
+                return this.str(this.u32());
+            case 0xdc:
+                return this.array(this.u16(), depth);
+            case 0xdd:
+                return this.array(this.u32(), depth);
+            case 0xde:
+                return this.map(this.u16(), depth);
+            case 0xdf:
+                return this.map(this.u32(), depth);
+            default: // 0xc1
+                throw this.err('invalid_marker', 'reserved marker 0xc1', this.pos - 1);
+        }
+    }
+    uint64() {
+        this.need(8);
+        const p = this.pos;
+        this.pos += 8;
+        const hi = this.view.getUint32(p);
+        if (!this.bigAlways && hi < 0x200000)
+            return hi * TWO_32 + this.view.getUint32(p + 4);
+        return this.view.getBigUint64(p);
+    }
+    int64() {
+        this.need(8);
+        const p = this.pos;
+        this.pos += 8;
+        if (!this.bigAlways) {
+            // Exact whenever the result is a safe integer; never safe-looking when it isn't.
+            const v = this.view.getInt32(p) * TWO_32 + this.view.getUint32(p + 4);
+            if (Number.isSafeInteger(v))
+                return v;
+        }
+        return this.view.getBigInt64(p);
+    }
+    str(len) {
+        if (len > this.end - this.pos)
+            throw this.err('truncated', 'string runs past the end of input');
+        const s = (0, utf8_js_1.decodeUtf8)(this.bytes, this.pos, len, this.strict);
+        if (s === undefined)
+            throw this.err('invalid_utf8', 'string is not valid UTF-8');
+        this.pos += len;
+        return s;
+    }
+    bin(len) {
+        if (len > this.end - this.pos)
+            throw this.err('truncated', 'binary runs past the end of input');
+        const b = this.bytes.slice(this.pos, this.pos + len);
+        this.pos += len;
+        return b;
+    }
+    array(n, depth) {
+        if (depth >= this.maxDepth)
+            throw this.err('max_depth', 'maximum nesting depth exceeded');
+        // Every element takes at least one byte.
+        if (n > this.end - this.pos)
+            throw this.err('truncated', 'array length exceeds the remaining input');
+        const a = new Array(n);
+        for (let i = 0; i < n; i++)
+            a[i] = this.value(depth + 1);
+        return a;
+    }
+    key() {
+        if (this.pos >= this.end)
+            throw this.err('truncated', 'unexpected end of input');
+        const m = this.bytes[this.pos];
+        let len;
+        if (m >= 0xa0 && m <= 0xbf) {
+            this.pos++;
+            len = m & 0x1f;
+        }
+        else if (m === 0xd9) {
+            this.pos++;
+            len = this.u8();
+        }
+        else if (m === 0xda) {
+            this.pos++;
+            len = this.u16();
+        }
+        else if (m === 0xdb) {
+            this.pos++;
+            len = this.u32();
+        }
+        else {
+            throw this.err('non_string_key', 'map key is not a string');
+        }
+        if (len <= KEY_CACHE_MAX_LEN && len <= this.end - this.pos) {
+            const bytes = this.bytes;
+            const p = this.pos;
+            let h = len;
+            let high = 0;
+            for (let i = p; i < p + len; i++) {
+                const b = bytes[i];
+                h = (Math.imul(h, 31) + b) | 0;
+                high |= b;
+            }
+            if (high < 0x80) {
+                const slot = h & (KEY_CACHE_SIZE - 1);
+                let s = keyCache[slot];
+                if (s !== undefined && s.length === len) {
+                    let i = 0;
+                    while (i < len && s.charCodeAt(i) === bytes[p + i])
+                        i++;
+                    if (i === len) {
+                        this.pos = p + len;
+                        return s;
+                    }
+                }
+                s = len === 0 ? '' : fromCharCode.apply(null, bytes.subarray(p, p + len));
+                keyCache[slot] = s;
+                this.pos = p + len;
+                return s;
+            }
+        }
+        return this.str(len);
+    }
+    map(n, depth) {
+        if (depth >= this.maxDepth)
+            throw this.err('max_depth', 'maximum nesting depth exceeded');
+        // Every entry takes at least two bytes.
+        if (n > (this.end - this.pos) / 2)
+            throw this.err('truncated', 'map length exceeds the remaining input');
+        const obj = {};
+        // While keys arrive strictly increasing (as in canonical input) none can repeat; after
+        // the first out-of-order key every key is checked against the object.
+        let prev = '';
+        let ordered = true;
+        for (let i = 0; i < n; i++) {
+            const k = this.key();
+            const v = this.value(depth + 1);
+            if (ordered && (i === 0 || prev < k)) {
+                prev = k;
+            }
+            else {
+                ordered = false;
+                // Decoded values are never undefined, so this skips hasOwn for fresh keys.
+                if (obj[k] !== undefined && hasOwn.call(obj, k) && this.strict) {
+                    throw this.err('duplicate_key', `duplicate map key ${JSON.stringify(k)}`);
+                }
+            }
+            setProperty(obj, k, v);
+        }
+        return obj;
+    }
+    ext(len, depth) {
+        this.need(1);
+        const type = this.view.getInt8(this.pos++);
+        if (len > this.end - this.pos)
+            throw this.err('truncated', 'extension payload runs past the end of input');
+        const start = this.pos;
+        this.pos = start + len;
+        return this.extValue(type, start, len, depth);
+    }
+    /** Interprets the payload `bytes[start, start+len)` of an extension of `type`. */
+    extValue(type, start, len, depth) {
+        const view = this.view;
+        const bad = (what) => this.err('invalid_extension', what, start);
+        switch (type) {
+            case constants_js_1.EXT_TIMESTAMP: {
+                let sec;
+                let ns;
+                let off;
+                switch (len) {
+                    case 4:
+                        sec = view.getUint32(start);
+                        ns = 0;
+                        break;
+                    case 8: {
+                        const hi = view.getUint32(start);
+                        ns = hi >>> 2;
+                        sec = (hi & 3) * TWO_32 + view.getUint32(start + 4);
+                        break;
+                    }
+                    case 12:
+                    case 14:
+                        ns = view.getUint32(start);
+                        sec = view.getBigInt64(start + 4);
+                        if (len === 14) {
+                            off = view.getInt16(start + 12);
+                            if (off < -constants_js_1.MAX_OFFSET_MINUTES || off > constants_js_1.MAX_OFFSET_MINUTES)
+                                throw bad('timestamp offset out of range');
+                        }
+                        break;
+                    default:
+                        throw bad('invalid timestamp length');
+                }
+                if (ns >= constants_js_1.NANOS_PER_SECOND)
+                    throw bad('timestamp nanoseconds out of range');
+                return this.instant(sec, ns, off);
+            }
+            case constants_js_1.EXT_DATE: {
+                if (len !== 8)
+                    throw bad('invalid date length');
+                const ms = view.getBigInt64(start);
+                if (!this.tsObjects && ms <= BigInt(constants_js_1.MAX_DATE_MS) && ms >= -BigInt(constants_js_1.MAX_DATE_MS))
+                    return new Date(Number(ms));
+                const [s, r] = floorDiv(ms, 1000n);
+                return new values_js_1.Timestamp(s, Number(r) * 1e6);
+            }
+            case constants_js_1.EXT_DATETIME: {
+                if (len !== 8)
+                    throw bad('invalid datetime length');
+                const ns = view.getBigInt64(start);
+                if (!this.tsObjects)
+                    return new Date(Number(floorDiv(ns, 1000000n)[0]));
+                const [s, r] = floorDiv(ns, 1000000000n);
+                return new values_js_1.Timestamp(s, Number(r));
+            }
+            case constants_js_1.EXT_BIGINT:
+                if (len === 0)
+                    throw bad('empty bigint');
+                return this.bigint(start, len);
+            case constants_js_1.EXT_F32_VECTOR:
+            case constants_js_1.EXT_F64_VECTOR: {
+                const size = type === constants_js_1.EXT_F32_VECTOR ? 4 : 8;
+                if (len % size !== 0)
+                    throw bad(`float${size * 8} vector length is not a multiple of ${size}`);
+                // Always a fresh, aligned copy: never a view into the input.
+                const out = type === constants_js_1.EXT_F32_VECTOR ? new Float32Array(len / 4) : new Float64Array(len / 8);
+                const raw = new Uint8Array(out.buffer);
+                raw.set(this.bytes.subarray(start, start + len));
+                if (!LITTLE_ENDIAN) {
+                    for (let i = 0; i < len; i += size)
+                        raw.subarray(i, i + size).reverse();
+                }
+                return out;
+            }
+            case constants_js_1.EXT_TABULAR:
+                return this.tabular(start, len, depth);
+            default:
+                return new values_js_1.Ext(type, this.bytes.slice(start, start + len));
+        }
+    }
+    /** A timestamp as a Date (default) or a Timestamp (`timestamps: 'object'`, or out of Date range). */
+    instant(sec, ns, off) {
+        if (!this.tsObjects) {
+            const s = typeof sec === 'number' ? sec : sec <= BigInt(MAX_DATE_SECONDS) && sec >= -BigInt(MAX_DATE_SECONDS) ? Number(sec) : NaN;
+            const ms = s * 1000 + Math.floor(ns / 1e6);
+            if (ms <= constants_js_1.MAX_DATE_MS && ms >= -constants_js_1.MAX_DATE_MS)
+                return new Date(ms);
+        }
+        return new values_js_1.Timestamp(sec, ns, off);
+    }
+    bigint(start, len) {
+        const bytes = this.bytes;
+        let v;
+        try {
+            let hex = '';
+            if (len <= 64) {
+                for (let i = start; i < start + len; i++)
+                    hex += HEX[bytes[i]];
+            }
+            else {
+                const parts = new Array(len);
+                for (let i = 0; i < len; i++)
+                    parts[i] = HEX[bytes[start + i]];
+                hex = parts.join('');
+            }
+            v = BigInt('0x' + hex);
+            if (bytes[start] >= 0x80)
+                v -= 1n << BigInt(len * 8);
+        }
+        catch (e) {
+            throw (0, errors_js_1.fail)('size_limit', `bigint too large for this JavaScript engine (at byte ${start})`, e);
+        }
+        if (!this.bigAlways && v >= -0x1fffffffffffffn && v <= 0x1fffffffffffffn)
+            return Number(v);
+        return v;
+    }
+    tabular(start, len, depth) {
+        if (depth + 1 >= this.maxDepth)
+            throw this.err('max_depth', 'maximum nesting depth exceeded', start);
+        const view = this.view;
+        const end = start + len;
+        let p = start;
+        const bad = (what) => this.err('invalid_tabular', what, p);
+        if (end - p < 12)
+            throw bad('tabular payload truncated');
+        const version = view.getUint32(p);
+        const cols = view.getUint32(p + 4);
+        const rowCount = view.getUint32(p + 8);
+        p += 12;
+        if (version !== constants_js_1.TABULAR_VERSION)
+            throw bad(`unsupported tabular version ${version}`);
+        if (cols === 0 && rowCount > 0)
+            throw bad('tabular rows without columns');
+        // Each column needs at least 9 bytes: name length, type code, column length.
+        if (cols > (end - p) / 9)
+            throw bad('tabular column count exceeds the payload');
+        const names = new Array(cols);
+        for (let c = 0; c < cols; c++) {
+            if (end - p < 4)
+                throw bad('tabular payload truncated');
+            const n = view.getUint32(p);
+            p += 4;
+            if (n > end - p)
+                throw bad('tabular column name runs past the payload');
+            const name = (0, utf8_js_1.decodeUtf8)(this.bytes, p, n, this.strict);
+            if (name === undefined)
+                throw this.err('invalid_utf8', 'column name is not valid UTF-8', p);
+            names[c] = name;
+            p += n;
+        }
+        if (new Set(names).size !== cols)
+            throw bad('duplicate tabular column name');
+        if (cols > end - p)
+            throw bad('tabular payload truncated');
+        p += cols; // type codes are informational (SPEC §5.6.1)
+        // Every cell is at least one byte.
+        if (rowCount * cols > end - p)
+            throw bad('tabular row count exceeds the payload');
+        const rows = new Array(rowCount);
+        for (let r = 0; r < rowCount; r++)
+            rows[r] = {};
+        const savedEnd = this.end;
+        for (let c = 0; c < cols; c++) {
+            if (end - p < 4)
+                throw bad('tabular payload truncated');
+            const colLen = view.getUint32(p);
+            p += 4;
+            if (colLen > end - p)
+                throw bad('tabular column runs past the payload');
+            const colEnd = p + colLen;
+            const name = names[c];
+            this.pos = p;
+            this.end = colEnd;
+            try {
+                if (name === '__proto__') {
+                    for (let r = 0; r < rowCount; r++)
+                        setProperty(rows[r], name, this.value(depth + 2));
+                }
+                else {
+                    for (let r = 0; r < rowCount; r++)
+                        rows[r][name] = this.value(depth + 2);
+                }
+            }
+            catch (e) {
+                if (e instanceof errors_js_1.BtoonError && e.code === 'truncated') {
+                    throw (0, errors_js_1.fail)('invalid_tabular', `tabular column holds fewer values than rows (at byte ${this.pos})`, e);
+                }
+                throw e;
+            }
+            if (this.pos !== colEnd)
+                throw this.err('invalid_tabular', 'tabular column length mismatch');
+            p = colEnd;
+        }
+        this.end = savedEnd;
+        if (p !== end)
+            throw bad('trailing bytes in tabular payload');
+        this.pos = end;
+        return rows;
+    }
+}
+/** Decodes one bare BTOON document (no envelopes). */
+function decodeDocument(bytes, cfg) {
+    const d = new Decoder(bytes, cfg.strict, cfg.maxDepth, cfg.timestampObjects, cfg.bigintAlways);
+    let v;
+    try {
+        v = d.value(0);
+    }
+    catch (e) {
+        if ((0, errors_js_1.isStackOverflow)(e))
+            throw (0, errors_js_1.fail)('max_depth', 'input nests too deeply for the JavaScript call stack', e);
+        throw e;
+    }
+    if (d.pos !== d.end && cfg.strict)
+        throw d.err('trailing_data', 'trailing bytes after the top-level value');
+    return v;
+}
+/**
+ * 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.
+ */
+function validateBtoonExt(type, data, depth, maxDepth = constants_js_1.DEFAULT_MAX_DEPTH) {
+    if (!((type <= constants_js_1.EXT_TIMESTAMP && type >= constants_js_1.EXT_F64_VECTOR) || type === constants_js_1.EXT_TABULAR))
+        return;
+    const d = new Decoder(data, true, maxDepth, true, true);
+    try {
+        d.extValue(type, 0, d.end, depth);
+    }
+    catch (e) {
+        if (e instanceof errors_js_1.BtoonError) {
+            throw (0, errors_js_1.fail)('invalid_argument', `Ext(${type}) does not hold a valid payload for that BTOON type: ${e.message}`, e);
+        }
+        if ((0, errors_js_1.isStackOverflow)(e))
+            throw (0, errors_js_1.fail)('max_depth', 'Ext payload nests too deeply', e);
+        throw e;
+    }
+}

package/dist/cjs/encode.d.ts

@@ -0,0 +1,2 @@
+/** Canonical encoding of `value` (no envelopes). */
+export declare function encodeDocument(value: unknown, maxDepth: number, autoTabular: boolean): Uint8Array<ArrayBuffer>;