@bare-ts/lib 0.5.0 → 0.6.0

package/dist/codec/u64-array.js

@@ -1,51 +1,50 @@
-"use strict";
+//! Copyright (c) 2022 Victorien Elvinger
+//! Licensed under the MIT License (https://mit-license.org/)
 import { check, reserve } from "../core/byte-cursor.js";
 import { assert, DEV } from "../util/assert.js";
 import { IS_LITTLE_ENDIAN_PLATFORM } from "../util/constants.js";
 import { isU32 } from "../util/validator.js";
 import { readFixedData } from "./data.js";
-import {
-  readU64,
-  readUintSafe32,
-  writeU64,
-  writeUintSafe32
-} from "./primitive.js";
+import { readU64, writeU64 } from "./fixed-primitive.js";
 import { writeU8FixedArray } from "./u8-array.js";
-export const readU64FixedArray = IS_LITTLE_ENDIAN_PLATFORM ? readU64FixedArrayLe : readU64FixedArrayBe;
+import { readUintSafe32, writeUintSafe32 } from "./uint.js";
+export const readU64FixedArray = IS_LITTLE_ENDIAN_PLATFORM
+    ? readU64FixedArrayLe
+    : readU64FixedArrayBe;
 export function readU64Array(bc) {
-  return readU64FixedArray(bc, readUintSafe32(bc));
+    return readU64FixedArray(bc, readUintSafe32(bc));
 }
 function readU64FixedArrayLe(bc, len) {
-  if (DEV) {
-    assert(isU32(len));
-  }
-  const byteCount = len * 8;
-  return new BigUint64Array(readFixedData(bc, byteCount));
+    if (DEV) {
+        assert(isU32(len));
+    }
+    const byteCount = len * 8;
+    return new BigUint64Array(readFixedData(bc, byteCount));
 }
 function readU64FixedArrayBe(bc, len) {
-  if (DEV) {
-    assert(isU32(len));
-  }
-  check(bc, len * 8);
-  const result = new BigUint64Array(len);
-  for (let i = 0; i < len; i++) {
-    result[i] = readU64(bc);
-  }
-  return result;
+    if (DEV) {
+        assert(isU32(len));
+    }
+    check(bc, len * 8);
+    const result = new BigUint64Array(len);
+    for (let i = 0; i < len; i++) {
+        result[i] = readU64(bc);
+    }
+    return result;
 }
 export const writeU64FixedArray = IS_LITTLE_ENDIAN_PLATFORM ? writeU64FixedArrayLe : writeU64FixedArrayBe;
 export function writeU64Array(bc, x) {
-  writeUintSafe32(bc, x.length);
-  if (x.length > 0) {
-    writeU64FixedArray(bc, x);
-  }
+    writeUintSafe32(bc, x.length);
+    if (x.length > 0) {
+        writeU64FixedArray(bc, x);
+    }
 }
 function writeU64FixedArrayLe(bc, x) {
-  writeU8FixedArray(bc, new Uint8Array(x.buffer, x.byteOffset, x.byteLength));
+    writeU8FixedArray(bc, new Uint8Array(x.buffer, x.byteOffset, x.byteLength));
 }
 function writeU64FixedArrayBe(bc, x) {
-  reserve(bc, x.length * 8);
-  for (let i = 0; i < x.length; i++) {
-    writeU64(bc, x[i]);
-  }
+    reserve(bc, x.length * 8);
+    for (let i = 0; i < x.length; i++) {
+        writeU64(bc, x[i]);
+    }
 }

package/dist/codec/u8-array.d.ts

@@ -1,4 +1,4 @@
-import { type ByteCursor } from "../core/byte-cursor.js";
+import { type ByteCursor } from "../core/byte-cursor.ts";
 export declare function readU8Array(bc: ByteCursor): Uint8Array<ArrayBuffer>;
 export declare function writeU8Array(bc: ByteCursor, x: Uint8Array): void;
 export declare function readU8FixedArray(bc: ByteCursor, len: number): Uint8Array<ArrayBuffer>;

package/dist/codec/u8-array.js

@@ -1,32 +1,38 @@
-"use strict";
+//! Copyright (c) 2022 Victorien Elvinger
+//! Licensed under the MIT License (https://mit-license.org/)
 import { check, reserve } from "../core/byte-cursor.js";
 import { assert, DEV } from "../util/assert.js";
 import { isU32 } from "../util/validator.js";
