@estjs/signals 0.0.15-beta.1

package/dist/signals.d.ts

@@ -0,0 +1,1213 @@
+/**
+ * Reactive node state flags
+ */
+declare const enum ReactiveFlags {
+    /** No state flags */
+    NONE = 0,
+    /**
+     * Mutable flag - The node's value can change
+     *
+     * Signal and Computed are mutable, triggering propagation when their values change.
+     * Immutable nodes (like constants) don't set this flag.
+     */
+    MUTABLE = 1,// 0b00000001 = 1
+    /**
+     * Watching flag - The node is being watched by an Effect
+     *
+     * Set when an Effect depends on this node.
+     * Used to determine whether to add the Effect to the execution queue.
+     */
+    WATCHING = 2,// 0b00000010 = 2
+    /**
+     * Recursion check flag - Currently checking for circular dependencies
+     *
+     * Set during the checkDirty process to detect and handle circular dependencies.
+     * Prevents infinite recursion.
+     */
+    RECURSED_CHECK = 4,// 0b00000100 = 4
+    /**
+     * Recursed flag - Already in the recursion chain
+     *
+     * Marks that the node has already appeared in the current propagation path.
+     * Used to handle complex dependency graph structures.
+     */
+    RECURSED = 8,// 0b00001000 = 8
+    /**
+     * Dirty flag - The node's value has changed but hasn't propagated yet
+     *
+     * Set when a Signal value changes.
+     * Also set when Computed detects dependency changes.
+     * Indicates need to recompute or notify subscribers.
+     */
+    DIRTY = 16,// 0b00010000 = 16
+    /**
+     * Pending flag - The node may need updating
+     *
+     * Set during propagation, indicating the node's dependencies may have become dirty.
+     * Need to call checkDirty to confirm if update is actually needed.
+     */
+    PENDING = 32,// 0b00100000 = 32
+    /**
+     * Queued flag - Effect has been added to the execution queue
+     *
+     * Prevents the same Effect from being added to the queue multiple times.
+     * This flag is cleared before queue execution.
+     */
+    QUEUED = 64
+}
+declare const TriggerOpTypes: {
+    readonly SET: "SET";
+    readonly ADD: "ADD";
+    readonly DELETE: "DELETE";
+    readonly CLEAR: "CLEAR";
+};
+/**
+ * Internal flags used to mark and identify different types of reactive objects.
+ * These flags are attached as properties to objects to indicate their reactive characteristics.
+ */
+declare enum SignalFlags {
+    /** Mark an object as reactive */
+    IS_REACTIVE = "_IS_REACTIVE",
+    /** Mark an object as readonly */
+    IS_READONLY = "_IS_READONLY",
+    /** Mark an object as shallow reactive (only top-level properties are reactive) */
+    IS_SHALLOW = "_IS_SHALLOW",
+    /** Used to access the raw (non-reactive) version of an object */
+    RAW = "_RAW",
+    /** Mark an object as a signal */
+    IS_SIGNAL = "_IS_SIGNAL",
+    /** Mark an object as a computed property */
+    IS_COMPUTED = "_IS_COMPUTED",
+    /** Mark an object as a ref */
+    IS_REF = "_IS_REF",
+    /** Mark an object as an effect */
+    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;
+}
+/**
+ * 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
+ */
+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 (optional, used for debugging)
+ *
+ * @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)
+ * ```
+ */
+declare function trigger(target: object, type: string, key?: string | symbol | (string | symbol)[], newValue?: unknown): void;
+
+/**
+ * Signal is a reactive primitive that holds a value and notifies subscribers when the value changes.
+ * It provides methods for reading, writing, and observing value changes.
+ *
+ * @template T - The type of value held by the Signal
+ */
+interface Signal<T> {
+    /**
+     * The current value of the Signal. Reading this property tracks dependencies,
+     * and writing to it notifies subscribers of changes.
+     */
+    value: T;
+    /**
+     * Get the current value without establishing a dependency relationship.
+     * Useful when you need to read the value without tracking dependencies.
+     *
+     * @returns The current value
+     */
+    peek(): T;
+    /**
+     * Set a new value without notifying subscribers.
+     * Used for batching multiple updates together.
+     *
+     * @param value - The new value to set
+     */
+    set(value: T): void;
+    /**
+     * Update the value using a function that receives the current value.
+     * This is an atomic operation that only notifies subscribers once.
+     *
+     * @param updater - A function that receives the current value and returns the new value
+     */
+    update(updater: (prev: T) => T): void;
+}
+/**
+ * A more precise type for the value held by a signal.
+ * This type helps TypeScript understand the type of the unwrapped value.
+ *
+ * @template T - The type of value held by the signal
+ */
+type SignalValue<T> = T extends Signal<infer V> ? V : never;
+/**
+ * Extract the value type from a Signal
+ *
+ * @template T - The Signal type
+ *
+ * @example
+ * ```typescript
+ * import { signal, type SignalType } from '@estjs/signals';
+ *
+ * const count = signal(0);
+ * type CountValue = SignalType<typeof count>; // number
+ * ```
+ */
+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
+ *
+ * @example
+ * ```typescript
+ * const count = signal(0);
+ * const user = signal({ name: 'John' });
+ * const empty = signal(); // undefined
+ * ```
+ */
+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
+ *
+ * @example
+ * ```typescript
+ * const state = shallowSignal({ nested: { value: 1 } });
+ * // Only state.nested is reactive, not state.nested.value
+ * ```
+ */
+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
+ */
+declare function isSignal<T>(value: unknown): value is Signal<T>;
+
+/**
+ * Computed getter function type
+ */
+type ComputedGetter<T> = () => T;
+/**
+ * Computed setter function type
+ */
+type ComputedSetter<T> = (value: T) => void;
+/**
+ * Computed options configuration
+ */
+interface ComputedOptions<T> {
+    /** Getter function to compute the value */
+    get: ComputedGetter<T>;
+    /** Optional setter function to make the computed writable */
+    set?: ComputedSetter<T>;
+    /**
+     * Debug callback invoked when a dependency is tracked
+     * Only called in development mode
+     *
+     * @param event - Information about the tracked dependency
+     */
+    onTrack?: (event: DebuggerEvent) => void;
+    /**
+     * Debug callback invoked when the computed is triggered by a dependency change
+     * Only called in development mode
+     *
+     * @param event - Information about what triggered the recomputation
+     */
+    onTrigger?: (event: DebuggerEvent) => void;
+}
+/**
+ * Computed interface
+ */
+interface Computed<T> {
+    readonly value: T;
+    peek(): T;
+}
+/**
+ * Extract the value type from a Computed
+ *
+ * @template T - The Computed type
+ *
+ * @example
+ * ```typescript
+ * import { computed, type ComputedType } from '@estjs/signals';
+ *
+ * const doubled = computed(() => count.value * 2);
+ * type DoubledValue = ComputedType<typeof doubled>; // number
+ * ```
+ */
+type ComputedType<T> = T extends Computed<infer V> ? V : never;
+/**
+ * Computed implementation class
+ *
+ * Implements both Computed and ReactiveNode interfaces.
+ * Features:
+ * - Lazy evaluation: only computes when accessed
+ * - Smart caching: returns cached value when dependencies haven't changed
+ * - Automatic tracking: automatically tracks dependencies during computation
+ *
+ * @template T - The type of the computed value
+ */
+declare class ComputedImpl<T = any> implements Computed<T>, ReactiveNode {
+    depLink?: Link;
+    subLink?: Link;
+    depLinkTail?: Link;
+    subLinkTail?: Link;
+    flag: ReactiveFlags;
+    private readonly [SignalFlags.IS_COMPUTED];
+    readonly getter: ComputedGetter<T>;
+    readonly setter?: ComputedSetter<T>;
+    readonly onTrack?: (event: DebuggerEvent) => void;
+    readonly onTrigger?: (event: DebuggerEvent) => void;
+    private _value;
+    /**
+     * 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
+     */
+    constructor(getter: ComputedGetter<T>, setter?: ComputedSetter<T>, onTrack?: (event: DebuggerEvent) => void, onTrigger?: (event: DebuggerEvent) => void);
+    get value(): T;
+    /**
+     * Set value (only effective when setter is provided)
+     *
+     * @param newValue - The new value
+     */
+    set value(newValue: T);
+    /**
+     * Read value without tracking dependencies
+     *
+     * @returns Current value
+     */
+    peek(): T;
+    /**
+     * Recompute the value
+     *
+     *  computation logic:
+     * 1. Start tracking dependencies
+     * 2. Execute getter function
+     * 3. Check if value changed using optimized comparison
+     * 4. If changed, update cache and notify subscribers
+     * 5. End tracking, clean up stale dependencies
+     * @private
+     */
+    private recompute;
+    /**
+     * Check if update is needed
+     *
+     * Internal use, called by reactive system.
+     *
+     * @returns true if value changed
+     */
+    shouldUpdate(): boolean;
+}
+/**
+ * Create a Computed value
+ *
+ * @param getterOrOptions - Computation function or configuration object
+ * @returns Computed instance
+ *
+ * @example
+ * ```typescript
+ * // Read-only computed
+ * const count = signal(0);
+ * const doubled = computed(() => count.value * 2);
+ *
+ * console.log(doubled.value); // 0
+ * count.value = 5;
+ * console.log(doubled.value); // 10
+ *
+ * // Writable computed
+ * const firstName = signal('John');
+ * const lastName = signal('Doe');
+ *
+ * const fullName = computed({
+ *   get: () => `${firstName.value} ${lastName.value}`,
+ *   set: (value) => {
+ *     const [first, last] = value.split(' ');
+ *     firstName.value = first;
+ *     lastName.value = last;
+ *   }
+ * });
+ *
+ * fullName.value = 'Jane Smith';
+ * console.log(firstName.value); // 'Jane'
+ * ```
+ */
+declare function computed<T>(getterOrOptions: ComputedGetter<T> | ComputedOptions<T>): ComputedImpl<T>;
+/**
+ * Type guard - Check if value is Computed
+ *
+ * @param value - The value to check
+ * @returns true if value is Computed
+ */
+declare function isComputed<T>(value: unknown): value is Computed<T>;
+
+/**
+ * Return the raw underlying value of a reactive proxy or signal.
+ * Recursively unwraps nested reactive objects and arrays.
+ *
+ * @param value - Reactive or signal value.
+ * @returns 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.
+ */
+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
+ *
+ * @example
+ * ```typescript
+ * const state = reactive({ count: 0, nested: { value: 1 } });
+ * // Both state.count and state.nested.value are reactive
+ * ```
+ */
+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
+ *
+ * @example
+ * ```typescript
+ * const state = shallowReactive({ count: 0, nested: { value: 1 } });
+ * // Only state.count is reactive, not state.nested.value
+ * ```
+ */
+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.
+ */
+declare function isShallow(value: unknown): boolean;
+/**
+ * Return a reactive proxy for the given value (if possible).
+ * 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.
+ */
+declare const toReactive: <T extends unknown>(value: T) => T;
+/**
+ * Type alias representing a reactive object.
+ *
+ * @template T - The type of the original object.
+ */
+type Reactive<T extends object> = T;
+
+/**
+ * Represents a task (job) that can be scheduled for execution
+ */
+type Job = () => void;
+/**
+ * Represents a callback function that should be executed before the main task queue
+ */
+type PreFlushCallback = () => void;
+/**
+ * Represents the possible flush timing strategies for effects
+ *
+ * - 'pre': Execute before the main queue (useful for component updates)
+ * - 'post': Execute after the main queue (default behavior)
+ * - 'sync': Execute immediately and synchronously (use sparingly)
+ */
+type FlushTiming = 'pre' | 'post' | 'sync';
+/**
+ * Schedules a function to be executed in the next microtask
+ *
+ * If no function is provided, returns a Promise that resolves in the next microtask.
+ * This is useful for waiting until the DOM is update or deferring 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
+ *
+ * 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
+ */
+declare function queueJob(job: Job): void;
+/**
+ * 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
+ */
+declare function queuePreFlushCb(cb: PreFlushCallback): void;
+
+/**
+ * Unwrap a Signal, Computed, or Reactive type to get the underlying value type
+ *
+ * @template T - The wrapped type
+ *
+ * @example
+ * ```typescript
+ * import type { Signal, Computed, Reactive, Unwrap } from '@estjs/signals';
+ *
+ * type Count = Unwrap<Signal<number>>; // number
+ * type User = Unwrap<Reactive<{ name: string }>>; // { name: string }
+ * type Double = Unwrap<Computed<number>>; // number
+ * ```
+ */
+type Unwrap<T> = T extends Signal<infer V> ? V : T extends Computed<infer V> ? V : T extends Reactive<infer V extends object> ? V : T;
+/**
+ * Effect function type
+ */
+type EffectFunction<T = any> = () => T;
+/**
+ * Effect scheduler function type
+ */
+type EffectScheduler = (effect: EffectImpl) => void;
+/**
+ * Effect options configuration
+ */
+interface EffectOptions {
+    /**
+     * Custom scheduler for controlling when the effect runs
+     * Can be a function or a timing string ('sync', 'pre', 'post')
+     */
+    scheduler?: EffectScheduler | FlushTiming;
+    /**
+     * Alias for scheduler - controls when the effect runs
+     * Can be 'sync', 'pre', or 'post'
+     */
+    flush?: FlushTiming;
+    /**
+     * Callback invoked when the effect is stopped
+     * Useful for cleanup operations
+     */
+    onStop?: () => void;
+    /**
+     * Debug callback invoked when a dependency is tracked
+     * Only called in development mode
+     *
+     * @param event - Information about the tracked dependency
+     *
+     * @example
+     * ```typescript
+     * effect(() => {
+     *   console.log(signal.value);
+     * }, {
+     *   onTrack(event) {
+     *     console.log('Tracked:', event.type, event.key);
+     *   }
+     * });
+     * ```
+     */
+    onTrack?: (event: DebuggerEvent) => void;
+    /**
+     * Debug callback invoked when the effect is triggered by a dependency change
+     * Only called in development mode
+     *
+     * @param event - Information about what triggered the effect
+     *
+     * @example
+     * ```typescript
+     * effect(() => {
+     *   console.log(signal.value);
+     * }, {
+     *   onTrigger(event) {
+     *     console.log('Triggered by:', event.type, event.key, event.newValue);
+     *   }
+     * });
+     * ```
+     */
+    onTrigger?: (event: DebuggerEvent) => void;
+}
+/**
+ * Effect runner function with attached effect instance
+ */
+interface EffectRunner<T = any> {
+    (): T;
+    effect: EffectImpl<T>;
+    stop: () => void;
+}
+/**
+ * Effect implementation class
+ *
+ * Implements the ReactiveNode interface, acting as a subscriber in the reactive system.
+ *
+ * Core features:
+ * - Automatically tracks dependent reactive values
+ * - Automatically re-executes when dependencies change
+ * - Supports custom scheduling strategies
+ * - Complete lifecycle management
+ *
+ * @template T - The return type of the effect function
+ */
+declare class EffectImpl<T = any> implements ReactiveNode {
+    depLink?: Link;
+    subLink?: Link;
+    depLinkTail?: Link;
+    subLinkTail?: Link;
+    flag: ReactiveFlags;
+    private readonly [SignalFlags.IS_EFFECT];
+    readonly fn: EffectFunction<T>;
+    readonly scheduler?: EffectScheduler | FlushTiming;
+    readonly onStop?: () => void;
+    readonly onTrack?: (event: DebuggerEvent) => void;
+    readonly onTrigger?: (event: DebuggerEvent) => void;
+    readonly flash?: 'sync' | 'pre' | 'post';
+    private _active;
+    /**
+     * Create an Effect instance
+     *
+     * @param fn - The effect function
+     * @param options - Configuration options
+     */
+    constructor(fn: EffectFunction<T>, options?: EffectOptions);
+    /**
+     * Check if the Effect is active
+     */
+    get active(): boolean;
+    /**
+     * Check if the Effect is dirty (needs re-execution)
+  
+     */
+    get dirty(): boolean;
+    /**
+     * 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
+     *
+     * Use cases:
+     * - 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
+     * ```
+     */
+    pause(): void;
+    /**
+     * Resume Effect execution
+     *
+     * When an effect is resumed:
+     * - 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
+     *
+     * 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));
+     *
+     * runner.effect.pause();
+     * count.value = 1; // Queued
+     * count.value = 2; // Queued
+     * runner.effect.resume(); // Executes once with count.value = 2
+     * ```
+     */
+    resume(): void;
+    /**
+     * Execute the Effect function
+     *
+     * Core execution flow:
+     * 1. Check if active
+     * 2. Clear dirty flag
+     * 3. Start tracking dependencies
+     * 4. Execute user function
+     * 5. End tracking, clean up stale dependencies
+  
+     * @returns The return value of the effect function
+     */
+    run(): T;
+    private _job?;
+    /**
+     * Get or create the job function for this effect
+     */
+    private getJob;
+    /**
+     * Notify that the Effect needs to execute
+     *
+     * Called by dependent reactive values.
+     * Decides whether to execute immediately or defer based on scheduling strategy.
+     */
+    notify(): void;
+    /**
+     * 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
+     */
+    stop(): void;
+}
+/**
+ * Create and immediately execute an Effect
+ *
+ * @param fn - The effect function
+ * @param options - Configuration options
+ * @returns Effect runner
+ *
+ * @example
+ * ```typescript
+ * const count = signal(0);
+ *
+ * // Basic usage
+ * const runner = effect(() => {
+ *   console.log('Count:', count.value);
+ * });
+ *
+ * count.value = 1; // Automatically executes, prints 'Count: 1'
+ *
+ * // Manual execution
+ * runner();
+ *
+ * // Stop
+ * runner.effect.stop();
+ *
+ * // Custom scheduling
+ * effect(() => {
+ *   console.log(count.value);
+ * }, {
+ *   scheduler: (eff) => {
+ *     setTimeout(() => eff.run(), 100);
+ *   }
+ * });
+ * ```
+ */
+declare function effect<T = any>(fn: EffectFunction<T>, options?: EffectOptions): EffectRunner<T>;
+/**
+ * Stop Effect execution
+ *
+ * @param runner - The effect runner
+ */
+declare function stop(runner: EffectRunner): void;
+/**
+ * Type guard - Check if value is an Effect
+ *
+ * @param value - The value to check
+ * @returns true if value is an Effect
+ */
+declare function isEffect(value: any): value is EffectImpl;
+/**
+ * Memoized effect function type
+ *
+ * @template T - State type
+ * @param prevState - State from previous execution
+ * @returns New state
+ */
+type MemoEffectFn<T> = (prevState: T) => T;
+/**
+ * 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
+ *
+ * @example
+ * ```typescript
+ * const width = signal(100);
+ *
+ * // Only update DOM when width changes
+ * memoEffect(prev => {
+ *   const current = width.value;
+ *
+ *   if (current !== prev.width) {
+ *     element.style.width = `${current}px`;
+ *     prev.width = current;
+ *   }
+ *
+ *   return prev;
+ * }, { width: 0 });
+ * ```
+ */
+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.
+ *
+ * @param fn - The function to execute in batch mode
+ * @returns The return value of the function
+ *
+ * @example
+ * ```typescript
+ * const x = signal(0);
+ * const y = signal(0);
+ *
+ * effect(() => {
+ *   console.log('Sum:', x.value + y.value);
+ * });
+ *
+ * // Without batch - Effect executes 2 times
+ * x.value = 1; // Effect executes
+ * y.value = 2; // Effect executes
+ *
+ * // With batch - Effect executes only 1 time
+ * batch(() => {
+ *   x.value = 10;
+ *   y.value = 20;
+ * }); // Effect executes once
+ * ```
+ */
+declare function batch<T>(fn: () => T): T;
+/**
+ * Start batch update
+ *
+ * Increases batch depth.
+ * During batch, Effects won't execute immediately.
+ */
+declare function startBatch(): void;
+/**
+ * End batch update
+ *
+ * Decreases batch depth.
+ * When depth reaches zero, flush all queued Effects and clean up.
+ *
+ * ## 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
+ *
+ */
+declare function endBatch(): void;
+/**
+ * Check if currently in batch update mode
+ *
+ * @returns true if currently in batch
+ */
+declare function isBatching(): boolean;
+/**
+ * Get current batch depth
+ *
+ * Mainly used for debugging.
+ *
+ * @returns Current batch nesting depth
+ */
+declare function getBatchDepth(): number;
+
+/**
+ * Represents a store's state object.
+ * Must be a plain object containing the store's reactive state.
+ */
+type State = Record<string, any>;
+/**
+ * Represents a store's getters object.
+ * Each getter is a function that receives the state and returns a computed value.
+ */
+type Getters<S extends State> = Record<string, (state: S) => any>;
+/**
+ * Represents a store's actions object.
+ * Each action is a function that can modify the store's state.
+ */
+type Actions = Record<string, (...args: any[]) => any>;
+/**
+ * Configuration options for creating a store.
+ *
+ * @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
+ */
+interface StoreOptions<S extends State, G extends Getters<S>, A extends Actions> {
+    /** The initial state of the store */
+    state: S;
+    /** Computed values derived from the state */
+    getters?: G;
+    /** Methods that can modify the store's state */
+    actions?: A;
+}
+/**
+ * Payload for patching store state.
+ * Must be a partial object matching the store's state shape.
+ */
+type PatchPayload<S> = Partial<S>;
+/**
+ * Callback function for store subscriptions and action notifications.
+ */
+type StoreCallback<S> = (state: S) => void;
+/**
+ * Built-in actions available on all stores.
+ *
+ * @template S - The type of the store's state
+ */
+interface StoreActions<S extends State> {
+    /**
+     * Updates multiple state properties at once.
+     * Triggers a single update notification.
+     *
+     * @param payload - Object containing state updates
+     */
+    patch$: (payload: PatchPayload<S>) => void;
+    /**
+     * Subscribes to state changes.
+     * The callback is called whenever the state changes.
+     *
+     * @param callback - Function to call on state changes
+     */
+    subscribe$: (callback: StoreCallback<S>) => void;
+    /**
+     * Unsubscribes from state changes.
+     *
+     * @param callback - The callback to remove
+     */
+    unsubscribe$: (callback: StoreCallback<S>) => void;
+    /**
+     * Subscribes to action executions.
+     * The callback is called whenever an action is executed.
+     *
+     * @param callback - Function to call on action execution
+     */
+    onAction$: (callback: StoreCallback<S>) => void;
+    /**
+     * Resets the store state to its initial values.
+     */
+    reset$: () => void;
+}
+/**
+ * Computed values from getters.
+ *
+ * @template G - The type of the store's getters
+ */
+type GetterValues<G extends Getters<any>> = {
+    [K in keyof G]: ReturnType<G[K]>;
+};
+/**
+ * Store definition type that can be either a class or an options object.
+ */
+type StoreDefinition<S extends State, G extends Getters<S>, A extends Actions> = (new () => S) | ({
+    state: S;
+    getters?: G;
+    actions?: A;
+} & ThisType<S & GetterValues<G> & A & StoreActions<S>>);
+/**
+ * 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
+ *
+ * @example
+ * ```ts
+ * // Options-based store
+ * const useCounter = createStore({
+ *   state: { count: 0 },
+ *   getters: {
+ *     double: state => state.count * 2
+ *   },
+ *   actions: {
+ *     increment() {
+ *       this.count++;
+ *     }
+ *   }
+ * });
+ *
+ * // Class-based store
+ * class Counter {
+ *   count = 0;
+ *
+ *   get double() {
+ *     return this.count * 2;
+ *   }
+ *
+ *   increment() {
+ *     this.count++;
+ *   }
+ * }
+ *
+ * const useCounter = createStore(Counter);
+ * ```
+ */
+declare function createStore<S extends State, G extends Getters<S>, A extends Actions>(storeDefinition: StoreDefinition<S, G, A>): () => S & GetterValues<G> & A & StoreActions<S> & {
+    state: S;
+};
+
+/**
+ * A Ref is a special type of Signal used primarily for DOM element references.
+ * It provides methods to read, write, and observe changes to the value.
+ *
+ * @template T - The type of value held by the ref
+ */
+interface Ref<T> extends Signal<T> {
+    /**
+     * The current value of the ref. Reading this property will track dependencies,
+     * and writing to it will notify subscribers of changes.
+     */
+    value: 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
+ *
+ * @example
+ * ```ts
+ * const divRef = ref();
+ * <div ref={divRef}></div>
+ * ```
+ */
+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
+ */
+declare function isRef<T>(value: unknown): value is Ref<T>;
+
+interface WatchOptions {
+    immediate?: boolean;
+    deep?: boolean;
+}
+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.
+ */
+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 };