json-as 1.4.0 → 1.6.0

package/assembly/deserialize/swar/float.ts

@@ -12,13 +12,14 @@
 //
 // Inspired by Daniel Lemire, "Number parsing at a gigabyte per second" (2021)
 // and the simdjson `fast_float` implementation. The integer-part loop stays
-// scalar — most JSON float payloads have 1-3 digit integer parts, so a parse4
+// scalar - most JSON float payloads have 1-3 digit integer parts, so a parse4
 // stride there pays the wasted-validate cost on every call without saving
 // enough scalar iterations.
 
 import { ptrToStr } from "../../util/ptrToStr";
 import { parse4Digits_PairMul } from "../../util/swar-int";
 import { scientific } from "../../util/scientific";
+import { eiselLemire22 } from "../../util/eisel-lemire";
 
 export const POW10_F64_POS: usize = memory.data<f64>([
   1, 1e1, 1e2, 1e3, 1e4, 1e5, 1e6, 1e7, 1e8, 1e9, 1e10, 1e11, 1e12, 1e13, 1e14,
@@ -34,14 +35,11 @@ const ASCII_DOT: u16 = 46;
 const ASCII_ZERO: u16 = 48;
 const ASCII_E_UP: u16 = 69;
 const ASCII_E_LO: u16 = 101;
-
-// @ts-ignore: inline
-@inline export function loadPow10(exp: u32): f64 {
+export function loadPow10(exp: u32): f64 {
   return load<f64>(POW10_F64_POS + ((<usize>exp) << 3));
 }
 
-// @ts-ignore: inline
-@inline function fallback<T>(srcStart: usize, srcEnd: usize): T {
+function fallback<T>(srcStart: usize, srcEnd: usize): T {
   const s = ptrToStr(srcStart, srcEnd);
   // @ts-ignore
   const type: T = 0;
@@ -50,9 +48,7 @@ const ASCII_E_LO: u16 = 101;
   // @ts-ignore
   return <T>(<f32>f32.parse(s));
 }
-
-// @ts-ignore: inline
-@inline function fallbackField<T extends number>(
+function fallbackField<T extends number>(
   origStart: usize,
   end: usize,
   fieldPtr: usize,
@@ -77,37 +73,37 @@ export function deserializeFloat_SWAR<T>(srcStart: usize, srcEnd: usize): T {
   // Integer part: scalar. Most JSON integers are 1-3 digits, so parse4 would
   // waste a validate per call.
   let mantissa: u64 = 0;
-  let intDigits: i32 = 0;
+  const intStart = p;
   while (p < srcEnd) {
     const d = <u32>load<u16>(p) - ASCII_ZERO;
     if (d > 9) break;
     mantissa = mantissa * 10 + <u64>d;
-    intDigits++;
     p += 2;
   }
+  const intDigits = <i32>((p - intStart) >> 1);
 
   // Fractional part: parse4 stride (8 bytes / 4 digits) → scalar tail.
   // parse8 was tried and benchmarked even/worse; the saved mantissa mul
   // didn't outweigh the extra load and combined-validation latency, and the
   // dependency chain is the same length either way.
-  let fracDigits: i32 = 0;
+  let fracStart = p;
   if (p < srcEnd && load<u16>(p) == ASCII_DOT) {
     p += 2;
+    fracStart = p;
     while (p + 6 < srcEnd) {
       const parsed = parse4Digits_PairMul(load<u64>(p));
       if (parsed == U32.MAX_VALUE) break;
       mantissa = mantissa * 10_000 + <u64>parsed;
-      fracDigits += 4;
       p += 8;
     }
     while (p < srcEnd) {
       const d = <u32>load<u16>(p) - ASCII_ZERO;
       if (d > 9) break;
       mantissa = mantissa * 10 + <u64>d;
-      fracDigits++;
       p += 2;
     }
   }
+  const fracDigits = <i32>((p - fracStart) >> 1);
 
   const mantDigits = intDigits + fracDigits;
   if (mantDigits == 0) return fallback<T>(origStart, srcEnd);
@@ -163,7 +159,10 @@ export function deserializeFloat_SWAR<T>(srcStart: usize, srcEnd: usize): T {
       result /= loadPow10(<u32>-exponent);
     }
   } else if (mantDigits <= 19) {
-    result = scientific(mantissa, exponent);
+    result =
+      exponent >= -22 && exponent <= 22
+        ? eiselLemire22(mantissa, exponent)
+        : scientific(mantissa, exponent);
   } else {
     return fallback<T>(origStart, srcEnd);
   }
@@ -193,33 +192,33 @@ export function deserializeFloatField_SWAR<T extends number>(
   }
 
   let mantissa: u64 = 0;
-  let intDigits: i32 = 0;
+  const intStart = p;
   while (p < srcEnd) {
     const d = <u32>load<u16>(p) - ASCII_ZERO;
     if (d > 9) break;
     mantissa = mantissa * 10 + <u64>d;
-    intDigits++;
     p += 2;
   }
+  const intDigits = <i32>((p - intStart) >> 1);
 
-  let fracDigits: i32 = 0;
+  let fracStart = p;
   if (p < srcEnd && load<u16>(p) == ASCII_DOT) {
     p += 2;
+    fracStart = p;
     while (p + 6 < srcEnd) {
       const parsed = parse4Digits_PairMul(load<u64>(p));
       if (parsed == U32.MAX_VALUE) break;
       mantissa = mantissa * 10_000 + <u64>parsed;
-      fracDigits += 4;
       p += 8;
     }
     while (p < srcEnd) {
       const d = <u32>load<u16>(p) - ASCII_ZERO;
       if (d > 9) break;
       mantissa = mantissa * 10 + <u64>d;
-      fracDigits++;
       p += 2;
     }
   }
+  const fracDigits = <i32>((p - fracStart) >> 1);
 
   const mantDigits = intDigits + fracDigits;
   if (mantDigits == 0) unreachable();
@@ -282,7 +281,10 @@ export function deserializeFloatField_SWAR<T extends number>(
       result /= loadPow10(<u32>-exponent);
     }
   } else if (mantDigits <= 19) {
-    result = scientific(mantissa, exponent);
+    result =
+      exponent >= -22 && exponent <= 22
+        ? eiselLemire22(mantissa, exponent)
+        : scientific(mantissa, exponent);
   } else {
     fallbackField<T>(origStart, p, fieldPtr);
     return p;

package/assembly/deserialize/swar/integer.ts

@@ -40,11 +40,7 @@ const ASCII_ZERO: u16 = 48;
  * @param value  The `u64` accumulator, interpreted as a two's-complement
  *               signed integer for narrower types.
  */
-// @ts-expect-error: @inline is a valid decorator
-@inline function storeSignedToField<T extends number>(
-  dstPtr: usize,
-  value: u64,
-): void {
+function storeSignedToField<T extends number>(dstPtr: usize, value: u64): void {
   if (sizeof<T>() == 1) {
     store<i8>(dstPtr, <i8>value);
   } else if (sizeof<T>() == 2) {
@@ -63,8 +59,7 @@ const ASCII_ZERO: u16 = 48;
  * @param dstPtr Destination pointer (already includes any field offset).
  * @param value  The `u64` accumulator.
  */
-// @ts-expect-error: @inline is a valid decorator
-@inline function storeUnsignedToField<T extends number>(
+function storeUnsignedToField<T extends number>(
   dstPtr: usize,
   value: u64,
 ): void {

package/assembly/deserialize/swar/string.ts

@@ -4,6 +4,8 @@ import { __heap_base } from "memory";
 import { BACK_SLASH, QUOTE } from "../../custom/chars";
 import { DESERIALIZE_ESCAPE_TABLE } from "../../globals/tables";
 import { hex4_to_u16_swar } from "../../util/swar";
+import { markProductionParseError } from "../error";
+import { isValidStringEscape } from "../string-validation";
 
 // Overflow Pattern for Unicode Escapes (READ)
 // \u0001     0 \u00|01__   + 4
@@ -41,11 +43,7 @@ import { hex4_to_u16_swar } from "../../util/swar";
  * @param dst buffer to write to
  * @returns number of bytes written
  */
-// @ts-expect-error: @inline is a valid decorator
-@inline function copyStringFromSource(
-  srcStart: usize,
-  byteLength: usize,
-): string {
+function copyStringFromSource(srcStart: usize, byteLength: usize): string {
   if (byteLength == 0) return changetype<string>("");
   const out = __new(byteLength, idof<string>());
   memory.copy(out, srcStart, byteLength);
@@ -75,7 +73,7 @@ function deserializeEscapedString_SWAR(
   }
 
   let srcStart = escapeStart;
-  const srcEnd8 = srcEnd >= 8 ? srcEnd - 8 : 0;
+  const srcEnd8 = srcEnd - 8;
 
   while (srcStart <= srcEnd8) {
     const block = load<u64>(srcStart);
@@ -111,6 +109,11 @@ function deserializeEscapedString_SWAR(
       const srcIdx = srcStart + laneIdx;
       if ((load<u32>(srcIdx) & 0xffff) !== 0x5c) continue; // false positive
       bs.offset += laneIdx;
+      if (!isValidStringEscape(srcIdx, srcEnd)) {
+        bs.offset = bs.buffer + outStart;
+        markProductionParseError();
+        return changetype<string>(0);
+      }
       const code = load<u16>(srcIdx, 2);
       if (code !== 0x75) {
         store<u16>(bs.offset, load<u16>(DESERIALIZE_ESCAPE_TABLE + code));
@@ -138,6 +141,11 @@ function deserializeEscapedString_SWAR(
       srcStart += 2;
       continue;
     }
+    if (!isValidStringEscape(srcStart, srcEnd)) {
+      bs.offset = bs.buffer + outStart;
+      markProductionParseError();
+      return changetype<string>(0);
+    }
     const code = load<u16>(srcStart, 2);
     if (code !== 0x75) {
       store<u16>(bs.offset, load<u16>(DESERIALIZE_ESCAPE_TABLE + code));
@@ -245,7 +253,7 @@ function writeStringToField(
 // the next unread src pointer.
 //
 // HYBRID strategy (validated against the prior run-copy scanner across escape
-// densities — see __benches__/custom/swar-string-deser-hybrid-h2h: +17–70%):
+// densities - see __benches__/custom/swar-string-deser-hybrid-h2h: +17–70%):
 //   * Escape-bearing block: one optimistic whole-block u64 store copies the
 //     plain prefix for free, then the (scalar-confirmed) escape is decoded.
 //   * Clean block: stream the first one, then if the clean run continues switch
@@ -260,16 +268,25 @@ function deserializeEscapedStringField_SWAR(
 ): usize {
   const prefixLen = <u32>(escapeStart - payloadStart);
   bs.offset = bs.buffer;
-  bs.ensureSize(<u32>(srcEnd - payloadStart) + 8); // +8 slack for u64 overcopy
+  // `srcEnd` may be the end of a containing map/document when a generated
+  // parser is cursor-driven. Reserving that entire remainder for one escaped
+  // field retained multi-megabyte scratch buffers. Grow with the decoded
+  // string instead; escapes only shrink relative to the source.
+  bs.ensureSize(prefixLen + 1024);
   if (prefixLen != 0) {
     memory.copy(bs.buffer, payloadStart, prefixLen);
     bs.offset += prefixLen;
   }
 
   let srcStart = escapeStart;
-  const srcEnd8 = srcEnd >= 8 ? srcEnd - 8 : 0;
+  const srcEnd8 = srcEnd - 8;
+  let scratchEnd = bs.buffer + bs.bufferSize - 8;
 
   while (srcStart <= srcEnd8) {
+    if (bs.offset > scratchEnd) {
+      bs.ensureSize(1024);
+      scratchEnd = bs.buffer + bs.bufferSize - 8;
+    }
     const block = load<u64>(srcStart);
     let mask = backslash_or_quote_mask(block);
     if (mask == 0) {
@@ -289,6 +306,10 @@ function deserializeEscapedStringField_SWAR(
           srcStart += 8;
         }
         const runLen = <u32>(srcStart - runStart);
+        if (bs.offset + runLen > scratchEnd) {
+          bs.ensureSize(runLen + 1024);
+          scratchEnd = bs.buffer + bs.bufferSize - 8;
+        }
         memory.copy(bs.offset, runStart, runLen);
         bs.offset += runLen;
       }
@@ -314,6 +335,11 @@ function deserializeEscapedStringField_SWAR(
         bs.offset = bs.buffer;
         return srcIdx + 2;
       }
+      if (!isValidStringEscape(srcIdx, srcEnd)) {
+        bs.offset = bs.buffer;
+        markProductionParseError();
+        return 0;
+      }
       const code = load<u16>(srcIdx, 2);
       if (code !== 0x75) {
         store<u16>(bs.offset, load<u16>(DESERIALIZE_ESCAPE_TABLE + code));
@@ -334,6 +360,7 @@ function deserializeEscapedStringField_SWAR(
   }
 
   // scalar tail (< 8 bytes remaining)
+  bs.ensureSize(<u32>(srcEnd - srcStart) + 2);
   while (srcStart < srcEnd) {
     const char = load<u16>(srcStart);
     if (char == QUOTE) {
@@ -347,6 +374,11 @@ function deserializeEscapedStringField_SWAR(
       srcStart += 2;
       continue;
     }
+    if (!isValidStringEscape(srcStart, srcEnd)) {
+      bs.offset = bs.buffer;
+      markProductionParseError();
+      return 0;
+    }
     const code = load<u16>(srcStart, 2);
     if (code !== 0x75) {
       store<u16>(bs.offset, load<u16>(DESERIALIZE_ESCAPE_TABLE + code));
@@ -360,122 +392,37 @@ function deserializeEscapedStringField_SWAR(
   }
 
   bs.offset = bs.buffer;
-  abort("Unterminated string literal");
-  return srcStart;
+  markProductionParseError();
+  return 0;
 }
 
-function deserializeEscapedStringContinuation_SWAR_MergedTuned(
-  lastPtr: usize,
+export function deserializeStringField_SWAR<T extends string | null>(
   srcStart: usize,
   srcEnd: usize,
-  dstFieldPtr: usize,
+  dstObj: usize,
+  dstOffset: usize = 0,
 ): usize {
-  const srcEnd8 = srcEnd - 8;
-
-  while (srcStart <= srcEnd8) {
-    const blockStart = srcStart;
-    let mask = backslash_or_quote_mask(load<u64>(srcStart));
-    if (mask === 0) {
-      srcStart += 8;
-      continue;
-    }
-
-    do {
-      const laneIdx = usize(ctz(mask) >> 3);
-      mask &= mask - 1;
-      const srcIdx = srcStart + laneIdx;
-      const char = load<u16>(srcIdx);
-      if (char == QUOTE) {
-        const runLen = <u32>(srcIdx - lastPtr);
-        if (runLen != 0) {
-          memory.copy(bs.offset, lastPtr, runLen);
-          bs.offset += runLen;
-        }
-        writeStringToField(
-          dstFieldPtr,
-          bs.buffer,
-          <u32>(bs.offset - bs.buffer),
-        );
-        bs.offset = bs.buffer;
-        return srcIdx + 2;
-      }
-      if (char != BACK_SLASH) continue;
-
-      const runLen = <u32>(srcIdx - lastPtr);
-      if (runLen != 0) {
-        memory.copy(bs.offset, lastPtr, runLen);
-        bs.offset += runLen;
-      }
-
-      const chunk = load<u32>(srcIdx);
-      const code = <u16>(chunk >> 16);
-      if (code !== 0x75) {
-        store<u16>(bs.offset, load<u16>(DESERIALIZE_ESCAPE_TABLE + code));
-        bs.offset += 2;
-        lastPtr = srcIdx + 4;
-      } else {
-        store<u16>(bs.offset, hex4_to_u16_swar(load<u64>(srcIdx, 4)));
-        bs.offset += 2;
-        lastPtr = srcIdx + 12;
-      }
-      srcStart = lastPtr;
-      break;
-    } while (mask !== 0);
-
-    if (srcStart == blockStart) srcStart += 8;
-  }
-
-  while (srcStart < srcEnd) {
-    const tailChar = load<u16>(srcStart);
-    if (tailChar == QUOTE) {
-      const runLen = <u32>(srcStart - lastPtr);
-      if (runLen != 0) {
-        memory.copy(bs.offset, lastPtr, runLen);
-        bs.offset += runLen;
-      }
-      writeStringToField(dstFieldPtr, bs.buffer, <u32>(bs.offset - bs.buffer));
-      bs.offset = bs.buffer;
-      return srcStart + 2;
-    }
-    if (tailChar != BACK_SLASH) {
-      srcStart += 2;
-      continue;
-    }
-
-    const runLen = <u32>(srcStart - lastPtr);
-    if (runLen != 0) {
-      memory.copy(bs.offset, lastPtr, runLen);
-      bs.offset += runLen;
-    }
-    const tailCode = load<u16>(srcStart, 2);
-    if (tailCode !== 0x75) {
-      store<u16>(bs.offset, load<u16>(DESERIALIZE_ESCAPE_TABLE + tailCode));
-      bs.offset += 2;
-      srcStart += 4;
-    } else {
-      store<u16>(bs.offset, hex4_to_u16_swar(load<u64>(srcStart, 4)));
-      bs.offset += 2;
-      srcStart += 12;
-    }
-    lastPtr = srcStart;
+  if (srcStart + 2 > srcEnd || load<u16>(srcStart) != QUOTE) {
+    markProductionParseError();
+    return 0;
   }
-
-  bs.offset = bs.buffer;
-  return srcStart;
+  return deserializeStringFieldTrusted_SWAR(
+    srcStart + 2,
+    srcEnd,
+    dstObj,
+    dstOffset,
+  );
 }
 
-export function deserializeStringField_SWAR<T extends string | null>(
-  srcStart: usize,
+export function deserializeStringFieldTrusted_SWAR(
+  payloadStart: usize,
   srcEnd: usize,
   dstObj: usize,
   dstOffset: usize = 0,
 ): usize {
   const dstFieldPtr = dstObj + dstOffset;
-  if (srcStart + 2 > srcEnd || load<u16>(srcStart) != QUOTE)
-    abort("Expected leading quote");
-
-  const payloadStart = srcStart + 2;
-  srcStart = payloadStart;
+  let srcStart = payloadStart;
+  let pendingMask: u64 = 0;
 
   // Wide pre-scan: skip 16 bytes per iter while both halves are clean. The
   // common case (plain ASCII payloads, no escape) hits this loop exclusively
@@ -483,16 +430,29 @@ export function deserializeStringField_SWAR<T extends string | null>(
   if (srcEnd >= 16) {
     const srcEnd16 = srcEnd - 16;
     while (srcStart <= srcEnd16) {
-      const m0 = backslash_or_quote_mask(load<u64>(srcStart));
-      const m1 = backslash_or_quote_mask(load<u64>(srcStart, 8));
-      if ((m0 | m1) != 0) break;
+      // Test the first word before loading the second: short values and keys
+      // close (or escape) within the first 8 bytes, so this skips the second
+      // load on the common case while still skipping 16 bytes when both clean.
+      const firstMask = backslash_or_quote_mask(load<u64>(srcStart));
+      if (firstMask != 0) {
+        pendingMask = firstMask;
+        break;
+      }
+      const secondMask = backslash_or_quote_mask(load<u64>(srcStart, 8));
+      if (secondMask != 0) {
+        srcStart += 8;
+        pendingMask = secondMask;
+        break;
+      }
       srcStart += 16;
     }
   }
 
   const srcEnd8 = srcEnd - 8;
   while (srcStart <= srcEnd8) {
-    let mask = backslash_or_quote_mask(load<u64>(srcStart));
+    let mask = pendingMask;
+    if (mask == 0) mask = backslash_or_quote_mask(load<u64>(srcStart));
+    pendingMask = 0;
     if (mask === 0) {
       srcStart += 8;
       continue;
@@ -544,8 +504,8 @@ export function deserializeStringField_SWAR<T extends string | null>(
     srcStart += 2;
   }
 
-  abort("Unterminated string literal");
-  return srcStart;
+  markProductionParseError();
+  return 0;
 }
 
 /**
@@ -555,8 +515,7 @@ export function deserializeStringField_SWAR<T extends string | null>(
  * so callers must confirm the hit scalarly.
  * Each matching lane sets itself to 0x80.
  */
-// @ts-expect-error: @inline is a valid decorator
-@inline function backslash_or_quote_mask(block: u64): u64 {
+function backslash_or_quote_mask(block: u64): u64 {
   const b = block ^ 0x005c_005c_005c_005c;
   const q = block ^ 0x0022_0022_0022_0022;
   return (
@@ -575,8 +534,7 @@ export function deserializeStringField_SWAR<T extends string | null>(
  *
  * Each matching lane sets itself to 0x80.
  */
-// @ts-expect-error: @inline is a valid decorator
-@inline function backslash_mask(block: u64): u64 {
+function backslash_mask(block: u64): u64 {
   const b = block ^ 0x005c_005c_005c_005c;
   const backslash_mask =
     (b - 0x0001_0001_0001_0001) & ~b & 0x0080_0080_0080_0080;
@@ -597,8 +555,7 @@ export function deserializeStringField_SWAR<T extends string | null>(
  * WARNING: The low byte of a code unit *may* be a backslash, thus triggering false positives!
  * This is useful for a hot path where it is possible to detect the false positive scalarly.
  */
-// @ts-expect-error: @inline is a valid decorator
-@inline function backslash_mask_unsafe(block: u64): u64 {
+function backslash_mask_unsafe(block: u64): u64 {
   const b = block ^ 0x005c_005c_005c_005c;
   const backslash_mask =
     (b - 0x0001_0001_0001_0001) & ~b & 0x0080_0080_0080_0080;

package/assembly/deserialize/swar/typedarray.ts

@@ -6,10 +6,10 @@
 //
 //   - **No count pass.** TypedArrays have a fixed length at construction,
 //     so the natural approach is to count first then allocate. We tried
-//     that with a SWAR comma counter — it cut the per-element cost but
+//     that with a SWAR comma counter - it cut the per-element cost but
 //     kept us ~30% below the top-level `f64[]` path because the count
 //     scan still touched the whole input twice. Instead we allocate
-//     worst-case (`(srcEnd - srcStart) >> 2 + 1` elements — each
+//     worst-case (`(srcEnd - srcStart) >> 2 + 1` elements - each
 //     element needs >= "D," = 2 UTF-16 chars = 4 bytes) and `__renew`
 //     the underlying buffer down to the exact byte count after parsing.
 //     The over-allocation peaks at ~2-3× the final size for typical
@@ -46,7 +46,7 @@ import {
  * Worst-case element count: each element occupies >= 1 digit + 1
  * delimiter = 2 UTF-16 chars = 4 bytes. So `(srcEnd - srcStart) >> 2`
  * upper-bounds the count. Allocating to worst-case lets us skip a
- * full count pass over the input — at the cost of an over-allocated
+ * full count pass over the input - at the cost of an over-allocated
  * underlying buffer that we trim via `__renew` once we know the
  * actual element count.
  *
@@ -125,7 +125,7 @@ export function deserializeTypedArray_SWAR<T extends ArrayLike<number>>(
   // directly: `__renew` the buffer to the actual byte length and
   // update the view's `byteLength` and `dataStart`. AS's TypedArray
   // structure has `buffer`, `dataStart` (= buffer), `byteLength`
-  // (capacity in bytes) in that order — same layout as ArrayBufferView.
+  // (capacity in bytes) in that order - same layout as ArrayBufferView.
   const actualCount = i32(<usize>(writePtr - dataStart) / elementSize);
   if (actualCount != maxElements) {
     const actualBytes = <usize>actualCount * elementSize;

package/assembly/index.d.ts

@@ -8,12 +8,12 @@ declare class JSONConfig {
    * access; untouched fields pass their original bytes straight through on
    * serialize.
    *
-   * - `"none"` *(default)* — every field is parsed eagerly, up-front.
-   * - `"auto"` — the transform defers fields whose estimated parse cost is high
+   * - `"none"` *(default)* - every field is parsed eagerly, up-front.
+   * - `"auto"` - the transform defers fields whose estimated parse cost is high
    *   (nested structs, arrays, maps, long strings) and keeps cheap fields
    *   (primitives, enums, `Date`) eager. Use `@eager` to force a field back to
    *   eager, or `@lazy` to force one on.
-   * - `"all"` — every field is deferred. Best for proxy / filter / forward
+   * - `"all"` - every field is deferred. Best for proxy / filter / forward
    *   workloads over large payloads; note it generates a getter and a serialize
    *   branch per field, so module size grows with very wide schemas.
    *
@@ -50,9 +50,9 @@ declare class JSONConfig {
  * JSON.parse<Vec3>('{"x":1,"y":2,"z":3}');
  * ```
  */
-// @ts-ignore: type
 declare function json(config?: JSONConfig): Function;
-
+// @ts-expect-error: type
+declare function json(..._): void;
 /**
  * Alias for {@link json}. `@serializable` and `@json` are interchangeable.
  */
@@ -96,7 +96,7 @@ declare function omit(..._): void;
  * The field is still parsed normally; the condition only affects serialization.
  *
  * @param condition - A predicate that receives the **instance** and returns
- *   `true` to omit the field — `(self: T) => boolean` — or a string expression
+ *   `true` to omit the field - `(self: T) => boolean` - or a string expression
  *   evaluated in the instance's scope (reference fields via `this`).
  *
  * @example
@@ -124,13 +124,31 @@ declare function omitif(condition: string | ((self: any) => boolean)): Function;
  * ```
  */
 // @ts-ignore: type
-declare function omitnull(..._): Function;
+declare function omitnull(..._): void;
+
+/**
+ * Field decorator that marks a property as optional for deserialization: the
+ * key may be absent from (or appear anywhere in) the input, and the field keeps
+ * its default. Unlike `@omitnull`/`@omitif` it does NOT omit the field on
+ * serialize and has no nullability requirement - it only opts the field into
+ * the order-tolerant fast path.
+ *
+ * @example
+ * ```ts
+ * @json
+ * class Tweet {
+ *   @optional retweeted_status: Retweet | null = null; // key may be absent
+ * }
+ * ```
+ */
+// @ts-ignore: type
+declare function optional(..._): void;
 
 /**
  * Field decorator that defers parsing of a property until it is first read
  * (on-demand / lazy parsing). The raw JSON slice is stored at parse time and
  * materialized into the field's type on first access, then cached; an untouched
- * field round-trips by copying its original bytes — never re-parsed or
+ * field round-trips by copying its original bytes - never re-parsed or
  * re-serialized.
  *
  * Equivalent to the `JSON.Lazy<T>` type-wrapper form. Pays off for fields you
@@ -170,7 +188,7 @@ declare function eager(..._): void;
  * the generated serialization. The method receives the instance and must return
  * a **valid JSON string**. Pair with {@link deserializer}.
  *
- * @param shape - Optional JSON value shape the output conforms to — one of
+ * @param shape - Optional JSON value shape the output conforms to - one of
  *   `"any"` (default), `"string"`, `"number"`, `"object"`, `"array"`,
  *   `"boolean"`, or `"null"`.
  *
@@ -212,11 +230,11 @@ declare function serializer(
 /**
  * Method decorator marking a member as the class's custom deserializer,
  * replacing the generated deserialization. The method receives the raw JSON
- * string and must return a **new** instance — never assume an existing
+ * string and must return a **new** instance - never assume an existing
  * destination is reused. Pair with {@link serializer} (see it for a full,
  * round-tripping example).
  *
- * @param shape - Optional JSON value shape the input conforms to — one of
+ * @param shape - Optional JSON value shape the input conforms to - one of
  *   `"any"` (default), `"string"`, `"number"`, `"object"`, `"array"`,
  *   `"boolean"`, or `"null"`.
  *
@@ -235,19 +253,6 @@ declare function deserializer(
   shape?: "any" | "string" | "number" | "object" | "array" | "boolean" | "null",
 ): any;
 
-/**
- * Parsing/serialization strategy selected at build time via the `JSON_MODE`
- * environment variable and exposed as {@link JSON_MODE}.
- */
-declare const enum JSONMode {
-  /** Scalar/word-at-a-time (SWAR) scanning. The default; no extra flags. */
-  SWAR = 0,
-  /** 128-bit SIMD scanning. Fastest on larger payloads; needs `--enable simd`. */
-  SIMD = 1,
-  /** Straightforward byte-at-a-time scanning. Smallest code, slowest. */
-  NAIVE = 2,
-}
-
 /**
  * The active {@link JSONMode}, injected by the transform from the `JSON_MODE`
  * build-time environment variable (default `SWAR`). Set it on the `asc`
@@ -262,6 +267,12 @@ declare const enum JSONMode {
  */
 declare const JSON_MODE: JSONMode;
 
+/**
+ * Whether strict RFC 8259 validation is enabled. Injected by the transform from
+ * the `JSON_STRICT` build-time environment variable (default `false`).
+ */
+declare const JSON_STRICT: bool;
+
 /**
  * Whether the string cache is enabled (default off). Injected from the
  * `JSON_CACHE` build-time environment variable. When on, repeated strings are