@but212/atom-effect 0.31.0 → 0.32.0

package/dist/core/lens.d.ts

@@ -0,0 +1,102 @@
+import { Equal, MergedDependencyValue, WritableAtom } from '../types';
+/**
+ * Logic: Numeric Key Conversion
+ * Casts numeric string literals to numbers for correct array index typing.
+ */
+export type StringKeyToNumber<S extends string> = S extends `${infer N extends number}` ? N : S;
+/**
+ * Logic: Broad Index Detection
+ * Detects if a type has a broad string indexer (e.g., Record<string, any>).
+ */
+export type HasBroadStringKey<T> = string extends keyof T ? true : false;
+/** @public */
+export type StringIndexValue<T> = T extends Record<string, infer V> ? V : never;
+/** @public */
+export type ArrayElement<T> = T extends readonly (infer U)[] ? U : never;
+/**
+ * Constraint: Depth limit for recursive path generation to prevent TypeScript
+ * recursion errors and IDE lag in complex schemas.
+ */
+export type MaxDepth = 8;
+/**
+ * Logic: Recursion Termination
+ * Types that stop the recursive path exploration.
+ */
+export type TerminalTypes = Date | RegExp | Map<unknown, unknown> | Set<unknown> | Promise<unknown> | Function;
+/**
+ * Computes a union of all valid dot-separated paths for type T.
+ *
+ * Constraint: If T has a broad string indexer, it returns `string` to avoid
+ * infinite union generation.
+ */
+export type Paths<T, D extends unknown[] = []> = Equal<T, any> extends true ? string : D['length'] extends MaxDepth ? never : T extends TerminalTypes ? never : T extends readonly unknown[] ? NonNullable<ArrayElement<T>> extends object ? `${number}` | `${number}.${Paths<NonNullable<ArrayElement<T>>, [...D, 1]>}` : `${number}` : T extends object ? HasBroadStringKey<T> extends true ? string : {
+    [K in keyof T & (string | number)]: T[K] extends Function ? never : NonNullable<T[K]> extends object ? `${K}` | `${K}.${Paths<NonNullable<T[K]>, [...D, 1]>}` : `${K}`;
+}[keyof T & (string | number)] : never;
+/**
+ * Resolves the type of a value at a given dot-path string.
+ */
+export type PathValue<T, P extends string> = Equal<T, any> extends true ? any : P extends `${infer K}.${infer Rest}` ? NonNullable<T> extends readonly unknown[] ? K extends `${number}` ? PathValue<NonNullable<ArrayElement<NonNullable<T>>>, Rest> : never : HasBroadStringKey<NonNullable<T>> extends true ? PathValue<NonNullable<StringIndexValue<NonNullable<T>>>, Rest> : StringKeyToNumber<K> extends keyof NonNullable<T> ? PathValue<NonNullable<NonNullable<T>[StringKeyToNumber<K> & keyof NonNullable<T>]>, Rest> : never : NonNullable<T> extends readonly unknown[] ? P extends `${number}` ? NonNullable<ArrayElement<NonNullable<T>>> : never : HasBroadStringKey<NonNullable<T>> extends true ? NonNullable<StringIndexValue<NonNullable<T>>> : StringKeyToNumber<P> extends keyof NonNullable<T> ? NonNullable<T>[StringKeyToNumber<P> & keyof NonNullable<T>] : never;
+/**
+ * Core engine for recursive immutable deep updates.
+ *
+ * Optimization: Net-zero suppression
+ * Returns the original object if the leaf value is identical (Object.is),
+ * preventing unnecessary allocation and downstream notifications.
+ *
+ * @internal
+ */
+export declare function setDeepValue(obj: unknown, keys: string[], index: number, value: unknown): unknown;
+/**
+ * Reads a value from a nested path.
+ * Supports standard property access and Map.get().
+ *
+ * @internal
+ */
+export declare function getPathValue(source: unknown, parts: string[]): unknown;
+/**
+ * Creates a reactive, two-way Lens into a nested atom property.
+ *
+ * When to use:
+ * - When a component only needs a specific sub-field of a complex state object.
+ * - To implement "noise filtering": the lens only notifies subscribers if its
+ *   specific nested value changes, even if other parts of the root atom update.
+ * - For type-safe deep state management.
+ *
+ * @param atom - The root WritableAtom to project from.
+ * @param path - A dot-separated string representing the path to the nested property.
+ *
+ * @example
+ * const user = atom({ profile: { name: 'Alice', score: 10 } });
+ * const scoreLens = atomLens(user, 'profile.score');
+ *
+ * $.effect(() => console.log('Score:', scoreLens.value));
+ * scoreLens.value = 20; // Propagates to 'user' atom.
+ */
+export declare function atomLens<T extends object, P extends Paths<T>>(atom: WritableAtom<T>, path: P): WritableAtom<PathValue<T, P>>;
+/**
+ * Chains a lens with a further sub-path to create a more specific lens.
+ *
+ * @example
+ * const userLens = atomLens(rootAtom, 'user');
+ * const nameLens = composeLens(userLens, 'name');
+ */
+export declare const composeLens: <T extends object, P extends Paths<T>>(lens: WritableAtom<T>, path: P) => WritableAtom<PathValue<T, P>>;
+/**
+ * Creates a factory function for generating multiple lenses from a single root atom.
+ *
+ * @example
+ * const fromUser = lensFor(userAtom);
+ * const nameLens = fromUser('name');
+ * const ageLens = fromUser('age');
+ */
+export declare const lensFor: <T extends object>(atom: WritableAtom<T>) => <P extends Paths<T>>(path: P) => WritableAtom<PathValue<T, P>>;
+/**
+ * Merges multiple writable lenses into a single unified lens with a flattened type.
+ *
+ * This utility combines the value types of all input lenses into a single
+ * unified object type using the {@link Merge} utility.
+ *
+ * @param lenses - A variadic list of WritableAtoms (lenses).
+ */
+export declare function mergeLenses<L extends WritableAtom<unknown>[]>(...lenses: L): WritableAtom<MergedDependencyValue<L>>;
+//# sourceMappingURL=lens.d.ts.map

