@estjs/signals 0.0.15 → 0.0.16-beta.2

package/dist/signals.d.ts

@@ -125,17 +125,11 @@ interface Link {
      * Examples: Effect, Computed
      */
     subNode: ReactiveNode;
-    /**
-     * Connects multiple subscribers of the same depNode.
-     * Previous subscriber Link
-     */
+    /** Previous subscriber Link */
     prevSubLink?: Link;
     /** Next subscriber Link */
     nextSubLink?: Link;
-    /**
-     * Connects multiple dependencies of the same subNode.
-     * Previous dependency Link
-     */
+    /** Previous dependency Link */
     prevDepLink?: Link;
     /** Next dependency Link */
     nextDepLink?: Link;
@@ -216,21 +210,34 @@ interface ReactiveNode {
      * @see ReactiveFlags
      */
     flag: ReactiveFlags;
-    _triggerVersion?: number;
+    /**
+     * Optional debugging hook called when dependencies are tracked
+     */
     onTrack?: (event: DebuggerEvent) => void;
+    /**
+     * Optional debugging hook called when reactive changes are triggered.
+     */
     onTrigger?: (event: DebuggerEvent) => void;
+    /**
+     * When true, this node is a pure dependency (leaf); it should not receive
+     * a DIRTY flag during invalidation because it has no derived value to recompute.
+     */
+    isDep?: boolean;
+    /**
+     * Deduplication stamp used during batch notification.
+     * Prevents the same effect from being pushed into the pending queue twice.
+     */
+    _triggerVersion?: number;
 }
 /**
- * Execute function with tracking disabled
+ * Execute function with tracking disabled.
  *
- * During function execution, accessing Signals won't establish dependencies.
- *
- * @param fn - The function to execute
- * @returns The function's return value
+ * @param fn - The function to execute.
+ * @returns {T} The function's return value.
  */
 declare function untrack<T>(fn: () => T): T;
 /**
- * Trigger updates for subscribers of a reactive object property
+ * Trigger updates for subscribers of a reactive object property.
  *
  * This function notifies all subscribers (effects/computed) that depend on a specific
  * property of a reactive object that the property has changed.
@@ -251,11 +258,11 @@ declare function untrack<T>(fn: () => T): T;
  * - **CLEAR**: Collection cleared (affects iteration)
  *
  * ## Iteration Dependencies
-
- * @param target - The reactive object that changed
- * @param type - The type of operation: 'SET' | 'ADD' | 'DELETE' | 'CLEAR'
- * @param key - The property key that changed (optional for CLEAR operations)
- * @param newValue - The new value (optional, used for debugging)
+ *
+ * @param target - The reactive object that changed.
+ * @param type - The type of operation: 'SET' | 'ADD' | 'DELETE' | 'CLEAR'.
+ * @param key - The property key that changed (optional for CLEAR operations).
+ * @param newValue - The new value.
  *
  * @example
  * ```typescript
@@ -277,6 +284,15 @@ declare function untrack<T>(fn: () => T): T;
  *                      // trigger(state.items, 'ADD', '3', 4)
  * ```
  */
+/**
+ * Trigger updates for subscribers of a reactive object property.
+ *
+ * @param target - The reactive object that changed.
+ * @param type - The type of operation: 'SET' | 'ADD' | 'DELETE' | 'CLEAR'.
+ * @param key - The property key that changed (optional for CLEAR operations).
+ * @param newValue - The new value.
+ * @returns {void}
+ */
 declare function trigger(target: object, type: string, key?: string | symbol | (string | symbol)[], newValue?: unknown): void;
 
 /**
@@ -338,9 +354,9 @@ type SignalType<T> = T extends Signal<infer V> ? V : never;
  * Create a new signal with the given initial value.
  * The signal will track all nested properties of object values.
  *
- * @template T - The type of value to store in the signal
- * @param value - Initial value (defaults to undefined)
- * @returns A new signal instance
+ * @template T - The type of value to store in the signal.
+ * @param value - Initial value (defaults to undefined).
+ * @returns A new signal instance.
  *
  * @example
  * ```typescript
@@ -349,15 +365,14 @@ type SignalType<T> = T extends Signal<infer V> ? V : never;
  * const empty = signal(); // undefined
  * ```
  */
-declare function signal<T>(value: Signal<T>): Signal<T>;
 declare function signal<T>(value?: T): Signal<T>;
 /**
  * Create a new shallow signal with the given initial value.
  * Only the top-level properties of object values are reactive.
  *
- * @template T - The type of value to store in the signal
- * @param value - Initial value (defaults to undefined)
- * @returns A new shallow signal instance
+ * @template T - The type of value to store in the signal.
+ * @param value - Initial value (defaults to undefined).
+ * @returns A new shallow signal instance.
  *
  * @example
  * ```typescript
@@ -369,9 +384,9 @@ declare function shallowSignal<T>(value?: T): Signal<T>;
 /**
  * Type guard to check if a value is a Signal instance.
  *
- * @template T - The type of value held by the signal
- * @param value - The value to check
- * @returns true if the value is a Signal instance
+ * @template T - The type of value held by the signal.
+ * @param value - The value to check.
+ * @returns true if the value is a Signal instance.
  */
 declare function isSignal<T>(value: unknown): value is Signal<T>;
 
@@ -451,31 +466,36 @@ declare class ComputedImpl<T = any> implements Computed<T>, ReactiveNode {
     readonly onTrigger?: (event: DebuggerEvent) => void;
     private _value;
     /**
-     * Create a Computed instance
+     * Create a Computed instance.
      *
-     * @param getter - The computation function
-     * @param setter - Optional setter function
-     * @param onTrack - Optional debug callback for dependency tracking
-     * @param onTrigger - Optional debug callback for triggers
+     * @param getter - The computation function.
+     * @param setter - Optional setter function.
+     * @param onTrack - Optional debug callback for dependency tracking.
+     * @param onTrigger - Optional debug callback for triggers.
      */
     constructor(getter: ComputedGetter<T>, setter?: ComputedSetter<T>, onTrack?: (event: DebuggerEvent) => void, onTrigger?: (event: DebuggerEvent) => void);
+    /**
+     * Returns the current value.
+     *
+     * @returns {T} The current value.
+     */
     get value(): T;
     /**
-     * Set value (only effective when setter is provided)
+     * Set value (only effective when setter is provided).
      *
-     * @param newValue - The new value
+     * @param newValue - The new value.
      */
     set value(newValue: T);
     /**
-     * Read value without tracking dependencies
+     * Read value without tracking dependencies.
      *
-     * @returns Current value
+     * @returns {T} The current value.
      */
     peek(): T;
     /**
      * Recompute the value
      *
-     * computation logic:
+     *  computation logic:
      * 1. Start tracking dependencies
      * 2. Execute getter function
      * 3. Check if value changed using optimized comparison
@@ -485,19 +505,19 @@ declare class ComputedImpl<T = any> implements Computed<T>, ReactiveNode {
      */
     private recompute;
     /**
-     * Check if update is needed
+     * Check if update is needed.
      *
      * Internal use, called by reactive system.
      *
-     * @returns true if value changed
+     * @returns {boolean} True if value changed.
      */
     shouldUpdate(): boolean;
 }
 /**
- * Create a Computed value
+ * Create a Computed value.
  *
- * @param getterOrOptions - Computation function or configuration object
- * @returns Computed instance
+ * @param getterOrOptions - Computation function or configuration object.
+ * @returns {ComputedImpl<T>} Computed instance.
  *
  * @example
  * ```typescript
@@ -528,10 +548,11 @@ declare class ComputedImpl<T = any> implements Computed<T>, ReactiveNode {
  */
 declare function computed<T>(getterOrOptions: ComputedGetter<T> | ComputedOptions<T>): ComputedImpl<T>;
 /**
- * Type guard - Check if value is Computed
+ * Type guard - Check if value is a Computed instance.
  *
- * @param value - The value to check
- * @returns true if value is Computed
+ * @template T - The type of value held by the computed instance.
+ * @param value - The value to check.
+ * @returns {boolean} True if value is a Computed instance.
  */
 declare function isComputed<T>(value: unknown): value is Computed<T>;
 
@@ -540,22 +561,22 @@ declare function isComputed<T>(value: unknown): value is Computed<T>;
  * Recursively unwraps nested reactive objects and arrays.
  *
  * @param value - Reactive or signal value.
- * @returns Raw value without any reactive wrapping.
+ * @returns {T} Raw value without any reactive wrapping.
  */
 declare function toRaw<T>(value: T): T;
 /**
  * Check if the target object is reactive.
  *
  * @param target - The object to check.
- * @returns True if the object is reactive, false otherwise.
+ * @returns {boolean} True if the object is reactive, false otherwise.
  */
 declare function isReactive(target: unknown): boolean;
 /**
  * Create a reactive proxy for the given target object. If the object is already reactive, return directly.
  *
- * @template T - The type of the object to make reactive
- * @param target - The object to make reactive
- * @returns The reactive proxy of the target object
+ * @template T - The type of the object to make reactive.
+ * @param target - The object to make reactive.
+ * @returns {T} The reactive proxy of the target object.
  *
  * @example
  * ```typescript
@@ -567,9 +588,9 @@ declare function reactive<T extends object>(target: T): T;
 /**
  * Create a shallow reactive proxy for the given object. Only root-level properties are reactive.
  *
- * @template T - The type of the object to make shallow reactive
- * @param target - The object to make shallow reactive
- * @returns The shallow reactive proxy of the object
+ * @template T - The type of the object to make shallow reactive.
+ * @param target - The object to make shallow reactive.
+ * @returns {T} The shallow reactive proxy of the object.
  *
  * @example
  * ```typescript
@@ -582,7 +603,7 @@ declare function shallowReactive<T extends object>(target: T): T;
  * Check if the target object is a shallow reactive proxy.
  *
  * @param value - The object to check.
- * @returns True if the object is shallow reactive, false otherwise.
+ * @returns {boolean} True if the object is shallow reactive, false otherwise.
  */
 declare function isShallow(value: unknown): boolean;
 /**
@@ -590,6 +611,7 @@ declare function isShallow(value: unknown): boolean;
  * If the given value is not an object, return the original value itself.
  *
  * @param value - The value that needs a reactive proxy created for it.
+ * @returns {T} The reactive proxy of the value, or the original value.
  */
 declare const toReactive: <T extends unknown>(value: T) => T;
 /**
@@ -616,30 +638,22 @@ type PreFlushCallback = () => void;
  */
 type FlushTiming = 'pre' | 'post' | 'sync';
 /**
- * Schedules a function to be executed in the next microtask
- *
- * Returns a Promise that resolves in the next microtask.
- * Passing fn chains it onto the shared resolved promise — cheaper than
- * constructing a new Promise + queueMicrotask pair.
+ * Schedules a function to be executed in the next microtask.
  *
- * @param fn - Optional function to execute
- * @returns A Promise that resolves after the function execution
+ * @param fn - Optional function to execute.
+ * @returns A Promise that resolves after the function execution.
  */
 declare function nextTick(fn?: () => void): Promise<void>;
 /**
- * Adds a job to the main queue and ensures it will be executed
+ * Adds a job to the main queue and ensures it will be executed.
  *
- * Jobs are automatically deduplicated - the same job reference won't be added multiple times.
- * This is useful for batching updates and avoiding redundant work.
- * @param job - The job to enqueue
+ * @param job - The job to enqueue.
  */
 declare function queueJob(job: Job): void;
 /**
- * Adds a callback to be executed before the main queue processing
+ * Adds a callback to be executed before the main queue processing.
  *
- * Pre-flush callbacks are useful for setup work that needs to run before effects,
- * such as computing derived values or preparing state.
- * @param cb - The callback to execute before the main queue
+ * @param cb - The callback to execute before the main queue.
  */
 declare function queuePreFlushCb(cb: PreFlushCallback): void;
 
@@ -751,80 +765,66 @@ declare class EffectImpl<T = any> implements ReactiveNode {
     flag: ReactiveFlags;
     private readonly [SignalFlags.IS_EFFECT];
     readonly fn: EffectFunction<T>;
+    readonly options?: EffectOptions;
     private _flushScheduler?;
-    _active: boolean;
     onTrack?: (event: DebuggerEvent) => void;
     onTrigger?: (event: DebuggerEvent) => void;
-    onStop?: () => void;
+    private _active;
     /**
-     * Create an Effect instance
+     * Create an Effect instance.
      *
-     * @param fn - The effect function
-     * @param options - Configuration options
+     * @param fn - The effect function.
+     * @param options - Configuration options.
      */
     constructor(fn: EffectFunction<T>, options?: EffectOptions);
     /**
-     * Check if the Effect is active
+     * Check if the Effect is active.
+     *
+     * @returns {boolean} True if the effect is active.
      */
     get active(): boolean;
     /**
-     * Check if the Effect is dirty (needs re-execution)
+     * Check if the Effect is dirty (needs re-execution).
+     *
+     * @returns {boolean} True if the effect is dirty.
      */
     get dirty(): boolean;
     /**
-     * Pause Effect execution
+     * Pause Effect execution.
      *
      * When an effect is paused:
-     * - It stops responding to dependency changes
-     * - Notifications are ignored (see notify method)
-     * - DIRTY and PENDING flags are still set when dependencies change
-     * - The effect remains active and maintains its dependency links
+     * - It stops responding to dependency changes.
+     * - Notifications are ignored (see notify method).
+     * - DIRTY and PENDING flags are still set when dependencies change.
+     * - The effect remains active and maintains its dependency links.
      *
      * Use cases:
-     * - Temporarily disable effects during bulk updates
-     * - Prevent effects from running during initialization
-     * - Control when side effects should execute
+     * - Temporarily disable effects during bulk updates.
+     * - Prevent effects from running during initialization.
+     * - Control when side effects should execute.
      *
-     * @example
-     * ```typescript
-     * const count = signal(0);
-     * const runner = effect(() => console.log(count.value));
-     *
-     * runner.effect.pause();
-     * count.value = 1; // Effect won't run
-     * count.value = 2; // Effect won't run
-     * runner.effect.resume(); // Effect runs once with latest value
-     * ```
+     * @returns {void}
      */
     pause(): void;
     /**
-     * Resume Effect execution
+     * Resume Effect execution.
      *
      * When an effect is resumed:
-     * - The PAUSED flag is cleared
+     * - The PAUSED flag is cleared.
      * - If dependencies changed during pause (DIRTY or PENDING flags set),
-     *   the effect executes immediately via notify()
-     * - If no changes occurred, the effect simply becomes active again
+     *   the effect executes immediately via notify().
+     * - If no changes occurred, the effect simply becomes active again.
      *
      * State management:
-     * - Clears PAUSED flag atomically
-     * - Checks for accumulated DIRTY/PENDING flags
-     * - Triggers execution if needed
-     *
-     * @example
-     * ```typescript
-     * const count = signal(0);
-     * const runner = effect(() => console.log(count.value));
+     * - Clears PAUSED flag atomically.
+     * - Checks for accumulated DIRTY/PENDING flags.
+     * - Triggers execution if needed.
      *
-     * runner.effect.pause();
-     * count.value = 1; // Queued
-     * count.value = 2; // Queued
-     * runner.effect.resume(); // Executes once with count.value = 2
-     * ```
+     * @returns {void}
      */
     resume(): void;
     /**
-     * Execute the Effect function
+     * Execute the Effect function.
      *
      * Core execution flow:
      * 1. Check if active
@@ -832,40 +832,46 @@ declare class EffectImpl<T = any> implements ReactiveNode {
      * 3. Start tracking dependencies
      * 4. Execute user function
      * 5. End tracking, clean up stale dependencies
-  
-     * @returns The return value of the effect function
+     *
+     * @returns {T} The return value of the effect function.
      */
     run(): T;
     private _job?;
     /**
-     * Get or create the job function for this effect
+     * Get or create the job function for this effect.
+     *
+     * @returns {() => void} The job function.
      */
     private getJob;
     /**
-     * Notify that the Effect needs to execute
+     * Notify that the Effect needs to execute.
      *
      * Called by dependent reactive values.
      * Decides whether to execute immediately or defer based on scheduling strategy.
+     *
+     * @returns {void}
      */
     notify(): void;
     /**
-     * Stop the Effect
+     * Stop the Effect.
      *
      * After stopping:
-     * - No longer responds to dependency changes
-     * - Disconnects all dependency links
-     * - Clears cached job function
-     * - Calls onStop callback
-     * - Verifies complete cleanup in development mode
+     * - No longer responds to dependency changes.
+     * - Disconnects all dependency links.
+     * - Clears cached job function.
+     * - Calls onStop callback.
+     * - Verifies complete cleanup in development mode.
+     *
+     * @returns {void}
      */
     stop(): void;
 }
 /**
- * Create and immediately execute an Effect
+ * Create and immediately execute an Effect.
  *
- * @param fn - The effect function
- * @param options - Configuration options
- * @returns Effect runner
+ * @param fn - The effect function.
+ * @param options - Configuration options.
+ * @returns {EffectRunner<T>} Effect runner.
  *
  * @example
  * ```typescript
@@ -896,16 +902,17 @@ declare class EffectImpl<T = any> implements ReactiveNode {
  */
 declare function effect<T = any>(fn: EffectFunction<T>, options?: EffectOptions): EffectRunner<T>;
 /**
- * Stop Effect execution
+ * Stop Effect execution.
  *
- * @param runner - The effect runner
+ * @param runner - The effect runner to stop.
+ * @returns {void}
  */
 declare function stop(runner: EffectRunner): void;
 /**
- * Type guard - Check if value is an Effect
+ * Type guard - Check if value is an Effect instance.
  *
- * @param value - The value to check
- * @returns true if value is an Effect
+ * @param value - The value to check.
+ * @returns {boolean} True if value is an Effect instance.
  */
 declare function isEffect(value: any): value is EffectImpl;
 /**
@@ -917,21 +924,15 @@ declare function isEffect(value: any): value is EffectImpl;
  */
 type MemoEffectFn<T> = (prevState: T) => T;
 /**
- * Create a memoized Effect
+ * Create a memoized Effect.
  *
  * A memoized effect remembers the return value from the previous execution
  * and passes it as a parameter on the next execution.
  *
- * Use cases:
- * - Incremental DOM updates
- * - Avoiding duplicate operations
- * - State persistence
- * - Difference detection
- *
- * @param fn - The memoized function
- * @param initialState - Initial state
- * @param options - Configuration options
- * @returns Effect runner
+ * @param fn - The memoized function.
+ * @param initialState - Initial state.
+ * @param options - Configuration options.
+ * @returns {EffectRunner<void>} Effect runner.
  *
  * @example
  * ```typescript
@@ -953,13 +954,10 @@ type MemoEffectFn<T> = (prevState: T) => T;
 declare function memoEffect<T>(fn: MemoEffectFn<T>, initialState: T, options?: EffectOptions): EffectRunner<void>;
 
 /**
- * Execute a function in batch mode
- *
- * Executes the function in a batch context, where all Signal changes
- * are deferred and processed together after the batch ends.
+ * Execute a function in batch mode.
  *
- * @param fn - The function to execute in batch mode
- * @returns The return value of the function
+ * @param fn - The function to execute in batch mode.
+ * @returns The return value of the function.
  *
  * @example
  * ```typescript
@@ -983,45 +981,27 @@ declare function memoEffect<T>(fn: MemoEffectFn<T>, initialState: T, options?: E
  */
 declare function batch<T>(fn: () => T): T;
 /**
- * Start batch update
+ * Start batch update.
  *
- * Increases batch depth.
- * During batch, Effects won't execute immediately.
+ * @returns {void}
  */
 declare function startBatch(): void;
 /**
- * End batch update
+ * End batch update.
  *
- * Decreases batch depth.
- * When depth reaches zero, flush all queued Effects.
- *
- * ## Cleanup Process
- *
- * When the outermost batch ends:
- * 1. Flush all queued jobs (effects execute)
- * 2. Job queue is automatically cleared by flushJobs()
- * 3. Temporary flags (QUEUED, DIRTY) are cleared by effect execution
- *
- * ## Development Mode Checks
- *
- * In development mode, this function performs additional validation:
- * - Detects unbalanced batch calls (endBatch without startBatch)
- * - Prevents batchDepth from becoming negative
- * - Provides clear error messages to help debug batch management issues
+ * @returns {void}
  */
 declare function endBatch(): void;
 /**
- * Check if currently in batch update mode
+ * Check if currently in batch update mode.
  *
- * @returns true if currently in batch
+ * @returns True if currently in batch mode.
  */
 declare function isBatching(): boolean;
 /**
- * Get current batch depth
+ * Get current batch depth.
  *
- * Mainly used for debugging.
- *
- * @returns Current batch nesting depth
+ * @returns Current batch nesting depth.
  */
 declare function getBatchDepth(): number;
 
@@ -1097,6 +1077,12 @@ interface StoreActions<S extends State> {
      * @param callback - Function to call on action execution
      */
     onAction$: (callback: StoreCallback<S>) => void;
+    /**
+     * Removes a previously registered action callback.
+     *
+     * @param callback - The callback to remove.
+     */
+    offAction$: (callback: StoreCallback<S>) => void;
     /**
      * Resets the store state to its initial values.
      */
@@ -1122,11 +1108,11 @@ type StoreDefinition<S extends State, G extends Getters<S>, A extends Actions> =
  * Creates a new store with the given definition.
  * The store can be defined either as a class or as an options object.
  *
- * @template S - The type of the store's state
- * @template G - The type of the store's getters
- * @template A - The type of the store's actions
- * @param storeDefinition - The store definition (class or options)
- * @returns A function that creates a new store instance
+ * @template S - The type of the store's state.
+ * @template G - The type of the store's getters.
+ * @template A - The type of the store's actions.
+ * @param storeDefinition - The store definition (class or options).
+ * @returns A function that creates a new store instance.
  *
  * @example
  * ```ts
@@ -1180,9 +1166,9 @@ interface Ref<T> extends Signal<T> {
  * Creates a new ref with the given initial value.
  * Unlike signals, refs don't create reactive proxies for object values.
  *
- * @template T - The type of value to store in the ref
- * @param value - The initial value
- * @returns A new ref instance
+ * @template T - The type of value to store in the ref.
+ * @param value - The initial value.
+ * @returns A new ref instance.
  *
  * @example
  * ```ts
@@ -1194,9 +1180,9 @@ declare function ref<T>(value?: T): Ref<T>;
 /**
  * Type guard to check if a value is a Ref instance.
  *
- * @template T - The type of value held by the ref
- * @param value - The value to check
- * @returns True if the value is a Ref instance
+ * @template T - The type of value held by the ref.
+ * @param value - The value to check.
+ * @returns True if the value is a Ref instance.
  */
 declare function isRef<T>(value: unknown): value is Ref<T>;
 
@@ -1204,17 +1190,17 @@ interface WatchOptions {
     immediate?: boolean;
     deep?: boolean;
 }
-/** Watch source type, can be value, ref/signal, getter function or array. */
 type WatchSource<T = any> = T | {
     value: T;
 } | (() => T);
 type WatchCallback<T = any> = (newValue: T, oldValue: T | undefined) => void;
 /**
  * Watch one or more reactive data sources and execute callback when sources change.
+ *
  * @param source - The source(s) to watch.
  * @param callback - The callback function to execute when source changes.
  * @param options - Configuration options like immediate and deep.
- * @returns A function to stop watching.
+ * @returns {Function} A function to stop watching.
  */
 declare function watch<T = any>(source: WatchSource<T>, callback: WatchCallback<T>, options?: WatchOptions): () => void;