@but212/atom-effect 0.16.1 → 0.17.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Async computation states for computed atoms
+ * Async operation states.
  */
 export declare const AsyncState: {
     readonly IDLE: "idle";
@@ -8,7 +8,9 @@ export declare const AsyncState: {
     readonly REJECTED: "rejected";
 };
 
-/** Type derived from AsyncState constant values */
+/**
+ * Async state values.
+ */
 export declare type AsyncStateType = (typeof AsyncState)[keyof typeof AsyncState];
 
 /**
@@ -20,72 +22,49 @@ export declare type AsyncStateType = (typeof AsyncState)[keyof typeof AsyncState
 export declare function atom<T>(initialValue: T, options?: AtomOptions): WritableAtom<T>;
 
 /**
- * Base error class for all atom-effect errors
- *
- * Provides enhanced error information including:
- * - Original cause tracking for error chains
- * - Recoverability flag for error handling strategies
- * - Timestamp for debugging and logging
- *
- * @example
- * ```ts
- * throw new AtomError('Invalid state', originalError, false);
- * ```
+ * Base error class.
  */
 export declare class AtomError extends Error {
-    /** Original error that caused this error, if any */
     cause: Error | null;
-    /** Whether this error can be recovered from */
     recoverable: boolean;
-    /** When this error occurred */
-    timestamp: Date;
-    /**
-     * Creates a new AtomError
-     * @param message - Error message describing what went wrong
-     * @param cause - Original error that caused this error
-     * @param recoverable - Whether the operation can be retried
-     */
+    readonly timestamp: Date;
     constructor(message: string, cause?: Error | null, recoverable?: boolean);
 }
 
-/** Configuration options for creating an atom. */
+/**
+ * Atom options.
+ */
 export declare interface AtomOptions {
-    /** If true, the atom will notify its subscribers synchronously when its value changes. */
+    /** If true, subscribers are notified synchronously. Default: false (microtask scheduled). */
     sync?: boolean;
 }
 
 /**
- * Groups multiple state updates into a single notification cycle.
- * This optimizes performance by deferring the execution of scheduled effects
- * until the provided callback finishes execution, preventing redundant computations.
+ * Batches updates.
  *
- * @param callback - The function containing state updates to be batched.
- * @returns The value returned by the callback.
- * @throws {AtomError} If the provided callback is not a function.
+ * @param fn - Batch function.
+ * @returns - Result of `fn`.
  */
-export declare function batch<T>(callback: () => T): T;
+export declare function batch<T>(fn: () => T): T;
 
 /**
- * Generic Branded Type helper.
- * T: The base type (e.g., number, string)
- * Brand: The unique brand tag
+ * Nominal type brand.
  */
 export declare type Branded<T, Brand> = T & {
     readonly __brand: Brand;
 };
 
 /**
- * Context tracked during the computation phase of a reactive node.
+ * Computation context.
  */
 export declare interface ComputationContext {
     links: DependencyLink[];
 }
 
 /**
- * Creates a computed value with automatic dependency tracking.
- * Supports sync/async computations with caching and lazy evaluation.
- * @param fn - Computation function (sync or async)
- * @param options - { equal?, defaultValue?, onError?, lazy? }
+ * Creates a computed value.
+ * @param fn - Computation function
+ * @param options - Options object
  */
 export declare function computed<T>(fn: () => T, options?: ComputedOptions<T>): ComputedAtom<T>;
 
@@ -93,434 +72,329 @@ export declare function computed<T>(fn: () => Promise<T>, options: ComputedOptio
     defaultValue: T;
 }): ComputedAtom<T>;
 
-/** Represents a reactive atom whose value is derived from other reactive state. */
+/**
+ * Computed atom interface.
+ */
 export declare interface ComputedAtom<T = unknown> extends ReadonlyAtom<T> {
-    /** Current asynchronous state of the computation. */
     readonly state: AsyncStateType;
-    /** true if self or any dependency has an error. */
     readonly hasError: boolean;
-    /** The error object from the last failed computation, if any. */
     readonly lastError: Error | null;
-    /** true if an asynchronous computation is currently in progress. */
     readonly isPending: boolean;
-    /** true if the computation has successfully completed and has a value. */
     readonly isResolved: boolean;
-    /** Accumulated errors from self and all dependencies (immutable). */
-    readonly errors: readonly Error[];
-    /** true if no errors in self or dependencies (inverse of hasError). */
     readonly isValid: boolean;
-    /** Manually invalidates the cached value, forcing recomputation on next access. */
+    /** List of errors encountered during computation. */
+    readonly errors: readonly Error[];
+    /** Invalidates atom. */
     invalidate(): void;
-    /** Disposed of the computed atom and its subscriptions. */
     dispose(): void;
 }
 
