@but212/atom-effect 0.1.4 → 0.2.0

package/dist/index.d.ts

@@ -1,12 +1,606 @@
-/**
- * @fileoverview Atom Effect - Main entry point
- */
-export { AsyncState, DEBUG_CONFIG, POOL_CONFIG, SCHEDULER_CONFIG } from './constants';
-export { atom, computed, effect } from './core';
-export { AtomError, ComputedError, EffectError, SchedulerError } from './errors/errors';
-export { batch, scheduler } from './scheduler';
-export { untracked } from './tracking';
-export * from './types';
-export { debug as DEBUG_RUNTIME } from './utils/debug';
-export { isAtom, isComputed, isEffect } from './utils/type-guards';
-//# sourceMappingURL=index.d.ts.map
+/**
+ * Async computation states for computed atoms
+ */
+export declare const AsyncState: {
+    IDLE: "idle";
+    PENDING: "pending";
+    RESOLVED: "resolved";
+    REJECTED: "rejected";
+};
+
+export declare type AsyncStateType = 'idle' | 'pending' | 'resolved' | 'rejected';
+
+/**
+ * Creates a new atom with the given initial value.
+ *
+ * @template T - The type of value stored in the atom
+ * @param initialValue - The initial value of the atom
+ * @param options - Optional configuration options
+ * @returns A writable atom instance
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const count = atom(0);
+ *
+ * // With sync option for immediate notifications
+ * const syncCount = atom(0, { sync: true });
+ *
+ * // Reading and writing
+ * console.log(count.value); // 0
+ * count.value = 5;
+ * console.log(count.peek()); // 5 (non-tracking read)
+ * ```
+ */
+export declare function atom<T>(initialValue: T, options?: AtomOptions): WritableAtom<T>;
+
+/**
+ * @fileoverview Error class hierarchy for atom-effect library
+ * @description Structured error classes with cause tracking and recoverability flags
+ */
+/**
+ * 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);
+ * ```
+ */
+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
+     */
+    constructor(message: string, cause?: Error | null, recoverable?: boolean);
+}
+
+export declare interface AtomOptions {
+    sync?: boolean;
+}
+
+/**
+ * Executes multiple reactive updates in a single batch.
+ *
+ * Batching groups multiple state changes together, deferring notifications
+ * until all updates are complete. This prevents intermediate states from
+ * triggering unnecessary recomputations and improves performance.
+ *
+ * @template T - The return type of the callback function
+ * @param callback - The function containing batched updates
+ * @returns The result of the callback function
+ * @throws {AtomError} If the callback is not a function
+ * @throws {AtomError} If an error occurs during batch execution
+ *
+ * @example
+ * ```typescript
+ * const firstName = atom('John');
+ * const lastName = atom('Doe');
+ *
+ * // Without batching: triggers 2 separate updates
+ * firstName.value = 'Jane';
+ * lastName.value = 'Smith';
+ *
+ * // With batching: triggers 1 combined update
+ * batch(() => {
+ *   firstName.value = 'Jane';
+ *   lastName.value = 'Smith';
+ * });
+ * ```
+ */
+export declare function batch<T>(callback: () => T): T;
+
+/**
+ * Creates a computed value that automatically tracks and reacts to dependencies
+ *
+ * Computed atoms are derived reactive state that:
+ * - Automatically track dependencies accessed during computation
+ * - Lazily recompute only when dependencies change (dirty checking)
+ * - Support both synchronous and asynchronous computations
+ * - Cache results until dependencies change (memoization)
+ * - Use bit flags for efficient state management
+ * - Provide async state tracking (idle/pending/resolved/rejected)
+ *
+ * @template T - The type of the computed value
+ * @param fn - Computation function (can return T or Promise<T>)
+ * @param options - Configuration options
+ * @returns A readonly computed atom with automatic dependency tracking
+ *
+ * @example
+ * ```ts
+ * // Synchronous computed
+ * const count = atom(0);
+ * const doubled = computed(() => count.value * 2);
+ *
+ * // Asynchronous computed with default value
+ * const userData = computed(
+ *   async () => fetch(`/api/user/${userId.value}`).then(r => r.json()),
+ *   { defaultValue: null }
+ * );
+ * ```
+ */
+export declare function computed<T>(fn: () => T, options?: ComputedOptions<T>): ComputedAtom<T>;
+
+export declare function computed<T>(fn: () => Promise<T>, options: ComputedOptions<T> & {
+    defaultValue: T;
+}): ComputedAtom<T>;
+
+export declare interface ComputedAtom<T = unknown> extends ReadonlyAtom<T> {
+    readonly state: AsyncStateType;
+    readonly hasError: boolean;
+    readonly lastError: Error | null;
+    readonly isPending: boolean;
+    readonly isResolved: boolean;
+    invalidate(): void;
+    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.
+ */
+export declare class ComputedError extends AtomError {
+    /**
+     * Creates a new ComputedError
+     * @param message - Error message
+     * @param cause - Original error
+     */
+    constructor(message: string, cause?: Error | null);
+}
+
+export declare interface ComputedOptions<T = unknown> {
+    equal?: (a: T, b: T) => boolean;
+    defaultValue?: T;
+    lazy?: boolean;
+    onError?: (error: Error) => void;
+}
+
+/**
+ * Debug configuration defaults
+ */
+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 configuration instance with runtime utilities.
+ *
+ * Provides development-time features including:
+ * - Circular dependency detection (direct and indirect)
+ * - Large dependency graph warnings
+ * - Debug metadata attachment for inspection
+ *
+ * @remarks
+ * Most features are only active when `NODE_ENV === 'development'`
+ * to avoid performance overhead in production builds.
+ *
+ * @example
+ * ```typescript
+ * // Check for circular dependencies
+ * debug.checkCircular(dependencyAtom, computedAtom);
+ *
+ * // Warn about potential issues
+ * debug.warn(count > 100, 'Large dependency count detected');
+ *
+ * // Attach debug info to a reactive object
+ * debug.attachDebugInfo(atom, 'atom', 42);
+ * ```
+ */
+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;
+    checkCircular(dep: unknown, current: unknown, visited?: Set<unknown>): void;
+    attachDebugInfo(obj: object, type: string, id: number): void;
+    getDebugName(obj: unknown): string | undefined;
+    getDebugType(obj: unknown): string | undefined;
+}
+
+/**
+ * Interface for subscribable dependencies
+ */
+export declare interface Dependency {
+    readonly id: number;
+    version: number;
+    _lastSeenEpoch: number;
+    subscribe(listener: (() => void) | Subscriber): () => void;
+    peek?(): unknown;
+    value?: unknown;
+}
+
+/**
+ * WeakRef-based dependency entry structure
+ */
+export declare interface DependencyEntry<T extends object = Dependency> {
+    ref: WeakRef<T>;
+    unsubscribe: () => void;
+}
+
+/**
+ * Creates a reactive effect that automatically re-executes when its dependencies change.
+ *
+ * @param fn - The effect function to execute. May return a cleanup function
+ *             or a Promise that resolves to a cleanup function.
+ * @param options - Configuration options for the effect
+ * @param options.sync - If true, re-executes synchronously on dependency changes.
+ *                       Defaults to false (scheduled/batched execution).
+ * @param options.maxExecutionsPerSecond - Maximum executions per second before
+ *                                          infinite loop detection triggers.
+ *                                          Defaults to `SCHEDULER_CONFIG.MAX_EXECUTIONS_PER_SECOND`.
+ * @param options.trackModifications - If true, tracks and warns about dependencies
+ *                                     that are both read and modified. Defaults to false.
+ *
+ * @returns An {@link EffectObject} with `run()`, `dispose()`, and state properties
+ *
+ * @throws {EffectError} If `fn` is not a function
+ *
+ * @remarks
+ * Effects are the primary way to perform side effects in response to reactive
+ * state changes. They automatically track which reactive values (atoms, computed)
+ * are accessed during execution and re-run when those values change.
+ *
+ * The effect function may return a cleanup function that will be called before
+ * the next execution or when the effect is disposed. This is useful for
+ * cleaning up subscriptions, timers, or other resources.
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const counter = atom(0);
+ *
+ * const fx = effect(() => {
+ *   console.log('Counter:', counter.value);
+ * });
+ * // Logs: "Counter: 0"
+ *
+ * counter.value = 1;
+ * // Logs: "Counter: 1"
+ *
+ * fx.dispose(); // Stop the effect
+ * ```
+ *
+ * @example
+ * With cleanup function:
+ * ```typescript
+ * const fx = effect(() => {
+ *   const timer = setInterval(() => console.log('tick'), 1000);
+ *   return () => clearInterval(timer); // Cleanup
+ * });
+ * ```
+ *
+ * @example
+ * Synchronous execution:
+ * ```typescript
+ * const fx = effect(
+ *   () => console.log(counter.value),
+ *   { sync: true }
+ * );
+ * ```
+ */
+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.
+ */
+export declare class EffectError extends AtomError {
+    /**
+     * Creates a new EffectError
+     * @param message - Error message
+     * @param cause - Original error
+     */
+    constructor(message: string, cause?: Error | null);
+}
+
+export declare type EffectFunction = () => void | (() => void) | Promise<undefined | (() => void)>;
+
+export declare interface EffectObject {
+    dispose(): void;
+    run(): void;
+    readonly isDisposed: boolean;
+    readonly executionCount: number;
+}
+
+export declare interface EffectOptions {
+    sync?: boolean;
+    maxExecutionsPerSecond?: number;
+    trackModifications?: boolean;
+}
+
+export declare function isAtom(obj: unknown): obj is ReadonlyAtom;
+
+export declare function isComputed(obj: unknown): obj is ComputedAtom;
+
+export declare function isEffect(obj: unknown): obj is EffectObject;
+
+/**
+ * Object pool configuration
+ * Controls memory management and GC pressure reduction
+ */
+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
+ */
+export declare interface Poolable {
+    reset(): void;
+}
+
+export declare interface ReadonlyAtom<T = unknown> {
+    readonly value: T;
+    subscribe(listener: (newValue?: T, oldValue?: T) => void): () => void;
+    peek(): T;
+}
+
+declare class Scheduler {
+    /** Queue of callbacks waiting for microtask execution */
+    /** Queue buffers for double buffering optimization */
+    private queueA;
+    private queueB;
+    /** Currently active queue receiving new tasks */
+    private queue;
+    private queueSize;
+    /** Epoch for O(1) deduplication */
+    private _epoch;
+    /** Whether the scheduler is currently processing the queue */
+    private isProcessing;
+    /** Whether batching is currently active */
+    isBatching: boolean;
+    /** Current nesting depth of batch operations */
+    private batchDepth;
+    /** Array of callbacks queued during batching */
+    private batchQueue;
+    /** Current size of the batch queue (for array reuse) */
+    private batchQueueSize;
+    /** Whether synchronous flush is in progress */
+    private isFlushingSync;
+    /** Maximum iterations allowed during flush to prevent infinite loops */
+    private maxFlushIterations;
+    /**
+     * Gets the current phase of the scheduler.
+     */
+    get phase(): SchedulerPhase;
+    /**
+     * Schedules a callback for execution.
+     *
+     * If batching is active or a sync flush is in progress, the callback
+     * is added to the batch queue. Otherwise, it's added to the main queue
+     * and a flush is triggered via microtask.
+     *
+     * @param callback - The function to schedule for execution
+     * @throws {SchedulerError} If callback is not a function
+     *
+     * @example
+     * ```typescript
+     * scheduler.schedule(() => {
+     *   // This runs in the next microtask (or sync if batching)
+     *   updateUI();
+     * });
+     * ```
+     */
+    schedule(callback: SchedulerJob): void;
+    /**
+     * Flushes the queue asynchronously via microtask.
+     *
+     * Executes all queued callbacks in a microtask, allowing the current
+     * synchronous execution to complete first. Errors in individual
+     * callbacks are caught and logged without interrupting others.
+     *
+     * @private
+     * @remarks
+     * This method is idempotent - calling it multiple times while
+     * processing is active has no effect.
+     */
+    private flush;
+    /**
+     * Flushes all queued callbacks synchronously.
+     *
+     * This method is called when a batch ends. It processes all callbacks
+     * in the batch queue and main queue synchronously, allowing callbacks
+     * to schedule additional callbacks that are processed in the same flush.
+     *
+     * @private
+     * @remarks
+     * - Includes infinite loop protection via maxFlushIterations
+     * - Errors in callbacks are caught and logged individually
+     * - The isFlushingSync flag prevents re-entrancy issues
+     */
+    private flushSync;
+    /**
+     * Starts a new batch operation.
+     *
+     * While batching is active, all scheduled callbacks are deferred
+     * until endBatch() is called. Batches can be nested - only the
+     * outermost endBatch() triggers execution.
+     *
+     * @example
+     * ```typescript
+     * scheduler.startBatch();
+     * // All updates here are deferred
+     * atom1.value = 'a';
+     * atom2.value = 'b';
+     * scheduler.endBatch(); // Both updates processed together
+     * ```
+     */
+    startBatch(): void;
+    /**
+     * Ends a batch operation.
+     *
+     * Decrements the batch depth counter. When depth reaches zero,
+     * all queued callbacks are flushed synchronously and batching
+     * is disabled.
+     *
+     * @remarks
+     * Safe to call even if startBatch() wasn't called - depth is
+     * clamped to zero minimum.
+     *
+     * @example
+     * ```typescript
+     * scheduler.startBatch();
+     * try {
+     *   // ... batched operations
+     * } finally {
+     *   scheduler.endBatch(); // Always end batch, even on error
+     * }
+     * ```
+     */
+    endBatch(): void;
+    /**
+     * Sets the maximum number of flush iterations allowed.
+     *
+     * This limit prevents infinite loops when reactive dependencies
+     * form cycles. If exceeded, the queue is cleared and an error
+     * is logged.
+     *
+     * @param max - Maximum iterations (must be at least 10)
+     * @throws {SchedulerError} If max is less than 10
+     *
+     * @example
+     * ```typescript
+     * // Increase limit for complex dependency graphs
+     * scheduler.setMaxFlushIterations(5000);
+     * ```
+     */
+    setMaxFlushIterations(max: number): void;
+}
+
+/** Global scheduler instance for reactive updates */
+export declare const scheduler: Scheduler;
+
+/**
+ * Scheduler configuration
+ * Controls batching behavior and performance limits
+ */
+export declare const SCHEDULER_CONFIG: {
+    /** Maximum effect executions per second to detect infinite loops */
+    readonly MAX_EXECUTIONS_PER_SECOND: 100;
+    /** Threshold for cleaning up old execution timestamps */
+    readonly CLEANUP_THRESHOLD: 100;
+};
+
+/**
+ * Error thrown by the scheduler system
+ *
+ * Scheduler errors indicate fundamental issues with the batching/scheduling
+ * mechanism and are considered non-recoverable.
+ */
+export declare class SchedulerError extends AtomError {
+    /**
+     * Creates a new SchedulerError
+     * @param message - Error message
+     * @param cause - Original error
+     */
+    constructor(message: string, cause?: Error | null);
+}
+
+declare type SchedulerJob = (() => void) & {
+    _nextEpoch?: number;
+};
+
+/**
+ * Scheduler for managing reactive updates and batching operations.
+ *
+ * The Scheduler is responsible for coordinating when reactive computations
+ * are executed. It supports both immediate (microtask) execution and
+ * batched synchronous execution for optimal performance.
+ *
+ * Key features:
+ * - Deduplication of callbacks via Set
+ * - Nested batch support with depth tracking
+ * - Infinite loop protection with configurable iteration limit
+ * - Error isolation to prevent one callback from breaking others
+ *
+ * @example
+ * ```typescript
+ * // Schedule a callback for microtask execution
+ * scheduler.schedule(() => console.log('Updated!'));
+ *
+ * // Batch multiple updates
+ * scheduler.startBatch();
+ * scheduler.schedule(() => console.log('Update 1'));
+ * scheduler.schedule(() => console.log('Update 2'));
+ * scheduler.endBatch(); // Both execute synchronously here
+ * ```
+ */
+/**
+ * Phases of the scheduler execution cycle.
+ */
+declare enum SchedulerPhase {
+    IDLE = 0,
+    BATCHING = 1,
+    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.
+ *
+ * This utility allows reading atom values without establishing
+ * a dependency relationship, useful for accessing values that
+ * shouldn't trigger recomputation when they change.
+ *
+ * @template T - The return type of the function
+ * @param fn - The function to execute without tracking
+ * @returns The result of the executed function
+ * @throws {AtomError} If the callback is not a function
+ * @throws {AtomError} If an error occurs during execution
+ *
+ * @example
+ * ```typescript
+ * const count = atom(0);
+ * const doubled = computed(() => {
+ *   // This read will NOT be tracked as a dependency
+ *   const untrackedValue = untracked(() => count.value);
+ *   return untrackedValue * 2;
+ * });
+ * ```
+ */
+export declare function untracked<T>(fn: () => T): T;
+
+export declare interface WritableAtom<T = unknown> extends ReadonlyAtom<T> {
+    value: T;
+    dispose(): void;
+}
+
+export { }