package/dist/core/lens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lens.d.ts","sourceRoot":"","sources":["../../src/core/lens.ts"],"names":[],"mappings":"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"}

package/dist/core/scheduler.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Generates the next version number for stateful objects (Atoms).
+ */
+export declare function nextVersion(v: number): number;
+export interface SchedulerJobObject {
+    execute(): void;
+    /** Internal epoch tracking to prevent redundant scheduling in a single cycle. @internal */
+    _nextEpoch?: number | undefined;
+}
+export interface SchedulerJobFunction {
+    (): void;
+    /** Internal epoch tracking to prevent redundant scheduling in a single cycle. @internal */
+    _nextEpoch?: number | undefined;
+}
+export type SchedulerJob = SchedulerJobFunction | SchedulerJobObject;
+/**
+ * Internal state for the scheduler.
+ * @internal
+ */
+export interface SchedulerState {
+    size: number;
+    epoch: number;
+    batchQueueSize: number;
+    state: number;
+    batchDepth: number;
+    maxFlushIterations: number;
+    sessionActive: boolean;
+    sessionEpoch: number;
+    sessionExecutionCount: number;
+    /** Primary queue for the current flush cycle. */
+    activeBuffer: (SchedulerJob | undefined)[];
+    /** Secondary queue to collect new jobs scheduled during the current flush. */
+    standbyBuffer: (SchedulerJob | undefined)[];
+    /** Queue for jobs scheduled during a batch session. */
+    batchBuffer: (SchedulerJob | undefined)[];
+    onOverflow: ((droppedCount: number) => void) | null;
+}
+/**
+ * Factory for scheduler state.
+ * @internal
+ */
+export declare function createSchedulerState(): SchedulerState;
+/**
+ * Logic: Batch Queue Consolidation
+ * Moves jobs from the batch buffer to the active execution queue.
+ * @internal
+ */
+export declare function schedulerMergeBatchQueue(state: SchedulerState, nextEpoch: () => number): void;
+/**
+ * Logic: Recursive Queue Drainage
+ * Continuously flushes the queues until no more jobs are pending.
+ *
+ * Caution: Subject to maxFlushIterations to prevent infinite loops from circular dependencies.
+ * @internal
+ */
+export declare function schedulerDrainQueue(state: SchedulerState, nextEpoch: () => number, processQueue: (state: SchedulerState) => void, handleOverflow: (state: SchedulerState) => void): void;
+/**
+ * Logic: Double-Buffering Job Execution
+ * Swaps active/standby buffers to allow safe scheduling during execution.
+ * @internal
+ */
+export declare function schedulerProcessQueue(state: SchedulerState, nextEpoch: () => number): void;
+/**
+ * Logic: Overflow Recovery
+ * Cleans up state when the maximum flush iterations are exceeded.
+ * @internal
+ */
+export declare function schedulerHandleFlushOverflow(state: SchedulerState): void;
+/** @internal */
+export declare function schedulerNextEpoch(state: SchedulerState): number;
+/** @internal */
+export declare function schedulerStartFlush(state: SchedulerState): boolean;
+/** @internal */
+export declare function schedulerEndFlush(state: SchedulerState): void;
+/** @internal */
+export declare function schedulerIncrementFlushExecutionCount(state: SchedulerState): number;
+/** @internal */
+export declare function schedulerResetFlushState(state: SchedulerState): void;
+/**
+ * Core scheduling logic. Decisions between microtask or synchronous flush are made here.
+ * @internal
+ */
+export declare function schedulerSchedule(state: SchedulerState, callback: SchedulerJob): void;
+/**
+ * Forcefully flushes all pending jobs synchronously.
+ * @internal
+ */
+export declare function schedulerFlushSync(state: SchedulerState): void;
+/** @internal */
+export declare function schedulerStartBatch(state: SchedulerState): void;
+/** @internal */
+export declare function schedulerEndBatch(state: SchedulerState): void;
+/** @internal */
+export declare function schedulerSetMaxFlushIterations(state: SchedulerState, max: number): void;
+/** @internal */
+export declare function schedulerIsBatching(state: SchedulerState): boolean;
+/** @internal */
+export declare function schedulerQueueSize(state: SchedulerState): number;
+export declare const scheduler: SchedulerState;
+export declare const nextEpoch: () => number;
+export declare const currentEpoch: () => number;
+export declare const currentFlushEpoch: () => number;
+export declare const startFlush: () => boolean;
+export declare const endFlush: () => void;
+export declare const incrementFlushExecutionCount: () => number;
+export declare const resetFlushState: () => void;
+/**
+ * Groups multiple state updates into a single atomic change and flushes them synchronously.
+ *
+ * When to use:
+ * - Ensuring that all effects triggered by state changes are executed immediately before the function returns (Synchronous Settlement).
+ * - Creating a transactional scope where multiple updates are treated as one unit and settled predictably.
+ *
+ * @example
+ * ```typescript
+ * batch(() => {
+ *   atomA.set(1);
+ *   atomB.set(2);
+ * });
+ * // At this point, all triggered effects have already finished executing.
+ * ```
+ */
+export declare function batch<T>(fn: () => T): T;
+/**
+ * Scopes a function execution within a flush lifecycle.
+ * Ensures the scheduler state is cleaned up even if the provided function throws.
+ * @internal
+ */
+export declare function runInFlushScope<T>(fn: () => T): T | undefined;
+/**
+ * Returns a promise that resolves after the next scheduler flush.
+ *
+ * When to use:
+ * - Waiting for effects to finish in tests after state updates.
+ * - Synchronizing logic with the reactive system's "settled" state.
+ *
+ * @example
+ * ```typescript
+ * atom.set(100);
+ * await aeNextTick();
+ * // DOM or side effects are now guaranteed to be updated.
+ * ```
+ */
+export declare function aeNextTick(fn?: () => void): Promise<void>;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/core/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/core/scheduler.ts"],"names":[],"mappings":"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"}

