json-as 1.4.0 → 1.5.0

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`