json-as 1.3.9 → 1.5.0

package/assembly/deserialize/swar/string.ts

@@ -41,11 +41,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);
@@ -61,8 +57,7 @@ import { hex4_to_u16_swar } from "../../util/swar";
 // NOTE: vs the prior overflow scanner this is faster on dense and sparse
 // escaping but ~20% slower on sustained moderate-density escaping (escape
 // every ~20 chars), where multi-escape-per-block had an edge.
-// @ts-expect-error: @inline is a valid decorator
-@inline function deserializeEscapedString_SWAR(
+function deserializeEscapedString_SWAR(
   payloadStart: usize,
   escapeStart: usize,
   srcEnd: usize,
@@ -80,20 +75,20 @@ import { hex4_to_u16_swar } from "../../util/swar";
 
   while (srcStart <= srcEnd8) {
     const block = load<u64>(srcStart);
-    let mask = inline.always(backslash_mask_unsafe(block));
+    let mask = backslash_mask_unsafe(block);
     if (mask == 0) {
       store<u64>(bs.offset, block);
       bs.offset += 8;
       srcStart += 8;
       if (
         srcStart <= srcEnd8 &&
-        inline.always(backslash_mask_unsafe(load<u64>(srcStart))) == 0
+        backslash_mask_unsafe(load<u64>(srcStart)) == 0
       ) {
         const runStart = srcStart;
         srcStart += 8;
         while (
           srcStart <= srcEnd8 &&
-          inline.always(backslash_mask_unsafe(load<u64>(srcStart))) == 0
+          backslash_mask_unsafe(load<u64>(srcStart)) == 0
         ) {
           srcStart += 8;
         }
@@ -162,8 +157,8 @@ export function deserializeString_SWAR(srcStart: usize, srcEnd: usize): string {
     const srcEnd16Fast = srcEnd - 16;
 
     while (srcStart < srcEnd16Fast) {
-      const m0 = inline.always(backslash_mask_unsafe(load<u64>(srcStart)));
-      const m1 = inline.always(backslash_mask_unsafe(load<u64>(srcStart, 8)));
+      const m0 = backslash_mask_unsafe(load<u64>(srcStart));
+      const m1 = backslash_mask_unsafe(load<u64>(srcStart, 8));
       if ((m0 | m1) != 0) break;
       srcStart += 16;
     }
@@ -183,7 +178,7 @@ export function deserializeString_SWAR(srcStart: usize, srcEnd: usize): string {
 
   while (srcStart < srcEnd8) {
     const block = load<u64>(srcStart);
-    let mask = inline.always(backslash_mask_unsafe(block));
+    let mask = backslash_mask_unsafe(block);
 
     if (mask === 0) {
       srcStart += 8;
@@ -199,9 +194,7 @@ export function deserializeString_SWAR(srcStart: usize, srcEnd: usize): string {
       // Detect false positive (code unit where low byte is 0x5C)
       if ((header & 0xffff) !== 0x5c) continue;
 
-      return inline.always(
-        deserializeEscapedString_SWAR(payloadStart, srcIdx, srcEnd),
-      );
+      return deserializeEscapedString_SWAR(payloadStart, srcIdx, srcEnd);
     } while (mask !== 0);
 
     srcStart += 8;
@@ -209,9 +202,7 @@ export function deserializeString_SWAR(srcStart: usize, srcEnd: usize): string {
 
   while (srcStart < srcEnd) {
     if (load<u16>(srcStart) == BACK_SLASH) {
-      return inline.always(
-        deserializeEscapedString_SWAR(payloadStart, srcStart, srcEnd),
-      );
+      return deserializeEscapedString_SWAR(payloadStart, srcStart, srcEnd);
     }
     srcStart += 2;
   }
@@ -220,8 +211,7 @@ export function deserializeString_SWAR(srcStart: usize, srcEnd: usize): string {
 }
 
 // Writes into the destination field, reusing or resizing the backing string.
-// @ts-expect-error: @inline is a valid decorator
-@inline function writeStringToField(
+function writeStringToField(
   dstFieldPtr: usize,
   srcStart: usize,
   byteLength: u32,
@@ -251,15 +241,14 @@ export function deserializeString_SWAR(srcStart: usize, srcEnd: usize): string {
 // 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
 //     to one bulk memory.copy for the remainder.
 // SWAR masks carry high-byte false positives, so each hit is confirmed
 // scalarly before acting.
-// @ts-expect-error: @inline is a valid decorator
-@inline function deserializeEscapedStringField_SWAR(
+function deserializeEscapedStringField_SWAR(
   payloadStart: usize,
   escapeStart: usize,
   srcEnd: usize,
@@ -278,20 +267,20 @@ export function deserializeString_SWAR(srcStart: usize, srcEnd: usize): string {
 
   while (srcStart <= srcEnd8) {
     const block = load<u64>(srcStart);
-    let mask = inline.always(backslash_or_quote_mask(block));
+    let mask = backslash_or_quote_mask(block);
     if (mask == 0) {
       store<u64>(bs.offset, block);
       bs.offset += 8;
       srcStart += 8;
       if (
         srcStart <= srcEnd8 &&
-        inline.always(backslash_or_quote_mask(load<u64>(srcStart))) == 0
+        backslash_or_quote_mask(load<u64>(srcStart)) == 0
       ) {
         const runStart = srcStart;
         srcStart += 8;
         while (
           srcStart <= srcEnd8 &&
-          inline.always(backslash_or_quote_mask(load<u64>(srcStart))) == 0
+          backslash_or_quote_mask(load<u64>(srcStart)) == 0
         ) {
           srcStart += 8;
         }
@@ -371,8 +360,7 @@ export function deserializeString_SWAR(srcStart: usize, srcEnd: usize): string {
   return srcStart;
 }
 
-// @ts-expect-error: @inline is a valid decorator
-@inline function deserializeEscapedStringContinuation_SWAR_MergedTuned(
+function deserializeEscapedStringContinuation_SWAR_MergedTuned(
   lastPtr: usize,
   srcStart: usize,
   srcEnd: usize,
@@ -382,7 +370,7 @@ export function deserializeString_SWAR(srcStart: usize, srcEnd: usize): string {
 
   while (srcStart <= srcEnd8) {
     const blockStart = srcStart;
-    let mask = inline.always(backslash_or_quote_mask(load<u64>(srcStart)));
+    let mask = backslash_or_quote_mask(load<u64>(srcStart));
     if (mask === 0) {
       srcStart += 8;
       continue;
@@ -491,16 +479,21 @@ export function deserializeStringField_SWAR<T extends string | null>(
   if (srcEnd >= 16) {
     const srcEnd16 = srcEnd - 16;
     while (srcStart <= srcEnd16) {
-      const m0 = inline.always(backslash_or_quote_mask(load<u64>(srcStart)));
-      const m1 = inline.always(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.
+      if (backslash_or_quote_mask(load<u64>(srcStart)) != 0) break;
+      if (backslash_or_quote_mask(load<u64>(srcStart, 8)) != 0) {
+        srcStart += 8;
+        break;
+      }
       srcStart += 16;
     }
   }
 
   const srcEnd8 = srcEnd - 8;
   while (srcStart <= srcEnd8) {
-    let mask = inline.always(backslash_or_quote_mask(load<u64>(srcStart)));
+    let mask = backslash_or_quote_mask(load<u64>(srcStart));
     if (mask === 0) {
       srcStart += 8;
       continue;
@@ -520,13 +513,11 @@ export function deserializeStringField_SWAR<T extends string | null>(
         return srcIdx + 2;
       }
       if (char != BACK_SLASH) continue;
-      return inline.always(
-        deserializeEscapedStringField_SWAR(
-          payloadStart,
-          srcIdx,
-          srcEnd,
-          dstFieldPtr,
-        ),
+      return deserializeEscapedStringField_SWAR(
+        payloadStart,
+        srcIdx,
+        srcEnd,
+        dstFieldPtr,
       );
     } while (mask !== 0);
 
@@ -544,13 +535,11 @@ export function deserializeStringField_SWAR<T extends string | null>(
       return srcStart + 2;
     }
     if (char == BACK_SLASH) {
-      return inline.always(
-        deserializeEscapedStringField_SWAR(
-          payloadStart,
-          srcStart,
-          srcEnd,
-          dstFieldPtr,
-        ),
+      return deserializeEscapedStringField_SWAR(
+        payloadStart,
+        srcStart,
+        srcEnd,
+        dstFieldPtr,
       );
     }
     srcStart += 2;
@@ -567,8 +556,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 (
@@ -587,8 +575,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;
@@ -609,8 +596,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

@@ -1,57 +1,295 @@
 /**
- * Class decorator that enables the class to be recognized as JSON.
+ * Options for the {@link json} class decorator: `@json({ ... })`.
  */
-// @ts-ignore: type
-declare function json(..._): void;
+declare class JSONConfig {
+  /**
+   * Class-level lazy (on-demand) parsing mode. A lazy field stores its raw JSON
+   * slice at parse time and only parses it into the field's type on first
+   * 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
+   *   (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
+   *   workloads over large payloads; note it generates a getter and a serialize
+   *   branch per field, so module size grows with very wide schemas.
+   *
+   * @example
+   * ```ts
+   * @json({ lazy: "auto" })
+   * class Repo {
+   *   name: string = "";        // cheap -> stays eager
+   *   owner: Owner = new Owner; // costly -> deferred
+   *   @eager id: i32 = 0;       // opt back out
+   * }
+   * ```
+   */
+  lazy?: "none" | "auto" | "all";
+}
 
 /**
- * Class decorator that enables the class to be recognized as JSON.
+ * Marks a class as serializable, generating the (de)serialization methods the
+ * runtime needs. Required on every type passed to `JSON.parse` / `JSON.stringify`
+ * (including nested types).
+ *
+ * @param config - Optional {@link JSONConfig} (currently `{ lazy }`).
+ *
+ * @example
+ * ```ts
+ * @json
+ * class Vec3 {
+ *   x: f64 = 0;
+ *   y: f64 = 0;
+ *   z: f64 = 0;
+ * }
+ *
+ * JSON.stringify(new Vec3());       // '{"x":0.0,"y":0.0,"z":0.0}'
+ * JSON.parse<Vec3>('{"x":1,"y":2,"z":3}');
+ * ```
+ */
+declare function json(config?: JSONConfig): Function;
+// @ts-expect-error: type
+declare function json(..._): void;
+/**
+ * Alias for {@link json}. `@serializable` and `@json` are interchangeable.
  */
 // @ts-ignore: type
 declare function serializable(..._): void;
 
 /**
- * Property decorator that provides an alias name for JSON serialization.
+ * Field decorator that overrides the JSON key used for a property, decoupling
+ * the wire name from the AssemblyScript field name.
+ *
+ * @param newName - The key to emit and read for this field.
+ *
+ * @example
+ * ```ts
+ * @json
+ * class User {
+ *   @alias("user_id") userId: i32 = 0; // <-> {"user_id": 0}
+ * }
+ * ```
  */
 declare function alias(newName: string): Function;
 
 /**
- * Property decorator that allows omits a field, making it be ignored.
+ * Field decorator that excludes a property from JSON entirely: it is never
+ * serialized and is ignored during parsing.
+ *
+ * @example
+ * ```ts
+ * @json
+ * class Session {
+ *   token: string = "";
+ *   @omit secret: string = ""; // never (de)serialized
+ * }
+ * ```
  */
 // @ts-ignore: type
 declare function omit(..._): void;
 
 /**
- * Property decorator that allows a field to be omitted when equal to an Expression.
+ * Field decorator that omits a property from the output when a predicate holds.
+ * 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
+ *   evaluated in the instance's scope (reference fields via `this`).
+ *
+ * @example
+ * ```ts
+ * @json
+ * class Player {
+ *   age: i32 = 0;
+ *   @omitif((self: Player) => self.age < 18) email: string = ""; // arrow form
+ *   @omitif("this.age < 18") phone: string = "";                 // string form
+ * }
+ * ```
  */
-declare function omitif(
-  condition: string | ((value: any) => boolean),
-): Function;
+declare function omitif(condition: string | ((self: any) => boolean)): Function;
 
 /**
- * Property decorator that allows a field to be omitted when a property is null.
+ * Field decorator that omits a property from the output when its value is
+ * `null`. Shorthand for the common nullable case; the field is still parsed.
+ *
+ * @example
+ * ```ts
+ * @json
+ * class Profile {
+ *   @omitnull bio: string | null = null; // key absent when null
+ * }
+ * ```
  */
 // @ts-ignore: type
-declare function omitnull(..._): Function;
+declare function omitnull(..._): void;
 
 /**
- * Method decorator that denotes a function to handle that schema's serialization.
+ * 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 serializer(..._): any;
+declare function optional(..._): void;
 
 /**
- * Method decorator that denotes a function to handle that schema's deserialization.
+ * 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
+ * re-serialized.
+ *
+ * Equivalent to the `JSON.Lazy<T>` type-wrapper form. Pays off for fields you
+ * usually skip or forward; reading a deferred field is a one-time cost.
+ *
+ * @example
+ * ```ts
+ * @json
+ * class Repo {
+ *   name: string = "";              // eager
+ *   @lazy owner: Owner = new Owner; // parsed only when `repo.owner` is read
+ * }
+ * ```
  */
 // @ts-ignore: type
-declare function deserializer(..._): any;
+declare function lazy(..._): void;
 
-declare enum JSONMode {
-  SWAR = 0,
-  SIMD = 1,
-  NAIVE = 2,
-}
+/**
+ * Field decorator that forces a property to be parsed eagerly, opting it out of
+ * class-level lazy deferral (`@json({ lazy: "auto" | "all" })`). No effect on a
+ * class that is not lazy.
+ *
+ * @example
+ * ```ts
+ * @json({ lazy: "all" })
+ * class Event {
+ *   @eager id: i32 = 0;             // always parsed up-front
+ *   payload: Payload = new Payload; // deferred
+ * }
+ * ```
+ */
+// @ts-ignore: type
+declare function eager(..._): void;
+
+/**
+ * Method decorator marking a member as the class's custom serializer, replacing
+ * 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
+ *   `"any"` (default), `"string"`, `"number"`, `"object"`, `"array"`,
+ *   `"boolean"`, or `"null"`.
+ *
+ * @example
+ * ```ts
+ * @json
+ * class Point {
+ *   x: f64 = 0;
+ *   y: f64 = 0;
+ *   constructor(x: f64, y: f64) {
+ *     this.x = x;
+ *     this.y = y;
+ *   }
+ *
+ *   // Serialize a Point to a single JSON string.
+ *   @serializer("string")
+ *   serializer(self: Point): string {
+ *     return JSON.stringify(`${self.x},${self.y}`);
+ *   }
+ *
+ *   // ...and back. Always return a fresh instance.
+ *   @deserializer("string")
+ *   deserializer(data: string): Point {
+ *     const raw = JSON.parse<string>(data);
+ *     const c = raw.indexOf(",");
+ *     return new Point(f64.parse(raw.slice(0, c)), f64.parse(raw.slice(c + 1)));
+ *   }
+ * }
+ *
+ * JSON.stringify(new Point(3.5, -9.2)); // '"3.5,-9.2"'
+ * JSON.parse<Point>('"3.5,-9.2"'); // Point { x: 3.5, y: -9.2 }
+ * ```
+ */
+// @ts-ignore: type
+declare function serializer(
+  shape?: "any" | "string" | "number" | "object" | "array" | "boolean" | "null",
+): any;
 
+/**
+ * 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
+ * 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
+ *   `"any"` (default), `"string"`, `"number"`, `"object"`, `"array"`,
+ *   `"boolean"`, or `"null"`.
+ *
+ * @example
+ * ```ts
+ * @deserializer("string")
+ * deserializer(data: string): Point {
+ *   const raw = JSON.parse<string>(data); // unwrap the JSON string
+ *   const c = raw.indexOf(",");
+ *   return new Point(f64.parse(raw.slice(0, c)), f64.parse(raw.slice(c + 1)));
+ * }
+ * ```
+ */
+// @ts-ignore: type
+declare function deserializer(
+  shape?: "any" | "string" | "number" | "object" | "array" | "boolean" | "null",
+): any;
+
+/**
+ * The active {@link JSONMode}, injected by the transform from the `JSON_MODE`
+ * build-time environment variable (default `SWAR`). Set it on the `asc`
+ * command/build env; `SIMD` additionally requires `--enable simd`.
+ *
+ * @example
+ * ```sh
+ * JSON_MODE=SIMD  asc app.ts --transform json-as/transform --enable simd
+ * JSON_MODE=SWAR  asc app.ts --transform json-as/transform   # default
+ * JSON_MODE=NAIVE asc app.ts --transform json-as/transform
+ * ```
+ */
 declare const JSON_MODE: JSONMode;
+
+/**
+ * Whether the string cache is enabled (default off). Injected from the
+ * `JSON_CACHE` build-time environment variable. When on, repeated strings are
+ * reused to speed up string-heavy serialization.
+ *
+ * @example
+ * ```sh
+ * JSON_CACHE=true  asc app.ts --transform json-as/transform # default size
+ * JSON_CACHE=512kb asc app.ts --transform json-as/transform # enable + size
+ * JSON_CACHE=false asc app.ts --transform json-as/transform # off (default)
+ * ```
+ */
 declare const JSON_CACHE: bool;
+
+/**
+ * The string-cache size in bytes when {@link JSON_CACHE} is enabled. Both this
+ * and {@link JSON_CACHE} are derived from the single `JSON_CACHE` build-time
+ * environment variable, which accepts raw bytes (`JSON_CACHE=1048576`), bit
+ * units (`512kb`, `2mb`, `1gb`), or byte units (`64KB`, `2MB`, `1GB`).
+ *
+ * @example
+ * ```sh
+ * JSON_CACHE=1mb asc app.ts --transform json-as/transform # JSON_CACHE_SIZE == 1048576
+ * ```
+ */
 declare const JSON_CACHE_SIZE: usize;