@estjs/signals 0.0.16-beta.2 → 0.0.16-beta.3

package/dist/signals.d.cts

@@ -84,215 +84,35 @@ declare enum SignalFlags {
     IS_EFFECT = "_IS_EFFECT"
 }
 
-/**
- * Link - Bidirectional connection in the dependency graph
- *
- * A Link connects two ReactiveNodes:
- * - depNode: The dependency node (data source)
- * - subNode: The subscriber node (data consumer)
- *
- * Links form doubly-linked lists in two directions:
- * 1. Subscriber Chain: Connects all subscribers of the same dependency
- * 2. Dependency Chain: Connects all dependencies of the same subscriber
- *
- * @example
- * ```
- * Signal A ←─┐
- *            ├─→ Effect X
- * Signal B ←─┘
- *
- * Link1: A → X (A's subscriber chain, X's dependency chain)
- * Link2: B → X (B's subscriber chain, X's dependency chain)
- * ```
- */
 interface Link {
-    /**
-     * Version number
-     *
-     * Used to detect stale Links.
-     * The global version number increments each time dependency tracking starts.
-     * Links with old versions will be cleaned up.
-     *
-     */
     version: number;
-    /**
-     * Dependency node - The data source being depended on
-     * Examples: Signal, Computed
-     */
     depNode: ReactiveNode;
-    /**
-     * Subscriber node - The consumer of the data
-     * Examples: Effect, Computed
-     */
     subNode: ReactiveNode;
-    /** Previous subscriber Link */
     prevSubLink?: Link;
-    /** Next subscriber Link */
     nextSubLink?: Link;
-    /** Previous dependency Link */
     prevDepLink?: Link;
-    /** Next dependency Link */
     nextDepLink?: Link;
 }
-/**
- * Debugger event types for tracking reactive operations
- */
 type DebuggerEventType = 'get' | 'set' | 'add' | 'delete' | 'clear' | 'iterate';
-/**
- * Debugger event for tracking reactive operations
- *
- * This event is passed to onTrack and onTrigger callbacks to provide
- * detailed information about reactive operations for debugging purposes.
- *
- * @example
- * ```typescript
- * effect(() => {
- *   console.log(signal.value);
- * }, {
- *   onTrack(event) {
- *     console.log('Tracked:', event.type, event.key);
- *   },
- *   onTrigger(event) {
- *     console.log('Triggered:', event.type, event.key, event.newValue);
- *   }
- * });
- * ```
- */
 interface DebuggerEvent {
-    /** The effect or computed that is tracking/being triggered */
     effect: ReactiveNode;
-    /** The reactive object being accessed or modified */
     target: object;
-    /** The type of operation */
     type: DebuggerEventType | string;
-    /** The property key being accessed or modified (optional) */
     key?: any;
-    /** The new value being set (optional, only for trigger events) */
     newValue?: any;
 }
