mutts 1.0.9 → 1.0.11

package/dist/{types-DaHFfhlN.d.ts → types-Bx2PhORg.d.ts}

@@ -4,9 +4,9 @@ declare abstract class AZone<T> {
     protected leave(entered: unknown): void;
     with<R>(value: T | undefined, fn: () => R): R;
     root<R>(fn: () => R): R;
-    get zoned(): FunctionWrapper;
+    get zoned(): GetterWrapper;
 }
-type FunctionWrapper = <R>(fn: () => R) => R;
+type GetterWrapper = <R>(fn: () => R) => R;
 declare class Zone<T> extends AZone<T> {
     active: T | undefined;
 }
@@ -35,6 +35,17 @@ declare class ZoneAggregator extends AZone<Map<AZone<unknown>, unknown>> {
     delete(z: AZone<unknown>): void;
     clear(): void;
 }
+/**
+ * Aggregator of zones that should be preserved across async boundaries.
+ * If you add a zone here, it will be preserved across async boundaries.
+ *
+ * @example
+ * ```ts
+ * import { Zone, asyncZone } from 'mutts'
+ * const userZone = new Zone<User>()
+ * asyncZone.add(userZone)
+ * ```
+ */
 declare const asyncZone: ZoneAggregator;
 
 /**
@@ -54,7 +65,7 @@ interface EffectAccess {
      * })
      * ```
      */
-    tracked: FunctionWrapper;
+    tracked: GetterWrapper;
     /**
      * Tracks dependencies in the parent effect context
      * Use this when child effects should track dependencies in the parent,
@@ -72,36 +83,82 @@ interface EffectAccess {
      * })
      * ```
      */
-    ascend: FunctionWrapper;
+    ascend: GetterWrapper;
     /**
-     * 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
+     * `false` on the first execution, `true` or `CleanupReason` on subsequent runs.
+     * `true` means this is a re-run but detailed reason gathering is disabled or unavailable.
+     * A `CleanupReason` describes *why* the previous run was torn down.
      * @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
+     *     // First run — setup
+     *   } else if (reaction !== true && reaction.type === 'propChange') {
+     *     // Re-run due to dependency change (with details)
+     *     for (const { evolution } of reaction.triggers)
+     *       console.log(`${'prop' in evolution ? evolution.prop : evolution.method}: ${evolution.type}`)
      *   }
      * })
      * ```
      */
-    reaction: boolean;
+    reaction: boolean | CleanupReason;
+    /**
+     * AbortSignal that is aborted when the effect is cleaned up or re-runs.
+     * Use this to cancel async operations (like fetch) when the effect is no longer valid.
+     */
+    signal: AbortSignal;
 }
 /**
  * Base type for effect callbacks - simple function without additional properties
  */
-type ScopedCallback = () => void;
+type ScopedCallback = (reason?: CleanupReason) => void;
+type PropTrigger = {
+    obj: object;
+    evolution: Evolution;
+    dependency?: unknown;
+    touch?: unknown;
+};
 /**
- * Type for effect cleanup functions with stopped state tracking
+ * Reason for an effect cleanup/reaction
  */
