@alwatr/signal 4.1.0 → 5.0.0

package/dist/signal-base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal-base.d.ts","sourceRoot":"","sources":["../src/signal-base.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,SAAS,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAE,YAAY,EAAC,MAAM,WAAW,CAAC;AAC5G,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAKjD;;;;;;;;GAQG;AACH,8BAAsB,UAAU,CAAC,CAAC;IAChC;;OAEG;IACH,SAAgB,QAAQ,EAAE,MAAM,CAAC;IAEjC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAEzC;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,CAAM;IAEnD,SAAS,CAAC,YAAY,UAAS;IAE/B;;;;OAIG;IACH,IAAW,WAAW,IAAI,OAAO,CAEhC;IAED;;;OAGG;gBACgB,MAAM,EAAE,YAAY;IAIvC;;;;OAIG;IACH,SAAS,CAAC,eAAe,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;IAYvD;;;;;;;;OAQG;IACI,SAAS,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,eAAe;IAoB5F;;;;;;;;OAQG;IACH,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAkCjC;;;;;;;;;;;;OAYG;IACI,SAAS,IAAI,OAAO,CAAC,CAAC,CAAC;IAY9B;;;;;;OAMG;IACI,OAAO,IAAI,IAAI;IAMtB;;;;OAIG;IACH,SAAS,CAAC,eAAe,QAAO,IAAI,CAKlC;CACH"}

package/dist/state-signal.d.ts

