macroforge 0.1.33 → 0.1.34

package/js/serde/index.ts

@@ -1,21 +1,104 @@
 /**
- * Serde runtime helpers for macroforge Serialize/Deserialize macros.
- * These are used by the generated code to handle cycles, forward references,
- * and polymorphic deserialization.
+ * # Macroforge Serde Module
+ *
+ * This module provides runtime helpers for the `Serialize` and `Deserialize` macros.
+ * It handles complex serialization scenarios including:
+ *
+ * - **Cycle Detection**: Objects are assigned unique `__id` values during serialization.
+ *   When the same object is encountered again, a `{ "__ref": id }` marker is emitted
+ *   instead of re-serializing the object.
+ *
+ * - **Forward References**: During deserialization, references to objects that haven't
+ *   been created yet are tracked as `PendingRef` markers. After all objects are
+ *   instantiated, `applyPatches()` resolves these references.
+ *
+ * - **Validation Errors**: The `DeserializeError` class collects structured field-level
+ *   errors that can be displayed to users.
+ *
+ * ## Serialization Flow
+ *
+ * ```typescript
+ * // Generated code creates a context
+ * const ctx = SerializeContext.create();
+ *
+ * // Each object gets registered with a unique ID
+ * const id = ctx.register(obj);
+ *
+ * // Before serializing, check if already seen
+ * const existingId = ctx.getId(obj);
+ * if (existingId !== undefined) {
+ *   return { __ref: existingId };  // Return reference marker
+ * }
+ * ```
+ *
+ * ## Deserialization Flow
+ *
+ * ```typescript
+ * // Generated code creates a context
+ * const ctx = DeserializeContext.create();
+ *
+ * // Register objects as they're created
+ * ctx.register(id, instance);
+ *
+ * // References are resolved immediately if available, or deferred
+ * const value = ctx.getOrDefer(refId);
+ *
+ * // After all objects are created, resolve pending references
+ * ctx.applyPatches();
+ * ```
+ *
+ * @module macroforge/serde
  */
 
 // ============================================================================
 // Serialization Context
 // ============================================================================
 
+/**
+ * Context for tracking objects during serialization.
+ *
+ * The context assigns unique IDs to objects as they're serialized,
+ * enabling cycle detection. When an object is encountered that has
+ * already been serialized, a `{ "__ref": id }` marker is emitted instead.
+ */
 export interface SerializeContext {
-  /** Get the ID for an already-registered object, or undefined if not seen */
+  /**
+   * Gets the ID for an already-registered object.
+   * @param obj - The object to look up
+   * @returns The object's ID, or `undefined` if not yet registered
+   */
   getId(obj: object): number | undefined;
-  /** Register an object and return its assigned ID */
+
+  /**
+   * Registers an object and assigns it a unique ID.
+   * @param obj - The object to register
+   * @returns The newly assigned ID
+   */
   register(obj: object): number;
 }
 
