json-as 1.3.9 → 1.4.0

package/assembly/deserialize/swar/string.ts

@@ -61,8 +61,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 +79,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 +161,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 +182,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 +198,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 +206,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 +215,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,
@@ -258,8 +252,7 @@ export function deserializeString_SWAR(srcStart: usize, srcEnd: usize): string {
 //     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 +271,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 +364,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 +374,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,8 +483,8 @@ 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)));
+      const m0 = backslash_or_quote_mask(load<u64>(srcStart));
+      const m1 = backslash_or_quote_mask(load<u64>(srcStart, 8));
       if ((m0 | m1) != 0) break;
       srcStart += 16;
     }
@@ -500,7 +492,7 @@ export function deserializeStringField_SWAR<T extends string | null>(
 
   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 +512,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 +534,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;

package/assembly/index.d.ts

@@ -1,57 +1,290 @@
 /**
- * Class decorator that enables the class to be recognized as JSON.
+ * Options for the {@link json} class decorator: `@json({ ... })`.
+ */
+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";
+}
+
+/**
+ * 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}');
+ * ```
  */
 // @ts-ignore: type
-declare function json(..._): void;
+declare function json(config?: JSONConfig): Function;
 
 /**
- * Class decorator that enables the class to be recognized as JSON.
+ * 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;
 
 /**
- * Method decorator that denotes a function to handle that schema's serialization.
+ * 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 lazy(..._): void;
+
+/**
+ * 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(..._): any;
+declare function serializer(
+  shape?: "any" | "string" | "number" | "object" | "array" | "boolean" | "null",
+): any;
 
 /**
- * Method decorator that denotes a function to handle that schema's deserialization.
+ * 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(..._): any;
+declare function deserializer(
+  shape?: "any" | "string" | "number" | "object" | "array" | "boolean" | "null",
+): any;
 
-declare enum JSONMode {
+/**
+ * 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`
+ * 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;