-type EffectCleanup = ScopedCallback & {
-    [stopped]: boolean;
+type CleanupReason = {
+    type: 'propChange';
+    triggers: PropTrigger[];
+} | {
+    type: 'invalidate';
+    cause: CleanupReason;
+} | {
+    type: 'stopped';
+    detail?: string;
+} | {
+    type: 'gc';
+} | {
+    type: 'lineage';
+    parent: CleanupReason;
+} | {
+    type: 'error';
+    error: unknown;
+} | {
+    type: 'multiple';
+    reasons: CleanupReason[];
 };
+/**
+ * Console-friendly description of a `CleanupReason`.
+ * Returns an array of arguments to spread into `console.log` / `console.warn`,
+ * mixing strings and raw object references so the console can render them as inspectable values.
+ *
+ * @example
+ * ```typescript
+ * effect(({ reaction }) => {
+ *   if (reaction !== true) console.log(...formatCleanupReason(reaction))
+ * })
+ * ```
+ */
+declare function formatCleanupReason(reason: CleanupReason, depth?: number): unknown[];
+/**
+ * Type for effect cleanup functions.
+ */
+type EffectCleanup = ScopedCallback;
 /**
  * Type for the `runEffect` function of an effect - argument-less function to call to trigger the effect
  */
@@ -156,57 +213,48 @@ 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;
-}
+type EffectCloser = (reason?: CleanupReason) => void;
+type CatchFunction = (error: unknown) => EffectCloser | undefined | void;
 /**
  * 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"
+    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;
+    causalChain?: string[];
+    lineage?: unknown;
 };
 type MaxDepthDebugInfo = {
     code: ReactiveErrorCode.MaxDepthExceeded;
-    depth: number;
-    chain: string[];
+    effectuatedRoots: any[];
+    cycle: any[] | null;
+    trace: string;
+    maxEffectChain: number;
+    queued: string[];
+    queuedCount: number;
+    causalChain?: string[];
+    lineage?: unknown;
 };
 type MaxReactionDebugInfo = {
     code: ReactiveErrorCode.MaxReactionExceeded;
     count: number;
     effect: string;
+    causalChain?: string[];
+    lineage?: unknown;
 };
 type GenericDebugInfo = {
     code: ReactiveErrorCode;
     causalChain?: string[];
-    creationStack?: string | any[];
-    lineage?: any[];
+    lineage?: unknown;
     [key: string]: any;
 };
 type ReactiveDebugInfo = CycleDebugInfo | MaxDepthDebugInfo | MaxReactionDebugInfo | GenericDebugInfo;
@@ -256,13 +304,19 @@ declare const options: {
      * @param props - The properties that changed
      * @param deps - The dependencies that changed
      */
-    touched: (_obj: any, _evolution: Evolution, _props?: any[], _deps?: Set<EffectTrigger>) => void;
+    touched: (_obj: any, _evolution: Evolution, _props?: any[], _deps?: 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: called when an effect starts executing.
+     * @param effect - The effect being executed (root function)
+     * @param reaction - false for initial creation, true/CleanupReason for subsequent runs
+     */
+    effectRun: (_effect: Function, _reaction: boolean | CleanupReason) => void;
     /**
      * Debug purpose: maximum effect chain (like call stack max depth)
      * Used to prevent infinite loops
@@ -366,49 +420,41 @@ declare const options: {
     asyncMode: AsyncExecutionMode | false;
     warn: (...args: any[]) => void;
     /**
-     * Configuration for the introspection system
+     * Introspection and debug aids. Set to `null` to disable all debug overhead in production.
+     *
+     * - `gatherReasons`: collect `PropTrigger[]` for `CleanupReason` on effect re-runs (default `true`)
+     *   - `lineages`: what lineages to capture in PropTrigger (default `'touch'`)
+     * - `logErrors`: log errors with detailed context (default `true`)
+     * - `enableHistory`: keep a history of mutations (default `true`)
+     * - `historySize`: number of mutations to keep in history (default `50`)
+     *
+     * `enableDevTools()` sets `logErrors` to `true` automatically.
+     *
+     * @example
+     * ```typescript
+     * // Production: disable all introspection
+     * reactiveOptions.introspection = null
+     * ```
      */
     introspection: {
-        /**
-         * Whether to keep a history of mutations for debugging
-         * @default false
-         */
+        gatherReasons: {
+            lineages: "none" | "touch" | "dependency" | "both";
+        };
+        logErrors: boolean;
         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;
-    };
+    } | null;
 };