-/**
- * Error thrown during computed value computation
- *
- * Computed errors are considered recoverable by default since they typically
- * result from transient data issues rather than programming errors.
- */
+/** Computed error. */
 export declare class ComputedError extends AtomError {
-    /**
-     * Creates a new ComputedError
-     * @param message - Error message
-     * @param cause - Original error
-     */
     constructor(message: string, cause?: Error | null);
 }
 
-/** Configuration options for creating a computed atom. */
+/**
+ * Computed options.
+ */
 export declare interface ComputedOptions<T = unknown> {
-    /** Optional custom equality check for values. Defaults to `Object.is`. */
+    /** Equality check. */
     equal?: (a: T, b: T) => boolean;
-    /** Initial value to return while an async computation is pending. */
+    /** Initial value. */
     defaultValue?: T;
-    /** If true, the computation is deferred until the value is first accessed. */
+    /** Lazy evaluation. */
     lazy?: boolean;
-    /** Optional error handler for computation failures. */
+    /** Error handler. */
     onError?: (error: Error) => void;
 }
 
 /**
- * Debug configuration defaults
+ * Debugging thresholds.
  */
 export declare const DEBUG_CONFIG: {
-    /** Maximum dependencies before warning about large dependency graphs */
     readonly MAX_DEPENDENCIES: 1000;
-    /** Enable infinite loop detection warnings */
     readonly WARN_INFINITE_LOOP: true;
 };
 
 /**
- * Debug utilities for development-time dependency tracking and circular detection.
- * Most features only active when `NODE_ENV === 'development'`.
+ * Debug controller.
  */
 export declare const DEBUG_RUNTIME: DebugConfig;
 
-/**
- * Debug configuration interface
- */
 export declare interface DebugConfig {
     enabled: boolean;
     maxDependencies: number;
     warnInfiniteLoop: boolean;
     warn(condition: boolean, message: string): void;
-    /** Checks for circular dependencies between reactive nodes */
     checkCircular(dep: Dependency, current: object): void;
     attachDebugInfo(obj: object, type: string, id: number): void;
-    /** Returns debug name if available (requires obj to have DEBUG_NAME symbol) */
     getDebugName(obj: object | null | undefined): string | undefined;
-    /** Returns debug type if available (requires obj to have DEBUG_TYPE symbol) */
     getDebugType(obj: object | null | undefined): string | undefined;
 }
 
 /**
- * Interface for subscribable dependencies
+ * Dependency interface.
  */
 export declare interface Dependency {
     readonly id: DependencyId;
+    /** Version counter. */
     version: number;
+    /** State flags. */
     flags: number;
-    /**
-     * Last epoch seen by this dependency (used for invalidation)
-     */
+    /** Last validated epoch. */
     _lastSeenEpoch: number;
-    /* Excluded from this release type: _tempUnsub */
-    /* Excluded from this release type: _modifiedAtEpoch */
+    /** Temporary unsubscribe. */
+    _tempUnsub?: (() => void) | undefined;
+    /** Last modified epoch. */
+    _modifiedAtEpoch?: number;
     /**
-     * Subscribe to dependency updates
+     * Adds a subscriber to this dependency.
+     * @param listener - The subscriber (function or object with execute method).
      */
     subscribe(listener: (() => void) | Subscriber): () => void;
-    /**
-     * Peek at value without subscribing
-     */
+    /** Peek hook. */
     peek?(): unknown;
-    /**
-     * Current value (if cached)
-     */
+    /** Value accessor. */
     value?: unknown;
 }
 
 /**
- * WeakRef-based dependency entry structure
+ * Graph entry.
  */
 export declare interface DependencyEntry<T extends object = Dependency> {
+    /** Dependency reference. */
     ref: WeakRef<T>;
     unsubscribe: () => void;
 }
 
 /**
- * Unique identifier for reactive dependencies (Atoms, Computed, Effects).
- * Base type is number.
+ * Dependency ID.
  */
 export declare type DependencyId = Branded<number, 'DependencyId'>;
 
 /**
- * Encapsulates a link to a dependency with its version and subscription.
- * Part of the AOS (Array of Structs) refactoring to improve data cohesion.
+ * Dependency graph edge.
  */
 declare class DependencyLink {
-    /** The dependency node being tracked */
     node: Dependency;
-    /** The version of the dependency at the time of tracking */
     version: number;
-    /** The unsubscription function for the dependency */
     unsub: (() => void) | undefined;
     constructor(node: Dependency, version: number, unsub?: (() => void) | undefined);
 }
 
 /**
- * Creates and starts a reactive effect that automatically tracks dependencies.
- * The effect function is executed immediately and re-scheduled whenever its
- * reactive dependencies change.
+ * Creates and starts an effect.
  *
- * @param fn - The function to be executed as a reactive effect.
- * @param options - Configuration options to customize effect behavior (e.g., scheduling, error handling).
- * @returns An effect instance providing control over the effect's lifecycle.
- * @throws {EffectError} If the provided `fn` is not a function.
+ * @param fn - Effect function.
+ * @param options - Configuration options.
+ * @returns Effect instance.
  */
 export declare function effect(fn: EffectFunction, options?: EffectOptions): EffectObject;
 
