@but212/atom-effect 0.29.0 → 0.30.0

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 /**
- * Async operation states.
+ * Async operation states for public API and high-level checks.
  */
-export declare const AsyncState: {
-    readonly IDLE: "idle";
-    readonly PENDING: "pending";
-    readonly RESOLVED: "resolved";
-    readonly REJECTED: "rejected";
-};
+export declare const AsyncState: Readonly<{
+    IDLE: "idle";
+    PENDING: "pending";
+    RESOLVED: "resolved";
+    REJECTED: "rejected";
+}>;
 
 /**
  * Async state values.
@@ -22,13 +22,41 @@ export declare type AsyncStateType = (typeof AsyncState)[keyof typeof AsyncState
 export declare function atom<T>(initialValue: T, options?: AtomOptions): WritableAtom<T>;
 
 /**
- * Base error class.
+ * Base error class for the Atom system.
+ * Designed for high performance, traceability, and cycle protection.
  */
 export declare class AtomError extends Error {
-    cause: Error | null;
-    recoverable: boolean;
+    readonly cause: unknown;
+    readonly recoverable: boolean;
+    readonly code?: string | undefined;
+    readonly name: string;
+    constructor(message: string, cause?: unknown, recoverable?: boolean, code?: string | undefined);
+    /**
+     * Returns the entire error chain as an array.
+     * Includes the circular node if a cycle is detected.
+     */
+    getChain(): Array<AtomError | Error | unknown>;
+    /**
+     * Serializes the error to a structured object for logging.
+     * Protected against circular references.
+     */
+    toJSON(seen?: Set<unknown>): AtomErrorJSON;
+    /**
+     * Internal helper to format wrapped messages consistently.
+     */
+    static format(source: string, context: string, message: string): string;
+}
+
+/**
+ * Structured JSON representation of an AtomError.
+ */
+declare interface AtomErrorJSON {
     name: string;
-    constructor(message: string, cause?: Error | null, recoverable?: boolean);
+    message: string;
+    code?: string | undefined;
+    recoverable: boolean;
+    stack?: string | undefined;
+    cause?: unknown | undefined;
 }
 
 /**
@@ -45,19 +73,31 @@ export declare function atomLens<T extends object, P extends Paths<T>>(atom: Wri
 /**
  * Atom options.
  */
