@but212/atom-effect 0.15.4 → 0.16.1

package/dist/index.d.ts

@@ -55,30 +55,13 @@ export declare interface AtomOptions {
 }
 
 /**
- * Executes multiple reactive updates in a single batch and flushes them synchronously.
+ * 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.
  *
- * While the engine automatically batches updates using microtasks, `batch()`
- * provides a way to group multiple changes and guarantee their immediate
- * reflection (synchronous flush) once the callback completes.
- *
- * @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 Propagates any error thrown by the callback function
- *
- * @example
- * ```typescript
- * const firstName = atom('John');
- * const lastName = atom('Doe');
- *
- * // With batching: triggers 1 combined synchronous update at the end
- * batch(() => {
- *   firstName.value = 'Jane';
- *   lastName.value = 'Smith';
- * });
- * // Changes are guaranteed to be applied here
- * ```
+ * @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.
  */
 export declare function batch<T>(callback: () => T): T;
 
@@ -95,14 +78,7 @@ export declare type Branded<T, Brand> = T & {
  * Context tracked during the computation phase of a reactive node.
  */
 export declare interface ComputationContext {
-    prevDeps: Dependency[];
-    prevVersions: number[];
-    nextDeps: Dependency[];
-    nextVersions: number[];
-    originalAdd: (dep: Dependency) => void;
-    state: {
-        depCount: number;
-    };
+    links: DependencyLink[];
 }
 
 /**
@@ -212,15 +188,6 @@ export declare interface Dependency {
     _lastSeenEpoch: number;
     /* Excluded from this release type: _tempUnsub */
     /* Excluded from this release type: _modifiedAtEpoch */
-    /* Excluded from this release type: _visitedEpoch */
-    /**
-     * Calculates the logical distance (shift) between current and cached version.
-     * Used for priority scheduling - large shifts indicate stale updates.
-     *
-     * @param cachedVersion - The previously cached version
-     * @returns Non-negative shift distance (0 to 0x3fffffff)
-     */
-    getShift(cachedVersion: number): number;
     /**
      * Subscribe to dependency updates
      */
@@ -250,27 +217,28 @@ export declare interface DependencyEntry<T extends object = Dependency> {
 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.
+ * Encapsulates a link to a dependency with its version and subscription.
+ * Part of the AOS (Array of Structs) refactoring to improve data cohesion.
+ */
+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.
  *
- * @example
- * ```ts
- * const count = atom(0);
- * const stop = effect(() => {
- *   console.log('Count changed:', count.value);
- *   return () => console.log('Cleaning up...');
- * });
- * ```
+ * @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.
  */
 export declare function effect(fn: EffectFunction, options?: EffectOptions): EffectObject;
 
@@ -294,12 +262,8 @@ export declare class EffectError extends AtomError {
  * Bundles prev/next state for atomic lifecycle transitions.
  */
 export declare interface EffectExecutionContext {
-    prevDeps: Dependency[];
-    prevVersions: number[];
-    prevUnsubs: (() => void)[];
-    nextDeps: Dependency[];
-    nextVersions: number[];
-    nextUnsubs: (() => void)[];
+    prevLinks: DependencyLink[];
+    nextLinks: DependencyLink[];
 }
 
 /**
@@ -415,17 +379,17 @@ export declare interface ReadonlyAtom<T = unknown> {
  * Simplified scheduler for reactive updates with double-buffered queue.
  */
 declare class Scheduler {
-    private _queueBuffer;
+    private readonly _queueBuffer;
     private _bufferIndex;
     private _size;
     private _epoch;
-    private isProcessing;
+    private _isProcessing;
     private _isBatching;
-    private batchDepth;
-    private batchQueue;
-    private batchQueueSize;
-    private isFlushingSync;
-    private maxFlushIterations;
+    private _batchDepth;
+    private _batchQueue;
+    private _batchQueueSize;
+    private _isFlushingSync;
+    private _maxFlushIterations;
     constructor();
     /**
      * Returns the current operational phase of the scheduler.
@@ -543,27 +507,12 @@ export declare interface Subscriber {
 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 Propagates any error thrown by the callback function
+ * 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.
  *
- * @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;
- * });
- * ```
+ * @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.
  */
 export declare function untracked<T>(fn: () => T): T;