@sofa-buffers/corelib 0.8.0 → 0.10.0

package/dist/index.global.js

@@ -98,8 +98,6 @@ var SofaBuffers = (function (exports) {
   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`). */
@@ -134,9 +132,6 @@ var SofaBuffers = (function (exports) {
   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);
   }
@@ -450,6 +445,26 @@ var SofaBuffers = (function (exports) {
   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);
@@ -511,6 +526,7 @@ var SofaBuffers = (function (exports) {
     reset() {
       this.pos = this.start;
       this.depth = 0;
+      this.nPending = 0;
     }
     // --- scalars ------------------------------------------------------------
     /** Write an unsigned integer field. */
@@ -661,6 +677,23 @@ var SofaBuffers = (function (exports) {
         }
       }
     }
+    /**
+     * 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);
@@ -676,20 +709,82 @@ var SofaBuffers = (function (exports) {
       }
     }
     // --- 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). */
@@ -702,12 +797,44 @@ var SofaBuffers = (function (exports) {
       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);
@@ -827,9 +954,14 @@ var SofaBuffers = (function (exports) {
             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);
@@ -868,9 +1000,11 @@ var SofaBuffers = (function (exports) {
             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++) {
@@ -1131,8 +1265,10 @@ var SofaBuffers = (function (exports) {
             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;
           }
@@ -1214,8 +1350,10 @@ var SofaBuffers = (function (exports) {
             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;
@@ -1510,7 +1648,12 @@ var SofaBuffers = (function (exports) {
       }
       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);
@@ -1531,14 +1674,40 @@ var SofaBuffers = (function (exports) {
       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);
@@ -1550,13 +1719,18 @@ var SofaBuffers = (function (exports) {
      * 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();
@@ -1565,8 +1739,8 @@ var SofaBuffers = (function (exports) {
       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();
@@ -1579,8 +1753,8 @@ var SofaBuffers = (function (exports) {
      * 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();
@@ -1589,8 +1763,8 @@ var SofaBuffers = (function (exports) {
       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();
@@ -1602,15 +1776,29 @@ var SofaBuffers = (function (exports) {
       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;
@@ -1690,8 +1878,14 @@ var SofaBuffers = (function (exports) {
         }
         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 ------------------------------------------------------
@@ -1718,11 +1912,18 @@ var SofaBuffers = (function (exports) {
       }
       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}`
@@ -1739,13 +1940,20 @@ var SofaBuffers = (function (exports) {
       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";
@@ -1756,11 +1964,18 @@ var SofaBuffers = (function (exports) {
       }
       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}`