-/**
- * ReactiveNode - Reactive node interface
- *
- * All objects participating in the reactive system implement this interface.
- * Includes Signal, Computed, Effect, Reactive objects, etc.
- *
- * Nodes form a dependency graph through Links:
- * - depLink: List of nodes I depend on
- * - subLink: List of nodes that depend on me
- */
 interface ReactiveNode {
-    /**
-     * Dependency chain head - The first node I depend on
-     *
-     * Traverse all dependencies through nextDepLink.
-     */
     depLink?: Link;
-    /**
-     * Subscriber chain head - The first node that depends on me
-     *
-     * Traverse all subscribers through nextSubLink.
-     */
     subLink?: Link;
-    /**
-     * Dependency chain tail - The last node I depend on
-     *
-     * Used for O(1) time complexity linked list append operations.
-     */
     depLinkTail?: Link;
-    /**
-     * Subscriber chain tail - The last node that depends on me
-     *
-     * Used for O(1) time complexity linked list append operations.
-     */
     subLinkTail?: Link;
-    /**
-     * State flags
-     * @see ReactiveFlags
-     */
     flag: ReactiveFlags;
-    /**
-     * 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.
- *
- * @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.
- *
- * This function notifies all subscribers (effects/computed) that depend on a specific
- * property of a reactive object that the property has changed.
- *
- * ## When is this called?
- *
- * - When setting a property: `reactiveObj.prop = value` → trigger(obj, 'SET', 'prop', value)
- * - When adding a property: `reactiveObj.newProp = value` → trigger(obj, 'ADD', 'newProp', value)
- * - When deleting a property: `delete reactiveObj.prop` → trigger(obj, 'DELETE', 'prop')
- * - When clearing a collection: `reactiveArray.length = 0` → trigger(obj, 'CLEAR')
- * - When mutating arrays: `reactiveArray.push(item)` → trigger(obj, 'SET', 'length', newLength)
- *
- * ## Operation Types
- *
- * - **SET**: Property value changed (most common)
- * - **ADD**: New property added (affects iteration)
- * - **DELETE**: Property removed (affects iteration)
- * - **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.
- *
- * @example
- * ```typescript
- * const state = reactive({ count: 0, items: [1, 2, 3] });
- *
- * effect(() => {
- *   console.log(state.count); // Depends on 'count'
- * });
- *
- * effect(() => {
- *   console.log(state.items.length); // Depends on 'items' and iteration
- * });
- *
- * // Triggers first effect only
- * state.count = 1; // trigger(state, 'SET', 'count', 1)
- *
- * // Triggers second effect (changes length and iteration)
- * state.items.push(4); // trigger(state.items, 'SET', 'length', 4)
- *                      // 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;
 
 /**
@@ -390,6 +210,34 @@ declare function shallowSignal<T>(value?: T): Signal<T>;
  */
 declare function isSignal<T>(value: unknown): value is Signal<T>;
 
+interface ScopedReactiveEffect {
+    stop(): void;
+    pause?(): void;
+    resume?(): void;
+    scope?: EffectScope;
+}
+declare class EffectScope {
+    detached: boolean;
+    parent: EffectScope | undefined;
+    private _active;
+    private effects;
+    private scopes;
+    private cleanups;
+    constructor(detached?: boolean, parent?: EffectScope | undefined);
+    get active(): boolean;
+    pause(): void;
+    resume(): void;
+    run<T>(fn: () => T): T | undefined;
+    stop(fromParent?: boolean): void;
+    _record(effect: ScopedReactiveEffect): void;
+    _remove(effect: ScopedReactiveEffect): void;
+    _pushCleanup(fn: () => void): void;
+}
+declare function effectScope(detached?: boolean): EffectScope;
+declare function getCurrentScope(): EffectScope | undefined;
+declare function setCurrentScope(scope?: EffectScope): EffectScope | undefined;
+declare function onScopeDispose(fn: () => void, failSilently?: boolean): void;
+
 /**
  * Computed getter function type
  */
@@ -453,7 +301,7 @@ type ComputedType<T> = T extends Computed<infer V> ? V : never;
  *
  * @template T - The type of the computed value
  */
-declare class ComputedImpl<T = any> implements Computed<T>, ReactiveNode {
+declare class ComputedImpl<T = any> implements Computed<T>, ReactiveNode, ScopedReactiveEffect {
     depLink?: Link;
     subLink?: Link;
     depLinkTail?: Link;
@@ -464,7 +312,9 @@ declare class ComputedImpl<T = any> implements Computed<T>, ReactiveNode {
     readonly setter?: ComputedSetter<T>;
     readonly onTrack?: (event: DebuggerEvent) => void;
     readonly onTrigger?: (event: DebuggerEvent) => void;
+    scope?: EffectScope;
     private _value;
+    private _active;
     /**
      * Create a Computed instance.
      *
@@ -492,6 +342,7 @@ declare class ComputedImpl<T = any> implements Computed<T>, ReactiveNode {
      * @returns {T} The current value.
      */
     peek(): T;
+    get active(): boolean;
     /**
      * Recompute the value
      *
@@ -512,6 +363,7 @@ declare class ComputedImpl<T = any> implements Computed<T>, ReactiveNode {
      * @returns {boolean} True if value changed.
      */
     shouldUpdate(): boolean;
+    stop(): void;
 }
 /**
  * Create a Computed value.
@@ -757,7 +609,7 @@ interface EffectRunner<T = any> {
  *
  * @template T - The return type of the effect function
  */
-declare class EffectImpl<T = any> implements ReactiveNode {
+declare class EffectImpl<T = any> implements ReactiveNode, ScopedReactiveEffect {
     depLink?: Link;
     subLink?: Link;
     depLinkTail?: Link;
@@ -770,6 +622,7 @@ declare class EffectImpl<T = any> implements ReactiveNode {
     onTrack?: (event: DebuggerEvent) => void;
     onTrigger?: (event: DebuggerEvent) => void;
     private _active;
+    scope?: EffectScope;
     /**
      * Create an Effect instance.
      *
@@ -1204,4 +1057,4 @@ type WatchCallback<T = any> = (newValue: T, oldValue: T | undefined) => void;
  */
 declare function watch<T = any>(source: WatchSource<T>, callback: WatchCallback<T>, options?: WatchOptions): () => void;
 
-export { type Computed, type ComputedGetter, type ComputedOptions, type ComputedSetter, type ComputedType, type DebuggerEvent, type DebuggerEventType, type EffectFunction, type EffectOptions, type EffectRunner, type EffectScheduler, type FlushTiming, type Job, type MemoEffectFn, type PreFlushCallback, type Reactive, type Ref, type Signal, type SignalType, type SignalValue, type StoreActions, type StoreOptions, TriggerOpTypes, type Unwrap, batch, computed, createStore, effect, endBatch, getBatchDepth, isBatching, isComputed, isEffect, isReactive, isRef, isShallow, isSignal, memoEffect, nextTick, queueJob, queuePreFlushCb, reactive, ref, shallowReactive, shallowSignal, signal, startBatch, stop, toRaw, toReactive, trigger, untrack, watch };
+export { type Computed, type ComputedGetter, type ComputedOptions, type ComputedSetter, type ComputedType, type DebuggerEvent, type DebuggerEventType, type EffectFunction, type EffectOptions, type EffectRunner, type EffectScheduler, EffectScope, type FlushTiming, type Job, type MemoEffectFn, type PreFlushCallback, type Reactive, type Ref, type Signal, type SignalType, type SignalValue, type StoreActions, type StoreOptions, TriggerOpTypes, type Unwrap, batch, computed, createStore, effect, effectScope, endBatch, getBatchDepth, getCurrentScope, isBatching, isComputed, isEffect, isReactive, isRef, isShallow, isSignal, memoEffect, nextTick, onScopeDispose, queueJob, queuePreFlushCb, reactive, ref, setCurrentScope, shallowReactive, shallowSignal, signal, startBatch, stop, toRaw, toReactive, trigger, untrack, watch };

package/dist/signals.d.ts

@@ -84,215 +84,35 @@ declare enum SignalFlags {
     IS_EFFECT = "_IS_EFFECT"
 }
 
-/**
- * Link - Bidirectional connection in the dependency graph
- *
- * A Link connects two ReactiveNodes:
- * - depNode: The dependency node (data source)
- * - subNode: The subscriber node (data consumer)
- *
- * Links form doubly-linked lists in two directions:
- * 1. Subscriber Chain: Connects all subscribers of the same dependency
- * 2. Dependency Chain: Connects all dependencies of the same subscriber
- *
- * @example
- * ```
- * Signal A ←─┐
- *            ├─→ Effect X
- * Signal B ←─┘
- *
- * Link1: A → X (A's subscriber chain, X's dependency chain)
- * Link2: B → X (B's subscriber chain, X's dependency chain)
- * ```
- */
 interface Link {
-    /**
-     * Version number
-     *
-     * Used to detect stale Links.
-     * The global version number increments each time dependency tracking starts.
-     * Links with old versions will be cleaned up.
-     *
-     */
     version: number;
-    /**
-     * Dependency node - The data source being depended on
-     * Examples: Signal, Computed
-     */
     depNode: ReactiveNode;
-    /**
-     * Subscriber node - The consumer of the data
-     * Examples: Effect, Computed
-     */
     subNode: ReactiveNode;
-    /** Previous subscriber Link */
     prevSubLink?: Link;
-    /** Next subscriber Link */
     nextSubLink?: Link;
-    /** Previous dependency Link */
     prevDepLink?: Link;
-    /** Next dependency Link */
     nextDepLink?: Link;
 }
-/**
- * Debugger event types for tracking reactive operations
- */
 type DebuggerEventType = 'get' | 'set' | 'add' | 'delete' | 'clear' | 'iterate';
-/**
- * Debugger event for tracking reactive operations
- *
- * This event is passed to onTrack and onTrigger callbacks to provide
- * detailed information about reactive operations for debugging purposes.
- *
- * @example
- * ```typescript
- * effect(() => {
- *   console.log(signal.value);
- * }, {
- *   onTrack(event) {
- *     console.log('Tracked:', event.type, event.key);
- *   },
- *   onTrigger(event) {
- *     console.log('Triggered:', event.type, event.key, event.newValue);
- *   }
- * });
- * ```
- */
 interface DebuggerEvent {
-    /** The effect or computed that is tracking/being triggered */
     effect: ReactiveNode;
-    /** The reactive object being accessed or modified */
     target: object;
-    /** The type of operation */
     type: DebuggerEventType | string;
-    /** The property key being accessed or modified (optional) */
     key?: any;
-    /** The new value being set (optional, only for trigger events) */
     newValue?: any;
 }
-/**
- * ReactiveNode - Reactive node interface
- *
- * All objects participating in the reactive system implement this interface.
- * Includes Signal, Computed, Effect, Reactive objects, etc.
- *
- * Nodes form a dependency graph through Links:
- * - depLink: List of nodes I depend on
- * - subLink: List of nodes that depend on me
- */
 interface ReactiveNode {
-    /**
-     * Dependency chain head - The first node I depend on
-     *
-     * Traverse all dependencies through nextDepLink.
-     */
     depLink?: Link;
-    /**
-     * Subscriber chain head - The first node that depends on me
-     *
-     * Traverse all subscribers through nextSubLink.
-     */
     subLink?: Link;
-    /**
-     * Dependency chain tail - The last node I depend on
-     *
-     * Used for O(1) time complexity linked list append operations.
-     */
     depLinkTail?: Link;
-    /**
-     * Subscriber chain tail - The last node that depends on me
-     *
-     * Used for O(1) time complexity linked list append operations.
-     */
     subLinkTail?: Link;
-    /**
-     * State flags
-     * @see ReactiveFlags
-     */
     flag: ReactiveFlags;
-    /**
-     * 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.
- *
- * @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.
- *
- * This function notifies all subscribers (effects/computed) that depend on a specific
- * property of a reactive object that the property has changed.
- *
- * ## When is this called?
- *
- * - When setting a property: `reactiveObj.prop = value` → trigger(obj, 'SET', 'prop', value)
- * - When adding a property: `reactiveObj.newProp = value` → trigger(obj, 'ADD', 'newProp', value)
- * - When deleting a property: `delete reactiveObj.prop` → trigger(obj, 'DELETE', 'prop')
- * - When clearing a collection: `reactiveArray.length = 0` → trigger(obj, 'CLEAR')
- * - When mutating arrays: `reactiveArray.push(item)` → trigger(obj, 'SET', 'length', newLength)
- *
- * ## Operation Types
- *
- * - **SET**: Property value changed (most common)
- * - **ADD**: New property added (affects iteration)
- * - **DELETE**: Property removed (affects iteration)
- * - **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.
- *
- * @example
- * ```typescript
- * const state = reactive({ count: 0, items: [1, 2, 3] });
- *
- * effect(() => {
- *   console.log(state.count); // Depends on 'count'
- * });
- *
- * effect(() => {
- *   console.log(state.items.length); // Depends on 'items' and iteration
- * });
- *
- * // Triggers first effect only
- * state.count = 1; // trigger(state, 'SET', 'count', 1)
- *
- * // Triggers second effect (changes length and iteration)
- * state.items.push(4); // trigger(state.items, 'SET', 'length', 4)
- *                      // 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;
 
 /**
@@ -390,6 +210,34 @@ declare function shallowSignal<T>(value?: T): Signal<T>;
  */
 declare function isSignal<T>(value: unknown): value is Signal<T>;
 
+interface ScopedReactiveEffect {
+    stop(): void;
+    pause?(): void;
+    resume?(): void;
+    scope?: EffectScope;
+}
+declare class EffectScope {
+    detached: boolean;
+    parent: EffectScope | undefined;
+    private _active;
+    private effects;
+    private scopes;
+    private cleanups;
+    constructor(detached?: boolean, parent?: EffectScope | undefined);
+    get active(): boolean;
+    pause(): void;
+    resume(): void;
+    run<T>(fn: () => T): T | undefined;
+    stop(fromParent?: boolean): void;
+    _record(effect: ScopedReactiveEffect): void;
+    _remove(effect: ScopedReactiveEffect): void;
+    _pushCleanup(fn: () => void): void;
+}
+declare function effectScope(detached?: boolean): EffectScope;
+declare function getCurrentScope(): EffectScope | undefined;
+declare function setCurrentScope(scope?: EffectScope): EffectScope | undefined;
+declare function onScopeDispose(fn: () => void, failSilently?: boolean): void;
+
 /**
  * Computed getter function type
  */
@@ -453,7 +301,7 @@ type ComputedType<T> = T extends Computed<infer V> ? V : never;
  *
  * @template T - The type of the computed value
  */
-declare class ComputedImpl<T = any> implements Computed<T>, ReactiveNode {
+declare class ComputedImpl<T = any> implements Computed<T>, ReactiveNode, ScopedReactiveEffect {
     depLink?: Link;
     subLink?: Link;
     depLinkTail?: Link;
@@ -464,7 +312,9 @@ declare class ComputedImpl<T = any> implements Computed<T>, ReactiveNode {
     readonly setter?: ComputedSetter<T>;
     readonly onTrack?: (event: DebuggerEvent) => void;
     readonly onTrigger?: (event: DebuggerEvent) => void;
+    scope?: EffectScope;
     private _value;
+    private _active;
     /**
      * Create a Computed instance.
      *
@@ -492,6 +342,7 @@ declare class ComputedImpl<T = any> implements Computed<T>, ReactiveNode {
      * @returns {T} The current value.
      */
     peek(): T;
+    get active(): boolean;
     /**
      * Recompute the value
      *
@@ -512,6 +363,7 @@ declare class ComputedImpl<T = any> implements Computed<T>, ReactiveNode {
      * @returns {boolean} True if value changed.
      */
     shouldUpdate(): boolean;
+    stop(): void;
 }
 /**
  * Create a Computed value.
@@ -757,7 +609,7 @@ interface EffectRunner<T = any> {
  *
  * @template T - The return type of the effect function
  */
-declare class EffectImpl<T = any> implements ReactiveNode {
+declare class EffectImpl<T = any> implements ReactiveNode, ScopedReactiveEffect {
     depLink?: Link;
     subLink?: Link;
     depLinkTail?: Link;
@@ -770,6 +622,7 @@ declare class EffectImpl<T = any> implements ReactiveNode {
     onTrack?: (event: DebuggerEvent) => void;
     onTrigger?: (event: DebuggerEvent) => void;
     private _active;
+    scope?: EffectScope;
     /**
      * Create an Effect instance.
      *
@@ -1204,4 +1057,4 @@ type WatchCallback<T = any> = (newValue: T, oldValue: T | undefined) => void;
  */
 declare function watch<T = any>(source: WatchSource<T>, callback: WatchCallback<T>, options?: WatchOptions): () => void;
 
-export { type Computed, type ComputedGetter, type ComputedOptions, type ComputedSetter, type ComputedType, type DebuggerEvent, type DebuggerEventType, type EffectFunction, type EffectOptions, type EffectRunner, type EffectScheduler, type FlushTiming, type Job, type MemoEffectFn, type PreFlushCallback, type Reactive, type Ref, type Signal, type SignalType, type SignalValue, type StoreActions, type StoreOptions, TriggerOpTypes, type Unwrap, batch, computed, createStore, effect, endBatch, getBatchDepth, isBatching, isComputed, isEffect, isReactive, isRef, isShallow, isSignal, memoEffect, nextTick, queueJob, queuePreFlushCb, reactive, ref, shallowReactive, shallowSignal, signal, startBatch, stop, toRaw, toReactive, trigger, untrack, watch };
+export { type Computed, type ComputedGetter, type ComputedOptions, type ComputedSetter, type ComputedType, type DebuggerEvent, type DebuggerEventType, type EffectFunction, type EffectOptions, type EffectRunner, type EffectScheduler, EffectScope, type FlushTiming, type Job, type MemoEffectFn, type PreFlushCallback, type Reactive, type Ref, type Signal, type SignalType, type SignalValue, type StoreActions, type StoreOptions, TriggerOpTypes, type Unwrap, batch, computed, createStore, effect, effectScope, endBatch, getBatchDepth, getCurrentScope, isBatching, isComputed, isEffect, isReactive, isRef, isShallow, isSignal, memoEffect, nextTick, onScopeDispose, queueJob, queuePreFlushCb, reactive, ref, setCurrentScope, shallowReactive, shallowSignal, signal, startBatch, stop, toRaw, toReactive, trigger, untrack, watch };