mutts 1.0.8 → 1.0.10

package/dist/{reactive/types.d.ts → types-W5vD6m2n.d.ts}

@@ -1,9 +1,47 @@
-import { FunctionWrapper } from "../zone";
+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;
+
 /**
- * Dependency access passed to user callbacks within effects/watch
+ * Effect access passed to user callbacks within effects/watch
  * Provides functions to track dependencies and information about the effect execution
  */
-export interface DependencyAccess {
+interface EffectAccess {
     /**
      * Tracks dependencies in the current effect context
      * Use this for normal dependency tracking within the effect
@@ -36,39 +74,91 @@ export interface DependencyAccess {
      */
     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
+     * `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;
 }
 /**
- * Type for effect cleanup functions
+ * Base type for effect callbacks - simple function without additional properties
+ */
+type ScopedCallback = (reason?: CleanupReason) => void;
+type PropTrigger = {
+    obj: object;
+    evolution: Evolution;
+    dependency?: unknown;
+    touch?: unknown;
+};
+/**
+ * Reason for an effect cleanup/reaction
+ */
+type CleanupReason = {
+    type: 'propChange';
+    triggers: PropTrigger[];
+} | {
+    type: 'invalidate';
+    cause: CleanupReason;
+} | {
+    type: 'stopped';
+} | {
+    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))
+ * })
+ * ```
  */
-export type ScopedCallback = () => void;
+declare function formatCleanupReason(reason: CleanupReason, depth?: number): unknown[];
+/**
+ * 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
  */
-export type AsyncExecutionMode = 'cancel' | 'queue' | 'ignore';
+type AsyncExecutionMode = 'cancel' | 'queue' | 'ignore';
 /**
  * Options for effect creation
  */
-export interface EffectOptions {
+interface EffectOptions {
     /**
      * How to handle async effect executions when dependencies change
      * @default 'cancel'
@@ -80,103 +170,91 @@ export interface EffectOptions {
      * 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
  */
-export type PropEvolution = {
+type PropEvolution = {
     type: 'set' | 'del' | 'add' | 'invalidate';
     prop: any;
 };
 /**
  * Type for collection operation evolution events
  */
-export type BunchEvolution = {
+type BunchEvolution = {
     type: 'bunch';
     method: string;
 };
-export type Evolution = PropEvolution | BunchEvolution;
+type Evolution = PropEvolution | BunchEvolution;
 type State = {
     evolution: Evolution;
     next: State;
 } | {};
-declare const nativeReactive: unique symbol;
-/**
- * Symbol to mark individual objects as non-reactive
- */
-export declare const nonReactiveMark: unique symbol;
-/**
- * Symbol to mark class properties as non-reactive
- */
-export declare const unreactiveProperties: unique symbol;
-/**
- * Symbol representing all properties in reactive tracking
- */
-export declare const allProps: unique symbol;
-/**
- * Symbol for accessing projection information on reactive objects
- */
-export declare const projectionInfo: unique symbol;
 /**
  * Symbol to check if an effect is stopped
  */
-export declare const stopped: unique symbol;
+declare const stopped: unique symbol;
 /**
  * Symbol to access effect cleanup function
  */
-export declare const cleanup: unique symbol;
-/**
- * Context for a running projection item effect
- */
-export interface ProjectionContext {
-    source: any;
-    key?: any;
-    target: any;
-    depth: number;
-    parent?: ProjectionContext;
-}
-declare const rootFunction: unique symbol;
+declare const cleanup: unique symbol;
+type EffectCloser = (reason?: CleanupReason) => void;
+type CatchFunction = (error: any) => EffectCloser | undefined | void;
 /**
  * Structured error codes for machine-readable diagnosis
  */
-export declare enum ReactiveErrorCode {
-    CycleDetected = "CYCLE_DETECTED",
-    MaxDepthExceeded = "MAX_DEPTH_EXCEEDED",
-    MaxReactionExceeded = "MAX_REACTION_EXCEEDED",
-    WriteInComputed = "WRITE_IN_COMPUTED",
-    TrackingError = "TRACKING_ERROR",
-    BrokenEffects = "BROKEN_EFFECTS"
+declare enum ReactiveErrorCode {
+    CycleDetected = "Cycle detected",
+    MaxDepthExceeded = "Max depth exceeded",
+    MaxReactionExceeded = "Max reaction exceeded",
+    WriteInComputed = "Write in computed",
+    TrackingError = "Tracking error",
+    BrokenEffects = "Broken effects"
 }
-export type CycleDebugInfo = {
+type CycleDebugInfo = {
     code: ReactiveErrorCode.CycleDetected;
     cycle: string[];
     details?: string;
+    causalChain?: string[];
+    lineage?: unknown;
 };
-export type MaxDepthDebugInfo = {
+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;
 };
-export type MaxReactionDebugInfo = {
+type MaxReactionDebugInfo = {
     code: ReactiveErrorCode.MaxReactionExceeded;
     count: number;
     effect: string;
+    causalChain?: string[];
+    lineage?: unknown;
 };
-export type BrokenEffectsDebugInfo = {
-    code: ReactiveErrorCode.BrokenEffects;
-    cause: any;
-};
-export type GenericDebugInfo = {
+type GenericDebugInfo = {
     code: ReactiveErrorCode;
     causalChain?: string[];
-    creationStack?: string;
+    lineage?: unknown;
     [key: string]: any;
 };
-export type ReactiveDebugInfo = CycleDebugInfo | MaxDepthDebugInfo | MaxReactionDebugInfo | BrokenEffectsDebugInfo | GenericDebugInfo;
+type ReactiveDebugInfo = CycleDebugInfo | MaxDepthDebugInfo | MaxReactionDebugInfo | GenericDebugInfo;
 /**
  * Error class for reactive system errors
  */
-export declare class ReactiveError extends Error {
+declare class ReactiveError extends Error {
     debugInfo?: ReactiveDebugInfo;
     constructor(message: string, debugInfo?: ReactiveDebugInfo);
     get code(): ReactiveErrorCode | undefined;
@@ -185,7 +263,7 @@ export declare class ReactiveError extends Error {
 /**
  * Global options for the reactive system
  */
-export declare const options: {
+declare const options: {
     /**
      * Debug purpose: called when an effect is entered
      * @param effect - The effect that is entered
@@ -219,13 +297,13 @@ export declare const options: {
      * @param props - The properties that changed
      * @param deps - The dependencies that changed
      */
-    touched: (_obj: any, _evolution: Evolution, _props?: any[], _deps?: Set<ScopedCallback>) => 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: ScopedCallback) => void;
+    skipRunningEffect: (_effect: EffectTrigger) => void;
     /**
      * Debug purpose: maximum effect chain (like call stack max depth)
      * Used to prevent infinite loops
@@ -267,20 +345,20 @@ export declare const options: {
     /**
      * How to handle cycles detected in effect batches.
      *
-     * - `'none'` (Default): High-performance mode. Disables dependency graph maintenance and
+     * - `'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 execution counts).
+     *   Cycle detection is heuristic (uses maxEffectChain execution counts).
      *
-     * - `'throw'`: Traditional Topological Sorting. Guarantees dependency order and catches
-     *   circular dependencies mathematically before execution.
+     * - `'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.
      *
-     * - `'warn'`: Topological sorting, but logs a warning instead of throwing on cycles.
-     * - `'break'`: Topological sorting, but silently breaks cycles.
-     * - `'strict'`: Prevents cycle creation by checking the graph *during* dependency discovery.
+     * - `'debug'`: Full diagnostic mode with transitive closures and topological sorting.
+     *   Provides detailed cycle path reporting. Highest overhead but most informative for bug hunting.
      *
-     * @default 'none'
+     * @default 'production'
      */
-    cycleHandling: "none" | "throw" | "warn" | "break" | "strict";
+    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
@@ -329,20 +407,30 @@ export 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;
-    };
+    } | null;
     /**
      * Configuration for zone hooks - control which async APIs are hooked
      * Each option controls whether the corresponding async API is wrapped to preserve effect context
@@ -372,5 +460,10 @@ export declare const options: {
         queueMicrotask: boolean;
     };
 };
-export { type State, nativeReactive, rootFunction };
-//# sourceMappingURL=types.d.ts.map
+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 i, Zone as j, ZoneHistory as k, asyncZone as l, formatCleanupReason as m, isReactive as n, objectToProxy as o, proxyToObject as p, options as q, stopped as s, unwrap as u };
+export type { CatchFunction as C, EffectTrigger as E, FunctionWrapper as F, PropTrigger as P, ScopedCallback as S, Evolution as a, EffectCleanup as b, EffectCloser as d, EffectAccess as e, State as f, EffectOptions as g, CleanupReason as h };

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;
@@ -104,28 +105,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: {
-    cycleHandling: 'throw' | 'warn' | 'break' | 'strict';
-    introspection: { enableHistory: boolean; historySize: number };
+export declare const reactiveOptions: {
+    cycleHandling: 'production' | 'development' | 'debug';
+    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',
 }
 ```