mutts 1.0.7 → 1.0.9

package/dist/types-DaHFfhlN.d.ts

@@ -0,0 +1,414 @@
+declare abstract class AZone<T> {
+    abstract active?: T;
+    protected enter(value?: T): unknown;
+    protected leave(entered: unknown): void;
+    with<R>(value: T | undefined, fn: () => R): R;
+    root<R>(fn: () => R): R;
+    get zoned(): FunctionWrapper;
+}
+type FunctionWrapper = <R>(fn: () => R) => R;
+declare class Zone<T> extends AZone<T> {
+    active: T | undefined;
+}
+type HistoryValue<T> = {
+    present: T | undefined;
+    history: Set<T>;
+};
+declare class ZoneHistory<T> extends AZone<HistoryValue<T>> {
+    private controlled;
+    private history;
+    readonly present: AZone<T>;
+    has(value: T): boolean;
+    some(predicate: (value: T) => boolean): boolean;
+    constructor(controlled?: AZone<T>);
+    get active(): HistoryValue<T> | undefined;
+    set active(value: HistoryValue<T> | undefined);
+}
+declare class ZoneAggregator extends AZone<Map<AZone<unknown>, unknown>> {
+    #private;
+    constructor(...zones: AZone<unknown>[]);
+    get active(): Map<AZone<unknown>, unknown> | undefined;
+    set active(value: Map<AZone<unknown>, unknown> | undefined);
+    enter(value?: Map<AZone<unknown>, unknown> | undefined): Map<AZone<unknown>, unknown>;
+    leave(entered: Map<AZone<unknown>, unknown>): void;
+    add(z: AZone<unknown>): void;
+    delete(z: AZone<unknown>): void;
+    clear(): void;
+}
+declare const asyncZone: ZoneAggregator;
+
+/**
+ * Effect access passed to user callbacks within effects/watch
+ * Provides functions to track dependencies and information about the effect execution
+ */
+interface EffectAccess {
+    /**
+     * Tracks dependencies in the current effect context
+     * Use this for normal dependency tracking within the effect
+     * @example
+     * ```typescript
+     * effect(({ tracked }) => {
+     *   // In async context, use tracked to restore dependency tracking
+     *   await someAsyncOperation()
+     *   const value = tracked(() => state.count) // Tracks state.count in this effect
+     * })
+     * ```
+     */
+    tracked: FunctionWrapper;
+    /**
+     * Tracks dependencies in the parent effect context
+     * Use this when child effects should track dependencies in the parent,
+     * allowing parent cleanup to manage child effects while dependencies trigger the parent
+     * @example
+     * ```typescript
+     * effect(({ ascend }) => {
+     *   const length = inputs.length
+     *   if (length > 0) {
+     *     ascend(() => {
+     *       // Dependencies here are tracked in the parent effect
+     *       inputs.forEach(item => console.log(item))
+     *     })
+     *   }
+     * })
+     * ```
+     */
+    ascend: FunctionWrapper;
+    /**
+     * Indicates whether the effect is running as a reaction (i.e. not the first call)
+     * - `false`: First execution when the effect is created
+     * - `true`: Subsequent executions triggered by dependency changes
+     * @example
+     * ```typescript
+     * effect(({ reaction }) => {
+     *   if (!reaction) {
+     *     console.log('Effect initialized')
+     *     // Setup code that should only run once
+     *   } else {
+     *     console.log('Effect re-ran due to dependency change')
+     *     // Code that runs on every update
+     *   }
+     * })
+     * ```
+     */
+    reaction: boolean;
+}
+/**
+ * Base type for effect callbacks - simple function without additional properties
+ */
+type ScopedCallback = () => void;
+/**
+ * Type for effect cleanup functions with stopped state tracking
+ */
+type EffectCleanup = ScopedCallback & {
+    [stopped]: boolean;
+};
+/**
+ * Type for the `runEffect` function of an effect - argument-less function to call to trigger the effect
+ */
+type EffectTrigger = ScopedCallback;
+/**
+ * Async execution mode for effects
+ * - `cancel`: Cancel previous async execution when dependencies change (default)
+ * - `queue`: Queue next execution to run after current completes
+ * - `ignore`: Ignore new executions while async work is running
+ */
+type AsyncExecutionMode = 'cancel' | 'queue' | 'ignore';
+/**
+ * Options for effect creation
+ */
+interface EffectOptions {
+    /**
+     * How to handle async effect executions when dependencies change
+     * @default 'cancel'
+     */
+    asyncMode?: AsyncExecutionMode;
+    /**
+     * If true, this effect is "opaque" to deep optimizations: it sees the object reference itself
+     * and must be notified when it changes, regardless of deep content similarity.
+     * Use this for effects that depend on object identity (like memoize).
+     */
+    opaque?: boolean;
+    /**
+     * Used for debugging purpose. Provides a callback to be called every time a dependency is created.
+     */
+    dependencyHook?: (obj: any, prop: any) => void;
+    /**
+     * Used for debugging purpose. Provides a name for the effect.
+     */
+    name?: string;
+}
+/**
+ * Type for property evolution events
+ */
+type PropEvolution = {
+    type: 'set' | 'del' | 'add' | 'invalidate';
+    prop: any;
+};
+/**
+ * Type for collection operation evolution events
+ */
+type BunchEvolution = {
+    type: 'bunch';
+    method: string;
+};
+type Evolution = PropEvolution | BunchEvolution;
+type State = {
+    evolution: Evolution;
+    next: State;
+} | {};
+/**
+ * Symbol to check if an effect is stopped
+ */
+declare const stopped: unique symbol;
+/**
+ * Symbol to access effect cleanup function
+ */
+declare const cleanup: unique symbol;
+type EffectCloser = (error?: any) => void;
+type CatchFunction = (error: any) => EffectCloser | undefined | void;
+/**
+ * Context for a running projection item effect
+ */
+interface ProjectionContext {
+    source: any;
+    key?: any;
+    target: any;
+    depth: number;
+    parent?: ProjectionContext;
+}
+/**
+ * Structured error codes for machine-readable diagnosis
+ */
+declare enum ReactiveErrorCode {
+    CycleDetected = "CYCLE_DETECTED",
+    MaxDepthExceeded = "MAX_DEPTH_EXCEEDED",
+    MaxReactionExceeded = "MAX_REACTION_EXCEEDED",
+    WriteInComputed = "WRITE_IN_COMPUTED",
+    TrackingError = "TRACKING_ERROR",
+    BrokenEffects = "BROKEN_EFFECTS"
+}
+type CycleDebugInfo = {
+    code: ReactiveErrorCode.CycleDetected;
+    cycle: string[];
+    details?: string;
+};
+type MaxDepthDebugInfo = {
+    code: ReactiveErrorCode.MaxDepthExceeded;
+    depth: number;
+    chain: string[];
+};
+type MaxReactionDebugInfo = {
+    code: ReactiveErrorCode.MaxReactionExceeded;
+    count: number;
+    effect: string;
+};
+type GenericDebugInfo = {
+    code: ReactiveErrorCode;
+    causalChain?: string[];
+    creationStack?: string | any[];
+    lineage?: any[];
+    [key: string]: any;
+};
+type ReactiveDebugInfo = CycleDebugInfo | MaxDepthDebugInfo | MaxReactionDebugInfo | GenericDebugInfo;
+/**
+ * Error class for reactive system errors
+ */
+declare class ReactiveError extends Error {
+    debugInfo?: ReactiveDebugInfo;
+    constructor(message: string, debugInfo?: ReactiveDebugInfo);
+    get code(): ReactiveErrorCode | undefined;
+    get cause(): any;
+}
+/**
+ * Global options for the reactive system
+ */
+declare const options: {
+    /**
+     * Debug purpose: called when an effect is entered
+     * @param effect - The effect that is entered
+     */
+    enter: (_effect: Function) => void;
+    /**
+     * Debug purpose: called when an effect is left
+     * @param effect - The effect that is left
+     */
+    leave: (_effect: Function) => void;
+    /**
+     * Debug purpose: called when an effect is chained
+     * @param target - The effect that is being triggered
+     * @param caller - The effect that is calling the target
+     */
+    chain: (_targets: Function[], _caller?: Function) => void;
+    /**
+     * Debug purpose: called when an effect chain is started
+     * @param target - The effect that is being triggered
+     */
+    beginChain: (_targets: Function[]) => void;
+    /**
+     * Debug purpose: called when an effect chain is ended
+     */
+    endChain: () => void;
+    garbageCollected: (_fn: Function) => void;
+    /**
+     * Debug purpose: called when an object is touched
+     * @param obj - The object that is touched
+     * @param evolution - The type of change
+     * @param props - The properties that changed
+     * @param deps - The dependencies that changed
+     */
+    touched: (_obj: any, _evolution: Evolution, _props?: any[], _deps?: Set<EffectTrigger>) => void;
+    /**
+     * Debug purpose: called when an effect is skipped because it's already running
+     * @param effect - The effect that is already running
+     * @param runningChain - The array of effects from the detected one to the currently running one
+     */
+    skipRunningEffect: (_effect: EffectTrigger) => void;
+    /**
+     * Debug purpose: maximum effect chain (like call stack max depth)
+     * Used to prevent infinite loops
+     * @default 100
+     */
+    maxEffectChain: number;
+    /**
+     * Maximum number of times an effect can be triggered by the same cause in a single batch
+     * Used to detect aggressive re-computation or infinite loops
+     * @default 10
+     */
+    maxTriggerPerBatch: number;
+    /**
+     * Debug purpose: maximum effect reaction (like call stack max depth)
+     * Used to prevent infinite loops
+     * @default 'throw'
+     */
+    maxEffectReaction: "throw" | "debug" | "warn";
+    /**
+     * Callback called when a memoization discrepancy is detected (debug only)
+     * When defined, memoized functions will run a second time (untracked) to verify consistency.
+     * If the untracked run returns a different value than the cached one, this callback is triggered.
+     *
+     * This is the primary tool for detecting missing reactive dependencies in computed values.
+     *
+     * @param cached - The value currently in the memoization cache
+     * @param fresh - The value obtained by re-running the function untracked
+     * @param fn - The memoized function itself
+     * @param args - Arguments passed to the function
+     *
+     * @example
+     * ```typescript
+     * reactiveOptions.onMemoizationDiscrepancy = (cached, fresh, fn, args) => {
+     *   throw new Error(`Memoization discrepancy in ${fn.name}!`);
+     * };
+     * ```
+     */
+    onMemoizationDiscrepancy: ((cached: any, fresh: any, fn: Function, args: any[], cause: "calculation" | "comparison") => void) | undefined;
+    /**
+     * How to handle cycles detected in effect batches.
+     *
+     * - `'production'` (Default): High-performance mode. Disables dependency graph maintenance and
+     *   Topological Sorting in favor of a simple FIFO queue. Use this for trustworthy, acyclic UI code.
+     *   Cycle detection is heuristic (uses maxEffectChain execution counts).
+     *
+     * - `'development'`: Maintains direct dependency graph for early cycle detection during edge creation.
+     *   Catches cycles before effects execute via DFS check when adding edges. Throws immediately with
+     *   basic path information. Good balance of debugging help with moderate overhead.
+     *
+     * - `'debug'`: Full diagnostic mode with transitive closures and topological sorting.
+     *   Provides detailed cycle path reporting. Highest overhead but most informative for bug hunting.
+     *
+     * @default 'production'
+     */
+    cycleHandling: "production" | "development" | "debug";
+    /**
+     * Internal flag used by memoization discrepancy detector to avoid counting calls in tests
+     * @warning Do not modify this flag manually, this flag is given by the engine
+     */
+    isVerificationRun: boolean;
+    /**
+     * Maximum depth for deep watching traversal
+     * Used to prevent infinite recursion in circular references
+     * @default 100
+     */
+    maxDeepWatchDepth: number;
+    /**
+     * Only react on instance members modification (not inherited properties)
+     * For instance, do not track class methods
+     * @default true
+     */
+    instanceMembers: boolean;
+    /**
+     * Ignore accessors (getters and setters) and only track direct properties
+     * @default true
+     */
+    ignoreAccessors: boolean;
+    /**
+     * Enable recursive touching when objects with the same prototype are replaced
+     * When enabled, replacing an object with another of the same prototype triggers
+     * recursive diffing instead of notifying parent effects
+     * @default true
+     */
+    recursiveTouching: boolean;
+    /**
+     * Default async execution mode for effects that return Promises
+     * - 'cancel': Cancel previous async execution when dependencies change (default, enables async zone)
+     * - 'queue': Queue next execution to run after current completes (enables async zone)
+     * - 'ignore': Ignore new executions while async work is running (enables async zone)
+     * - false: Disable async zone and async mode handling (effects run concurrently)
+     *
+     * **When truthy:** Enables async zone (Promise.prototype wrapping) for automatic context
+     * preservation in Promise callbacks. Warning: This modifies Promise.prototype globally.
+     * Only enable if no other library modifies Promise.prototype.
+     *
+     * **When false:** Async zone is disabled. Use `tracked()` manually in Promise callbacks.
+     *
+     * Can be overridden per-effect via EffectOptions
+     * @default 'cancel'
+     */
+    asyncMode: AsyncExecutionMode | false;
+    warn: (...args: any[]) => void;
+    /**
+     * Configuration for the introspection system
+     */
+    introspection: {
+        /**
+         * Whether to keep a history of mutations for debugging
+         * @default false
+         */
+        enableHistory: boolean;
+        /**
+         * Number of mutations to keep in history
+         * @default 50
+         */
+        historySize: number;
+    };
+    /**
+     * Configuration for zone hooks - control which async APIs are hooked
+     * Each option controls whether the corresponding async API is wrapped to preserve effect context
+     * Only applies when asyncMode is enabled (truthy)
+     * @deprecated Should take all when we made sure PIXI.create, Game.create, ... are -> .root()
+     */
+    zones: {
+        /**
+         * Hook setTimeout to preserve effect context
+         * @default true
+         */
+        setTimeout: boolean;
+        /**
+         * Hook setInterval to preserve effect context
+         * @default true
+         */
+        setInterval: boolean;
+        /**
+         * Hook requestAnimationFrame (runs in untracked context when hooked)
+         * @default true
+         */
+        requestAnimationFrame: boolean;
+        /**
+         * Hook queueMicrotask to preserve effect context
+         * @default true
+         */
+        queueMicrotask: boolean;
+    };
+};
+
+export { AZone as A, ReactiveError as R, ZoneAggregator as Z, cleanup as c, ReactiveErrorCode as h, Zone as i, ZoneHistory as j, asyncZone as k, options as o };
+export type { CatchFunction as C, EffectTrigger as E, FunctionWrapper as F, ProjectionContext as P, ScopedCallback as S, Evolution as a, EffectCleanup as b, EffectCloser as d, EffectAccess as e, State as f, EffectOptions as g };

package/docs/ai/api-reference.md

@@ -120,7 +120,7 @@ export interface MutationRecord {
 export declare function getDependencyGraph(): ReactivityGraph;
 export declare function getMutationHistory(): MutationRecord[];
 export declare const options: {
-    cycleHandling: 'throw' | 'warn' | 'break' | 'strict';
+    cycleHandling: 'production' | 'development' | 'debug';
     introspection: { enableHistory: boolean; historySize: number };
 };