@but212/atom-effect 0.3.3 → 0.5.0

package/dist/index.d.ts

@@ -2,25 +2,35 @@
  * 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 reactive atom holding mutable state.
- * @param initialValue - Initial value
- * @param options - { sync?: boolean } for immediate notifications
+ *
+ * Atoms are the building blocks of reactive state. When an atom's value changes,
+ * any effects or computed atoms that depend on it will be automatically re-executed.
+ *
+ * @param initialValue - The initial value of the atom.
+ * @param options - Configuration options.
+ * @param options.sync - If true, notifications are delivered synchronously when the value changes.
+ * @returns A writable atom object.
+ *
+ * @example
+ * ```ts
+ * const count = atom(0);
+ * count.value = 1; // Notifies subscribers
+ * console.log(count.value); // 1
+ * ```
  */
 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
  *
@@ -50,7 +60,9 @@ export declare class AtomError extends Error {
     constructor(message: string, cause?: Error | null, recoverable?: boolean);
 }
 
+/** Configuration options for creating an atom. */
 export declare interface AtomOptions {
+    /** If true, the atom will notify its subscribers synchronously when its value changes. */
     sync?: boolean;
 }
 
@@ -65,7 +77,7 @@ export declare interface AtomOptions {
  * @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
+ * @throws Propagates any error thrown by the callback function
  *
  * @example
  * ```typescript
@@ -85,6 +97,15 @@ export declare interface AtomOptions {
  */
 export declare function batch<T>(callback: () => T): T;
 
+/**
+ * Generic Branded Type helper.
+ * T: The base type (e.g., number, string)
+ * Brand: The unique brand tag
+ */
+export declare type Branded<T, Brand> = T & {
+    readonly __brand: Brand;
+};
+
 /**
  * Creates a computed value with automatic dependency tracking.
  * Supports sync/async computations with caching and lazy evaluation.
@@ -97,13 +118,21 @@ 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. */
 export declare interface ComputedAtom<T = unknown> extends ReadonlyAtom<T> {
+    /** Current asynchronous state of the computation. */
     readonly state: AsyncStateType;
+    /** true if the last computation attempt failed. */
     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;
+    /** Manually invalidates the cached value, forcing recomputation on next access. */
     invalidate(): void;
+    /** Disposed of the computed atom and its subscriptions. */
     dispose(): void;
 }
 
@@ -122,10 +151,15 @@ export declare class ComputedError extends AtomError {
     constructor(message: string, cause?: Error | null);
 }
 
+/** Configuration options for creating a computed atom. */
 export declare interface ComputedOptions<T = unknown> {
+    /** Optional custom equality check for values. Defaults to `Object.is`. */
     equal?: (a: T, b: T) => boolean;
+    /** Initial value to return while an async computation is pending. */
     defaultValue?: T;
+    /** If true, the computation is deferred until the value is first accessed. */
     lazy?: boolean;
+    /** Optional error handler for computation failures. */
     onError?: (error: Error) => void;
 }
 
@@ -153,17 +187,20 @@ 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;
 }
 
 /**
  * Interface for subscribable dependencies
  */
 export declare interface Dependency {
-    readonly id: number;
+    readonly id: DependencyId;
     version: number;
     /**
      * Last epoch seen by this dependency (used for invalidation)
@@ -195,10 +232,33 @@ export declare interface DependencyEntry<T extends object = Dependency> {
 }
 
 /**
- * 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
+ * Unique identifier for reactive dependencies (Atoms, Computed, Effects).
+ * Base type is number.
+ */
+export declare type DependencyId = Branded<number, 'DependencyId'>;
+
+/**
+ * Creates a reactive effect that re-executes when its dependencies change.
+ *
+ * An effect automatically tracks any reactive state (atoms, computed) accessed during its execution.
+ * When those dependencies change, the effect is scheduled for re-execution.
+ *
+ * @param fn - The effect function to execute. Can return a cleanup function or a Promise that resolves to one.
+ * @param options - Configuration options for the effect.
+ * @param options.sync - If true, the effect runs synchronously when dependencies change. Defaults to false (scheduled).
+ * @param options.maxExecutionsPerSecond - Rate limiting for the effect.
+ * @param options.trackModifications - If true, warns when an effect modifies its own dependencies.
+ * @returns An object representing the effect with `run()` and `dispose()` methods.
+ * @throws {EffectError} If `fn` is not a function.
+ *
+ * @example
+ * ```ts
+ * const count = atom(0);
+ * const stop = effect(() => {
+ *   console.log('Count changed:', count.value);
+ *   return () => console.log('Cleaning up...');
+ * });
+ * ```
  */
 export declare function effect(fn: EffectFunction, options?: EffectOptions): EffectObject;
 
@@ -217,26 +277,43 @@ export declare class EffectError extends AtomError {
     constructor(message: string, cause?: Error | null);
 }
 
+/**
+ * A function to be executed by an effect.
+ * Can optionally return a cleanup function or a Promise that resolves to one.
+ */
 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;
 }
 
+/** Checks if the given object is a ReadonlyAtom. */
 export declare function isAtom(obj: unknown): obj is ReadonlyAtom;
 
+/** Checks if the given object is a ComputedAtom. */
 export declare function isComputed(obj: unknown): obj is ComputedAtom;
 
+/** Checks if the given object is an EffectObject. */
 export declare function isEffect(obj: unknown): obj is EffectObject;
 
 /**
@@ -257,15 +334,24 @@ export declare interface Poolable {
     reset(): void;
 }
 
+/** Represents a read-only reactive atom. */
 export declare interface ReadonlyAtom<T = unknown> {
+    /** The current value of the atom. Accessing this tracks it as a dependency. */
     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.
+     */
     subscribe(listener: (newValue?: T, oldValue?: T) => void): () => void;
+    /** Returns the current value without registering it as a dependency. */
     peek(): T;
 }
 
 /**
- * Scheduler for reactive updates with batching support.
- * Uses epoch-based O(1) deduplication and double buffering.
+ * Scheduler for reactive updates.
+ * Manages the execution of effects and computed updates using batching and double-buffering.
+ * Supports both asynchronous (microtask-based) and synchronous (manual or batch-end) flushing.
  */
 declare class Scheduler {
     private queueA;
@@ -281,11 +367,31 @@ declare class Scheduler {
     private isFlushingSync;
     private maxFlushIterations;
     get phase(): SchedulerPhase;
+    /**
+     * Schedules a task for execution.
+     * Tasks are deduplicated within the same flush cycle using epoch tracking.
+     * @param callback - The function to execute.
+     * @throws {SchedulerError} If the callback is not a function.
+     */
     schedule(callback: SchedulerJob): void;
     private flush;
     private flushSync;
+    private _mergeBatchQueue;
+    private _drainQueue;
+    private _processCurrentQueue;
+    private _handleFlushOverflow;
+    private _processJobs;
+    /** Starts a new batch of updates. Updates will be deferred until endBatch is called. */
     startBatch(): void;
+    /**
+     * Ends the current batch. If the batch depth reaches zero, all pending updates are flushed synchronously.
+     */
     endBatch(): void;
+    /**
+     * Configures the maximum number of iterations allowed during a synchronous flush.
+     * Used to prevent infinite loops.
+     * @param max - Maximum iterations count.
+     */
     setMaxFlushIterations(max: number): void;
 }
 
@@ -310,6 +416,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;
 };
 
 /**
@@ -327,9 +437,10 @@ export declare class SchedulerError extends AtomError {
     constructor(message: string, cause?: Error | null);
 }
 
-declare type SchedulerJob = (() => void) & {
+declare interface SchedulerJob {
+    (): void;
     _nextEpoch?: number;
-};
+}
 
 declare enum SchedulerPhase {
     IDLE = 0,
@@ -360,7 +471,7 @@ export declare type TransformFunction<T, U> = (value: T) => U;
  * @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
+ * @throws Propagates any error thrown by the callback function
  *
  * @example
  * ```typescript
@@ -374,8 +485,11 @@ export declare type TransformFunction<T, U> = (value: T) => U;
  */
 export declare function untracked<T>(fn: () => T): T;
 
+/** Represents a writable reactive atom. */
 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. */
     dispose(): void;
 }