-/**
- * Error thrown during effect execution
- *
- * Effect errors are considered non-recoverable by default since effects
- * typically represent critical side effects that shouldn't fail silently.
- */
+/** Effect error. */
 export declare class EffectError extends AtomError {
-    /**
-     * Creates a new EffectError
-     * @param message - Error message
-     * @param cause - Original error
-     */
     constructor(message: string, cause?: Error | null);
 }
 
-/**
- * Internal context used during effect execution to track dependency changes.
- * Bundles prev/next state for atomic lifecycle transitions.
- */
 export declare interface EffectExecutionContext {
     prevLinks: DependencyLink[];
     nextLinks: DependencyLink[];
 }
 
 /**
- * A function to be executed by an effect.
- * Can optionally return a cleanup function or a Promise that resolves to one.
+ * Effect return type.
  */
 export declare type EffectFunction = () => void | (() => void) | Promise<undefined | (() => void)>;
 
-/** Represents a running effect instance. */
 export declare interface EffectObject {
-    /** Stops the effect and unsubscribes from all dependencies. */
     dispose(): void;
-    /** Manually triggers an execution of the effect. */
     run(): void;
-    /** true if the effect has been disposed. */
     readonly isDisposed: boolean;
-    /** Number of times the effect has executed. */
     readonly executionCount: number;
 }
 
-/** Configuration options for creating an effect. */
 export declare interface EffectOptions {
-    /** If true, the effect runs synchronously whenever its dependencies change. */
     sync?: boolean;
-    /** Maximum number of executions allowed per second for rate limiting. */
     maxExecutionsPerSecond?: number;
-    /** Maximum number of executions allowed per scheduler flush for loop detection. */
     maxExecutionsPerFlush?: number;
-    /** If true, enables detection and warning for effects that modify their own dependencies. */
     trackModifications?: boolean;
-    /** Callback function called when an execution error occurs (including async rejections). */
     onError?: (error: unknown) => void;
 }
 
-/** Internal atom interface for core library usage. */
+/**
+ * Scheduler atom interface.
+ */
 export declare interface IAtom {
-    /** Numerical ID for the node. */
     readonly id: number;
-    /** Current version of the node's value. */
     version: number;
-    /** Internal method to trigger subscriber notifications. */
     _internalNotifySubscribers(): void;
-    /** Internal method to trigger recomputation. */
     recompute?(): void;
 }
 
-/** Checks if the given object is a ReadonlyAtom. */
+/**
+ * Readonly atom check.
+ *
+ * @param obj - Object to check.
+ */
 export declare function isAtom(obj: unknown): obj is ReadonlyAtom;
 