package/dist/core/tracking.d.ts

@@ -0,0 +1,123 @@
+import { Dependency, Subscriber } from '../types';
+/**
+ * Interface for nodes capable of recording reactive dependencies during execution.
+ * @internal
+ *
+ * Reason: Decouples dependency collection from the specific node implementation,
+ * allowing any object to participate in tracking as long as it can record dependencies.
+ */
+export interface DependencySubscriber {
+    addDependency(dep: Dependency): void;
+}
+/**
+ * Interface for nodes that can be scheduled for re-execution.
+ * @internal
+ *
+ * Reason: Provides a unified interface for the scheduler to trigger updates
+ * without knowing the internal logic of the node.
+ */
+export interface ExecutableSubscriber {
+    execute(): void;
+}
+/**
+ * Unified interface for nodes that both consume dependencies and execute logic.
+ * (e.g., Effects, Computed Atoms, Observers)
+ * @internal
+ */
+export interface DependencyTracker extends DependencySubscriber, ExecutableSubscriber {
+}
+/**
+ * Represents a single directed edge in the dependency graph (Subscriber -> Dependency).
+ * @internal
+ *
+ * Logic: Includes a version field to implement efficient stale checks.
+ * If the dependency's version doesn't match this version, the subscriber may need re-evaluation.
+ */
+export interface DependencyLink {
+    /** The node being watched. */
+    node: Dependency;
+    /** The version of the node when this link was established. */
+    version: number;
+    /** Cleanup function returned by the dependency. */
+    unsub: (() => void) | undefined;
+}
+/** @internal */
+export declare function createDependencyLink(node: Dependency, version: number, unsub?: (() => void) | undefined): DependencyLink;
+/**
+ * A handle for an active listener on a reactive node.
+ * Supports both raw callbacks and internal graph subscribers.
+ * @internal
+ */
+export interface Subscription<T> {
+    /** Raw callback for external listeners. */
+    fn: ((newValue?: T, oldValue?: T) => void) | undefined;
+    /** Internal subscriber for graph-based updates. */
+    sub: Subscriber | undefined;
+}
+/** @internal */
+export declare function createSubscription<T>(fn?: ((newValue?: T, oldValue?: T) => void) | undefined, sub?: Subscriber | undefined): Subscription<T>;
+/** @internal */
+export declare function notifySubscription<T>(subscription: Subscription<T> | null, newValue?: T, oldValue?: T): void;
+/**
+ * Internal state for the reactive tracking system.
+ * @internal
+ *
+ * Logic: Stack-based approach
+ * The stack enables nested tracking. When a computed atom is read inside an effect,
+ * the computed atom becomes the 'current' subscriber while it calculates its value,
+ * and the effect is restored as 'current' after the computation finishes.
+ */
+export interface TrackingContext {
+    stack: (DependencySubscriber | null)[];
+    current: DependencySubscriber | null;
+}
+/** @internal */
+export declare function createTrackingContext(): TrackingContext;
+/** @internal */
+export declare function pushTrackingSubscriber(context: TrackingContext, subscriber: DependencySubscriber | null): void;
+/** @internal */
+export declare function popTrackingSubscriber(context: TrackingContext): void;
+/**
+ * Resets the tracking stack to a specific depth.
+ * @internal
+ *
+ * Reason: Used during error recovery or transaction rollbacks where
+ * the execution stack might be corrupted or partially executed.
+ */
+export declare function rollbackTrackingSubscriber(context: TrackingContext, depth: number): void;
+/**
+ * Executes a function within the scope of a specific subscriber.
+ * @internal
+ */
+export declare function runInTrackingContext<T>(context: TrackingContext, subscriber: DependencySubscriber, fn: () => T): T;
+/** @internal */
+export declare function resetTrackingContext(context: TrackingContext): void;
+export declare const trackingContext: TrackingContext;
+/**
+ * Executes a function scope where reactive dependencies are ignored.
+ *
+ * When to use:
+ * - Accessing atom values inside an effect or computed without creating a dependency.
+ * - Performing side-effects (logging, analytics) that shouldn't trigger re-runs.
+ * - Breaking circular dependencies by reading a value "silently".
+ *
+ * @param fn - The function to execute in an untracked scope.
+ * @returns The result of the function.
+ *
+ * @example
+ * ```typescript
+ * const count = atom(0);
+ * effect(() => {
+ *   // This effect only runs when count changes.
+ *   const current = count.value;
+ *
+ *   untracked(() => {
+ *     // This read does NOT create a dependency.
+ *     // It won't cause the effect to re-run if logging was reactive.
+ *     console.log('Logging untracked value:', count.value);
+ *   });
+ * });
+ * ```
+ */
+export declare function untracked<T>(fn: () => T): T;
+//# sourceMappingURL=tracking.d.ts.map

