@evolu/common 8.6.2 → 8.8.0

package/dist/src/Binary.js

@@ -0,0 +1,958 @@
+/**
+ * Binary data handling and byte array utilities.
+ *
+ * Buffer-based decoding functions intentionally throw errors instead of
+ * returning {@link Result}. This is a deliberate micro-optimization for Evolu
+ * Protocol's hot paths: Result is inexpensive, but returning decoded values
+ * directly avoids its success-case allocation, and using `Error` objects
+ * preserves stack traces. In the future, we will try returning `Error` objects
+ * in `Result` values to measure the real-world performance impact.
+ *
+ * @module
+ */
+import { bytesToUtf8, utf8ToBytes } from "@noble/ciphers/utils.js";
+export { bytesToHex, concatBytes, hexToBytes } from "@noble/ciphers/utils.js";
+export { bytesToUtf8, utf8ToBytes };
+/**
+ * Custom error for {@link Buffer}-related failures like premature end of data.
+ * Provides better stack traces for debugging binary protocol issues.
+ */
+export class BufferError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+/** Creates a {@link Buffer} for efficient byte operations. */
+export const createBuffer = (arrayLike) => {
+    const initialLength = arrayLike?.length ?? 0;
+    assertNonNegativeInt(initialLength, "arrayLike.length");
+    let value = arrayLike ? new Uint8Array(arrayLike) : new Uint8Array(512);
+    let length = initialLength;
+    const buffer = {
+        getCapacity: () => value.length,
+        getLength: () => length,
+        extend: (arg) => {
+            const argLength = arg.length;
+            assertNonNegativeInt(argLength, "arg.length");
+            const targetSize = length + argLength;
+            assertNonNegativeInt(targetSize, "Buffer length");
+            if (value.length < targetSize) {
+                const oldValue = value;
+                const newCapacity = Math.max(value.length * 2, targetSize);
+                value = new Uint8Array(newCapacity);
+                value.set(oldValue);
+            }
+            value.set(arg, length);
+            length = targetSize;
+        },
+        shift: () => {
+            assertBufferHasRemainingBytes(length, 1);
+            const first = value[0];
+            value = value.subarray(1);
+            length--;
+            return first;
+        },
+        shiftN: (n) => {
+            assertBufferHasRemainingBytes(length, n);
+            const subarray = value.subarray(0, n);
+            value = value.subarray(n);
+            length = (length - n);
+            return subarray;
+        },
+        truncate: (newLength) => {
+            if (newLength > length) {
+                throw new BufferError("Cannot truncate to a length greater than current");
+            }
+            length = newLength;
+        },
+        reset: () => {
+            length = 0;
+        },
+        unwrap: () => (value.length === length ? value : value.subarray(0, length)),
+    };
+    return buffer;
+};
+/**
+ * Evolu uses MessagePack to handle finite numbers except for NonNegativeInt.
+ * For NonNegativeInt, Evolu provides more efficient encoding.
+ */
+export const encodeNumber = (buffer, number) => {
+    encodeJsonValue(buffer, number);
+};
+export const decodeNumber = (buffer) => {
+    const value = decodeJsonValue(buffer);
+    if (typeof value !== "number") {
+        throw new BufferError("Expected an encoded number.");
+    }
+    return value;
+};
+/**
+ * Encodes an array of boolean flags into a single byte.
+ *
+ * Each element in the array corresponds to a bit (0-7). Array can have 0-8
+ * elements.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertEqual, createBuffer, encodeFlags } from "@evolu/common";
+ *
+ * const buffer = createBuffer();
+ * encodeFlags(buffer, [true, false, true]);
+ *
+ * assertEqual(buffer.unwrap(), new Uint8Array([0b101]));
+ * ```
+ */
+export const encodeFlags = (buffer, flags) => {
+    let byte = 0;
+    for (let i = 0; i < flags.length && i < 8; i++) {
+        if (flags[i]) {
+            byte |= 1 << i;
+        }
+    }
+    buffer.extend([byte]);
+};
+/**
+ * Decodes a byte into an array of boolean flags.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   createBuffer,
+ *   decodeFlags,
+ *   PositiveInt,
+ * } from "@evolu/common";
+ *
+ * const buffer = createBuffer([0b101]);
+ * const flags = decodeFlags(buffer, PositiveInt.orThrow(3));
+ *
+ * assertEqual(flags, [true, false, true]);
+ * assertEqual(buffer.getLength(), 0);
+ * ```
+ */
+export const decodeFlags = (buffer, count) => {
+    const byte = buffer.shift();
+    const length = Math.min(count, 8);
+    // oxlint-disable-next-line unicorn/no-new-array -- Preallocation is intentional in this decoding hot path.
+    const flags = new Array(length);
+    for (let i = 0; i < length; i++) {
+        flags[i] = (byte & (1 << i)) !== 0;
+    }
+    return flags;
+};
+/**
+ * Encodes a non-negative integer into a variable-length integer format. It's
+ * more efficient than encoding via {@link encodeNumber}.
+ *
+ * https://en.wikipedia.org/wiki/Variable-length_quantity
+ */
+export const encodeNonNegativeInt = (buffer, value) => {
+    if (value === 0) {
+        buffer.extend([0]);
+        return;
+    }
+    let remaining = BigInt(value);
+    const bytes = [];
+    while (remaining !== 0n) {
+        const byte = Number(remaining & 127n);
+        bytes.push(byte);
+        remaining >>= 7n;
+    }
+    for (let i = 0; i < bytes.length - 1; i++) {
+        bytes[i] |= 128;
+    }
+    buffer.extend(bytes);
+};
+/**
+ * Decodes a non-negative integer from a variable-length integer format.
+ *
+ * https://en.wikipedia.org/wiki/Variable-length_quantity
+ */
+export const decodeNonNegativeInt = (buffer) => {
+    let result = 0n;
+    let shift = 0n;
+    let byte = 0;
+    // 8 is the smallest required count
+    for (let byteCount = 0; byteCount < 8; byteCount++) {
+        byte = buffer.shift();
+        result |= BigInt(byte & 127) << shift;
+        if ((byte & 128) === 0)
+            break;
+        shift += 7n;
+    }
+    if ((byte & 128) !== 0) {
+        throw new BufferError("Variable-length quantity must terminate within 8 bytes.");
+    }
+    const value = Number(result);
+    assertNonNegativeInt(value, "Decoded integer");
+    return value;
+};
+/** Encodes the length of an array-like value. */
+export const encodeLength = (buffer, value) => {
+    assertNonNegativeInt(value.length, "Array-like length");
+    encodeNonNegativeInt(buffer, value.length);
+};
+/** Decodes an array-like value length. */
+export const decodeLength = decodeNonNegativeInt;
+/** Encodes a length-prefixed UTF-8 string. */
+export const encodeString = (buffer, value) => {
+    const bytes = utf8ToBytes(value);
+    encodeLength(buffer, bytes);
+    buffer.extend(bytes);
+};
+/** Decodes a length-prefixed UTF-8 string. */
+export const decodeString = (buffer) => {
+    const length = decodeLength(buffer);
+    const bytes = buffer.shiftN(length);
+    return bytesToUtf8(bytes);
+};
+/** Creates an incremental run-length encoder. */
+export const createRunLengthEncoder = (encodeValue) => {
+    const buffer = createBuffer();
+    let previousLength = 0;
+    let previousValue = null;
+    let runLength = 0;
+    return {
+        add: (value) => {
+            if (Object.is(value, previousValue)) {
+                runLength++;
+                buffer.truncate(previousLength);
+            }
+            else {
+                previousValue = value;
+                runLength = 1;
+            }
+            previousLength = buffer.getLength();
+            encodeValue(buffer, value);
+            encodeNonNegativeInt(buffer, runLength);
+        },
+        getLength: () => buffer.getLength(),
+        unwrap: () => buffer.unwrap(),
+    };
+};
+/** Decodes a run-length encoded sequence. */
+export const decodeRle = (buffer, length, decodeValue) => {
+    // oxlint-disable-next-line unicorn/no-new-array -- Preallocation is intentional in this decoding hot path.
+    const values = new Array(length);
+    let index = 0;
+    while (index < length) {
+        const value = decodeValue();
+        const runLength = decodeNonNegativeInt(buffer);
+        // Prevent infinite loop on malformed input.
+        if (runLength === 0) {
+            throw new BufferError("Invalid RLE encoding: runLength must be positive");
+        }
+        const remaining = length - index;
+        // Prevent CPU/memory amplification via oversized runLength.
+        if (runLength > remaining) {
+            throw new BufferError(`Invalid RLE encoding: runLength ${runLength} exceeds remaining ${remaining}`);
+        }
+        for (let i = 0; i < runLength; i++) {
+            values[index] = value;
+            index++;
+        }
+    }
+    return values;
+};
+const jsonKeyCacheSize = 4096;
+const maxCachedJsonKeyByteLength = 32;
+const maxJsonNestingDepth = 1_000;
+let jsonEncoderTarget = new Uint8Array(8192);
+let jsonEncoderTargetView = new DataView(jsonEncoderTarget.buffer);
+let jsonEncoderPosition = 0;
+let jsonEncoderDepth = 0;
+let jsonEncoderIsActive = false;
+const emptyJsonDecoderSource = new Uint8Array(0);
+const emptyJsonDecoderView = new DataView(emptyJsonDecoderSource.buffer);
+let jsonDecoderSource = emptyJsonDecoderSource;
+let jsonDecoderView = emptyJsonDecoderView;
+let jsonDecoderPosition = 0;
+let jsonDecoderDepth = 0;
+const jsonStringFromCharCode = String.fromCharCode;
+// Cache only short keys and use a fixed table to bound retained memory.
+const jsonKeyCache = Array.from({ length: jsonKeyCacheSize }, () => undefined);
+/**
+ * Encodes a {@link JsonValue} using the MessagePack format.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   createBuffer,
+ *   encodeJsonValue,
+ *   JsonValue,
+ * } from "@evolu/common";
+ *
+ * const buffer = createBuffer();
+ * const value = JsonValue.orThrow({ name: "Ada" });
+ *
+ * encodeJsonValue(buffer, value);
+ *
+ * assertEqual(
+ *   buffer.unwrap(),
+ *   new Uint8Array([
+ *     0x81, 0xa4, 0x6e, 0x61, 0x6d, 0x65, 0xa3, 0x41, 0x64, 0x61,
+ *   ]),
+ * );
+ * ```
+ *
+ * Encoding is artificially limited to 1,000 nested arrays or objects to keep
+ * recursive encoding and decoding safe and symmetric. JSON data should not
+ * require such depth; flatten or split deeply nested data, or use a
+ * purpose-built serialization format.
+ */
+export const encodeJsonValue = (buffer, value) => {
+    if (jsonEncoderIsActive) {
+        throw new BufferError("Reentrant JSON encoding is not supported.");
+    }
+    jsonEncoderIsActive = true;
+    jsonEncoderPosition = 0;
+    try {
+        encodeJsonValueToTarget(value);
+        buffer.extend(jsonEncoderTarget.subarray(0, jsonEncoderPosition));
+    }
+    finally {
+        jsonEncoderPosition = 0;
+        jsonEncoderDepth = 0;
+        jsonEncoderIsActive = false;
+    }
+};
+/**
+ * Decodes a {@link JsonValue} using the MessagePack format.
+ *
+ * Throws a {@link BufferError} without modifying the Buffer if the encoded value
+ * is malformed, truncated, unsupported, outside the JsonValue domain, or
+ * exceeds 1,000 nested arrays or objects.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   createBuffer,
+ *   decodeJsonValue,
+ * } from "@evolu/common";
+ *
+ * const buffer = createBuffer([
+ *   0x81, 0xa4, 0x6e, 0x61, 0x6d, 0x65, 0xa3, 0x41, 0x64, 0x61,
+ * ]);
+ *
+ * assertEqual(decodeJsonValue(buffer), { name: "Ada" });
+ * assertEqual(buffer.unwrap(), new Uint8Array());
+ * ```
+ */
+export const decodeJsonValue = (buffer) => {
+    const source = buffer.unwrap();
+    jsonDecoderSource = source;
+    jsonDecoderView = new DataView(source.buffer, source.byteOffset, source.byteLength);
+    jsonDecoderPosition = 0;
+    try {
+        const value = decodeJsonValueFromSource();
+        buffer.shiftN(jsonDecoderPosition);
+        return value;
+    }
+    catch (error) {
+        if (error instanceof BufferError)
+            throw error;
+        throw new BufferError("Invalid MessagePack data");
+    }
+    finally {
+        jsonDecoderSource = emptyJsonDecoderSource;
+        jsonDecoderView = emptyJsonDecoderView;
+        jsonDecoderPosition = 0;
+        jsonDecoderDepth = 0;
+    }
+};
+const encodeJsonValueToTarget = (value) => {
+    if (value === null) {
+        writeJsonEncoderByte(0xc0);
+        return;
+    }
+    // oxlint-disable-next-line typescript/switch-exhaustiveness-check -- JsonValue excludes the additional runtime types reported by tsgolint.
+    switch (typeof value) {
+        case "string":
+            encodeJsonStringToTarget(value);
+            return;
+        case "number": {
+            if (Object.is(value, -0)) {
+                ensureJsonEncoderCapacity(9);
+                jsonEncoderTarget[jsonEncoderPosition++] = 0xcb;
+                jsonEncoderTargetView.setFloat64(jsonEncoderPosition, value);
+                jsonEncoderPosition += 8;
+                return;
+            }
+            if (value >>> 0 === value) {
+                if (value < 0x80) {
+                    writeJsonEncoderByte(value);
+                }
+                else if (value < 0x100) {
+                    ensureJsonEncoderCapacity(2);
+                    jsonEncoderTarget[jsonEncoderPosition++] = 0xcc;
+                    jsonEncoderTarget[jsonEncoderPosition++] = value;
+                }
+                else if (value < 0x10000) {
+                    ensureJsonEncoderCapacity(3);
+                    jsonEncoderTarget[jsonEncoderPosition++] = 0xcd;
+                    jsonEncoderTargetView.setUint16(jsonEncoderPosition, value);
+                    jsonEncoderPosition += 2;
+                }
+                else {
+                    ensureJsonEncoderCapacity(5);
+                    jsonEncoderTarget[jsonEncoderPosition++] = 0xce;
+                    jsonEncoderTargetView.setUint32(jsonEncoderPosition, value);
+                    jsonEncoderPosition += 4;
+                }
+                return;
+            }
+            if (Number.isInteger(value) && value >= -0x80000000 && value < 0) {
+                if (value >= -0x20) {
+                    writeJsonEncoderByte(0x100 + value);
+                }
+                else if (value >= -0x80) {
+                    ensureJsonEncoderCapacity(2);
+                    jsonEncoderTarget[jsonEncoderPosition++] = 0xd0;
+                    jsonEncoderTargetView.setInt8(jsonEncoderPosition++, value);
+                }
+                else if (value >= -0x8000) {
+                    ensureJsonEncoderCapacity(3);
+                    jsonEncoderTarget[jsonEncoderPosition++] = 0xd1;
+                    jsonEncoderTargetView.setInt16(jsonEncoderPosition, value);
+                    jsonEncoderPosition += 2;
+                }
+                else {
+                    ensureJsonEncoderCapacity(5);
+                    jsonEncoderTarget[jsonEncoderPosition++] = 0xd2;
+                    jsonEncoderTargetView.setInt32(jsonEncoderPosition, value);
+                    jsonEncoderPosition += 4;
+                }
+                return;
+            }
+            ensureJsonEncoderCapacity(9);
+            jsonEncoderTarget[jsonEncoderPosition++] = 0xcb;
+            jsonEncoderTargetView.setFloat64(jsonEncoderPosition, value);
+            jsonEncoderPosition += 8;
+            return;
+        }
+        case "boolean":
+            writeJsonEncoderByte(value ? 0xc3 : 0xc2);
+            return;
+        case "object": {
+            if (jsonEncoderDepth >= maxJsonNestingDepth) {
+                throw new BufferError(`JSON nesting exceeds the maximum depth of ${maxJsonNestingDepth}.`);
+            }
+            jsonEncoderDepth++;
+            if (Array.isArray(value)) {
+                const array = value;
+                const length = array.length;
+                writeJsonCollectionHeader(length, 0x90, 0xdc, 0xdd);
+                for (const item of array)
+                    encodeJsonValueToTarget(item);
+                jsonEncoderDepth--;
+                return;
+            }
+            const object = value;
+            const keys = Object.keys(object);
+            writeJsonCollectionHeader(keys.length, 0x80, 0xde, 0xdf);
+            for (const key of keys) {
+                encodeJsonStringToTarget(key);
+                encodeJsonValueToTarget(object[key]);
+            }
+            jsonEncoderDepth--;
+        }
+    }
+};
+const encodeJsonStringToTarget = (value) => {
+    const valueLength = value.length;
+    const headerLength = valueLength < 0x20
+        ? 1
+        : valueLength < 0x100
+            ? 2
+            : valueLength < 0x10000
+                ? 3
+                : 5;
+    ensureJsonEncoderCapacity(5 + valueLength * 3);
+    const headerPosition = jsonEncoderPosition;
+    jsonEncoderPosition += headerLength;
+    for (let index = 0; index < valueLength; index++) {
+        let first = value.charCodeAt(index);
+        if (first < 0x80) {
+            jsonEncoderTarget[jsonEncoderPosition++] = first;
+        }
+        else if (first < 0x800) {
+            jsonEncoderTarget[jsonEncoderPosition++] = (first >> 6) | 0xc0;
+            jsonEncoderTarget[jsonEncoderPosition++] = (first & 0x3f) | 0x80;
+        }
+        else if ((first & 0xfc00) === 0xd800 &&
+            (value.charCodeAt(index + 1) & 0xfc00) === 0xdc00) {
+            const second = value.charCodeAt(++index);
+            first = 0x10000 + ((first & 0x03ff) << 10) + (second & 0x03ff);
+            jsonEncoderTarget[jsonEncoderPosition++] = (first >> 18) | 0xf0;
+            jsonEncoderTarget[jsonEncoderPosition++] = ((first >> 12) & 0x3f) | 0x80;
+            jsonEncoderTarget[jsonEncoderPosition++] = ((first >> 6) & 0x3f) | 0x80;
+            jsonEncoderTarget[jsonEncoderPosition++] = (first & 0x3f) | 0x80;
+        }
+        else {
+            jsonEncoderTarget[jsonEncoderPosition++] = (first >> 12) | 0xe0;
+            jsonEncoderTarget[jsonEncoderPosition++] = ((first >> 6) & 0x3f) | 0x80;
+            jsonEncoderTarget[jsonEncoderPosition++] = (first & 0x3f) | 0x80;
+        }
+    }
+    const byteLength = jsonEncoderPosition - headerPosition - headerLength;
+    assertMessagePackLength(byteLength, "String byte length");
+    if (byteLength < 0x20) {
+        jsonEncoderTarget[headerPosition] = 0xa0 | byteLength;
+        return;
+    }
+    if (byteLength < 0x100) {
+        if (headerLength === 1) {
+            jsonEncoderTarget.copyWithin(headerPosition + 2, headerPosition + 1, jsonEncoderPosition);
+            jsonEncoderPosition++;
+        }
+        jsonEncoderTarget[headerPosition] = 0xd9;
+        jsonEncoderTarget[headerPosition + 1] = byteLength;
+        return;
+    }
+    if (byteLength < 0x10000) {
+        if (headerLength < 3) {
+            const additionalHeaderLength = 3 - headerLength;
+            jsonEncoderTarget.copyWithin(headerPosition + 3, headerPosition + headerLength, jsonEncoderPosition);
+            jsonEncoderPosition += additionalHeaderLength;
+        }
+        jsonEncoderTarget[headerPosition] = 0xda;
+        jsonEncoderTargetView.setUint16(headerPosition + 1, byteLength);
+        return;
+    }
+    if (headerLength < 5) {
+        const additionalHeaderLength = 5 - headerLength;
+        jsonEncoderTarget.copyWithin(headerPosition + 5, headerPosition + headerLength, jsonEncoderPosition);
+        jsonEncoderPosition += additionalHeaderLength;
+    }
+    jsonEncoderTarget[headerPosition] = 0xdb;
+    jsonEncoderTargetView.setUint32(headerPosition + 1, byteLength);
+};
+const writeJsonCollectionHeader = (length, fixedMarker, marker16, marker32) => {
+    assertMessagePackLength(length, "Collection length");
+    if (length < 0x10) {
+        writeJsonEncoderByte(fixedMarker | length);
+    }
+    else if (length < 0x10000) {
+        ensureJsonEncoderCapacity(3);
+        jsonEncoderTarget[jsonEncoderPosition++] = marker16;
+        jsonEncoderTargetView.setUint16(jsonEncoderPosition, length);
+        jsonEncoderPosition += 2;
+    }
+    else {
+        ensureJsonEncoderCapacity(5);
+        jsonEncoderTarget[jsonEncoderPosition++] = marker32;
+        jsonEncoderTargetView.setUint32(jsonEncoderPosition, length);
+        jsonEncoderPosition += 4;
+    }
+};
+const writeJsonEncoderByte = (value) => {
+    ensureJsonEncoderCapacity(1);
+    jsonEncoderTarget[jsonEncoderPosition++] = value;
+};
+const ensureJsonEncoderCapacity = (additionalLength) => {
+    const requiredLength = jsonEncoderPosition + additionalLength;
+    assertNonNegativeInt(requiredLength, "Encoded JSON value length");
+    if (requiredLength <= jsonEncoderTarget.length)
+        return;
+    const newCapacity = Math.max(jsonEncoderTarget.length * 2, requiredLength);
+    assertNonNegativeInt(newCapacity, "JSON encoder capacity");
+    const oldTarget = jsonEncoderTarget;
+    jsonEncoderTarget = new Uint8Array(newCapacity);
+    jsonEncoderTarget.set(oldTarget.subarray(0, jsonEncoderPosition));
+    jsonEncoderTargetView = new DataView(jsonEncoderTarget.buffer);
+};
+const assertMessagePackLength = (length, name) => {
+    if (length > 0xffffffff) {
+        throw new BufferError(`${name} exceeds the MessagePack uint32 limit.`);
+    }
+};
+const decodeJsonValueFromSource = () => {
+    const marker = readJsonDecoderByte();
+    if (marker <= 0x7f)
+        return marker;
+    if (marker <= 0x8f)
+        return decodeJsonMap(marker - 0x80);
+    if (marker <= 0x9f)
+        return decodeJsonArray(marker - 0x90);
+    if (marker <= 0xbf)
+        return decodeJsonString(marker - 0xa0);
+    if (marker >= 0xe0)
+        return (marker - 0x100);
+    switch (marker) {
+        case 0xc0:
+            return null;
+        case 0xc2:
+            return false;
+        case 0xc3:
+            return true;
+        case 0xca:
+            return decodeJsonFloat(4);
+        case 0xcb:
+            return decodeJsonFloat(8);
+        case 0xcc:
+            return readJsonDecoderByte();
+        case 0xcd:
+            return readJsonUint16();
+        case 0xce:
+            return readJsonUint32();
+        case 0xd0: {
+            assertJsonDecoderHasRemainingBytes(1);
+            return jsonDecoderView.getInt8(jsonDecoderPosition++);
+        }
+        case 0xd1: {
+            assertJsonDecoderHasRemainingBytes(2);
+            const value = jsonDecoderView.getInt16(jsonDecoderPosition);
+            jsonDecoderPosition += 2;
+            return value;
+        }
+        case 0xd2: {
+            assertJsonDecoderHasRemainingBytes(4);
+            const value = jsonDecoderView.getInt32(jsonDecoderPosition);
+            jsonDecoderPosition += 4;
+            return value;
+        }
+        case 0xd9:
+            return decodeJsonString(readJsonDecoderByte());
+        case 0xda:
+            return decodeJsonString(readJsonUint16());
+        case 0xdb:
+            return decodeJsonString(readJsonUint32());
+        case 0xdc:
+            return decodeJsonArray(readJsonUint16());
+        case 0xdd:
+            return decodeJsonArray(readJsonUint32());
+        case 0xde:
+            return decodeJsonMap(readJsonUint16());
+        case 0xdf:
+            return decodeJsonMap(readJsonUint32());
+        default:
+            throw new BufferError(`Unsupported MessagePack marker 0x${marker.toString(16).padStart(2, "0")}.`);
+    }
+};
+const decodeJsonFloat = (byteLength) => {
+    assertJsonDecoderHasRemainingBytes(byteLength);
+    const value = byteLength === 4
+        ? jsonDecoderView.getFloat32(jsonDecoderPosition)
+        : jsonDecoderView.getFloat64(jsonDecoderPosition);
+    jsonDecoderPosition += byteLength;
+    if (!Number.isFinite(value)) {
+        throw new BufferError("A decoded JSON number must be finite.");
+    }
+    return value;
+};
+const decodeJsonString = (byteLength) => {
+    assertJsonDecoderHasRemainingBytes(byteLength);
+    shortAscii: if (byteLength < 16) {
+        if (byteLength === 0)
+            return "";
+        const start = jsonDecoderPosition;
+        const first = jsonDecoderSource[jsonDecoderPosition++];
+        if ((first & 0x80) !== 0) {
+            jsonDecoderPosition = start;
+            break shortAscii;
+        }
+        if (byteLength === 1)
+            return jsonStringFromCharCode(first);
+        const second = jsonDecoderSource[jsonDecoderPosition++];
+        if ((second & 0x80) !== 0) {
+            jsonDecoderPosition = start;
+            break shortAscii;
+        }
+        if (byteLength === 2)
+            return jsonStringFromCharCode(first, second);
+        const third = jsonDecoderSource[jsonDecoderPosition++];
+        if ((third & 0x80) !== 0) {
+            jsonDecoderPosition = start;
+            break shortAscii;
+        }
+        if (byteLength === 3)
+            return jsonStringFromCharCode(first, second, third);
+        const fourth = jsonDecoderSource[jsonDecoderPosition++];
+        if ((fourth & 0x80) !== 0) {
+            jsonDecoderPosition = start;
+            break shortAscii;
+        }
+        if (byteLength === 4) {
+            return jsonStringFromCharCode(first, second, third, fourth);
+        }
+        const fifth = jsonDecoderSource[jsonDecoderPosition++];
+        if ((fifth & 0x80) !== 0) {
+            jsonDecoderPosition = start;
+            break shortAscii;
+        }
+        if (byteLength === 5) {
+            return jsonStringFromCharCode(first, second, third, fourth, fifth);
+        }
+        const sixth = jsonDecoderSource[jsonDecoderPosition++];
+        if ((sixth & 0x80) !== 0) {
+            jsonDecoderPosition = start;
+            break shortAscii;
+        }
+        if (byteLength === 6) {
+            return jsonStringFromCharCode(first, second, third, fourth, fifth, sixth);
+        }
+        const seventh = jsonDecoderSource[jsonDecoderPosition++];
+        if ((seventh & 0x80) !== 0) {
+            jsonDecoderPosition = start;
+            break shortAscii;
+        }
+        if (byteLength === 7) {
+            return jsonStringFromCharCode(first, second, third, fourth, fifth, sixth, seventh);
+        }
+        const eighth = jsonDecoderSource[jsonDecoderPosition++];
+        if ((eighth & 0x80) !== 0) {
+            jsonDecoderPosition = start;
+            break shortAscii;
+        }
+        if (byteLength === 8) {
+            return jsonStringFromCharCode(first, second, third, fourth, fifth, sixth, seventh, eighth);
+        }
+        const ninth = jsonDecoderSource[jsonDecoderPosition++];
+        if ((ninth & 0x80) !== 0) {
+            jsonDecoderPosition = start;
+            break shortAscii;
+        }
+        if (byteLength === 9) {
+            return jsonStringFromCharCode(first, second, third, fourth, fifth, sixth, seventh, eighth, ninth);
+        }
+        const tenth = jsonDecoderSource[jsonDecoderPosition++];
+        if ((tenth & 0x80) !== 0) {
+            jsonDecoderPosition = start;
+            break shortAscii;
+        }
+        if (byteLength === 10) {
+            return jsonStringFromCharCode(first, second, third, fourth, fifth, sixth, seventh, eighth, ninth, tenth);
+        }
+        const eleventh = jsonDecoderSource[jsonDecoderPosition++];
+        if ((eleventh & 0x80) !== 0) {
+            jsonDecoderPosition = start;
+            break shortAscii;
+        }
+        if (byteLength === 11) {
+            return jsonStringFromCharCode(first, second, third, fourth, fifth, sixth, seventh, eighth, ninth, tenth, eleventh);
+        }
+        const twelfth = jsonDecoderSource[jsonDecoderPosition++];
+        if ((twelfth & 0x80) !== 0) {
+            jsonDecoderPosition = start;
+            break shortAscii;
+        }
+        if (byteLength === 12) {
+            return jsonStringFromCharCode(first, second, third, fourth, fifth, sixth, seventh, eighth, ninth, tenth, eleventh, twelfth);
+        }
+        const thirteenth = jsonDecoderSource[jsonDecoderPosition++];
+        if ((thirteenth & 0x80) !== 0) {
+            jsonDecoderPosition = start;
+            break shortAscii;
+        }
+        if (byteLength === 13) {
+            return jsonStringFromCharCode(first, second, third, fourth, fifth, sixth, seventh, eighth, ninth, tenth, eleventh, twelfth, thirteenth);
+        }
+        const fourteenth = jsonDecoderSource[jsonDecoderPosition++];
+        if ((fourteenth & 0x80) !== 0) {
+            jsonDecoderPosition = start;
+            break shortAscii;
+        }
+        if (byteLength === 14) {
+            return jsonStringFromCharCode(first, second, third, fourth, fifth, sixth, seventh, eighth, ninth, tenth, eleventh, twelfth, thirteenth, fourteenth);
+        }
+        const fifteenth = jsonDecoderSource[jsonDecoderPosition++];
+        if ((fifteenth & 0x80) !== 0) {
+            jsonDecoderPosition = start;
+            break shortAscii;
+        }
+        return jsonStringFromCharCode(first, second, third, fourth, fifth, sixth, seventh, eighth, ninth, tenth, eleventh, twelfth, thirteenth, fourteenth, fifteenth);
+    }
+    const end = jsonDecoderPosition + byteLength;
+    const units = [];
+    let result = "";
+    while (jsonDecoderPosition < end) {
+        const first = jsonDecoderSource[jsonDecoderPosition++];
+        if (first < 0x80) {
+            units.push(first);
+        }
+        else if (first >= 0xc2 && first <= 0xdf) {
+            assertJsonStringHasRemainingBytes(end, 1);
+            const second = readJsonContinuationByte();
+            units.push(((first & 0x1f) << 6) | second);
+        }
+        else if (first >= 0xe0 && first <= 0xef) {
+            assertJsonStringHasRemainingBytes(end, 2);
+            const secondByte = jsonDecoderSource[jsonDecoderPosition];
+            if (first === 0xe0 && secondByte < 0xa0) {
+                throw new BufferError("Invalid UTF-8 string encoding.");
+            }
+            const second = readJsonContinuationByte();
+            const third = readJsonContinuationByte();
+            units.push(((first & 0x0f) << 12) | (second << 6) | third);
+        }
+        else if (first >= 0xf0 && first <= 0xf4) {
+            assertJsonStringHasRemainingBytes(end, 3);
+            const secondByte = jsonDecoderSource[jsonDecoderPosition];
+            if ((first === 0xf0 && secondByte < 0x90) ||
+                (first === 0xf4 && secondByte > 0x8f)) {
+                throw new BufferError("Invalid UTF-8 string encoding.");
+            }
+            const second = readJsonContinuationByte();
+            const third = readJsonContinuationByte();
+            const fourth = readJsonContinuationByte();
+            const codePoint = ((first & 0x07) << 18) | (second << 12) | (third << 6) | fourth;
+            const pair = codePoint - 0x10000;
+            units.push(0xd800 | (pair >> 10), 0xdc00 | (pair & 0x3ff));
+        }
+        else {
+            throw new BufferError("Invalid UTF-8 string encoding.");
+        }
+        if (units.length >= 0x1000) {
+            result += jsonStringFromCharCode(...units);
+            units.length = 0;
+        }
+    }
+    if (units.length > 0) {
+        result += jsonStringFromCharCode(...units);
+    }
+    return result;
+};
+const decodeJsonArray = (length) => {
+    if (jsonDecoderDepth >= maxJsonNestingDepth) {
+        throw new BufferError(`JSON nesting exceeds the maximum depth of ${maxJsonNestingDepth}.`);
+    }
+    if (length > jsonDecoderSource.length - jsonDecoderPosition) {
+        throw new BufferError("Buffer parse ended prematurely");
+    }
+    // oxlint-disable-next-line unicorn/no-new-array -- Preallocation is intentional in this decoding hot path.
+    const value = new Array(length);
+    jsonDecoderDepth++;
+    for (let index = 0; index < length; index++) {
+        value[index] = decodeJsonValueFromSource();
+    }
+    jsonDecoderDepth--;
+    return value;
+};
+const decodeJsonMap = (length) => {
+    if (jsonDecoderDepth >= maxJsonNestingDepth) {
+        throw new BufferError(`JSON nesting exceeds the maximum depth of ${maxJsonNestingDepth}.`);
+    }
+    if (length > (jsonDecoderSource.length - jsonDecoderPosition) / 2) {
+        throw new BufferError("Buffer parse ended prematurely");
+    }
+    const value = {};
+    jsonDecoderDepth++;
+    for (let index = 0; index < length; index++) {
+        const marker = readJsonDecoderByte();
+        let key;
+        if (marker >= 0xa0 && marker <= 0xbf) {
+            key = decodeCachedJsonKey(marker - 0xa0);
+        }
+        else if (marker === 0xd9) {
+            key = decodeCachedJsonKey(readJsonDecoderByte());
+        }
+        else if (marker === 0xda) {
+            key = decodeCachedJsonKey(readJsonUint16());
+        }
+        else if (marker === 0xdb) {
+            key = decodeCachedJsonKey(readJsonUint32());
+        }
+        else {
+            jsonDecoderPosition--;
+            decodeJsonValueFromSource();
+            throw new BufferError("A decoded JSON object key must be a string.");
+        }
+        const entryValue = decodeJsonValueFromSource();
+        if (key === "__proto__") {
+            Object.defineProperty(value, key, {
+                value: entryValue,
+                configurable: true,
+                enumerable: true,
+                writable: true,
+            });
+        }
+        else {
+            value[key] = entryValue;
+        }
+    }
+    jsonDecoderDepth--;
+    return value;
+};
+const decodeCachedJsonKey = (byteLength) => {
+    if (byteLength > maxCachedJsonKeyByteLength) {
+        return decodeJsonString(byteLength);
+    }
+    assertJsonDecoderHasRemainingBytes(byteLength);
+    const start = jsonDecoderPosition;
+    const end = start + byteLength;
+    const firstBytes = byteLength > 1
+        ? jsonDecoderView.getUint16(start)
+        : byteLength === 1
+            ? jsonDecoderSource[start]
+            : 0;
+    const cacheIndex = ((byteLength << 5) ^ firstBytes) & (jsonKeyCacheSize - 1);
+    const entry = jsonKeyCache[cacheIndex];
+    if (entry?.bytes.length === byteLength) {
+        let index = 0;
+        while (index < byteLength &&
+            entry.bytes[index] === jsonDecoderSource[start + index]) {
+            index++;
+        }
+        if (index === byteLength) {
+            jsonDecoderPosition = end;
+            return entry.value;
+        }
+    }
+    const value = decodeJsonString(byteLength);
+    jsonKeyCache[cacheIndex] = {
+        bytes: jsonDecoderSource.slice(start, end),
+        value,
+    };
+    return value;
+};
+const readJsonContinuationByte = () => {
+    const byte = jsonDecoderSource[jsonDecoderPosition++];
+    if ((byte & 0xc0) !== 0x80) {
+        throw new BufferError("Invalid UTF-8 string encoding.");
+    }
+    return byte & 0x3f;
+};
+const assertJsonStringHasRemainingBytes = (end, requiredBytes) => {
+    if (end - jsonDecoderPosition < requiredBytes) {
+        throw new BufferError("Invalid UTF-8 string encoding.");
+    }
+};
+const readJsonDecoderByte = () => {
+    assertJsonDecoderHasRemainingBytes(1);
+    return jsonDecoderSource[jsonDecoderPosition++];
+};
+const readJsonUint16 = () => {
+    assertJsonDecoderHasRemainingBytes(2);
+    const value = jsonDecoderView.getUint16(jsonDecoderPosition);
+    jsonDecoderPosition += 2;
+    return value;
+};
+const readJsonUint32 = () => {
+    assertJsonDecoderHasRemainingBytes(4);
+    const value = jsonDecoderView.getUint32(jsonDecoderPosition);
+    jsonDecoderPosition += 4;
+    return value;
+};
+const assertJsonDecoderHasRemainingBytes = (requiredBytes) => {
+    if (jsonDecoderSource.length - jsonDecoderPosition < requiredBytes) {
+        throw new BufferError("Buffer parse ended prematurely");
+    }
+};
+const assertNonNegativeInt = (value, name) => {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new BufferError(`${name} must be a non-negative safe integer.`);
+    }
+};
+const assertBufferHasRemainingBytes = (remainingBytes, requiredBytes) => {
+    if (remainingBytes < requiredBytes) {
+        throw new BufferError("Buffer parse ended prematurely");
+    }
+};