-/** Internal scheduler interface to break circular dependencies. */
 export declare interface IScheduler<T> {
     markDirty(atom: T): void;
     scheduleNotify(atom: T): void;
 }
 
-/** Checks if the given object is a ComputedAtom. */
+/**
+ * Computed atom check.
+ */
 export declare function isComputed(obj: unknown): obj is ComputedAtom;
 
-/** Checks if the given object is an EffectObject. */
+/**
+ * Effect object check.
+ */
 export declare function isEffect(obj: unknown): obj is EffectObject;
 
 /**
- * Object pool configuration
- * Controls memory management and GC pressure reduction
+ * Array pool configuration.
  */
 export declare const POOL_CONFIG: {
-    /** Maximum number of pooled objects to prevent memory bloat */
     readonly MAX_SIZE: 1000;
-    /** Number of objects to pre-allocate for performance-critical paths */
     readonly WARMUP_SIZE: 100;
 };
 
 /**
- * Interface for poolable objects
+ * Poolable interface.
  */
 export declare interface Poolable {
     reset(): void;
 }
 
-/** Statistics for pool usage and health. */
 export declare interface PoolStats {
-    /** Number of items acquired from the pool. */
     acquired: number;
-    /** Number of items released back to the pool. */
     released: number;
-    /** Details for items that could not be returned to the pool. */
     rejected: {
         frozen: number;
         tooLarge: number;
         poolFull: number;
     };
-    /** Approximate number of items that have leaked (not released or rejected). */
     leaked: number;
-    /** Current number of items available in the pool. */
     poolSize: number;
 }
 
-/** Represents a read-only reactive atom. */
+/**
+ * Readonly atom interface.
+ */
 export declare interface ReadonlyAtom<T = unknown> {
-    /** The current value of the atom. Accessing this tracks it as a dependency. */
+    /** The current value of the atom. */
     readonly value: T;
     /**
-     * Subscribes a listener function to changes in the atom's value.
-     * @param listener - Callback receiving both the new and old values.
-     * @returns An unsubscribe function.
+     * Subscribes to value changes.
+     * @param listener - Function called when value changes.
+     * @returns Unsubscribe function.
      */
     subscribe(listener: (newValue?: T, oldValue?: T) => void): () => void;
-    /** Returns the current value without registering it as a dependency. */
+    /**
+     * Non-reactive read.
+     */
     peek(): T;
 }
 
 /**
- * Simplified scheduler for reactive updates with double-buffered queue.
+ * Scheduler implementation.
  */