-import { readUintSafe32, writeUintSafe32 } from "./primitive.js";
+import { readUintSafe32, writeUintSafe32 } from "./uint.js";
 export function readU8Array(bc) {
-  return readU8FixedArray(bc, readUintSafe32(bc));
+    return readU8FixedArray(bc, readUintSafe32(bc));
 }
 export function writeU8Array(bc, x) {
-  writeUintSafe32(bc, x.length);
-  writeU8FixedArray(bc, x);
+    writeUintSafe32(bc, x.length);
+    writeU8FixedArray(bc, x);
 }
 export function readU8FixedArray(bc, len) {
-  return readUnsafeU8FixedArray(bc, len).slice();
+    return readUnsafeU8FixedArray(bc, len).slice();
 }
 export function writeU8FixedArray(bc, x) {
-  const len = x.length;
-  if (len > 0) {
-    reserve(bc, len);
-    bc.bytes.set(x, bc.offset);
-    bc.offset += len;
-  }
+    const len = x.length;
+    if (len > 0) {
+        reserve(bc, len);
+        bc.bytes.set(x, bc.offset);
+        bc.offset += len;
+    }
 }
+/**
+ * Advance `bc` by `len` bytes and return a view of the read bytes.
+ *
+ * WARNING: The returned array should not be modified.
+ */
 export function readUnsafeU8FixedArray(bc, len) {
-  if (DEV) {
-    assert(isU32(len));
-  }
-  check(bc, len);
-  const offset = bc.offset;
-  bc.offset += len;
-  return bc.bytes.subarray(offset, offset + len);
+    if (DEV) {
+        assert(isU32(len));
+    }
+    check(bc, len);
+    const offset = bc.offset;
+    bc.offset += len;
+    return bc.bytes.subarray(offset, offset + len);
 }

package/dist/codec/u8-clamped-array.d.ts

@@ -1,4 +1,4 @@
-import type { ByteCursor } from "../core/byte-cursor.js";
+import type { ByteCursor } from "../core/byte-cursor.ts";
 export declare function readU8ClampedArray(bc: ByteCursor): Uint8ClampedArray<ArrayBuffer>;
 export declare function writeU8ClampedArray(bc: ByteCursor, x: Uint8ClampedArray): void;
 export declare function readU8ClampedFixedArray(bc: ByteCursor, len: number): Uint8ClampedArray<ArrayBuffer>;

package/dist/codec/u8-clamped-array.js

@@ -1,22 +1,23 @@
-"use strict";
+//! Copyright (c) 2022 Victorien Elvinger
+//! Licensed under the MIT License (https://mit-license.org/)
 import { assert, DEV } from "../util/assert.js";
 import { isU32 } from "../util/validator.js";
 import { readFixedData } from "./data.js";
-import { readUintSafe32, writeUintSafe32 } from "./primitive.js";
 import { writeU8FixedArray } from "./u8-array.js";
+import { readUintSafe32, writeUintSafe32 } from "./uint.js";
 export function readU8ClampedArray(bc) {
-  return readU8ClampedFixedArray(bc, readUintSafe32(bc));
+    return readU8ClampedFixedArray(bc, readUintSafe32(bc));
 }
 export function writeU8ClampedArray(bc, x) {
-  writeUintSafe32(bc, x.length);
-  writeU8ClampedFixedArray(bc, x);
+    writeUintSafe32(bc, x.length);
+    writeU8ClampedFixedArray(bc, x);
 }
 export function readU8ClampedFixedArray(bc, len) {
-  if (DEV) {
-    assert(isU32(len));
-  }
-  return new Uint8ClampedArray(readFixedData(bc, len));
+    if (DEV) {
+        assert(isU32(len));
+    }
+    return new Uint8ClampedArray(readFixedData(bc, len));
 }
 export function writeU8ClampedFixedArray(bc, x) {
-  writeU8FixedArray(bc, new Uint8Array(x.buffer, x.byteOffset, x.byteLength));
+    writeU8FixedArray(bc, new Uint8Array(x.buffer, x.byteOffset, x.byteLength));
 }

package/dist/codec/uint.d.ts

@@ -0,0 +1,8 @@
+import type { ByteCursor } from "../core/byte-cursor.ts";
+export declare function readUint(bc: ByteCursor): bigint;
+export declare function writeUint(bc: ByteCursor, x: bigint): void;
+export declare function writeUintTruncated(bc: ByteCursor, x: bigint): void;
+export declare function readUintSafe32(bc: ByteCursor): number;
+export declare function writeUintSafe32(bc: ByteCursor, x: number): void;
+export declare function readUintSafe(bc: ByteCursor): number;
+export declare function writeUintSafe(bc: ByteCursor, x: number): void;

package/dist/codec/uint.js

