@sofa-buffers/corelib 0.8.0 → 0.10.0

package/dist/index.js

@@ -94,8 +94,6 @@ var DecodeStatus = {
 var SofabErrorCode = {
   /** A caller argument was invalid (e.g. id out of range, empty array). */
   Argument: "ARGUMENT",
-  /** The API was used incorrectly (e.g. unbalanced sequence end). */
-  Usage: "USAGE",
   /** The output buffer is full and no flush sink was provided. */
   BufferFull: "BUFFER_FULL",
   /** The input being decoded is malformed regardless of what follows (`INVALID`). */
@@ -130,9 +128,6 @@ var SofabError = class _SofabError extends Error {
 function argumentError(message) {
   return new SofabError(SofabErrorCode.Argument, message);
 }
-function usageError(message) {
-  return new SofabError(SofabErrorCode.Usage, message);
-}
 function bufferFullError(message) {
   return new SofabError(SofabErrorCode.BufferFull, message);
 }
@@ -446,6 +441,26 @@ var SIGNED_FAST_MAX2 = 4503599627370496;
 var OStream = class {
   constructor(buffer, offset = 0, flush) {
     this.depth = 0;
+    /**
+     * Ids of the innermost open sequences whose header has not been written yet
+     * (MESSAGE_SPEC §2 lazy framing, {@link OStream.writeSequenceBeginLazy}).
+     * Always a contiguous suffix of the open sequences: writing any field commits
+     * the whole run at once, so {@link OStream.writeSequenceEnd} can drop the
+     * innermost one by dropping the last entry. Held-back ids are encoder state,
+     * never buffer content, so a flush can never split a run.
+     *
+     * Storage plus an explicit count rather than `push`/`pop`, so the slots are
+     * reused across messages (no allocation on a pooled encoder) and so
+     * {@link OStream.commitPending} can zero the count *before* it writes.
+     *
+     * The array grows on demand and is bounded only by `MAX_DEPTH` — there is no
+     * fixed hold-back window and hence no eager-framing fallback, which is what
+     * CORELIB_PLAN §6 ("How deep the hold-back reaches") demands of an
+     * implementation that can allocate: canonical output at *every* depth.
+     */
+    this.pending = [];
+    /** Valid entries in {@link OStream.pending}. */
+    this.nPending = 0;
     this.kernel = getKernel();
     if (buffer === void 0) {
       this.buf = new Uint8Array(DEFAULT_CAPACITY);
@@ -507,6 +522,7 @@ var OStream = class {
   reset() {
     this.pos = this.start;
     this.depth = 0;
+    this.nPending = 0;
   }
   // --- scalars ------------------------------------------------------------
   /** Write an unsigned integer field. */
@@ -657,6 +673,23 @@ var OStream = class {
       }
     }
   }
+  /**
+   * Write an fp32 array from its raw little-endian element payload. The bytes
+   * are emitted verbatim — no per-element `setFloat32` — so a signaling NaN
+   * survives bit-for-bit (§4.6), which {@link writeFp32Array} cannot guarantee
+   * because it re-quantizes each JS `number`. `payload.length` must be a
+   * multiple of 4; the element count is `payload.length / 4`.
+   */
+  writeFp32ArrayRaw(id, payload) {
+    if ((payload.length & 3) !== 0) {
+      throw argumentError(
+        `fp32 array payload length ${payload.length} is not a multiple of 4`
+      );
+    }
+    this.arrayHead(id, WireType.ArrayFixlen, payload.length >> 2);
+    this.putVarintNum(4 * 8 + FixlenSubtype.Fp32);
+    this.writeRaw(payload);
+  }
   /** Write an array of IEEE-754 64-bit doubles. */
   writeFp64Array(id, values) {
     this.arrayHead(id, WireType.ArrayFixlen, values.length);
@@ -672,20 +705,82 @@ var OStream = class {
     }
   }
   // --- sequences ----------------------------------------------------------
-  /** Open a nested sequence (a fresh id scope). */
-  writeSequenceBegin(id) {
+  /**
+   * Open a nested sequence (a fresh id scope) whose header is **held back**
+   * until the sequence turns out to have content.
+   *
+   * MESSAGE_SPEC §2 omits a sequence-typed field whose value equals its declared
+   * default, and "not one child was written" is exactly that condition —
+   * evaluated per child field, recursively, for free, because the message layer
+   * already omits every child equal to its default. A sequence closed with
+   * nothing in it therefore emits **nothing** instead of a two-byte empty frame,
+   * and an all-default message becomes the empty byte string. No byte image is
+   * ever compared, so in-memory layout never enters the decision.
+   *
+   * This is the only way to open a sequence. How it closes decides whether a
+   * contentless one survives: {@link OStream.writeSequenceEnd} drops it,
+   * {@link OStream.writeSequenceEndKeep} forces the frame out.
+   */
+  writeSequenceBeginLazy(id) {
     if (this.depth >= MAX_DEPTH) {
-      throw usageError(`nesting exceeds MAX_DEPTH (${MAX_DEPTH})`);
+      throw argumentError(`nesting exceeds MAX_DEPTH (${MAX_DEPTH})`);
     }
-    this.header(id, WireType.SequenceStart);
+    if (id < 0 || id > ID_MAX || !Number.isInteger(id)) {
+      throw argumentError(`field id ${id} out of range 0..${ID_MAX}`);
+    }
+    this.pending[this.nPending++] = id;
     this.depth++;
   }
-  /** Close the current sequence. */
+  /**
+   * Close the current sequence, letting it **vanish** if it received no content.
+   *
+   * Use it wherever absence encodes the same value as an empty frame: a
+   * `struct`/`union` field, and an array field whose declared `default` is the
+   * empty collection (MESSAGE_SPEC §2). Where the frame must be visible, close
+   * with {@link OStream.writeSequenceEndKeep} instead.
+   *
+   * An end with no matching begin is not rejected: the encoder writes what it is
+   * told, and the resulting bytes are then malformed, which is the decoder's
+   * verdict to make. No other port refuses it. The depth counter stops at zero
+   * so the MAX_DEPTH check on begin cannot be fooled by an underflow.
+   */
   writeSequenceEnd() {
-    if (this.depth <= 0) throw usageError("sequence end without matching begin");
+    if (this.nPending !== 0) {
+      this.nPending--;
+      if (this.depth > 0) this.depth--;
+      return;
+    }
     this.ensure(1);
     this.buf[this.pos++] = WireType.SequenceEnd;
-    this.depth--;
+    if (this.depth > 0) this.depth--;
+  }
+  /**
+   * Close the current sequence, **keeping** its frame even when it received no
+   * content.
+   *
+   * Behaves like a write: it first emits any held-back headers — this frame's
+   * and every enclosing one's — and then the end marker, so an empty sequence
+   * reaches the wire as `begin` + `end`.
+   *
+   * Required wherever the frame carries information beyond its contents:
+   * - a **wrapper-array element** (`struct`/`union`/nested row): element
+   *   presence is what carries a dynamic array's length — *highest present id +
+   *   1* (MESSAGE_SPEC §5.1) — so dropping an all-default element would change
+   *   the decoded length, not just the bytes;
+   * - an array field already known to **differ from a non-empty declared
+   *   `default`**: absence would reconstruct that default, so the empty frame is
+   *   the only encoding of "explicitly empty" (§2, §3).
+   *
+   * The two failure directions are not symmetric, which is why this is the safe
+   * choice when in doubt: using it where {@link OStream.writeSequenceEnd} would
+   * do costs one non-canonical empty frame that a decoder normalizes away, while
+   * the reverse silently changes an array's length.
+   */
+  writeSequenceEndKeep() {
+    if (this.nPending !== 0) this.commitPending();
+    this.ensure(1);
+    this.buf[this.pos++] = WireType.SequenceEnd;
+    if (this.depth > 0) this.depth--;
   }
   // --- internals ----------------------------------------------------------
   /** Ensure exactly `value`'s varint size, then write it (bigint path). */
@@ -698,12 +793,44 @@ var OStream = class {
     this.ensure(varintSizeNum(value));
     this.pos = encodeVarintNum(value, this.buf, this.pos);
   }
+  /**
+   * Write a field header, the `(id << 3) | wireType` tag, as a varint.
+   *
+   * This is the single choke point every field write passes through — the
+   * scalar, fixlen, float, string, blob and both array writers all reach the
+   * wire through `header` / `fixlenHead` / `arrayHead`, and `fixlenHead` and
+   * `arrayHead` are themselves nothing but `header` plus a follow-up varint. So
+   * this is also where a held-back sequence run is committed: the field about to
+   * be written is content, which means every enclosing sequence is non-default
+   * and must be framed after all (MESSAGE_SPEC §2).
+   *
+   * The only writers that do *not* pass through here are the two sequence
+   * closers, which must not commit ({@link OStream.writeSequenceEnd}) or commit
+   * explicitly ({@link OStream.writeSequenceEndKeep}), and
+   * {@link OStream.writeSequenceBeginLazy}, which writes no byte at all.
+   */
   header(id, type) {
     if (id < 0 || id > ID_MAX || !Number.isInteger(id)) {
       throw argumentError(`field id ${id} out of range 0..${ID_MAX}`);
     }
+    if (this.nPending !== 0) this.commitPending();
     this.putVarintNum(id * 8 + type);
   }
+  /**
+   * Write out the held-back sequence headers, **outermost first**, and clear the
+   * run. Runs at most once per non-default sequence, never per field — the cost
+   * on the hot path is the single `nPending` test in {@link header}.
+   *
+   * The count is zeroed before the first byte goes out, so a write re-entered
+   * from a flush sink cannot emit the same run twice.
+   */
+  commitPending() {
+    const n = this.nPending;
+    this.nPending = 0;
+    for (let i = 0; i < n; i++) {
+      this.putVarintNum(this.pending[i] * 8 + WireType.SequenceStart);
+    }
+  }
   fixlenHead(id, length, subtype) {
     this.header(id, WireType.Fixlen);
     this.putVarintNum(length * 8 + subtype);
@@ -823,9 +950,14 @@ var FastDecoder = class {
           if (sub === FixlenSubtype.Fp32 || sub === FixlenSubtype.Fp64) {
             const want = sub === FixlenSubtype.Fp32 ? 4 : 8;
             if (len !== want) throw invalidMsgError("fixlen float length mismatch");
-            const value = sub === FixlenSubtype.Fp32 ? this.readFp32() : this.readFp64();
-            if (sub === FixlenSubtype.Fp32) top.fp32?.(id, value);
-            else top.fp64?.(id, value);
+            if (sub === FixlenSubtype.Fp32) {
+              const p = this.p;
+              const value = this.readFp32();
+              top.fp32?.(id, value, top.fp32Raw ? this.buf.subarray(p, p + 4) : void 0);
+            } else {
+              const value = this.readFp64();
+              top.fp64?.(id, value);
+            }
           } else {
             const chunk = this.take(len);
             if (sub === FixlenSubtype.String) top.string?.(id, len, 0, chunk);
@@ -864,9 +996,11 @@ var FastDecoder = class {
           else throw invalidMsgError("invalid fixlen array element type");
           top.arrayBegin?.(id, kind, count);
           if (kind === ArrayKind.Fp32) {
+            const wantRaw = top.fp32Raw === true;
             for (let i = 0; i < count; i++) {
+              const p = this.p;
               const value = this.readFp32();
-              top.arrayFp32?.(id, i, value);
+              top.arrayFp32?.(id, i, value, wantRaw ? this.buf.subarray(p, p + 4) : void 0);
             }
           } else {
             for (let i = 0; i < count; i++) {
@@ -1127,8 +1261,10 @@ var DecoderState = class {
           i = this.fpStep(input, i);
           if (this.have < this.need) return;
           const value = this.fixSub === FixlenSubtype.Fp32 ? unpackFp32(this.scratch, 0) : unpackFp64(this.scratch, 0);
-          if (this.fixSub === FixlenSubtype.Fp32) this.top().fp32?.(this.id, value);
-          else this.top().fp64?.(this.id, value);
+          if (this.fixSub === FixlenSubtype.Fp32) {
+            const top = this.top();
+            top.fp32?.(this.id, value, top.fp32Raw ? this.scratch.subarray(0, 4) : void 0);
+          } else this.top().fp64?.(this.id, value);
           this.state = 0 /* Header */;
           break;
         }
@@ -1210,8 +1346,10 @@ var DecoderState = class {
           i = this.fpStep(input, i);
           if (this.have < this.need) return;
           const value = this.arrKind === ArrayKind.Fp32 ? unpackFp32(this.scratch, 0) : unpackFp64(this.scratch, 0);
-          if (this.arrKind === ArrayKind.Fp32) this.top().arrayFp32?.(this.id, this.arrIndex, value);
-          else this.top().arrayFp64?.(this.id, this.arrIndex, value);
+          if (this.arrKind === ArrayKind.Fp32) {
+            const top = this.top();
+            top.arrayFp32?.(this.id, this.arrIndex, value, top.fp32Raw ? this.scratch.subarray(0, 4) : void 0);
+          } else this.top().arrayFp64?.(this.id, this.arrIndex, value);
           this.have = 0;
           this.advanceArray();
           break;
@@ -1506,7 +1644,12 @@ var Cursor = class {
     }
     const id = this.upper();
     if (id > ID_MAX) throw invalidMsgError(`field id ${id} out of range`);
-    if (wire === WireType.SequenceStart) this.depth++;
+    if (wire === WireType.SequenceStart) {
+      if (this.depth >= MAX_DEPTH) {
+        throw invalidMsgError(`nesting exceeds MAX_DEPTH (${MAX_DEPTH})`);
+      }
+      this.depth++;
+    }
     this.id = id;
     this.wire = wire;
     this.fixSub = this.peekFixSub(wire);
@@ -1527,14 +1670,40 @@ var Cursor = class {
     this.fixlenHeader(FixlenSubtype.Fp32, 4);
     return this.rawFp32();
   }
+  /**
+   * Read a 32-bit float scalar as its raw 4 wire bytes (little-endian), zero-copy
+   * — the bit-preserving companion to {@link readFp32}.
+   *
+   * {@link readFp32} returns a JS `number` (a 64-bit double), and widening an
+   * fp32 *signaling* NaN into a double quiets it (0x7F800001 → 0x7FC00001), so a
+   * value consumer can never round-trip one bit-for-bit (§4.6). Generated
+   * bit-exact decode reads the bytes here instead and re-emits them verbatim with
+   * {@link OStream.writeFixlen} (subtype fp32) — mirroring the visitor `raw`
+   * channel on the push paths (fast.ts / state.ts), which the pull path was
+   * missing (corelib-ts#66).
+   *
+   * The header (subtype fp32, length 4) is validated exactly as in
+   * {@link readFp32}; the returned view aliases the source buffer, valid only
+   * until it is reused, like {@link readBlob}.
+   */
+  readFp32Raw() {
+    this.fixlenHeader(FixlenSubtype.Fp32, 4);
+    return this.take(4);
+  }
   /** Read a 64-bit float scalar (wire {@link WireType.Fixlen}, subtype fp64). */
   readFp64() {
     this.fixlenHeader(FixlenSubtype.Fp64, 8);
     return this.rawFp64();
   }
-  /** Read a UTF-8 string scalar (wire {@link WireType.Fixlen}, subtype string). */
-  readString() {
-    const len = this.fixlenLen(FixlenSubtype.String);
+  /**
+   * Read a UTF-8 string scalar (wire {@link WireType.Fixlen}, subtype string).
+   * Pass the schema `maxlen` (byte length) for a bounded string so an
+   * over-length is rejected as `INVALID` at the header, before the payload is
+   * taken (see {@link fixlenLen}); the wire length is exactly the UTF-8 byte
+   * length, so the check is exact. Omit for an unbounded string.
+   */
+  readString(schemaMaxlen) {
+    const len = this.fixlenLen(FixlenSubtype.String, schemaMaxlen);
     const bytes = this.take(len);
     try {
       return _utf8.decode(bytes);
@@ -1546,13 +1715,18 @@ var Cursor = class {
    * Read a blob scalar (wire {@link WireType.Fixlen}, subtype blob) as a
    * zero-copy {@link Uint8Array} view into the source buffer.
    */
-  readBlob() {
-    const len = this.fixlenLen(FixlenSubtype.Blob);
+  readBlob(schemaMaxlen) {
+    const len = this.fixlenLen(FixlenSubtype.Blob, schemaMaxlen);
     return this.take(len);
   }
-  /** Read an unsigned array (wire {@link WireType.ArrayUnsigned}), number-first per element. */
-  readUnsignedArray() {
-    const count = this.arrayCount();
+  /**
+   * Read an unsigned array (wire {@link WireType.ArrayUnsigned}), number-first
+   * per element. Pass the schema `count` for a bounded array so an over-count is
+   * rejected as `INVALID` at the header (see {@link arrayCount}); omit it for an
+   * unbounded array (today's behavior).
+   */
+  readUnsignedArray(schemaCount) {
+    const count = this.arrayCount(schemaCount);
     const out = new Array(count);
     for (let i = 0; i < count; i++) {
       this.readVarint();
@@ -1561,8 +1735,8 @@ var Cursor = class {
     return out;
   }
   /** Read a signed array (wire {@link WireType.ArraySigned}), zig-zag, number-first per element. */
-  readSignedArray() {
-    const count = this.arrayCount();
+  readSignedArray(schemaCount) {
+    const count = this.arrayCount(schemaCount);
     const out = new Array(count);
     for (let i = 0; i < count; i++) {
       this.readVarint();
@@ -1575,8 +1749,8 @@ var Cursor = class {
    * Each element keeps the raw lo/hi halves; call {@link Long.toBigInt} to
    * materialise only the values the caller actually needs.
    */
-  readUnsignedArrayLong() {
-    const count = this.arrayCount();
+  readUnsignedArrayLong(schemaCount) {
+    const count = this.arrayCount(schemaCount);
     const out = new Array(count);
     for (let i = 0; i < count; i++) {
       this.readVarint();
@@ -1585,8 +1759,8 @@ var Cursor = class {
     return out;
   }
   /** Read a signed 64-bit array (zig-zag) into {@link Long}[] — the `bigint`-free path. */
-  readSignedArrayLong() {
-    const count = this.arrayCount();
+  readSignedArrayLong(schemaCount) {
+    const count = this.arrayCount(schemaCount);
     const out = new Array(count);
     for (let i = 0; i < count; i++) {
       this.readVarint();
@@ -1598,15 +1772,29 @@ var Cursor = class {
     return out;
   }
   /** Read an fp32 array (wire {@link WireType.ArrayFixlen}, element subtype fp32). */
-  readFp32Array() {
-    const count = this.arrayFixlenHeader(FixlenSubtype.Fp32, 4);
+  readFp32Array(schemaCount) {
+    const count = this.arrayFixlenHeader(FixlenSubtype.Fp32, 4, schemaCount);
     const out = new Array(count);
     for (let i = 0; i < count; i++) out[i] = this.rawFp32();
     return out;
   }
+  /**
+   * Read an fp32 array as its raw little-endian element payload (`count * 4`
+   * bytes), zero-copy — the bit-preserving companion to {@link readFp32Array}.
+   * Widening each element to a JS `number` quiets an fp32 *signaling* NaN just as
+   * on the scalar path (§4.6; see {@link readFp32Raw}), so bit-exact decode reads
+   * the whole payload here and re-emits it with {@link OStream.writeFp32ArrayRaw}
+   * (corelib-ts#66). The header (element subtype fp32, size 4) is validated
+   * exactly as in {@link readFp32Array}; the returned view aliases the source
+   * buffer, like {@link readBlob}.
+   */
+  readFp32ArrayRaw(schemaCount) {
+    const count = this.arrayFixlenHeader(FixlenSubtype.Fp32, 4, schemaCount);
+    return this.take(count * 4);
+  }
   /** Read an fp64 array (wire {@link WireType.ArrayFixlen}, element subtype fp64). */
-  readFp64Array() {
-    const count = this.arrayFixlenHeader(FixlenSubtype.Fp64, 8);
+  readFp64Array(schemaCount) {
+    const count = this.arrayFixlenHeader(FixlenSubtype.Fp64, 8, schemaCount);
     const out = new Array(count);
     for (let i = 0; i < count; i++) out[i] = this.rawFp64();
     return out;
@@ -1686,8 +1874,14 @@ var Cursor = class {
       }
       const id = this.upper();
       if (id > ID_MAX) throw invalidMsgError(`field id ${id} out of range`);
-      if (wire === WireType.SequenceStart) depth++;
-      else this.skipValue(wire);
+      if (wire === WireType.SequenceStart) {
+        if (this.depth + depth - 1 >= MAX_DEPTH) {
+          throw invalidMsgError(`nesting exceeds MAX_DEPTH (${MAX_DEPTH})`);
+        }
+        depth++;
+      } else {
+        this.skipValue(wire);
+      }
     }
   }
   // --- field helpers ------------------------------------------------------
@@ -1714,11 +1908,18 @@ var Cursor = class {
     }
     return -1;
   }
-  /** Read and validate an array count word (0..ARRAY_MAX; §4.7/§4.8). */
-  arrayCount() {
+  /**
+   * Read and validate an array count word (0..ARRAY_MAX; §4.7/§4.8). When a
+   * `schemaCount` is given, a count above it is a schema-bound violation and is
+   * rejected as `INVALID` — see the check below.
+   */
+  arrayCount(schemaCount) {
     this.readVarint();
     const count = this.num();
     if (count > ARRAY_MAX) throw invalidMsgError("array count out of range");
+    if (schemaCount !== void 0 && count > schemaCount) {
+      throw invalidMsgError("array count above schema capacity");
+    }
     if (count > this.maxArrayCount) {
       throw limitExceededError(
         `array count ${count} exceeds maxArrayCount ${this.maxArrayCount}`
@@ -1735,13 +1936,20 @@ var Cursor = class {
     if (sub !== wantSub) throw invalidMsgError(`invalid fixlen subtype ${sub}`);
     if (len !== wantLen) throw invalidMsgError("fixlen float length mismatch");
   }
-  /** Read a scalar fixlen sub-header for a string/blob, asserting subtype; returns byte length. */
-  fixlenLen(wantSub) {
+  /**
+   * Read a scalar fixlen sub-header for a string/blob, asserting subtype;
+   * returns the byte length. When a `schemaMaxlen` is given, a length above it
+   * is a schema-bound violation and is rejected as `INVALID` — see below.
+   */
+  fixlenLen(wantSub, schemaMaxlen) {
     this.readVarint();
     const sub = this.lo & 7;
     const len = this.upper();
     if (sub !== wantSub) throw invalidMsgError(`invalid fixlen subtype ${sub}`);
     if (len > FIXLEN_MAX) throw invalidMsgError("fixlen length out of range");
+    if (schemaMaxlen !== void 0 && len > schemaMaxlen) {
+      throw invalidMsgError("fixlen length above schema maxlen");
+    }
     const limit = wantSub === FixlenSubtype.String ? this.maxStringLen : this.maxBlobLen;
     if (len > limit) {
       const what = wantSub === FixlenSubtype.String ? "string" : "blob";
@@ -1752,11 +1960,18 @@ var Cursor = class {
     }
     return len;
   }
-  /** Read an array fixlen element header (count + element type); returns the count. */
-  arrayFixlenHeader(wantSub, wantSize) {
+  /**
+   * Read an array fixlen element header (count + element type); returns the
+   * count. When a `schemaCount` is given, a count above it is a schema-bound
+   * violation and is rejected as `INVALID` — see below.
+   */
+  arrayFixlenHeader(wantSub, wantSize, schemaCount) {
     this.readVarint();
     const count = this.num();
     if (count > ARRAY_MAX) throw invalidMsgError("array count out of range");
+    if (schemaCount !== void 0 && count > schemaCount) {
+      throw invalidMsgError("array count above schema capacity");
+    }
     if (count > this.maxArrayCount) {
       throw limitExceededError(
         `array count ${count} exceeds maxArrayCount ${this.maxArrayCount}`