package/dist/core/tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking.d.ts","sourceRoot":"","sources":["../../src/core/tracking.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,aAAa,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;CACtC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,oBAAoB,EAAE,oBAAoB;CAAG;AAExF;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,IAAI,EAAE,UAAU,CAAC;IACjB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,KAAK,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;CACjC;AAED,gBAAgB;AAChB,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAqB,GAC1C,cAAc,CAEhB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,2CAA2C;IAC3C,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IACvD,mDAAmD;IACnD,GAAG,EAAE,UAAU,GAAG,SAAS,CAAC;CAC7B;AAED,gBAAgB;AAChB,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,EAAE,GAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,KAAK,IAAI,CAAC,GAAG,SAAqB,EAClE,GAAG,GAAE,UAAU,GAAG,SAAqB,GACtC,YAAY,CAAC,CAAC,CAAC,CAEjB;AAED,gBAAgB;AAChB,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,EACpC,QAAQ,CAAC,EAAE,CAAC,EACZ,QAAQ,CAAC,EAAE,CAAC,GACX,IAAI,CAaN;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,CAAC,oBAAoB,GAAG,IAAI,CAAC,EAAE,CAAC;IACvC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAAC;CACtC;AAED,gBAAgB;AAChB,wBAAgB,qBAAqB,IAAI,eAAe,CAEvD;AAED,gBAAgB;AAChB,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,eAAe,EACxB,UAAU,EAAE,oBAAoB,GAAG,IAAI,GACtC,IAAI,CAGN;AAED,gBAAgB;AAChB,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAKpE;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAKxF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,OAAO,EAAE,eAAe,EACxB,UAAU,EAAE,oBAAoB,EAChC,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAUH;AAED,gBAAgB;AAChB,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAGnE;AAED,eAAO,MAAM,eAAe,iBAA0B,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAS3C"}