@@ -0,0 +1,138 @@
+import { BareError } from "../core/bare-error.js";
+import { assert, DEV } from "../util/assert.js";
+import { INT_SAFE_MAX_BYTE_COUNT, NON_CANONICAL_REPRESENTATION, TOO_LARGE_NUMBER, UINT_MAX_BYTE_COUNT, UINT_SAFE32_MAX_BYTE_COUNT, } from "../util/constants.js";
+import { isU32, isU64Safe } from "../util/validator.js";
+import { readU8, writeU8 } from "./fixed-primitive.js";
+export function readUint(bc) {
+    let low = readU8(bc);
+    if (low >= 0x80) {
+        low &= 0x7f;
+        let shiftMul = 0x80;
+        let byteCount = 1;
+        let byte;
+        do {
+            byte = readU8(bc);
+            low += (byte & 0x7f) * shiftMul;
+            shiftMul *= /* 2**7 */ 0x80;
+            byteCount++;
+        } while (byte >= 0x80 && byteCount < 7);
+        let height = 0;
+        shiftMul = 1;
+        while (byte >= 0x80 && byteCount < UINT_MAX_BYTE_COUNT) {
+            byte = readU8(bc);
+            height += (byte & 0x7f) * shiftMul;
+            shiftMul *= /* 2**7 */ 0x80;
+            byteCount++;
+        }
+        if (byte === 0 || (byteCount === UINT_MAX_BYTE_COUNT && byte > 1)) {
+            bc.offset -= byteCount;
+            throw new BareError(bc.offset, NON_CANONICAL_REPRESENTATION);
+        }
+        return BigInt(low) + (BigInt(height) << BigInt(7 * 7));
+    }
+    return BigInt(low);
+}
+export function writeUint(bc, x) {
+    // truncate to mimic DataView#setBigUint64
+    // this is useful when assertions are skipped
+    const truncated = BigInt.asUintN(64, x);
+    if (DEV) {
+        assert(truncated === x, TOO_LARGE_NUMBER);
+    }
+    writeUintTruncated(bc, truncated);
+}
+export function writeUintTruncated(bc, x) {
+    // For better performances, we decompose `x` into two safe uint.
+    let tmp = Number(BigInt.asUintN(7 * 7, x));
+    let rest = Number(x >> BigInt(7 * 7));
+    let byteCount = 0;
+    while (tmp >= 0x80 || rest > 0) {
+        writeU8(bc, 0x80 | (tmp & 0x7f));
+        tmp = Math.floor(tmp / /* 2**7 */ 0x80);
+        byteCount++;
+        if (byteCount === 7) {
+            tmp = rest;
+            rest = 0;
+        }
+    }
+    writeU8(bc, tmp);
+}
+export function readUintSafe32(bc) {
+    let result = readU8(bc);
+    if (result >= 0x80) {
+        result &= 0x7f;
+        let shift = 7;
+        let byteCount = 1;
+        let byte;
+        do {
+            byte = readU8(bc);
+            result += ((byte & 0x7f) << shift) >>> 0;
+            shift += 7;
+            byteCount++;
+        } while (byte >= 0x80 && byteCount < UINT_SAFE32_MAX_BYTE_COUNT);
+        if (byte === 0) {
+            bc.offset -= byteCount - 1;
+            throw new BareError(bc.offset - byteCount + 1, NON_CANONICAL_REPRESENTATION);
+        }
+        if (byteCount === UINT_SAFE32_MAX_BYTE_COUNT && byte > 0xf) {
+            bc.offset -= byteCount - 1;
+            throw new BareError(bc.offset, TOO_LARGE_NUMBER);
+        }
+    }
+    return result;
+}
+export function writeUintSafe32(bc, x) {
+    if (DEV) {
+        assert(isU32(x), TOO_LARGE_NUMBER);
+    }
+    // truncate to mimic other int encoders
+    // this is useful when assertions are skipped
+    let zigZag = x >>> 0;
+    while (zigZag >= 0x80) {
+        writeU8(bc, 0x80 | (x & 0x7f));
+        zigZag >>>= 7;
+    }
+    writeU8(bc, zigZag);
+}
+export function readUintSafe(bc) {
+    let result = readU8(bc);
+    if (result >= 0x80) {
+        result &= 0x7f;
+        let shiftMul = /* 2**7 */ 0x80;
+        let byteCount = 1;
+        let byte;
+        do {
+            byte = readU8(bc);
+            result += (byte & 0x7f) * shiftMul;
+            shiftMul *= /* 2**7 */ 0x80;
+            byteCount++;
+        } while (byte >= 0x80 && byteCount < INT_SAFE_MAX_BYTE_COUNT);
+        if (byte === 0) {
+            bc.offset -= byteCount - 1;
+            throw new BareError(bc.offset - byteCount + 1, NON_CANONICAL_REPRESENTATION);
+        }
+        if (byteCount === INT_SAFE_MAX_BYTE_COUNT && byte > 0xf) {
+            bc.offset -= byteCount - 1;
+            throw new BareError(bc.offset, TOO_LARGE_NUMBER);
+        }
+    }
+    return result;
+}
+export function writeUintSafe(bc, x) {
+    if (DEV) {
+        assert(isU64Safe(x), TOO_LARGE_NUMBER);
+    }
+    let byteCount = 1;
+    let zigZag = x;
+    while (zigZag >= 0x80 && byteCount < INT_SAFE_MAX_BYTE_COUNT) {
+        writeU8(bc, 0x80 | (zigZag & 0x7f));
+        zigZag = Math.floor(zigZag / /* 2**7 */ 0x80);
+        byteCount++;
+    }
+    if (byteCount === INT_SAFE_MAX_BYTE_COUNT) {
+        // truncate to mimic other int encoders
+        // this is useful when assertions are skipped
+        zigZag &= 0x0f;
+    }
+    writeU8(bc, zigZag);
+}