+/** Production preset: no introspection, heuristic cycle detection, minimal overhead */
+declare const prodPreset: Partial<typeof options>;
+/** Development preset (default): introspection on, early cycle detection, warnings */
+declare const devPreset: Partial<typeof options>;
+/** Debug preset: full diagnostics, throws on violations, rich lineage capture */
+declare const debugPreset: Partial<typeof options>;
+declare const objectToProxy: WeakMap<object, object>;
+declare const proxyToObject: WeakMap<object, object>;
+declare function unwrap<T>(obj: T): T;
+declare function isReactive(obj: any): 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 };
+export { AZone as A, ReactiveError as R, ZoneAggregator as Z, ReactiveErrorCode as h, Zone as i, ZoneHistory as j, asyncZone as k, debugPreset as l, devPreset as m, formatCleanupReason as n, isReactive as o, objectToProxy as p, prodPreset as q, proxyToObject as r, options as s, unwrap as u };
+export type { CleanupReason as C, EffectTrigger as E, GetterWrapper as G, HistoryValue as H, PropTrigger as P, ScopedCallback as S, Evolution as a, EffectCleanup as b, EffectAccess as c, EffectCloser as d, State as e, CatchFunction as f, EffectOptions as g };

package/docs/ai/api-reference.md

@@ -46,6 +46,7 @@ export declare function untracked<T>(fn: () => T): T;
 // --------------------------------------------------------------------------------
 
 export declare function atomic<T extends (...args: any[]) => any>(fn: T): T;
+export declare function atom<T>(fn: () => T): T;
 export declare function memoize<Result, Args extends any[]>(fn: (...args: Args) => Result, maxArgs?: number): (...args: Args) => Result;
 export declare function deepWatch(source: any, callback: (path: string[], value: any) => void): () => void;
 export declare function biDi<T>(target: (val: T) => void, source: { get: () => T, set: (v: T) => void }): (val: T) => void;
@@ -54,20 +55,6 @@ export declare function biDi<T>(target: (val: T) => void, source: { get: () => T
 // COLLECTIONS
 // --------------------------------------------------------------------------------
 
-export interface Register<T, K extends PropertyKey = PropertyKey> extends Iterable<T> {
-    length: number;
-    [index: number]: T;
-    get(key: K): T | undefined;
-    set(key: K, value: T): void;
-    hasKey(key: K): boolean;
-    indexOfKey(key: K): number;
-    remove(key: K): void;
-    removeAt(index: number): T | undefined;
-    push(...items: T[]): number;
-    // ... complete array methods are supported
-}
-
-export declare function register<T, K extends PropertyKey = PropertyKey>(keyFn: (item: T) => K, initial?: Iterable<T>): Register<T, K>;
 export declare function project<S, R>(source: S, apply: (access: any, target: any) => any): R;
 export declare function organized<S, T>(source: S, apply: (access: any, target: T) => any, baseTarget?: T): T;
 
@@ -104,28 +91,20 @@ export declare function deprecated(message?: string): Function;
 // INTROSPECTION (AI Debugging)
 // --------------------------------------------------------------------------------
 
-export interface ReactivityGraph {
-    nodes: { id: string, label: string, type: 'effect'|'object' }[];
-    edges: { source: string, target: string, type: string }[];
-}
-
-export interface MutationRecord {
-    type: 'set' | 'add' | 'delete';
-    prop: PropertyKey;
-    oldValue: any;
-    newValue: any;
-    objectName?: string;
-}
+// See: 'mutts/debug' for programmatic access
+// buildReactivityGraph, getMutationHistory, getDependents, getDependencies, etc.
 
-export declare function getDependencyGraph(): ReactivityGraph;
-export declare function getMutationHistory(): MutationRecord[];
-export declare const options: {
+export declare const reactiveOptions: {
     cycleHandling: 'production' | 'development' | 'debug';
-    introspection: { enableHistory: boolean; historySize: number };
+    introspection: { enableHistory: boolean; historySize: number; logErrors: boolean };
 };
 
 export enum ReactiveErrorCode {
-    CYCLE_DETECTED = 'CYCLE_DETECTED',
-    MAX_DEPTH_EXCEEDED = 'MAX_DEPTH_EXCEEDED',
+    CycleDetected = 'Cycle detected',
+    MaxDepthExceeded = 'Max depth exceeded',
+    MaxReactionExceeded = 'Max reaction exceeded',
+    WriteInComputed = 'Write in computed',
+    TrackingError = 'Tracking error',
+    BrokenEffects = 'Broken effects',
 }
 ```