+/**
+ * Factory functions for creating serialization contexts.
+ */
 export namespace SerializeContext {
+  /**
+   * Creates a new serialization context.
+   *
+   * The context uses a `WeakMap` to track objects, so objects can be
+   * garbage collected if no other references exist.
+   *
+   * @returns A new `SerializeContext` instance
+   *
+   * @example
+   * ```typescript
+   * const ctx = SerializeContext.create();
+   * const id = ctx.register(myObject);
+   * // Later...
+   * if (ctx.getId(myObject) !== undefined) {
+   *   // Object was already serialized, emit reference
+   * }
+   * ```
+   */
   export function create(): SerializeContext {
     const ids = new WeakMap<object, number>();
     let nextId = 0;
@@ -34,25 +117,107 @@ export namespace SerializeContext {
 // Deserialization Context
 // ============================================================================
 
+/**
+ * Context for tracking objects and resolving references during deserialization.
+ *
+ * The context maintains a registry of objects by their `__id` values and
+ * collects "patches" for forward references that need to be resolved after
+ * all objects are created.
+ *
+ * ## Forward Reference Resolution
+ *
+ * When deserializing circular or forward references:
+ *
+ * 1. Object A references Object B (which hasn't been created yet)
+ * 2. A `PendingRef` marker is stored temporarily
+ * 3. Object B is created and registered with its ID
+ * 4. `applyPatches()` resolves A's reference to point to B
+ */
 export interface DeserializeContext {
-  /** Register an object with a known ID */
+  /**
+   * Registers an object with a known ID.
+   * @param id - The object's ID from the `__id` field
+   * @param instance - The deserialized object instance
+   */
   register(id: number, instance: any): void;
-  /** Get an object by ID, or return a PendingRef if not yet available */
+
+  /**
+   * Gets an object by ID, or returns a `PendingRef` if not yet available.
+   * @param refId - The ID from the `__ref` field
+   * @returns The object if already registered, or a `PendingRef` marker
+   */
   getOrDefer(refId: number): any;
-  /** Defer a patch using a setter callback (called when ref is resolved) */
-  deferPatch(refId: number, setter: (val: any) => void): void;
-  /** Track an object for optional freezing */
+
+  /**
+   * Assigns a value to a property, deferring if it's a `PendingRef`.
+   * If the value is a `PendingRef`, the assignment is recorded as a patch
+   * to be applied later.
+   * @param target - The object to assign to
+   * @param prop - The property name or index
+   * @param value - The value to assign (may be a `PendingRef`)
+   */
+  assignOrDefer(target: any, prop: string | number, value: any): void;
+
+  /**
+   * Manually adds a patch for later resolution.
+   * @param target - The object containing the reference
+   * @param prop - The property name or index
+   * @param refId - The ID of the referenced object
+   */
+  addPatch(target: any, prop: string | number, refId: number): void;
+
+  /**
+   * Tracks an object for optional freezing after deserialization.
+   * @param obj - The object to track
+   */
   trackForFreeze(obj: object): void;
-  /** Apply all deferred patches (call after deserialization is complete) */
+
+  /**
+   * Applies all deferred patches, resolving forward references.
+   * Call this after all objects have been created.
+   * @throws Error if any referenced ID is not in the registry
+   */
   applyPatches(): void;
-  /** Freeze all tracked objects (call after applyPatches if immutability is desired) */
+
+  /**
+   * Freezes all tracked objects for immutability.
+   * Call this after `applyPatches()` if immutable objects are desired.
+   */
   freezeAll(): void;
 }
 
+/**
+ * Factory functions for creating deserialization contexts.
+ */
 export namespace DeserializeContext {
+  /**
+   * Creates a new deserialization context.
+   *
+   * The context maintains:
+   * - A registry mapping IDs to deserialized objects
+   * - A list of patches for forward references
+   * - A list of objects to freeze (if immutability is enabled)
+   *
+   * @returns A new `DeserializeContext` instance
+   *
+   * @example
+   * ```typescript
+   * const ctx = DeserializeContext.create();
+   *
+   * // Register objects as they're created
+   * ctx.register(1, user);
+   * ctx.register(2, friend);
+   *
+   * // Resolve forward references
+   * ctx.applyPatches();
+   *
+   * // Optionally freeze for immutability
+   * ctx.freezeAll();
+   * ```
+   */
   export function create(): DeserializeContext {
     const registry = new Map<number, any>();
-    const patches: Array<{ refId: number; setter: (val: any) => void }> = [];
+    const patches: Array<{ target: any; prop: string | number; refId: number }> = [];
     const toFreeze: object[] = [];
 
     return {
@@ -67,8 +232,17 @@ export namespace DeserializeContext {
         return PendingRef.create(refId);
       },
 
-      deferPatch: (refId, setter) => {
-        patches.push({ refId, setter });
+      assignOrDefer: (target, prop, value) => {
+        if (PendingRef.is(value)) {
+          target[prop] = null;
+          patches.push({ target, prop, refId: value.id });
+        } else {
+          target[prop] = value;
+        }
+      },
+
+      addPatch: (target, prop, refId) => {
+        patches.push({ target, prop, refId });
       },
 
       trackForFreeze: (obj) => {
@@ -76,11 +250,11 @@ export namespace DeserializeContext {
       },
 
       applyPatches: () => {
-        for (const { refId, setter } of patches) {
+        for (const { target, prop, refId } of patches) {
           if (!registry.has(refId)) {
             throw new Error(`Unresolved reference: __ref ${refId}`);
           }
-          setter(registry.get(refId));
+          target[prop] = registry.get(refId);
         }
       },
 
@@ -97,17 +271,38 @@ export namespace DeserializeContext {
 // Pending Reference Marker
 // ============================================================================
 
-/** Marker interface for forward references that need patching */
+/**
+ * Marker interface for forward references that need patching.
+ *
+ * When deserializing a `{ "__ref": id }` marker for an object that hasn't
+ * been created yet, a `PendingRef` is stored temporarily. After all objects
+ * are created, `DeserializeContext.applyPatches()` resolves these markers.
+ */
 export interface PendingRef {
+  /** Discriminant field to identify pending references */
   readonly __pendingRef: true;
+  /** The ID of the referenced object */
   readonly id: number;
 }
 
+/**
+ * Factory and type guard functions for `PendingRef`.
+ */
 export namespace PendingRef {
+  /**
+   * Creates a new pending reference marker.
+   * @param id - The ID of the referenced object
+   * @returns A `PendingRef` marker
+   */
   export function create(id: number): PendingRef {
     return { __pendingRef: true, id };
   }
 
+  /**
+   * Type guard to check if a value is a `PendingRef`.
+   * @param value - The value to check
+   * @returns `true` if the value is a `PendingRef`
+   */
   export function is(value: any): value is PendingRef {
     return (
       value !== null &&
@@ -122,8 +317,15 @@ export namespace PendingRef {
 // Options for fromStringifiedJSON
 // ============================================================================
 
+/**
+ * Options for configuring deserialization behavior.
+ */
 export interface DeserializeOptions {
-  /** If true, freeze all deserialized objects after patching */
+  /**
+   * If `true`, all deserialized objects are frozen after patching.
+   * This provides immutability guarantees but prevents modification.
+   * @default false
+   */
   freeze?: boolean;
 }
 
@@ -131,16 +333,57 @@ export interface DeserializeOptions {
 // Structured Error for Deserialization
 // ============================================================================
 
-/** Structured field error for validation failures */
+/**
+ * Structured error for a single field validation failure.
+ *
+ * Used by the `Deserialize` macro to collect validation errors
+ * in a format suitable for display to users.
+ */
 export interface FieldError {
+  /**
+   * The field path that failed validation.
+   * For nested fields, uses dot notation (e.g., `"address.street"`).
+   */
   field: string;
+
+  /**
+   * Human-readable error message describing the validation failure.
+   * @example "must be a valid email"
+   * @example "must have at least 3 characters"
+   */
   message: string;
 }
 
-/** Error class that carries structured field errors */
+/**
+ * Error class that carries structured field validation errors.
+ *
+ * Thrown by deserialization methods when validation fails. Contains
+ * an array of `FieldError` objects that can be displayed to users
+ * or used for form validation feedback.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const user = User.fromStringifiedJSON(json);
+ * } catch (e) {
+ *   if (e instanceof DeserializeError) {
+ *     for (const { field, message } of e.errors) {
+ *       console.error(`${field}: ${message}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export class DeserializeError extends Error {
+  /**
+   * Array of field-level validation errors.
+   */
   public readonly errors: FieldError[];
 
+  /**
+   * Creates a new deserialization error.
+   * @param errors - Array of field validation errors
+   */
   constructor(errors: FieldError[]) {
     const message = errors.map((e) => `${e.field}: ${e.message}`).join("; ");
     super(message);

package/js/traits/index.d.ts

@@ -1,33 +1,258 @@
 /**
- * Trait interfaces for macroforge derive macros.
- * All members are readonly and use function-style signatures (for namespace compatibility).
+ * # Macroforge Traits Module
+ *
+ * This module defines TypeScript interfaces that correspond to Rust-like traits.
+ * These interfaces describe the shape of the methods generated by Macroforge's
+ * derive macros for interfaces, enums, and type aliases.
+ *
+ * For **classes**, the generated methods are instance methods (e.g., `user.clone()`).
+ * For **interfaces/enums/type aliases**, the generated methods are namespace
+ * functions that take the value as the first parameter (e.g., `User.clone(user)`).
+ *
+ * ## Usage
+ *
+ * These traits are primarily used for type checking generated code:
+ *
+ * ```typescript
+ * import type { Clone, Debug } from "macroforge/traits";
+ *
+ * // Type-check that a namespace implements Clone
+ * const UserNs: Clone<User> = User;
+ * ```
+ *
+ * @module macroforge/traits
+ */
+/**
+ * Trait for types that can be deep-copied.
+ *
+ * Analogous to Rust's `Clone` trait. The generated `clone` method creates
+ * an independent copy of the value.
+ *
+ * @template T - The type being cloned
+ *
+ * @example
+ * ```typescript
+ * // For interfaces/type aliases, use as namespace:
+ * const cloned = UserNs.clone(original);
+ *
+ * // For classes, methods are on the instance:
+ * const cloned = original.clone();
+ * ```
  */
 export interface Clone<T> {
+    /**
+     * Creates a deep copy of the value.
+     * @param self - The value to clone
+     * @returns A new independent copy of the value
+     */
     readonly clone: (self: T) => T;
 }
+/**
+ * Trait for types with a human-readable string representation.
+ *
+ * Analogous to Rust's `Debug` trait. The generated `toString` method
+ * produces a string like `"TypeName { field1: value1, field2: value2 }"`.
+ *
+ * @template T - The type being formatted
+ *
+ * @example
+ * ```typescript
+ * console.log(User.toString(user));
+ * // Output: "User { id: 1, name: Alice }"
+ * ```
+ */
 export interface Debug<T> {
+    /**
+     * Returns a debug string representation of the value.
+     * @param self - The value to format
+     * @returns A human-readable string for debugging
+     */
     readonly toString: (self: T) => string;
 }
+/**
+ * Trait for types with a default value.
+ *
+ * Analogous to Rust's `Default` trait. The generated `defaultValue` method
+ * creates an instance with all fields set to their default values.
+ *
+ * @template T - The type being constructed
+ *
+ * @example
+ * ```typescript
+ * const user = User.defaultValue();
+ * // Creates: { id: 0, name: "", active: false }
+ * ```
+ */
 export interface Default<T> {
+    /**
+     * Creates a new instance with default values for all fields.
+     * @returns A new instance with default field values
+     */
     readonly defaultValue: () => T;
 }
+/**
+ * Trait for types that support equality comparison.
+ *
+ * Analogous to Rust's `PartialEq` trait. The generated `equals` method
+ * performs structural equality comparison on all non-skipped fields.
+ *
+ * @template T - The type being compared
+ *
+ * @example
+ * ```typescript
+ * if (User.equals(user1, user2)) {
+ *   console.log("Users are equal");
+ * }
+ * ```
+ */
 export interface PartialEq<T> {
+    /**
+     * Compares two values for equality.
+     * @param self - The first value
+     * @param other - The second value (accepts unknown for flexibility)
+     * @returns `true` if the values are equal, `false` otherwise
+     */
     readonly equals: (self: T, other: unknown) => boolean;
 }
+/**
+ * Trait for types that can produce a hash code.
+ *
+ * Analogous to Rust's `Hash` trait. The generated `hashCode` method
+ * computes a 32-bit integer hash suitable for use in hash-based collections.
+ *
+ * **Hash Contract**: Objects that are equal (via `PartialEq`) must produce
+ * the same hash code.
+ *
+ * @template T - The type being hashed
+ *
+ * @example
+ * ```typescript
+ * const hash = User.hashCode(user);
+ * // Use in Map: map.set(hash, user);
+ * ```
+ */
 export interface Hash<T> {
+    /**
+     * Computes a hash code for the value.
+     * @param self - The value to hash
+     * @returns A 32-bit integer hash code
+     */
     readonly hashCode: (self: T) => number;
 }
+/**
+ * Trait for types with partial ordering.
+ *
+ * Analogous to Rust's `PartialOrd` trait. The generated `compareTo` method
+ * returns a number for comparable values, or `null` for incomparable values.
+ *
+ * @template T - The type being compared
+ *
+ * @example
+ * ```typescript
+ * const cmp = User.compareTo(user1, user2);
+ * if (cmp !== null) {
+ *   if (cmp < 0) console.log("user1 < user2");
+ *   else if (cmp > 0) console.log("user1 > user2");
+ *   else console.log("user1 == user2");
+ * } else {
+ *   console.log("Incomparable");
+ * }
+ * ```
+ */
 export interface PartialOrd<T> {
+    /**
+     * Compares two values for ordering.
+     * @param self - The first value
+     * @param other - The second value
+     * @returns `-1` if self < other, `0` if equal, `1` if self > other, or `null` if incomparable
+     */
     readonly compareTo: (self: T, other: unknown) => number | null;
 }
+/**
+ * Trait for types with total ordering.
+ *
+ * Analogous to Rust's `Ord` trait. The generated `compareTo` method
+ * always returns a number (never null) - all values are comparable.
+ *
+ * @template T - The type being compared
+ *
+ * @example
+ * ```typescript
+ * // Sort an array using Ord
+ * users.sort((a, b) => User.compareTo(a, b));
+ * ```
+ */
 export interface Ord<T> {
+    /**
+     * Compares two values for ordering (total order).
+     * @param self - The first value
+     * @param other - The second value
+     * @returns `-1` if self < other, `0` if equal, `1` if self > other
+     */
     readonly compareTo: (self: T, other: T) => number;
 }
+/**
+ * Trait for types that can be serialized to JSON.
+ *
+ * Analogous to Rust's serde `Serialize` trait. The generated methods
+ * convert objects to JSON with cycle detection via `__id`/`__ref` markers.
+ *
+ * @template T - The type being serialized
+ *
+ * @example
+ * ```typescript
+ * const json = User.toStringifiedJSON(user);
+ * // => '{"__type":"User","__id":1,"name":"Alice"}'
+ *
+ * const obj = User.toObject(user);
+ * // => { __type: "User", __id: 1, name: "Alice" }
+ * ```
+ */
 export interface Serialize<T> {
+    /**
+     * Serializes the value to a JSON string.
+     * @param self - The value to serialize
+     * @returns JSON string with `__type` and `__id` markers
+     */
     readonly toStringifiedJSON: (self: T) => string;
+    /**
+     * Converts the value to a plain JavaScript object.
+     * @param self - The value to convert
+     * @returns Plain object suitable for JSON.stringify
+     */
     readonly toObject: (self: T) => Record<string, unknown>;
 }
+/**
+ * Trait for types that can be deserialized from JSON.
+ *
+ * Analogous to Rust's serde `Deserialize` trait. The generated methods
+ * parse JSON, resolve `__ref` markers, and validate field values.
+ *
+ * @template T - The type being deserialized
+ *
+ * @example
+ * ```typescript
+ * import { Result } from "macroforge/utils";
+ *
+ * const result = User.fromStringifiedJSON(json);
+ * if (Result.isOk(result)) {
+ *   const user = result.value;
+ * } else {
+ *   console.error(result.error); // Validation errors
+ * }
+ * ```
+ */
 export interface Deserialize<T> {
+    /**
+     * Deserializes a value from a JSON string.
+     * @param json - JSON string to parse
+     * @returns The deserialized value (may throw on invalid input)
+     */
     readonly fromStringifiedJSON: (json: string) => T;
+    /**
+     * Deserializes a value from a plain JavaScript object.
+     * @param obj - Object to deserialize from
+     * @returns The deserialized value (may throw on invalid input)
+     */
     readonly fromObject: (obj: unknown) => T;
 }