package/dist/errors.d.ts

@@ -0,0 +1,163 @@
+/**
+ * A structured JSON representation of an `AtomError` for cross-context transport.
+ */
+export interface AtomErrorJSON {
+    /** The specific name of the error class. */
+    name: string;
+    /** The human-readable error message. */
+    message: string;
+    /** Machine-readable error identifier. */
+    code?: string | undefined;
+    /** When true, the reactive engine may attempt re-execution. */
+    recoverable: boolean;
+    /** Trace information. */
+    stack?: string | undefined;
+    /** The underlying cause resolved into a plain object or primitive. */
+    cause?: unknown | undefined;
+}
+/**
+ * Constructor signature for system-branded error classes.
+ * @internal
+ */
+export type AtomErrorConstructor = new (message: string, cause?: unknown, recoverable?: boolean, code?: string) => AtomError;
+/**
+ * The base error class for the reactive system.
+ *
+ * Logic: Execution Context Traceability
+ * Maintains a causal chain (`cause`) to allow developers to trace errors
+ * through multiple layers of atoms, computed nodes, and effects.
+ *
+ * When to use:
+ * - To define custom error categories within the engine.
+ * - To wrap third-party errors with system-specific metadata.
+ *
+ * @example
+ * ```typescript
+ * import { AtomError } from '@but212/atom-effect';
+ *
+ * throw new AtomError(
+ *   'Validation failed',
+ *   rawInput,
+ *   true,
+ *   'ERR_VAL_001'
+ * );
+ * ```
+ */
+export declare class AtomError extends Error {
+    /** The raw value or error that triggered this instance. */
+    readonly cause: unknown;
+    /**
+     * Logic: Error Recovery
+     * When true, indicate that the state might be corrected by a subsequent
+     * update. When false, the node is considered permanently failed.
+     */
+    readonly recoverable: boolean;
+    /** Unique category identifier for programmatic handling. */
+    readonly code?: string | undefined;
+    readonly name: string;
+    constructor(message: string, 
+    /** The raw value or error that triggered this instance. */
+    cause?: unknown, 
+    /**
+     * Logic: Error Recovery
+     * When true, indicate that the state might be corrected by a subsequent
+     * update. When false, the node is considered permanently failed.
+     */
+    recoverable?: boolean, 
+    /** Unique category identifier for programmatic handling. */
+    code?: string | undefined);
+    /**
+     * Retrieves the full sequence of causal errors.
+     *
+     * Logic: Trace Reconstruction
+     * Recursively traverses the `.cause` property while protecting against
+     * infinite loops caused by circular error chains.
+     *
+     * @returns Sequential array of errors, starting from the current instance.
+     */
+    getChain(): Array<AtomError | Error | unknown>;
+    /**
+     * Logic: Safe Serialization
+     * Converts the error into a plain JSON object.
+     * Automatically replaces circular references with a sentinel message to
+     * prevent serialization crashes in loggers.
+     */
+    toJSON(seen?: Set<unknown>): AtomErrorJSON;
+    /**
+     * Formatting utility for internal diagnostic messages.
+     * @internal
+     */
+    static format(source: string, context: string, message: string): string;
+}
+/**
+ * Thrown during the evaluation phase of a computed atom.
+ */
+export declare class ComputedError extends AtomError {
+    readonly name = "ComputedError";
+}
+/**
+ * Thrown during the execution or cleanup phase of a reactive effect.
+ * Typically represents a side-effect failure.
+ */
+export declare class EffectError extends AtomError {
+    readonly name = "EffectError";
+    constructor(message: string, cause?: unknown, recoverable?: boolean, code?: string);
+}
+/**
+ * Thrown by the internal engine when scheduling or flush limits are violated.
+ */
+export declare class SchedulerError extends AtomError {
+    readonly name = "SchedulerError";
+    constructor(message: string, cause?: unknown, recoverable?: boolean, code?: string);
+}
+/**
+ * Central registry of standardized error messages.
+ *
+ * When to use:
+ * - To ensure consistent diagnostic output.
+ * - To identify specific failure conditions during unit testing.
+ */
+export declare const ERROR_MESSAGES: {
+    readonly COMPUTED_MUST_BE_FUNCTION: "Computed target must be a function";
+    readonly COMPUTED_ASYNC_PENDING_NO_DEFAULT: "Async computation pending with no default value";
+    readonly COMPUTED_COMPUTATION_FAILED: "Computation execution failed";
+    readonly COMPUTED_ASYNC_COMPUTATION_FAILED: "Async computation execution failed";
+    readonly COMPUTED_CIRCULAR_DEPENDENCY: "Circular dependency detected";
+    readonly COMPUTED_DISPOSED: "Attempted to access disposed computed";
+    readonly ATOM_SUBSCRIBER_MUST_BE_FUNCTION: "Subscriber must be a function or Subscriber object";
+    readonly ATOM_INDIVIDUAL_SUBSCRIBER_FAILED: "Subscriber execution failed";
+    readonly EFFECT_MUST_BE_FUNCTION: "Effect target must be a function";
+    readonly EFFECT_EXECUTION_FAILED: "Effect execution failed";
+    readonly EFFECT_CLEANUP_FAILED: "Effect cleanup failed";
+    readonly EFFECT_DISPOSED: "Attempted to run disposed effect";
+    /** Returns a formatted message for flush overflow limits. */
+    readonly SCHEDULER_FLUSH_OVERFLOW: (max: number, dropped: number) => string;
+    readonly CALLBACK_ERROR_IN_ERROR_HANDLER: "Exception encountered in onError handler";
+    /** Logic: Loop Protection */
+    readonly EFFECT_FREQUENCY_LIMIT_EXCEEDED: "Effect executed too frequently within 1 second. Suspected infinite loop.";
+    readonly SCHEDULER_CALLBACK_MUST_BE_FUNCTION: "Scheduler callback must be a function";
+    readonly SCHEDULER_END_BATCH_WITHOUT_START: "endBatch() called without matching startBatch(). Ignoring.";
+    readonly BATCH_CALLBACK_MUST_BE_FUNCTION: "Batch callback must be a function";
+};
+/**
+ * Normalizes an unknown error into the system's error hierarchy.
+ *
+ * When to use:
+ * - In `catch` blocks within the engine to ensure cross-module traceability.
+ * - To wrap user-provided callbacks with appropriate context (e.g., 'Effect Phase').
+ *
+ * @param error - The raw error value to wrap.
+ * @param ErrorClass - The targeted `AtomError` subclass.
+ * @param context - Label describing the origin of the failure.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   fn();
+ * } catch (err) {
+ *   throw wrapError(err, EffectError, 'Effect Execution');
+ * }
+ * ```
+ */
+export declare function wrapError(error: unknown, ErrorClass: AtomErrorConstructor, context: string): AtomError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,+DAA+D;IAC/D,WAAW,EAAE,OAAO,CAAC;IACrB,yBAAyB;IACzB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,KACjC,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO,EACf,WAAW,CAAC,EAAE,OAAO,EACrB,IAAI,CAAC,EAAE,MAAM,KACV,SAAS,CAAC;AAEf;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAKhC,2DAA2D;aAC3C,KAAK,EAAE,OAAO;IAC9B;;;;OAIG;aACa,WAAW,EAAE,OAAO;IACpC,4DAA4D;aAC5C,IAAI,CAAC,EAAE,MAAM;IAb/B,SAAkB,IAAI,EAAE,MAAM,CAAe;gBAG3C,OAAO,EAAE,MAAM;IACf,2DAA2D;IAC3C,KAAK,GAAE,OAAc;IACrC;;;;OAIG;IACa,WAAW,GAAE,OAAc;IAC3C,4DAA4D;IAC5C,IAAI,CAAC,EAAE,MAAM,YAAA;IAc/B;;;;;;;;OAQG;IACH,QAAQ,IAAI,KAAK,CAAC,SAAS,GAAG,KAAK,GAAG,OAAO,CAAC;IAa9C;;;;;OAKG;IACH,MAAM,CAAC,IAAI,GAAE,GAAG,CAAC,OAAO,CAAa,GAAG,aAAa;IAqBrD;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;CAGxE;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC1C,SAAkB,IAAI,mBAAmB;CAC1C;AAED;;;GAGG;AACH,qBAAa,WAAY,SAAQ,SAAS;IACxC,SAAkB,IAAI,iBAAiB;gBAE3B,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,OAAc,EAAE,WAAW,UAAQ,EAAE,IAAI,CAAC,EAAE,MAAM;CAGvF;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,SAAS;IAC3C,SAAkB,IAAI,oBAAoB;gBAE9B,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,OAAc,EAAE,WAAW,UAAQ,EAAE,IAAI,CAAC,EAAE,MAAM;CAGvF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;IAoBzB,6DAA6D;6CAC7B,MAAM,WAAW,MAAM,KAAG,MAAM;;IAKhE,6BAA6B;;;;;CAM8C,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,oBAAoB,EAChC,OAAO,EAAE,MAAM,GACd,SAAS,CASX"}