package/dist/core/bare-error.js

@@ -1,10 +1,14 @@
-"use strict";
+//! Copyright (c) 2022 Victorien Elvinger
+//! Licensed under the MIT License (https://mit-license.org/)
+/**
+ * @sealed
+ */
 export class BareError extends Error {
-  constructor(offset, issue, opts) {
-    super(`(byte:${offset}) ${issue}`);
-    this.name = "BareError";
-    this.issue = issue;
-    this.offset = offset;
-    this.cause = opts?.cause;
-  }
+    constructor(offset, issue, opts) {
+        super(`(byte:${offset}) ${issue}`);
+        this.name = "BareError";
+        this.issue = issue;
+        this.offset = offset;
+        this.cause = opts?.cause;
+    }
 }

package/dist/core/byte-cursor.d.ts

@@ -1,4 +1,4 @@
-import type { Config } from "./config.js";
+import type { Config } from "./config.ts";
 /**
  * @invariant `bytes.buffer === view.buffer`
  * @invariant `bytes.byteOffset === view.byteOffset`

package/dist/core/byte-cursor.js

@@ -1,46 +1,118 @@
-"use strict";
+//! Copyright (c) 2022 Victorien Elvinger
+//! Licensed under the MIT License (https://mit-license.org/)
 import { assert, DEV } from "../util/assert.js";
 import { TOO_LARGE_BUFFER } from "../util/constants.js";
 import { isU32 } from "../util/validator.js";
 import { BareError } from "./bare-error.js";
+/**
+ * @invariant `bytes.buffer === view.buffer`
+ * @invariant `bytes.byteOffset === view.byteOffset`
+ * @invariant `bytes.byteLength === view.byteLength`
+ * @invariant `0 <= offset <= bytes.byteLength`
+ * @invariant `bytes.byteLength <= config.maxBufferLength`
+ *
+ * ```txt
+ * |         {bytes,view}.buffer                      |
+ *        |          bytes                    |
+ *        |          view                     |
+ *        |<------ offset ------>|
+ *        |<----------- config.maxBufferLength ------------>|
+ * ```
+ *
+ * @sealed
+ */
 export class ByteCursor {
-  /**
-   * @throws {BareError} Buffer exceeds `config.maxBufferLength`
-   */
-  constructor(bytes, config) {
     /**
-     * Read and write Offset in {@link view} and {@link bytes}
+     * @throws {BareError} Buffer exceeds `config.maxBufferLength`
      */
-    this.offset = 0;
-    if (bytes.length > config.maxBufferLength) {
-      throw new BareError(0, TOO_LARGE_BUFFER);
-    }
-    this.bytes = bytes;
-    this.config = config;
-    this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.length);
-  }
+    constructor(bytes, config) {
+        /**
+         * Read and write Offset in {@link view} and {@link bytes}
+         */
+        this.offset = 0;
+        if (bytes.length > config.maxBufferLength) {
+            throw new BareError(0, TOO_LARGE_BUFFER);
+        }
+        this.bytes = bytes;
+        this.config = config;
+        this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.length);
+    }
 }
+/**
+ * Check that `min` number of bytes are available.
+ *
+ * @throws {BareError} bytes are missing.
+ */
 export function check(bc, min) {
-  if (DEV) {
-    assert(isU32(min));
-  }
-  if (bc.offset + min > bc.bytes.length) {
-    throw new BareError(bc.offset, "missing bytes");
-  }
+    // We try to keep this function as small as possible to allow inling.
+    if (DEV) {
+        assert(isU32(min));
+    }
+    if (bc.offset + min > bc.bytes.length) {
+        throw new BareError(bc.offset, "missing bytes");
+    }
 }