-declare class Scheduler {
-    private readonly _queueBuffer;
-    private _bufferIndex;
-    private _size;
-    private _epoch;
-    private _isProcessing;
-    private _isBatching;
-    private _batchDepth;
-    private _batchQueue;
-    private _batchQueueSize;
-    private _isFlushingSync;
-    private _maxFlushIterations;
-    constructor();
-    /**
-     * Returns the current operational phase of the scheduler.
-     */
-    get phase(): SchedulerPhase;
-    /** Current number of pending jobs. */
-    get queueSize(): number;
-    /**
-     * Returns whether the scheduler is currently batching updates.
-     */
-    get isBatching(): boolean;
+export declare const scheduler: {
+    /** Queue buffer */
+    _queueBuffer: [SchedulerJob[], SchedulerJob[]];
+    _bufferIndex: number;
+    _size: number;
+    /** Epoch counter */
+    _epoch: number;
+    /** State flags */
+    _isProcessing: boolean;
+    _isBatching: boolean;
+    _isFlushingSync: boolean;
+    /** Batching state */
+    _batchDepth: number;
+    _batchQueue: SchedulerJob[];
+    _batchQueueSize: number;
+    /** Config */
+    _maxFlushIterations: number;
+    readonly phase: SchedulerPhase;
+    readonly queueSize: number;
+    readonly isBatching: boolean;
     /**
-     * Schedules a task for execution.
+     * Schedules job.
      */
     schedule(callback: SchedulerJob): void;
     /**
-     * Schedules a microtask-based flush of the queue.
-     * Coalesces multiple schedule calls into a single microtask execution.
-     */
-    private flush;
-    /**
-     * Immediately flushes all queues synchronously.
-     * Used at the end of a batch block or when immediate reflection is required.
+     * Triggers flush.
      */
-    private flushSync;
+    _flush(): void;
     /**
-     * Merges jobs from the batching queue into the primary queue.
-     * Increments the epoch to ensure deduplication.
+     * Scheduler loop.
      */
-    private _mergeBatchQueue;
-    private _drainQueue;
-    private _processQueue;
-    private _handleFlushOverflow;
-    private _processJobs;
+    _runLoop: () => void;
+    _flushSync(): void;
+    _mergeBatchQueue(): void;
+    _drainQueue(): void;
+    _processQueue(): void;
+    _handleFlushOverflow(): void;
     startBatch(): void;
     endBatch(): void;
     setMaxFlushIterations(max: number): void;
-}
-
-export declare const scheduler: Scheduler;
+};
 
 /**
- * Scheduler configuration
- * Controls batching behavior and performance limits
+ * Scheduler configuration.
  */
 export declare const SCHEDULER_CONFIG: {
-    /** Maximum effect executions per second to detect infinite loops (Legacy/Fallback) */
     readonly MAX_EXECUTIONS_PER_SECOND: 1000;
-    /** Threshold for cleaning up old execution timestamps */
-    readonly CLEANUP_THRESHOLD: 1000;
-    /**
-     * Maximum executions per effect within a single flush cycle
-     * Increased from 50 to 100
-     */
     readonly MAX_EXECUTIONS_PER_EFFECT: 100;
-    /**
-     * Maximum total executions across all effects in a single flush cycle
-     * Increased from 5000 to 10000
-     */
     readonly MAX_EXECUTIONS_PER_FLUSH: 10000;
-    /** Maximum iterations for synchronous flush loop to prevent infinite loops */
     readonly MAX_FLUSH_ITERATIONS: 1000;
-    /** Minimum allowed value for max flush iterations */
     readonly MIN_FLUSH_ITERATIONS: 10;
-    /** Threshold for shrinking the batch queue to assist GC */
+    readonly CLEANUP_THRESHOLD: 1000;
     readonly BATCH_QUEUE_SHRINK_THRESHOLD: 1000;
 };
 
-/**
- * Error thrown by the scheduler system
- *
- * Scheduler errors indicate fundamental issues with the batching/scheduling
- * mechanism and are considered non-recoverable.
- */
+/** Scheduler error. */
 export declare class SchedulerError extends AtomError {
-    /**
-     * Creates a new SchedulerError
-     * @param message - Error message
-     * @param cause - Original error
-     */
     constructor(message: string, cause?: Error | null);
 }
 
-/**
- * Scheduler job interface.
- */
 declare interface SchedulerJob {
     (): void;
-    /** Epoch for deduplication */
+    /** Next scheduled epoch */
     _nextEpoch?: number;
 }
 
-/**
- * Current state of the scheduler.
- */
 declare enum SchedulerPhase {
-    /** No pending jobs, not currently flushing. */
     IDLE = 0,
-    /** Currently within a batch() block. */
     BATCHING = 1,
-    /** Currently executing queued jobs. */
     FLUSHING = 2
 }
 
-/**
- * Subscriber interface for dependency notifications
- */
 export declare interface Subscriber {
     execute(): void;
 }
 
-/**
- * Transform function type
- */
 export declare type TransformFunction<T, U> = (value: T) => U;
 
 /**
- * Executes a function without tracking any reactive dependencies accessed during its execution.
- * This prevents the calling context from subscribing to any atoms read within the callback.
+ * Untracked execution.
  *
- * @param fn - The function to execute in an untracked context.
- * @returns The value returned by the provided function.
- * @throws {AtomError} If the provided argument is not a function.
+ * @param fn - Function to execute.
+ * @returns Result of `fn`.
  */
 export declare function untracked<T>(fn: () => T): T;
 
-/** Represents a writable reactive atom. */
+/**
+ * Writable atom interface.
+ */
 export declare interface WritableAtom<T = unknown> extends ReadonlyAtom<T> {
-    /** The current value of the atom. Setting this will trigger notifications if the value changes. */
     value: T;
-    /** Disposes of the atom and releases associated resources. */
+    /**
+     * Cleans up the atom and releases resources.
+     */
     dispose(): void;
 }