@@ -0,0 +1,83 @@
+import { SignalBase } from './signal-base.js';
+import type { StateSignalConfig, ListenerCallback, SubscribeOptions, SubscribeResult, IReadonlySignal } from './type.js';
+/**
+ * A stateful signal that holds a value and notifies listeners when the value changes.
+ *
+ * `StateSignal` is the core of the signal library, representing a piece of mutable state.
+ * It always has a value, and new subscribers immediately receive the current value by default.
+ *
+ * @template T The type of the state it holds.
+ * @implements {IReadonlySignal<T>}
+ *
+ * @example
+ * // Create a new state signal with an initial value.
+ * const counter = new StateSignal<number>({
+ *   signalId: 'counter-signal',
+ *   initialValue: 0,
+ * });
+ *
+ * // Get the current value.
+ * console.log(counter.value); // Outputs: 0
+ *
+ * // Subscribe to changes.
+ * const subscription = counter.subscribe(newValue => {
+ *   console.log(`Counter changed to: ${newValue}`);
+ * });
+ *
+ * // Set a new value, which triggers the notification.
+ * counter.set(1); // Outputs: "Counter changed to: 1"
+ *
+ * // Unsubscribe when no longer needed.
+ * subscription.unsubscribe();
+ */
+export declare class StateSignal<T> extends SignalBase<T> implements IReadonlySignal<T> {
+    private value__;
+    protected logger_: import("@alwatr/logger").AlwatrLogger;
+    /**
+     * Initializes a new `StateSignal`.
+     * @param config The configuration for the state signal, including `signalId` and `initialValue`.
+     */
+    constructor(config: StateSignalConfig<T>);
+    /**
+     * Retrieves the current value of the signal.
+     *
+     * @returns The current value.
+     *
+     * @example
+     * console.log(mySignal.value);
+     */
+    get value(): T;
+    /**
+     * Updates the signal's value and notifies all active listeners.
+     *
+     * The notification is scheduled as a microtask, which means the update is deferred
+     * slightly to batch multiple synchronous changes.
+     *
+     * @param newValue The new value to set.
+     *
+     * @example
+     * // For primitive types
+     * mySignal.set(42);
+     *
+     * // For object types, it's best practice to set an immutable new object.
+     * mySignal.set({ ...mySignal.value, property: 'new-value' });
+     */
+    set(newValue: T): void;
+    /**
+     * Subscribes a listener to this signal.
+     *
+     * By default, the listener is immediately called with the signal's current value (`receivePrevious: true`).
+     * This behavior can be customized via the `options` parameter.
+     *
+     * @param callback The function to be called when the signal's value changes.
+     * @param options Subscription options, including `receivePrevious` and `once`.
+     * @returns An object with an `unsubscribe` method to remove the listener.
+     */
+    subscribe(callback: ListenerCallback<T>, options?: SubscribeOptions): SubscribeResult;
+    /**
+     * Destroys the signal, clearing its value and all listeners.
+     * This is crucial for memory management to prevent leaks.
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=state-signal.d.ts.map

package/dist/state-signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-signal.d.ts","sourceRoot":"","sources":["../src/state-signal.ts"],"names":[],"mappings":"AAGA,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAE5C,OAAO,KAAK,EAAC,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAC,MAAM,WAAW,CAAC;AAEvH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,WAAW,CAAC,CAAC,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,CAAC;IAC7E,OAAO,CAAC,OAAO,CAAI;IACnB,SAAS,CAAC,OAAO,wCAAkD;IAEnE;;;OAGG;gBACgB,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAM/C;;;;;;;OAOG;IACH,IAAW,KAAK,IAAI,CAAC,CAGpB;IAED;;;;;;;;;;;;;;OAcG;IACI,GAAG,CAAC,QAAQ,EAAE,CAAC,GAAG,IAAI;IAe7B;;;;;;;;;OASG;IACa,SAAS,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,gBAAqB,GAAG,eAAe;IA4BzG;;;OAGG;IACa,OAAO,IAAI,IAAI;CAKhC"}

package/dist/type.d.ts

@@ -0,0 +1,240 @@
+/**
+ * @package @alwatr/signal
+ *
+ * The callback function signature for a signal listener. It's a function that receives a value of type `T`
+ * and returns `void` or `Promise<void>`.
+ *
+ * @template T The type of the value that the signal holds or dispatches.
+ */
+export type ListenerCallback<T> = (value: T) => Awaitable<void>;
+/**
+ * Options for fine-tuning the behavior of a subscription to a signal.
+ */
+export interface SubscribeOptions {
+    /**
+     * If `true`, the listener will be called only once and then automatically unsubscribed.
+     * This is useful for scenarios where you only need to react to the next change.
+     *
+     * @default false
+     *
+     * @example
+     * // The listener will be removed after the first click.
+     * onUserClick.subscribe(() => console.log('User clicked!'), { once: true });
+     */
+    once?: boolean;
+    /**
+     * If `true`, the listener will be placed at the beginning of the notification queue and will be called before
+     * other, non-priority listeners.
+     *
+     * @default false
+     *
+     * @example
+     * // This listener will run before the others.
+     * mySignal.subscribe(() => console.log('High-priority action'), { priority: true });
+     */
+    priority?: boolean;
+    /**
+     * **For `StateSignal` only.** If `true` (the default), the listener will be called immediately with the
+     * signal's current value upon subscription. Set to `false` if you only want to be notified of *future* changes.
+     *
+     * @default true
+     *
+     * @example
+     * const counter = new StateSignal({initialValue: 10});
+     *
+     * // This will log "Current value: 10" immediately.
+     * counter.subscribe(value => console.log(`Current value: ${value}`));
+     *
+     * // This will *not* log immediately, only when the counter is next updated.
+     * counter.subscribe(value => console.log(`New value: ${value}`), { receivePrevious: false });
+     */
+    receivePrevious?: boolean;
+}
+/**
+ * The object returned from a `subscribe` call, which contains the `unsubscribe` method.
+ * This allows for easy removal of the subscription when it's no longer needed.
+ */
+export interface SubscribeResult {
+    /**
+     * A function that, when called, removes the listener from the signal, preventing future notifications.
+     * It's crucial to call this to avoid memory leaks when a component or listener is destroyed.
+     *
+     * @example
+     * const subscription = mySignal.subscribe(value => console.log(value));
+     * // ... later ...
+     * subscription.unsubscribe(); // The listener is now removed.
+     */
+    unsubscribe: () => void;
+}
+/**
+ * Internal representation of an observer, containing the listener's callback and its subscription options.
+ * @internal
+ */
+export interface Observer_<T> {
+    callback: ListenerCallback<T>;
+    options?: SubscribeOptions;
+}
+/**
+ * Basic configuration for creating any signal.
+ */
+export interface SignalConfig {
+    /**
+     * A unique identifier for the signal. This is crucial for debugging, logging, and differentiating signals,
+     * especially in large applications.
+     *
+     * @example
+     * 'user-profile-signal'
+     * 'app-theme-signal'
+     */
+    readonly signalId: string;
+}
+/**
+ * Configuration specifically for creating a `StateSignal`.
+ * @template T The type of the state held by the signal.
+ */
+export interface StateSignalConfig<T> extends SignalConfig {
+    /**
+     * The initial value of the `StateSignal`. A `StateSignal` must always have a value.
+     */
+    readonly initialValue: T;
+}
+/**
+ * Represents a signal that can be read from but not written to.
+ * Both `StateSignal` and `ComputedSignal` implement this interface, allowing them to be used
+ * as dependencies in other signals without exposing their `set` or `dispatch` methods.
+ *
+ * @template T The type of the signal's value.
+ */
+export interface IReadonlySignal<T> {
+    /**
+     * The current value of the signal.
+     */
+    readonly value: T;
+    /**
+     * Indicates whether the signal has been destroyed.
+     * A destroyed signal cannot be used and will throw an error if interacted with.
+     * @returns `true` if the signal is destroyed, `false` otherwise.
+     */
+    readonly isDestroyed: boolean;
+    /**
+     * Subscribes a listener to this signal.
+     *
+     * @param callback The function to be called when the signal's value changes.
+     * @param options Optional settings for the subscription.
+     * @returns An object with an `unsubscribe` method for cleanup.
+     */
+    subscribe(callback: ListenerCallback<T>, options?: SubscribeOptions): SubscribeResult;
+    /**
+     * Returns a Promise that resolves with the next value dispatched by the signal.
+     * This provides an elegant way to wait for a single, future event using `async/await`.
+     *
+     * @returns A Promise that resolves with the next dispatched value.
+     *
+     * @example
+     * async function onButtonClick() {
+     *   console.log('Waiting for the next signal...');
+     *   const nextValue = await mySignal.untilNext();
+     *   console.log('Signal received:', nextValue);
+     * }
+     */
+    untilNext(): Promise<T>;
+    /**
+     * Destroys the signal, clearing all its listeners and making it inactive.
+     *
+     * After destruction, any interaction with the signal (like `subscribe` or `untilNext`)
+     * will throw an error. This is crucial for preventing memory leaks by allowing
+     * garbage collection of the signal and its observers.
+     */
+    destroy(): void;
+}
+/**
+ * A list of `IReadonlySignal` instances that a computed or effect signal depends on.
+ * This ensures that dependencies can be read from but not modified by the dependent signal.
+ */
+export type DependencyList = readonly IReadonlySignal<unknown>[];
+/**
+ * Configuration for creating a `ComputedSignal`.
+ * @template T The type of the value computed by the signal.
+ */
+export interface ComputedSignalConfig<T> extends SignalConfig {
+    /**
+     * An array of dependency signals (`StateSignal` or other `ComputedSignal` instances).
+     * The `ComputedSignal` will automatically re-evaluate its value whenever any of these dependencies change.
+     */
+    deps: DependencyList;
+    /**
+     * The function that computes the signal's value.
+     * It is executed once initially and then again whenever a dependency changes.
+     * This function should be pure and not have side effects.
+     *
+     * @example
+     * // A computed signal that derives a boolean from a number.
+     * const counter = new StateSignal({initialValue: 0});
+     * const isEven = new ComputedSignal({
+     *   deps: [counter],
+     *   get: () => counter.value % 2 === 0,
+     * });
+     */
+    get: () => T;
+}
+/**
+ * The public interface for a `ComputedSignal`. It is a read-only signal
+ * that also includes a `destroy` method for essential lifecycle management.
+ *
+ * @template T The type of the computed value.
+ */
+export interface IComputedSignal<T> extends IReadonlySignal<T> {
+    /**
+     * Disconnects the `ComputedSignal` from its dependencies.
+     * This must be called to prevent memory leaks when the signal is no longer needed,
+     * as it stops the automatic re-evaluation.
+     */
+    destroy: () => void;
+}
+/**
+ * Configuration for creating an `EffectSignal`.
+ */
+export interface EffectSignalConfig {
+    /**
+     * An array of dependency signals (`StateSignal` or `ComputedSignal` instances).
+     * The effect's `run` function will be executed whenever any of these signals change.
+     */
+    readonly deps: DependencyList;
+    /**
+     * The function to execute as the side-effect (e.g., logging, DOM updates, network requests).
+     * It can be synchronous or asynchronous.
+     *
+     * @example
+     * // An effect that logs the counter's value to the console.
+     * const counter = new StateSignal({initialValue: 0});
+     * new EffectSignal({
+     *   deps: [counter],
+     *   run: () => console.log(`The counter is now: ${counter.value}`),
+     * });
+     */
+    run: () => Awaitable<void>;
+    /**
+     * If `true`, the effect's `run` function will be executed once immediately upon initialization.
+     *
+     * @default false
+     */
+    runImmediately?: boolean;
+}
+/**
+ * The public interface for an `EffectSignal`, which provides a `destroy` method for cleanup.
+ */
+export interface IEffectSignal {
+    /**
+     * Permanently disposes of the effect, unsubscribing from all dependencies
+     * and stopping any future executions. This is crucial for preventing memory leaks
+     * and unwanted side effects from running.
+     */
+    destroy: () => void;
+    /**
+     * Indicates whether the signal has been destroyed.
+     * A destroyed signal cannot be used and will throw an error if interacted with.
+     * @returns `true` if the signal is destroyed, `false` otherwise.
+     */
+    readonly isDestroyed: boolean;
+}
+//# sourceMappingURL=type.d.ts.map

package/dist/type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../src/type.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,SAAS,CAAC,IAAI,CAAC,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;OAQG;IACH,WAAW,EAAE,MAAM,IAAI,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAC9B,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,CAAE,SAAQ,YAAY;IACxD;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAElB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAE9B;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,eAAe,CAAC;IAEtF;;;;;;;;;;;;OAYG;IACH,SAAS,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAExB;;;;;;OAMG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;AAEjE;;;GAGG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,CAAE,SAAQ,YAAY;IAC3D;;;OAGG;IACH,IAAI,EAAE,cAAc,CAAC;IAErB;;;;;;;;;;;;OAYG;IACH,GAAG,EAAE,MAAM,CAAC,CAAC;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,CAAE,SAAQ,eAAe,CAAC,CAAC,CAAC;IAC5D;;;;OAIG;IACH,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAE9B;;;;;;;;;;;OAWG;IACH,GAAG,EAAE,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC;IAE3B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,OAAO,EAAE,MAAM,IAAI,CAAC;IAEpB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B"}

package/package.json

@@ -1,18 +1,20 @@
 {
   "name": "@alwatr/signal",
-  "description": "A simple and efficient TypeScript library for event-driven communication using signals.",
-  "version": "4.1.0",
+  "description": "Alwatr Signal is a powerful, lightweight, and modern reactive programming library. It is inspired by the best concepts from major reactive libraries but engineered to be faster and more efficient than all of them. It provides a robust and elegant way to manage application state through a system of signals, offering fine-grained reactivity, predictability, and excellent performance.",
+  "version": "5.0.0",
   "author": "S. Ali Mihandoost <ali.mihandoost@gmail.com>",
   "bugs": "https://github.com/Alwatr/flux/issues",
   "dependencies": {
-    "@alwatr/nanolib": "^6.0.1",
-    "@alwatr/observable": "^4.1.0"
+    "@alwatr/delay": "^6.0.1",
+    "@alwatr/logger": "^5.5.10",
+    "@alwatr/package-tracer": "^5.5.10"
   },
   "devDependencies": {
-    "@alwatr/nano-build": "^6.1.0",
-    "@alwatr/prettier-config": "^5.0.2",
-    "@alwatr/tsconfig-base": "^6.0.0",
-    "@alwatr/type-helper": "^6.0.0",
+    "@alwatr/nano-build": "^6.1.1",
+    "@alwatr/prettier-config": "^5.0.3",
+    "@alwatr/tsconfig-base": "^6.0.1",
+    "@alwatr/type-helper": "^6.0.1",
+    "@jest/globals": "^30.1.2",
     "@types/node": "^22.18.1",
     "jest": "^30.1.3",
     "typescript": "^5.9.2"
@@ -66,5 +68,5 @@
   },
   "type": "module",
   "types": "./dist/main.d.ts",
-  "gitHead": "200dcb5e63a3330a3060b51778dd920963b20763"
+  "gitHead": "395a61b801b670ce58084a19f5ade96bb8338c5f"
 }

package/src/computed-signal.test.js

@@ -0,0 +1,150 @@
+import {describe, beforeEach, afterEach, it, expect, jest} from '@jest/globals';
+import {ComputedSignal, StateSignal} from '@alwatr/signal';
+import {delay} from '@alwatr/delay';
+
+describe('ComputedSignal', () => {
+  /** @type {StateSignal<number>} */
+  let dep1;
+  /** @type {StateSignal<number>} */
+  let dep2;
+  /** @type {ComputedSignal<number>} */
+  let signal;
+  const signalId = 'test-computed-signal';
+
+  beforeEach(() => {
+    dep1 = new StateSignal({signalId: 'dep1', initialValue: 1});
+    dep2 = new StateSignal({signalId: 'dep2', initialValue: 2});
+    signal = new ComputedSignal({
+      signalId,
+      deps: [dep1, dep2],
+      get: () => dep1.value + dep2.value,
+    });
+  });
+
+  afterEach(() => {
+    signal.destroy();
+    dep1.destroy();
+    dep2.destroy();
+  });
+
+  it('should be defined and have the correct signalId and initial value', () => {
+    expect(ComputedSignal).toBeDefined();
+    expect(signal).toBeInstanceOf(ComputedSignal);
+    expect(signal.signalId).toBe(signalId);
+    expect(signal.value).toBe(3); // 1 + 2
+  });
+
+  it('should compute value from dependencies', async () => {
+    expect(signal.value).toBe(3);
+    dep1.set(5);
+    await signal.untilNext();
+    expect(signal.value).toBe(7); // 5 + 2
+  });
+
+  it('should notify subscribers when computed value changes', async () => {
+    const callback = jest.fn();
+    signal.subscribe(callback, {receivePrevious: false});
+    dep1.set(10);
+    await signal.untilNext();
+    expect(callback).toHaveBeenCalledTimes(1);
+    expect(callback).toHaveBeenCalledWith(12); // 10 + 2
+  });
+
+  it('should not notify if computed value does not change', async () => {
+    const callback = jest.fn();
+    signal.subscribe(callback, {receivePrevious: false});
+    dep1.set(1); // Same as initial
+    await delay.by(5);
+    expect(callback).not.toHaveBeenCalled();
+  });
+
+  it('should compute once if multiple dependencies change', async () => {
+    const callback = jest.fn();
+    signal.subscribe(callback, {receivePrevious: false});
+    dep1.set(3);
+    await delay.nextMicrotask();
+    dep2.set(4);
+    await signal.untilNext();
+    expect(callback).toHaveBeenCalledTimes(1);
+    expect(callback).toHaveBeenCalledWith(7); // 3 + 4
+  });
+
+  it('should notify multiple subscribers', async () => {
+    const callback1 = jest.fn();
+    const callback2 = jest.fn();
+    signal.subscribe(callback1, {receivePrevious: false});
+    signal.subscribe(callback2, {receivePrevious: false});
+    dep2.set(5);
+    await signal.untilNext();
+    expect(callback1).toHaveBeenCalledTimes(1);
+    expect(callback1).toHaveBeenCalledWith(6); // 1 + 5
+    expect(callback2).toHaveBeenCalledTimes(1);
+    expect(callback2).toHaveBeenCalledWith(6);
+  });
+
+  it('should not notify unsubscribed listeners', async () => {
+    const callback = jest.fn();
+    const subscription = signal.subscribe(callback, {receivePrevious: false});
+    subscription.unsubscribe();
+    dep1.set(10);
+    await signal.untilNext();
+    expect(callback).not.toHaveBeenCalled();
+  });
+
+  it('should handle subscriptions with the "once" option', async () => {
+    const callback = jest.fn();
+    signal.subscribe(callback, {once: true, receivePrevious: false});
+    dep1.set(10);
+    await signal.untilNext();
+    expect(callback).toHaveBeenCalledTimes(1);
+    expect(callback).toHaveBeenCalledWith(12);
+    dep2.set(20);
+    await signal.untilNext();
+    expect(callback).toHaveBeenCalledTimes(1); // Should not be called again
+  });
+
+  it('should resolve untilNext() with the next computed value', async () => {
+    const untilNextPromise = signal.untilNext();
+    dep1.set(5);
+    await expect(untilNextPromise).resolves.toBe(7);
+  });
+
+  it('should handle no dependencies', () => {
+    const noDepSignal = new ComputedSignal({
+      signalId: 'no-dep',
+      deps: [],
+      get: () => 42,
+    });
+    expect(noDepSignal.value).toBe(42);
+    noDepSignal.destroy();
+  });
+
+  it('should continue notifying other subscribers if one callback throws an error', async () => {
+    const callback1 = jest.fn(() => {
+      throw new Error('Test error');
+    });
+    const callback2 = jest.fn();
+    signal.subscribe(callback1, {receivePrevious: false});
+    signal.subscribe(callback2, {receivePrevious: false});
+    dep1.set(10);
+    await signal.untilNext();
+    expect(callback1).toHaveBeenCalledTimes(1);
+    expect(callback2).toHaveBeenCalledTimes(1);
+  });
+
+  describe('destroyed signal', () => {
+    it('should throw error when accessing value after destroy', () => {
+      signal.destroy();
+      expect(() => signal.value).toThrow();
+    });
+
+    it('should not notify after destroy', async () => {
+      const callback = jest.fn();
+      signal.subscribe(callback, {receivePrevious: false});
+      signal.destroy();
+      dep1.set(10);
+      await delay.by(5);
+      expect(callback).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/effect-signal.test.js

@@ -0,0 +1,150 @@
+import {describe, beforeEach, afterEach, it, expect, jest} from '@jest/globals';
+import {EffectSignal, StateSignal} from '@alwatr/signal';
+import {delay} from '@alwatr/delay';
+
+describe('EffectSignal', () => {
+  /** @type {StateSignal<number>} */
+  let depSignal;
+  /** @type {EffectSignal} */
+  let effectSignal;
+
+  beforeEach(() => {
+    depSignal = new StateSignal({signalId: 'dep', initialValue: 0});
+  });
+
+  afterEach(() => {
+    if (effectSignal && !effectSignal.isDestroyed) {
+      effectSignal.destroy();
+    }
+    depSignal.destroy();
+  });
+
+  it('should be defined', () => {
+    const runFn = jest.fn();
+    effectSignal = new EffectSignal({
+      deps: [depSignal],
+      run: runFn,
+    });
+    expect(EffectSignal).toBeDefined();
+    expect(effectSignal).toBeInstanceOf(EffectSignal);
+  });
+
+  it('should run the effect immediately if runImmediately is true', async () => {
+    const runFn = jest.fn();
+    effectSignal = new EffectSignal({
+      deps: [depSignal],
+      run: runFn,
+      runImmediately: true,
+    });
+    await delay.by(5);
+    expect(runFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should not run the effect immediately if runImmediately is false or undefined', async () => {
+    const runFn = jest.fn();
+    effectSignal = new EffectSignal({
+      deps: [depSignal],
+      run: runFn,
+    });
+    await delay.by(5);
+    expect(runFn).not.toHaveBeenCalled();
+  });
+
+  it('should run the effect when a dependency changes', async () => {
+    const runFn = jest.fn();
+    effectSignal = new EffectSignal({
+      deps: [depSignal],
+      run: runFn,
+    });
+    await delay.by(5);
+    expect(runFn).not.toHaveBeenCalled();
+    depSignal.set(1);
+    await delay.by(5);
+    expect(runFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should run the effect for each dependency change', async () => {
+    const runFn = jest.fn();
+    effectSignal = new EffectSignal({
+      deps: [depSignal],
+      run: runFn,
+    });
+    depSignal.set(1);
+    await delay.by(5);
+
+    depSignal.set(2);
+    await delay.by(5);
+
+    expect(runFn).toHaveBeenCalledTimes(2);
+  });
+
+  it('should handle multiple dependencies', async () => {
+    const depSignal2 = new StateSignal({signalId: 'dep2', initialValue: 'a'});
+    const runFn = jest.fn();
+    effectSignal = new EffectSignal({
+      deps: [depSignal, depSignal2],
+      run: runFn,
+    });
+    depSignal.set(1);
+    await delay.by(5);
+
+    expect(runFn).toHaveBeenCalledTimes(1);
+    depSignal2.set('b');
+    await delay.by(5);
+
+    expect(runFn).toHaveBeenCalledTimes(2);
+    depSignal2.destroy();
+  });
+
+  it('should not run the effect after destroy', async () => {
+    const runFn = jest.fn();
+    effectSignal = new EffectSignal({
+      deps: [depSignal],
+      run: runFn,
+    });
+    effectSignal.destroy();
+    depSignal.set(1);
+    await delay.by(5);
+
+    expect(runFn).not.toHaveBeenCalled();
+  });
+
+  it('should handle async run functions', async () => {
+    const runFn = jest.fn().mockResolvedValue(undefined);
+    effectSignal = new EffectSignal({
+      deps: [depSignal],
+      run: runFn,
+    });
+    depSignal.set(1);
+    await delay.by(5);
+
+    expect(runFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should not run if dependencies do not change', async () => {
+    const runFn = jest.fn();
+    effectSignal = new EffectSignal({
+      deps: [depSignal],
+      run: runFn,
+    });
+    depSignal.set(0); // Same value
+    await delay.by(5);
+
+    expect(runFn).not.toHaveBeenCalled();
+  });
+
+  describe('destroyed signal', () => {
+    it('should not run effect after destroy', async () => {
+      const runFn = jest.fn();
+      effectSignal = new EffectSignal({
+        deps: [depSignal],
+        run: runFn,
+      });
+      effectSignal.destroy();
+      depSignal.set(1);
+      await delay.by(5);
+
+      expect(runFn).not.toHaveBeenCalled();
+    });
+  });
+});