-export declare interface AtomOptions {
+export declare interface AtomOptions<T = unknown> {
+    /** Optional name for debugging. */
+    name?: string;
     /** If true, subscribers are notified synchronously. Default: false (microtask scheduled). */
     sync?: boolean;
+    /** Equality check. */
+    equal?: (a: T, b: T) => boolean;
 }
 
 /**
- * Batches updates.
+ * Groups multiple state updates into a single batch, delaying effects and computations
+ * until the batch is closed.
  *
- * @param fn - Batch function.
- * @returns - Result of `fn`.
+ * @param fn - The function containing state updates.
+ * @returns The result of the function execution.
+ * @throws {TypeError} If fn is not a function.
  */
 export declare function batch<T>(fn: () => T): T;
 
+/**
+ * Global brand symbol for all reactive primitives.
+ * Uses a bitwise mask for high-performance type identification.
+ */
+declare const BRAND: unique symbol;
+
 /**
  * Composes an existing lens with a sub-path to create a deeper lens.
  */
@@ -77,7 +117,8 @@ export declare function computed<T>(fn: () => Promise<T>, options: ComputedOptio
 /**
  * Computed atom interface.
  */
-export declare interface ComputedAtom<T = unknown> extends ReadonlyAtom<T>, Disposable {
+export declare interface ComputedAtom<T = unknown> extends ReadonlyAtom<T>, Disposable_2 {
+    /* Excluded from this release type: [BRAND] */
     readonly state: AsyncStateType;
     readonly hasError: boolean;
     readonly lastError: Error | null;
@@ -89,18 +130,20 @@ export declare interface ComputedAtom<T = unknown> extends ReadonlyAtom<T>, Disp
     /** Invalidates atom. */
     invalidate(): void;
     dispose(): void;
+    [Symbol.dispose](): void;
 }
 
-/** Computed error. */
+/** Thrown when a computation fails. */
 export declare class ComputedError extends AtomError {
-    name: string;
-    constructor(message: string, cause?: Error | null);
+    readonly name = "ComputedError";
 }
 
 /**
  * Computed options.
  */
 export declare interface ComputedOptions<T = unknown> {
+    /** Optional name for debugging. */
+    name?: string;
     /** Equality check. */
     equal?: (a: T, b: T) => boolean;
     /** Initial value. */
@@ -114,33 +157,37 @@ export declare interface ComputedOptions<T = unknown> {
 /**
  * Debugging thresholds.
  */
-export declare const DEBUG_CONFIG: {
-    readonly WARN_INFINITE_LOOP: true;
-    readonly EFFECT_FREQUENCY_WINDOW: 1000;
-};
+export declare const DEBUG_CONFIG: Readonly<{
+    WARN_INFINITE_LOOP: true;
+    EFFECT_FREQUENCY_WINDOW: 1000;
+    LOOP_THRESHOLD: 100;
+}>;
 
-/**
- * Global debug controller singleton.
- */
-export declare const DEBUG_RUNTIME: DebugConfig;
-
-export declare interface DebugConfig {
+declare interface DebugConfig {
     enabled: boolean;
     warnInfiniteLoop: boolean;
     warn(condition: boolean, message: string): void;
-    attachDebugInfo(obj: object, type: string, id: number): void;
+    attachDebugInfo(obj: object, type: string, id: number, customName?: string): void;
     getDebugName(obj: object | null | undefined): string | undefined;
     getDebugType(obj: object | null | undefined): string | undefined;
+    trackUpdate(id: DependencyId, name?: string): void;
+    registerNode(node: object & {
+        id: DependencyId;
+    }): void;
+    dumpGraph(): Record<string, unknown>[];
 }
 
 /**
  * Dependency interface.
+ * Core contract for reactive nodes. All properties are required to ensure
+ * high-performance access within the engine.
  *
  * @remarks
  * Internal fields (`version`, `flags`, `_lastSeenEpoch`) are part of the
  * engine contract between reactive nodes and must not be mutated externally.
  */
-export declare interface Dependency {
+export declare interface Dependency<T = unknown> {
+    /* Excluded from this release type: [BRAND] */
     readonly id: DependencyId;
     /* Excluded from this release type: version */
     /* Excluded from this release type: flags */
@@ -152,17 +199,36 @@ export declare interface Dependency {
      * The listener may optionally receive the new and previous values.
      * @param listener - A callback or Subscriber object.
      */
-    subscribe(listener: ((newValue?: unknown, oldValue?: unknown) => void) | Subscriber): () => void;
-    /** Peek hook. */
-    peek?(): unknown;
-    /** Value accessor. */
-    value?: unknown;
+    subscribe(listener: ((newValue?: T, oldValue?: T) => void) | Subscriber): () => void;
+    /**
+     * Non-reactive read of the current value.
+     */
+    peek(): T;
+    /**
+     * Current value accessor.
+     */
+    readonly value: T;
 }
 
 /**
  * Dependency ID.
  */
-export declare type DependencyId = number;
+declare type DependencyId = number;
+
+/**
+ * Custom Disposable interface for explicit resource management.
+ */
+declare interface Disposable_2 {
+    /**
+     * Cleans up the object and releases resources.
+     */
+    dispose(): void;
+    /**
+     * Support for explicit resource management (TS 5.2+).
+     */
+    [Symbol.dispose](): void;
+}
+export { Disposable_2 as Disposable }
 
 /**
  * Creates and starts an effect.
@@ -173,19 +239,28 @@ export declare type DependencyId = number;
  */
 export declare function effect(fn: EffectFunction, options?: EffectOptions): EffectObject;
 
-/** Effect error. */
+/**
+ * Effect cleanup function.
+ */
+export declare type EffectCleanup = () => void;
+
+/** Thrown when an effect execution or cleanup fails. */
 export declare class EffectError extends AtomError {
-    name: string;
-    constructor(message: string, cause?: Error | null);
+    readonly name = "EffectError";
+    constructor(message: string, cause?: unknown, recoverable?: boolean, code?: string);
 }
 
 /**
- * Effect return type.
+ * Effect function type.
+ * Sync effects can return a cleanup function.
+ * Async effects can return a promise that resolves to a cleanup function or void.
  */
-export declare type EffectFunction = () => void | (() => void) | Promise<undefined | (() => void)>;
+export declare type EffectFunction = () => (void | EffectCleanup) | Promise<void | EffectCleanup>;
 
-export declare interface EffectObject extends Disposable {
+export declare interface EffectObject extends Disposable_2 {
+    /* Excluded from this release type: [BRAND] */
     dispose(): void;
+    [Symbol.dispose](): void;
     run(): void;
     readonly isDisposed: boolean;
     readonly executionCount: number;
@@ -205,10 +280,11 @@ export declare interface EffectOptions {
  */
 export declare function getPathValue(source: unknown, parts: string[]): unknown;
 
+/** Global scheduler instance. */
+export declare const globalScheduler: Scheduler_2;
+
 /**
  * Readonly atom check.
- *
- * @param obj - Object to check.
  */
 export declare function isAtom(obj: unknown): obj is ReadonlyAtom;
 
@@ -228,46 +304,33 @@ export declare function isEffect(obj: unknown): obj is EffectObject;
 export declare const lensFor: <T extends object>(atom: WritableAtom<T>) => <P extends Paths<T>>(path: P) => WritableAtom<PathValue<T, P>>;
 
 /** Max recursion depth for dot-paths. */
-export declare type MaxDepth = 8;
+declare type MaxDepth = 8;
 
 /**
  * Generates a union of all possible dot-separated paths for a given type T.
+ * Excludes prototype methods and stops at TerminalTypes.
  *
  * Used for `atomLens` to provide IDE autocomplete and type safety when
  * zooming into deeply nested reactive objects.
- *
- * @example
- * type User = { profile: { name: string } };
- * type P = Paths<User>; // "profile" | "profile.name"
  */
-export declare type Paths<T, D extends unknown[] = []> = D['length'] extends MaxDepth ? never : T extends object ? {
-    [K in keyof T & (string | number)]-?: `${K}` | (T[K] extends object ? `${K}.${Paths<T[K], [...D, 1]>}` : never);
+export declare type Paths<T, D extends unknown[] = []> = D['length'] extends MaxDepth ? never : T extends TerminalTypes ? never : T extends object ? {
+    [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 specific dot-path P within type T.
+ * Uses NonNullable to correctly handle optional (?) or nullable properties.
  *
  * Works in tandem with `Paths<T>` to ensure that lensed atoms have
  * the correct inferred type for the member they point to.
  */
-export declare type PathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? StringKeyToNumber<K> extends keyof T ? PathValue<T[StringKeyToNumber<K> & keyof T], Rest> : never : StringKeyToNumber<P> extends keyof T ? T[StringKeyToNumber<P> & keyof T] : never;
-
-export declare interface PoolStats {
-    acquired: number;
-    released: number;
-    rejected: {
-        frozen: number;
-        tooLarge: number;
-        poolFull: number;
-    };
-    leaked: number;
-    poolSize: number;
-}
+export declare type PathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? StringKeyToNumber<K> extends keyof NonNullable<T> ? PathValue<NonNullable<NonNullable<T>[StringKeyToNumber<K> & keyof NonNullable<T>]>, Rest> : never : StringKeyToNumber<P> extends keyof NonNullable<T> ? NonNullable<T>[StringKeyToNumber<P> & keyof NonNullable<T>] : never;
 
 /**
  * Readonly atom interface.
  */
 export declare interface ReadonlyAtom<T = unknown> {
+    /* Excluded from this release type: [BRAND] */
     /** The current value of the atom. */
     readonly value: T;
     /**
@@ -287,85 +350,125 @@ export declare interface ReadonlyAtom<T = unknown> {
 }
 
 /**
- * Scheduler implementation.
+ * The global debug singleton instance.
+ * Automatically switches between development and production implementations
+ * based on the environment configuration (IS_DEV).
+ *
+ * In production, this becomes a lightweight object with empty methods,
+ * allowing engines to inline or ignore calls, effectively providing zero overhead.
+ *
+ * @public
+ */
+export declare const runtimeDebug: DebugConfig;
+
+/**
+ * Core Scheduler that manages asynchronous and synchronous task execution.
+ *
+ * Features:
+ * - Double buffering for stable queue processing.
+ * - Automatic job deduplication via Epoch tagging.
+ * - Nested batching support with automatic coalescence.
+ * - Microsecond-level scheduling via queueMicrotask.
  */
 declare class Scheduler_2 {
-    /** Queue buffer */
-    _queueBuffer: [SchedulerJob[], SchedulerJob[]];
-    _bufferIndex: number;
-    _size: number;
-    /** Epoch counter */
-    _epoch: number;
-    /** State flags */
-    _isProcessing: boolean;
-    _isFlushingSync: boolean;
-    /** Batching state */
-    _batchDepth: number;
-    _batchQueue: SchedulerJob[];
-    _batchQueueSize: number;
-    /** Config */
-    _maxFlushIterations: number;
-    /** Overflow callback */
+    /** Double buffer to allow scheduling new jobs while processing the current queue. */
+    private _queueBuffer;
+    /** Pointer to the currently active buffer for ingestion. */
+    private _bufferIndex;
+    /** Current size of the active ingestion buffer. */
+    private _size;
+    /** Current internal epoch for job tagging. */
+    private _epoch;
+    /** Flag indicating the scheduler is currently draining a microtask loop. */
+    private _isProcessing;
+    /** Flag indicating a synchronous flush (batch end) is currently active. */
+    private _isFlushingSync;
+    /** Number of active nested batch contexts. */
+    private _batchDepth;
+    /** Temporary holding area for jobs scheduled during an active batch or sync flush. */
+    private _batchQueue;
+    /** Current number of jobs in the batch holding area. */
+    private _batchQueueSize;
+    /** Maximum allowed internal loop iterations before assuming an infinite loop. */
+    private _maxFlushIterations;
+    /** Optional callback fired when the scheduler drops jobs due to overflow. */
     onOverflow: ((droppedCount: number) => void) | null;
-    /** Bound run loop for microtask */
     private readonly _boundRunLoop;
+    /** Returns the total number of pending jobs (active + batched). */
     get queueSize(): number;
+    /** Returns true if the scheduler is currently within a `batch()` scope. */
     get isBatching(): boolean;
     /**
-     * Schedules job.
+     * Schedules a job for execution.
+     * Jobs are deduplicated based on the current epoch; if the same job is scheduled twice
+     * in the same epoch, the second call is ignored.
+     *
+     * @param callback - The task to be executed.
      */
     schedule(callback: SchedulerJob): void;
+    /** Initiates an asynchronous flush via microtask. */
+    private _flush;
+    /** Internal microtask execution loop. */
+    private _runLoop;
+    /** Internal synchronous flush typically triggered at the end of a batch. */
+    _flushSync(): void;
     /**
-     * Triggers flush.
+     * Merges the temporal batch queue into the main active buffer.
+     * Increments the epoch to allow previously executed jobs to be re-scheduled if needed.
      */
-    _flush(): void;
+    private _mergeBatchQueue;
     /**
-     * Scheduler loop.
+     * Continuous loop that drains both main and batch queues.
+     * Processes until all queues are empty or max iterations reached.
      */
-    private _runLoop;
-    _flushSync(): void;
-    _mergeBatchQueue(): void;
-    _drainQueue(): void;
-    _processQueue(): void;
+    private _drainQueue;
+    /** Executes all jobs currently in the primary buffer and swaps buffers. */
+    private _processQueue;
+    /** Resets the scheduler state on infinite loop detection and notifies via onOverflow. */
     private _handleFlushOverflow;
+    /** Enters a new batching depth. */
     startBatch(): void;
+    /**
+     * Decrements batching depth. If depth reaches 0, triggers a synchronous flush
+     * to apply all coherent updates collected during the batch.
+     */
     endBatch(): void;
+    /** Configures the maximum safety iterations for the flush loop. */
     setMaxFlushIterations(max: number): void;
 }
 
-declare const scheduler_2: Scheduler_2;
-export { scheduler_2 as scheduler }
-
 /**
  * Scheduler configuration.
  */
-export declare const SCHEDULER_CONFIG: {
-    readonly MAX_EXECUTIONS_PER_SECOND: 1000;
-    readonly MAX_EXECUTIONS_PER_EFFECT: 100;
-    readonly MAX_EXECUTIONS_PER_FLUSH: 10000;
-    readonly MAX_FLUSH_ITERATIONS: 1000;
-    readonly MIN_FLUSH_ITERATIONS: 10;
-    readonly BATCH_QUEUE_SHRINK_THRESHOLD: 1000;
-};
-
-/** Scheduler error. */
+export declare const SCHEDULER_CONFIG: Readonly<{
+    MAX_EXECUTIONS_PER_SECOND: 1000;
+    MAX_EXECUTIONS_PER_EFFECT: 100;
+    MAX_EXECUTIONS_PER_FLUSH: 10000;
+    MAX_FLUSH_ITERATIONS: 1000;
+    MIN_FLUSH_ITERATIONS: 10;
+    BATCH_QUEUE_SHRINK_THRESHOLD: 1000;
+}>;
+
+/** Thrown by the execution engine or scheduler. */
 export declare class SchedulerError extends AtomError {
-    name: string;
-    constructor(message: string, cause?: Error | null);
+    readonly name = "SchedulerError";
+    constructor(message: string, cause?: unknown, recoverable?: boolean, code?: string);
 }
 
+/** Union type representing any valid schedulable task. */
 declare type SchedulerJob = SchedulerJobFunction | SchedulerJobObject;
 
+/** Represents a job that can be executed by the scheduler via a function interface. */
 declare interface SchedulerJobFunction {
     (): void;
-    /** Next scheduled epoch */
-    _nextEpoch?: number;
+    /** Internal tracking for deduplication within the same epoch. */
+    _nextEpoch?: number | undefined;
 }
 
 declare interface SchedulerJobObject {
     execute(): void;
-    /** Next scheduled epoch */
-    _nextEpoch?: number;
+    /** Internal tracking for deduplication within the same epoch. */
+    _nextEpoch?: number | undefined;
 }
 
 /**
@@ -375,14 +478,17 @@ declare interface SchedulerJobObject {
 export declare function setDeepValue(obj: unknown, keys: string[], index: number, value: unknown): unknown;
 
 /** Helper to convert numeric string to number for array indexing. */
-export declare type StringKeyToNumber<S extends string> = S extends `${infer N extends number}` ? N : S;
+declare type StringKeyToNumber<S extends string> = S extends `${infer N extends number}` ? N : S;
 
-export declare interface Subscriber {
+declare interface Subscriber {
     execute(): void;
 }
 
+/** Types that should be treated as terminals (no further path exploration). */
+declare type TerminalTypes = Date | RegExp | Map<unknown, unknown> | Set<unknown> | Promise<unknown> | Function;
+
 /**
- * Untracked execution.
+ * Executes a function without dependency tracking.
  *
  * @param fn - Function to execute.
  * @returns Result of `fn`.
@@ -392,12 +498,13 @@ export declare function untracked<T>(fn: () => T): T;
 /**
  * Writable atom interface.
  */
-export declare interface WritableAtom<T = unknown> extends ReadonlyAtom<T>, Disposable {
+export declare interface WritableAtom<T = unknown> extends ReadonlyAtom<T>, Disposable_2 {
     value: T;
     /**
      * Cleans up the atom and releases resources.
      */
     dispose(): void;
+    [Symbol.dispose](): void;
 }
 
 export { }