@but212/atom-effect 0.3.2 → 0.4.0

package/dist/index.d.ts

@@ -2,42 +2,22 @@
  * Async computation states for computed atoms
  */
 export declare const AsyncState: {
-    IDLE: "idle";
-    PENDING: "pending";
-    RESOLVED: "resolved";
-    REJECTED: "rejected";
+    readonly IDLE: "idle";
+    readonly PENDING: "pending";
+    readonly RESOLVED: "resolved";
+    readonly REJECTED: "rejected";
 };
 
-export declare type AsyncStateType = 'idle' | 'pending' | 'resolved' | 'rejected';
+/** Type derived from AsyncState constant values */
+export declare type AsyncStateType = (typeof AsyncState)[keyof typeof AsyncState];
 
 /**
- * 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)
- * ```
+ * Creates a reactive atom holding mutable state.
+ * @param initialValue - Initial value
+ * @param options - { sync?: boolean } for immediate notifications
  */
 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
  *
@@ -103,33 +83,10 @@ export declare interface AtomOptions {
 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 }
- * );
- * ```
+ * 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? }
  */
 export declare function computed<T>(fn: () => T, options?: ComputedOptions<T>): ComputedAtom<T>;
 
@@ -180,28 +137,8 @@ export declare const DEBUG_CONFIG: {
 };
 
 /**
- * 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);
- * ```
+ * Debug utilities for development-time dependency tracking and circular detection.
+ * Most features only active when `NODE_ENV === 'development'`.
  */
 export declare const DEBUG_RUNTIME: DebugConfig;
 
@@ -213,10 +150,13 @@ export declare interface DebugConfig {
     maxDependencies: number;
     warnInfiniteLoop: boolean;
     warn(condition: boolean, message: string): void;
-    checkCircular(dep: unknown, current: unknown, visited?: Set<unknown>): void;
+    /** Checks for circular dependencies between reactive nodes */
+    checkCircular(dep: Dependency, current: object): void;
     attachDebugInfo(obj: object, type: string, id: number): void;
-    getDebugName(obj: unknown): string | undefined;
-    getDebugType(obj: unknown): string | undefined;
+    /** 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;
 }
 
 /**
@@ -255,65 +195,10 @@ export declare interface DependencyEntry<T extends object = Dependency> {
 }
 
 /**
- * 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 }
- * );
- * ```
+ * Creates a reactive effect that re-executes when dependencies change.
+ * @param fn - Effect function (may return cleanup function or Promise)
+ * @param options - { sync?: boolean, maxExecutionsPerSecond?: number, trackModifications?: boolean }
+ * @throws {EffectError} If fn is not a function
  */
 export declare function effect(fn: EffectFunction, options?: EffectOptions): EffectObject;
 
@@ -378,139 +263,32 @@ export declare interface ReadonlyAtom<T = unknown> {
     peek(): T;
 }
 
+/**
+ * Scheduler for reactive updates with batching support.
+ * Uses epoch-based O(1) deduplication and double buffering.
+ */
 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;
 
 /**
@@ -532,6 +310,10 @@ export declare const SCHEDULER_CONFIG: {
      * Increased from 1000 to 5000 based on evaluation report
      */
     readonly MAX_EXECUTIONS_PER_FLUSH: 5000;
+    /** 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;
 };
 
 /**
@@ -553,34 +335,6 @@ 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,