+/**
+ * Reserve `min` number of bytes.
+ *
+ * @throws {BareError} Buffer exceeds `config.maxBufferLength`.
+ */
 export function reserve(bc, min) {
-  if (DEV) {
-    assert(isU32(min));
-  }
-  const minLen = bc.offset + min | 0;
-  if (minLen > bc.bytes.length) {
+    // We try to keep this function as small as possible to allow inling.
+    if (DEV) {
+        assert(isU32(min));
+    }
+    const minLen = (bc.offset + min) | 0;
+    if (minLen > bc.bytes.length) {
+        grow(bc, minLen);
+    }
+}
+/**
+ * Grow the underlying buffer of `bc` such that its length is
+ * greater or equal to `minLen`.
+ *
+ * @throws {BareError} Buffer exceeds `config.maxBufferLength`.
+ */
+function grow(bc, minLen) {
     if (minLen > bc.config.maxBufferLength) {
-      throw new BareError(0, TOO_LARGE_BUFFER);
+        throw new BareError(0, TOO_LARGE_BUFFER);
+    }
+    //
+    // |     bytes,view}.buffer         |
+    //     |        bytes        |
+    //     |        view         |
+    //     |<-- offset -->|<-- min -->|
+    //     |<-------- minLen -------->|
+    //     |         new view                         |
+    //     |         new bytes                        |
+    //     |         new {bytes,view}.buffer          |
+    //     |<------------- config.maxBufferLength -------------->|
+    //
+    const buffer = bc.bytes.buffer;
+    let newBytes;
+    if (isEs2024ArrayBufferLike(buffer) &&
+        // Make sure that the view covers the end of the buffer.
+        // If it is not the case, this indicates that the user don't want
+        // to override the trailing bytes.
+        bc.bytes.byteOffset + bc.bytes.byteLength === buffer.byteLength &&
+        bc.bytes.byteLength + minLen <= buffer.maxByteLength) {
+        const newLen = Math.min(minLen << 1, bc.config.maxBufferLength, buffer.maxByteLength);
+        if (buffer instanceof ArrayBuffer) {
+            buffer.resize(newLen);
+        }
+        else {
+            buffer.grow(newLen);
+        }
+        newBytes = new Uint8Array(buffer, bc.bytes.byteOffset, newLen);
+    }
+    else {
+        const newLen = Math.min(minLen << 1, bc.config.maxBufferLength);
+        newBytes = new Uint8Array(newLen);
+        newBytes.set(bc.bytes);
     }
-    const newLen = Math.min(minLen << 1, bc.config.maxBufferLength);
-    const newBytes = new Uint8Array(newLen);
-    newBytes.set(bc.bytes);
     bc.bytes = newBytes;
     bc.view = new DataView(newBytes.buffer);
-  }
+}
+function isEs2024ArrayBufferLike(buffer) {
+    return "maxByteLength" in buffer;
 }

package/dist/core/config.js

@@ -1,22 +1,17 @@
-"use strict";
+//! Copyright (c) 2022 Victorien Elvinger
+//! Licensed under the MIT License (https://mit-license.org/)
 import { assert, DEV } from "../util/assert.js";
 import { TOO_LARGE_NUMBER } from "../util/constants.js";
 import { isU32 } from "../util/validator.js";
-export function Config({
-  initialBufferLength = 1024,
-  maxBufferLength = 1024 * 1024 * 32
-}) {
-  if (DEV) {
-    assert(isU32(initialBufferLength), TOO_LARGE_NUMBER);
-    assert(isU32(maxBufferLength), TOO_LARGE_NUMBER);
-    assert(
-      initialBufferLength <= maxBufferLength,
-      "initialBufferLength must be lower than or equal to maxBufferLength"
-    );
-  }
-  return {
-    initialBufferLength,
-    maxBufferLength
-  };
+export function Config({ initialBufferLength = 1024, maxBufferLength = 1024 * 1024 * 32 /* 32 MiB */, }) {
+    if (DEV) {
+        assert(isU32(initialBufferLength), TOO_LARGE_NUMBER);
+        assert(isU32(maxBufferLength), TOO_LARGE_NUMBER);
+        assert(initialBufferLength <= maxBufferLength, "initialBufferLength must be lower than or equal to maxBufferLength");
+    }
+    return {
+        initialBufferLength,
+        maxBufferLength,
+    };
 }
 export const DEFAULT_CONFIG = /* @__PURE__ */ Config({});