@alwatr/signal 5.0.0 → 5.1.0

package/CHANGELOG.md

@@ -3,6 +3,48 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [5.1.0](https://github.com/Alwatr/flux/compare/v5.0.0...v5.1.0) (2025-09-14)
+
+### ✨ Features
+
+* add createComputedSignal function for reactive value management ([da4ad2e](https://github.com/Alwatr/flux/commit/da4ad2ec31e24d0756007b666e6c6c3c3ad75709))
+* add createEventSignal function for dispatching transient events ([0729eca](https://github.com/Alwatr/flux/commit/0729eca8ad7ed9fd4fca02c5f2c5f5d2f1a5acf4))
+* add createFilteredSignal function to emit values from a source signal based on a predicate ([ad4873c](https://github.com/Alwatr/flux/commit/ad4873c2f5ca8d26e44db371c1387f450e12189b))
+* add createMappedSignal function for transforming source signal values ([6fcefed](https://github.com/Alwatr/flux/commit/6fcefed778bd6007c639d218e3736aaf9d071d10))
+* add createStateSignal function for creating stateful signals ([2764b50](https://github.com/Alwatr/flux/commit/2764b501dfc39488f7b5446935e7ebdfe06fcd35))
+* add optional onDestroy callback to SignalConfig and EffectSignalConfig for resource cleanup ([d0ed93a](https://github.com/Alwatr/flux/commit/d0ed93a1f7e9da5c73222fb9a3e7e1b95fa88212))
+* add signalId property to IReadonlySignal for debugging and update DebounceSignalConfig type ([d7a43ba](https://github.com/Alwatr/flux/commit/d7a43bad568d12264482475bddb045467dfe229c))
+* add update method for state transitions based on previous value ([77b3593](https://github.com/Alwatr/flux/commit/77b3593df19e166b0446938104a9795b037b2d3d))
+* call optional onDestroy callback in createDebouncedSignal for improved resource cleanup ([8eef425](https://github.com/Alwatr/flux/commit/8eef4252d193db5809850bd624e739bcc8549077))
+* call optional onDestroy callback in destroy method for resource cleanup ([64a0e3b](https://github.com/Alwatr/flux/commit/64a0e3b6f242e91bccc48fe0cf8d1e214bcc2a5e))
+* enhance createDebouncedSignal with optional signalId and onDestroy callback for improved resource management ([7ce880a](https://github.com/Alwatr/flux/commit/7ce880a40b96a3aaa78297d68cd3e7e9e05b7a20))
+* enhance destroy method in SignalBase and StateSignal for improved memory management ([a81f005](https://github.com/Alwatr/flux/commit/a81f0057803fe1c0c0650d0a2223319064739067))
+* implement createDebouncedSignal function for debouncing updates from a source signal ([42bd6a9](https://github.com/Alwatr/flux/commit/42bd6a915494222171317142bd21e11ff3ef2e25))
+* implement createEffect function for managing reactive side-effects ([730c847](https://github.com/Alwatr/flux/commit/730c847ed6720ca7761dfb5745d957a681352a9c))
+* implement IReadonlySignal interface in ComputedSignal and call optional onDestroy callback in destroy method ([8828230](https://github.com/Alwatr/flux/commit/8828230fa2ea8246d6b08d73dfee863eceea4c82))
+* improve resource cleanup in createDebouncedSignal by checking internalSignal state before destruction ([36b8505](https://github.com/Alwatr/flux/commit/36b850505c0541906038a05f2cf5967baac1b2cb))
+* update createDebouncedSignal to use ComputedSignal type and streamline resource cleanup in onDestroy callback ([bb0908a](https://github.com/Alwatr/flux/commit/bb0908a03ad9a86e432b8bfa17e21ced881c8f41))
+
+### 🐛 Bug Fixes
+
+* debounce destroy ([e14a39a](https://github.com/Alwatr/flux/commit/e14a39a6b4729980d5aa7486873b4aae272bec0b))
+* initialize signalId in constructor and call optional onDestroy callback in destroy method ([198f9b3](https://github.com/Alwatr/flux/commit/198f9b3b08a259d118b8645bb144677ea7f24613))
+* remove unused dependency @alwatr/package-tracer from package.json ([9008a40](https://github.com/Alwatr/flux/commit/9008a40b8eb7e996ee8995956ab14d93bf021407))
+
+### 🔨 Code Refactoring
+
+* move fundamental signals to core ([5fc4cd9](https://github.com/Alwatr/flux/commit/5fc4cd90cb3463a876bc21f4699510aace7db8f4))
+* remove packageTracer import and related dev mode initialization ([d02276e](https://github.com/Alwatr/flux/commit/d02276eed37337b1f68d2c74cc5ee366add55f35))
+* remove unused IComputedSignal and IEffectSignal imports from computed and effect creators ([bf7d3f2](https://github.com/Alwatr/flux/commit/bf7d3f287ee2db101b6ca0ad30eccf5f1af4bdd1))
+* reorganize exports to use core and creators directories ([cdb5225](https://github.com/Alwatr/flux/commit/cdb5225773c5a909f176bb5550ce4f3a0517f09f))
+* simplify parameter and return type annotations in createComputedSignal, createEffect, and createEventSignal ([024025e](https://github.com/Alwatr/flux/commit/024025e68fb4793ab7ecd97e51ccb5f271002a52))
+
+### 🔗 Dependencies update
+
+* bump the npm-dependencies group with 6 updates ([f6ae979](https://github.com/Alwatr/flux/commit/f6ae9795e34ba3913fa208f7f94794b5753b90c9))
+* update @alwatr/debounce dependency to version 1.1.0 ([bce3ffe](https://github.com/Alwatr/flux/commit/bce3ffe6c174c05aef60dc9fdc7e78aa31dcc71b))
+* update @types/node dependency to version 22.18.3 ([6e1a847](https://github.com/Alwatr/flux/commit/6e1a8477095f102d09b020dccfe4e638c1d058ca))
+
 ## [5.0.0](https://github.com/Alwatr/flux/compare/v4.1.1...v5.0.0) (2025-09-12)
 
 ### ⚠ BREAKING CHANGES

package/dist/{computed-signal.d.ts → core/computed-signal.d.ts}

@@ -1,5 +1,5 @@
 import { StateSignal } from './state-signal.js';
-import type { ComputedSignalConfig, IComputedSignal, SubscribeResult } from './type.js';
+import type { ComputedSignalConfig, IReadonlySignal, SubscribeResult } from '../type.js';
 /**
  * A read-only signal that derives its value from a set of dependency signals.
  *
@@ -39,7 +39,7 @@ import type { ComputedSignalConfig, IComputedSignal, SubscribeResult } from './t
  * // --- IMPORTANT: Clean up when done ---
  * fullName.destroy();
  */
-export declare class ComputedSignal<T> implements IComputedSignal<T> {
+export declare class ComputedSignal<T> implements IReadonlySignal<T> {
     protected config_: ComputedSignalConfig<T>;
     readonly signalId: string;
     protected readonly logger_: import("@alwatr/logger").AlwatrLogger;
@@ -51,10 +51,6 @@ export declare class ComputedSignal<T> implements IComputedSignal<T> {
     protected readonly internalSignal_: StateSignal<T>;
     private readonly subscriptionList__;
     private isRecalculating__;
-    /**
-     * Initializes a new `ComputedSignal`.
-     * @param config The configuration, including dependencies (`deps`) and the getter function (`get`).
-     */
     constructor(config_: ComputedSignalConfig<T>);
     /**
      * The current value of the computed signal.
@@ -70,7 +66,7 @@ export declare class ComputedSignal<T> implements IComputedSignal<T> {
      * @returns `true` if the signal is destroyed, `false` otherwise.
      */
     get isDestroyed(): boolean;
-    readonly subscribe: (callback: import("./type.js").ListenerCallback<T>, options?: import("./type.js").SubscribeOptions) => SubscribeResult;
+    readonly subscribe: (callback: import("../type.js").ListenerCallback<T>, options?: import("../type.js").SubscribeOptions) => SubscribeResult;
     readonly untilNext: () => Promise<T>;
     /**
      * Permanently disposes of the computed signal.

package/dist/core/computed-signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"computed-signal.d.ts","sourceRoot":"","sources":["../../src/core/computed-signal.ts"],"names":[],"mappings":"AAGA,OAAO,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAE9C,OAAO,KAAK,EAAC,oBAAoB,EAAE,eAAe,EAAE,eAAe,EAAC,MAAM,YAAY,CAAC;AAEvF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,cAAc,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,CAAC;IAkBvC,SAAS,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAjB7D,SAAgB,QAAQ,SAAyB;IAEjD,SAAS,CAAC,QAAQ,CAAC,OAAO,wCAAqD;IAE/E;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,eAAe,iBAG/B;IAEH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAyB;IAC5D,OAAO,CAAC,iBAAiB,CAAS;gBAEL,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAU7D;;;;;;OAMG;IACH,IAAW,KAAK,IAAI,CAAC,CAEpB;IAED;;;;OAIG;IACH,IAAW,WAAW,IAAI,OAAO,CAEhC;IAED,SAAgB,SAAS,2HAA6D;IAEtF,SAAgB,SAAS,mBAA6D;IAEtF;;;;;;;;OAQG;IACI,OAAO,IAAI,IAAI;IAsBtB;;;;;;;OAOG;cACa,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;CAqC9C"}

package/dist/{effect-signal.d.ts → core/effect-signal.d.ts}

@@ -1,4 +1,4 @@
-import type { EffectSignalConfig, IEffectSignal } from './type.js';
+import type { EffectSignalConfig, IEffectSignal } from '../type.js';
 /**
  * Manages a side-effect that runs in response to changes in dependency signals.
  *
@@ -49,10 +49,6 @@ export declare class EffectSignal implements IEffectSignal {
      * @returns `true` if the signal is destroyed, `false` otherwise.
      */
     get isDestroyed(): boolean;
-    /**
-     * Initializes a new `EffectSignal`.
-     * @param config The configuration, including dependencies (`deps`) and the `run` function.
-     */
     constructor(config_: EffectSignalConfig);
     /**
      * Schedules the execution of the effect's `run` function.

package/dist/core/effect-signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect-signal.d.ts","sourceRoot":"","sources":["../../src/core/effect-signal.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,kBAAkB,EAAE,aAAa,EAAkB,MAAM,YAAY,CAAC;AAEnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,YAAa,YAAW,aAAa;IAgB7B,SAAS,CAAC,OAAO,EAAE,kBAAkB;IAfxD,SAAS,CAAC,QAAQ,CAAC,OAAO,wCAAiC;IAE3D,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAyB;IAC5D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,aAAa,CAAS;IAE9B;;;;OAIG;IACH,IAAW,WAAW,IAAI,OAAO,CAEhC;gBAE4B,OAAO,EAAE,kBAAkB;IAiBxD;;;;;;;OAOG;cACa,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAmCrC;;;;;;OAMG;IACI,OAAO,IAAI,IAAI;CAmBvB"}

package/dist/{event-signal.d.ts → core/event-signal.d.ts}

@@ -1,5 +1,5 @@
 import { SignalBase } from './signal-base.js';
-import type { SignalConfig } from './type.js';
+import type { SignalConfig } from '../type.js';
 /**
  * A stateless signal for dispatching transient events.
  *
@@ -29,10 +29,6 @@ import type { SignalConfig } from './type.js';
  */
 export declare class EventSignal<T = void> extends SignalBase<T> {
     protected logger_: import("@alwatr/logger").AlwatrLogger;
-    /**
-     * Initializes a new `EventSignal`.
-     * @param config The configuration for the signal, containing its `signalId`.
-     */
     constructor(config: SignalConfig);
     /**
      * Dispatches an event with an optional payload to all active listeners.

package/dist/core/event-signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-signal.d.ts","sourceRoot":"","sources":["../../src/core/event-signal.ts"],"names":[],"mappings":"AAGA,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAE5C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,WAAW,CAAC,CAAC,GAAG,IAAI,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAC;IACtD,SAAS,CAAC,OAAO,wCAAkD;gBAEhD,MAAM,EAAE,YAAY;IAKvC;;;;;;OAMG;IACI,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI;CAQlC"}

package/dist/{signal-base.d.ts → core/signal-base.d.ts}

@@ -1,4 +1,4 @@
-import type { Observer_, SubscribeOptions, SubscribeResult, ListenerCallback, SignalConfig } from './type.js';
+import type { Observer_, SubscribeOptions, SubscribeResult, ListenerCallback, SignalConfig } from '../type.js';
 import type { AlwatrLogger } from '@alwatr/logger';
 /**
  * An abstract base class for signal implementations.
@@ -10,6 +10,7 @@ import type { AlwatrLogger } from '@alwatr/logger';
  * @template T The type of data the signal will handle.
  */
 export declare abstract class SignalBase<T> {
+    protected config_: SignalConfig;
     /**
      * The unique identifier for this signal instance. Useful for debugging.
      */
@@ -27,11 +28,7 @@ export declare abstract class SignalBase<T> {
      * @returns `true` if the signal is destroyed, `false` otherwise.
      */
     get isDestroyed(): boolean;
-    /**
-     * Initializes a new `SignalBase`.
-     * @param config The configuration for the signal, containing its `signalId`.
-     */
-    constructor(config: SignalConfig);
+    constructor(config_: SignalConfig);
     /**
      * Removes a specific observer from the observers list.
      * @param observer The observer instance to remove.

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

@@ -0,0 +1 @@
+{"version":3,"file":"signal-base.d.ts","sourceRoot":"","sources":["../../src/core/signal-base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAE,YAAY,EAAC,MAAM,YAAY,CAAC;AAC7G,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAGjD;;;;;;;;GAQG;AACH,8BAAsB,UAAU,CAAC,CAAC;IAyBb,SAAS,CAAC,OAAO,EAAE,YAAY;IAxBlD;;OAEG;IACH,SAAgB,QAAQ,EAAE,MAAM,CAAyB;IAEzD,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;gBAE4B,OAAO,EAAE,YAAY;IAElD;;;;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;IAStB;;;;OAIG;IACH,SAAS,CAAC,eAAe,QAAO,IAAI,CAKlC;CACH"}

package/dist/{state-signal.d.ts → core/state-signal.d.ts}

@@ -1,5 +1,5 @@
 import { SignalBase } from './signal-base.js';
-import type { StateSignalConfig, ListenerCallback, SubscribeOptions, SubscribeResult, IReadonlySignal } from './type.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.
  *
@@ -27,16 +27,15 @@ import type { StateSignalConfig, ListenerCallback, SubscribeOptions, SubscribeRe
  * // Set a new value, which triggers the notification.
  * counter.set(1); // Outputs: "Counter changed to: 1"
  *
+ * // Update value based on the previous value.
+ * counter.update(current => current + 1); // Outputs: "Counter changed to: 2"
+ *
  * // 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.
@@ -63,6 +62,22 @@ export declare class StateSignal<T> extends SignalBase<T> implements IReadonlySi
      * mySignal.set({ ...mySignal.value, property: 'new-value' });
      */
     set(newValue: T): void;
+    /**
+     * Updates the signal's value based on its previous value.
+     *
+     * This method is particularly useful for state transitions that depend on the current value,
+     * especially for objects or arrays, as it promotes an immutable update pattern.
+     *
+     * @param updater A function that receives the current value and returns the new value.
+     *
+     * @example
+     * // For a counter
+     * counterSignal.update(current => current + 1);
+     *
+     * // For an object state
+     * userSignal.update(currentUser => ({ ...currentUser, loggedIn: true }));
+     */
+    update(updater: (previousValue: T) => T): void;
     /**
      * Subscribes a listener to this signal.
      *

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

@@ -0,0 +1 @@
+{"version":3,"file":"state-signal.d.ts","sourceRoot":"","sources":["../../src/core/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,YAAY,CAAC;AAExH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;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;gBAEhD,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;;;;;;;;;;;;;;OAcG;IACI,MAAM,CAAC,OAAO,EAAE,CAAC,aAAa,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI;IAQrD;;;;;;;;;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/creators/computed.d.ts

@@ -0,0 +1,34 @@
+import { ComputedSignal } from '../core/computed-signal.js';
+import type { ComputedSignalConfig } from '../type.js';
+/**
+ * Creates a read-only signal that derives its value from a set of dependency signals.
+ *
+ * `ComputedSignal` is a powerful tool for creating values that reactively update when their underlying
+ * data sources change. Its value is memoized, meaning the `get` function is only re-evaluated when
+ * one of its dependencies has actually changed.
+ *
+ * A key feature is its lifecycle management: a `ComputedSignal` **must** be destroyed when no longer
+ * needed to prevent memory leaks from its subscriptions to dependency signals.
+ *
+ * @template T The type of the computed value.
+ *
+ * @param config The configuration for the computed signal.
+ * @returns A new, read-only computed signal.
+ *
+ * @example
+ * const firstName = createStateSignal({ signalId: 'firstName', initialValue: 'John' });
+ * const lastName = createStateSignal({ signalId: 'lastName', initialValue: 'Doe' });
+ *
+ * const fullName = createComputedSignal({
+ *   signalId: 'fullName',
+ *   deps: [firstName, lastName],
+ *   get: () => `${firstName.value} ${lastName.value}`,
+ * });
+ *
+ * console.log(fullName.value); // "John Doe"
+ *
+ * // IMPORTANT: Always destroy a computed signal when no longer needed.
+ * // fullName.destroy();
+ */
+export declare function createComputedSignal<T>(config: ComputedSignalConfig<T>): ComputedSignal<T>;
+//# sourceMappingURL=computed.d.ts.map

package/dist/creators/computed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"computed.d.ts","sourceRoot":"","sources":["../../src/creators/computed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,cAAc,EAAC,MAAM,4BAA4B,CAAC;AAE1D,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,YAAY,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAE1F"}

package/dist/creators/effect.d.ts

@@ -0,0 +1,43 @@
+import { EffectSignal } from '../core/effect-signal.js';
+import type { EffectSignalConfig } from '../type.js';
+/**
+ * Creates a side-effect that runs in response to changes in dependency signals.
+ *
+ * `EffectSignal` is designed for running logic that interacts with the "outside world"—such as
+ * logging, network requests, or DOM manipulation—whenever its dependencies are updated.
+ * It encapsulates the subscription and cleanup logic, providing a robust and memory-safe
+ * way to handle reactive side-effects.
+ *
+ * A key feature is its lifecycle management: an `EffectSignal` **must** be destroyed when no longer
+ * needed to prevent memory leaks and stop the effect from running unnecessarily.
+ *
+ * @param config The configuration for the effect.
+ * @returns An object with a `destroy` method to stop the effect.
+ *
+ * @example
+ * // --- Create dependency signals ---
+ * const counter = createStateSignal({ initialValue: 0, signalId: 'counter' });
+ * const user = createStateSignal({ initialValue: 'guest', signalId: 'user' });
+ *
+ * // --- Create an effect ---
+ * const analyticsEffect = createEffect({
+ *   deps: [counter, user],
+ *   run: () => {
+ *     console.log(`Analytics: User '${user.value}' clicked ${counter.value} times.`);
+ *   },
+ *   runImmediately: true, // Optional: run once on creation
+ * });
+ * // Immediately logs: "Analytics: User 'guest' clicked 0 times."
+ *
+ * // --- Trigger the effect by updating a dependency ---
+ * counter.set(1);
+ * // After a macrotask, logs: "Analytics: User 'guest' clicked 1 times."
+ *
+ * // --- IMPORTANT: Clean up when the effect is no longer needed ---
+ * analyticsEffect.destroy();
+ *
+ * // Further updates will not trigger the effect.
+ * counter.set(2); // Nothing is logged.
+ */
+export declare function createEffect(config: EffectSignalConfig): EffectSignal;
+//# sourceMappingURL=effect.d.ts.map

package/dist/creators/effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect.d.ts","sourceRoot":"","sources":["../../src/creators/effect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAC,MAAM,0BAA0B,CAAC;AAEtD,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,YAAY,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CAErE"}

package/dist/creators/event.d.ts

@@ -0,0 +1,28 @@
+import { EventSignal } from '../core/event-signal.js';
+import type { SignalConfig } from '../type.js';
+/**
+ * Creates a stateless signal for dispatching transient events.
+ *
+ * `EventSignal` is ideal for broadcasting events that do not have a persistent state.
+ * Unlike `StateSignal`, it does not hold a value. Listeners are only notified of new
+ * events as they are dispatched. This makes it suitable for modeling user interactions,
+ * system notifications, or any one-off message.
+ *
+ * @template T The type of the payload for the events.
+ *
+ * @param config The configuration for the event signal.
+ * @returns A new instance of EventSignal.
+ *
+ * @example
+ * const onUserClick = createEventSignal<{ x: number, y: number }>({
+ *   signalId: 'on-user-click'
+ * });
+ *
+ * onUserClick.subscribe(pos => {
+ *   console.log(`User clicked at: ${pos.x}, ${pos.y}`);
+ * });
+ *
+ * onUserClick.dispatch({ x: 100, y: 250 });
+ */
+export declare function createEventSignal<T = void>(config: SignalConfig): EventSignal<T>;
+//# sourceMappingURL=event.d.ts.map

package/dist/creators/event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../src/creators/event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,WAAW,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,YAAY,GAAG,WAAW,CAAC,CAAC,CAAC,CAEhF"}

package/dist/creators/state.d.ts

@@ -0,0 +1,25 @@
+import { StateSignal } from '../core/state-signal.js';
+import type { StateSignalConfig } from '../type.js';
+/**
+ * Creates 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.
+ *
+ * @param config The configuration for the state signal.
+ * @returns A new instance of StateSignal.
+ *
+ * @example
+ * const counter = createStateSignal({
+ *   signalId: 'counter-signal',
+ *   initialValue: 0,
+ * });
+ *
+ * console.log(counter.value); // Outputs: 0
+ * counter.set(1);
+ * console.log(counter.value); // Outputs: 1
+ */
+export declare function createStateSignal<T>(config: StateSignalConfig<T>): StateSignal<T>;
+//# sourceMappingURL=state.d.ts.map

package/dist/creators/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/creators/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,WAAW,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,YAAY,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAEjF"}

package/dist/main.cjs

@@ -1,4 +1,4 @@
-/* @alwatr/signal v5.0.0 */
+/* @alwatr/signal v5.1.0 */
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -25,19 +25,23 @@ __export(main_exports, {
   EffectSignal: () => EffectSignal,
   EventSignal: () => EventSignal,
   SignalBase: () => SignalBase,
-  StateSignal: () => StateSignal
+  StateSignal: () => StateSignal,
+  createComputedSignal: () => createComputedSignal,
+  createDebouncedSignal: () => createDebouncedSignal,
+  createEffect: () => createEffect,
+  createEventSignal: () => createEventSignal,
+  createStateSignal: () => createStateSignal
 });
 module.exports = __toCommonJS(main_exports);
 
-// src/signal-base.ts
-var import_package_tracer = require("@alwatr/package-tracer");
-__dev_mode__: import_package_tracer.packageTracer.add("@alwatr/signal", "5.0.0");
+// src/core/signal-base.ts
 var SignalBase = class {
-  /**
-   * Initializes a new `SignalBase`.
-   * @param config The configuration for the signal, containing its `signalId`.
-   */
-  constructor(config) {
+  constructor(config_) {
+    this.config_ = config_;
+    /**
+     * The unique identifier for this signal instance. Useful for debugging.
+     */
+    this.signalId = this.config_.signalId;
     /**
      * The list of observers (listeners) subscribed to this signal.
      * @protected
@@ -55,7 +59,6 @@ var SignalBase = class {
         throw new Error(`Cannot interact with a destroyed signal (id: ${this.signalId})`);
       }
     };
-    this.signalId = config.signalId;
   }
   /**
    * Indicates whether the signal has been destroyed.
@@ -169,19 +172,18 @@ var SignalBase = class {
    */
   destroy() {
     this.logger_.logMethod?.("destroy");
+    if (this.isDestroyed_) return;
     this.isDestroyed_ = true;
     this.observers_.length = 0;
+    this.config_.onDestroy?.();
+    this.config_ = null;
   }
 };
 
-// src/event-signal.ts
+// src/core/event-signal.ts
 var import_delay = require("@alwatr/delay");
 var import_logger = require("@alwatr/logger");
 var EventSignal = class extends SignalBase {
-  /**
-   * Initializes a new `EventSignal`.
-   * @param config The configuration for the signal, containing its `signalId`.
-   */
   constructor(config) {
     super(config);
     this.logger_ = (0, import_logger.createLogger)(`event-signal: ${this.signalId}`);
@@ -203,14 +205,10 @@ var EventSignal = class extends SignalBase {
   }
 };
 
-// src/state-signal.ts
+// src/core/state-signal.ts
 var import_delay2 = require("@alwatr/delay");
 var import_logger2 = require("@alwatr/logger");
 var StateSignal = class extends SignalBase {
-  /**
-   * Initializes a new `StateSignal`.
-   * @param config The configuration for the state signal, including `signalId` and `initialValue`.
-   */
   constructor(config) {
     super(config);
     this.logger_ = (0, import_logger2.createLogger)(`state-signal: ${this.signalId}`);
@@ -253,6 +251,26 @@ var StateSignal = class extends SignalBase {
       this.notify_(newValue);
     });
   }
+  /**
+   * Updates the signal's value based on its previous value.
+   *
+   * This method is particularly useful for state transitions that depend on the current value,
+   * especially for objects or arrays, as it promotes an immutable update pattern.
+   *
+   * @param updater A function that receives the current value and returns the new value.
+   *
+   * @example
+   * // For a counter
+   * counterSignal.update(current => current + 1);
+   *
+   * // For an object state
+   * userSignal.update(currentUser => ({ ...currentUser, loggedIn: true }));
+   */
+  update(updater) {
+    this.logger_.logMethod?.("update");
+    this.checkDestroyed_();
+    this.set(updater(this.value__));
+  }
   /**
    * Subscribes a listener to this signal.
    *
@@ -283,19 +301,15 @@ var StateSignal = class extends SignalBase {
    * This is crucial for memory management to prevent leaks.
    */
   destroy() {
-    super.destroy();
     this.value__ = null;
+    super.destroy();
   }
 };
 
-// src/computed-signal.ts
+// src/core/computed-signal.ts
 var import_delay3 = require("@alwatr/delay");
 var import_logger3 = require("@alwatr/logger");
 var ComputedSignal = class {
-  /**
-   * Initializes a new `ComputedSignal`.
-   * @param config The configuration, including dependencies (`deps`) and the getter function (`get`).
-   */
   constructor(config_) {
     this.config_ = config_;
     this.signalId = this.config_.signalId;
@@ -357,6 +371,7 @@ var ComputedSignal = class {
     }
     this.subscriptionList__.length = 0;
     this.internalSignal_.destroy();
+    this.config_.onDestroy?.();
     this.config_ = null;
   }
   /**
@@ -393,14 +408,10 @@ var ComputedSignal = class {
   }
 };
 
-// src/effect-signal.ts
+// src/core/effect-signal.ts
 var import_delay4 = require("@alwatr/delay");
 var import_logger4 = require("@alwatr/logger");
 var EffectSignal = class {
-  /**
-   * Initializes a new `EffectSignal`.
-   * @param config The configuration, including dependencies (`deps`) and the `run` function.
-   */
   constructor(config_) {
     this.config_ = config_;
     this.logger_ = (0, import_logger4.createLogger)(`effect-signal`);
@@ -475,15 +486,71 @@ var EffectSignal = class {
       subscription.unsubscribe();
     }
     this.subscriptionList__.length = 0;
+    this.config_.onDestroy?.();
     this.config_ = null;
   }
 };
+
+// src/creators/event.ts
+function createEventSignal(config) {
+  return new EventSignal(config);
+}
+
+// src/creators/state.ts
+function createStateSignal(config) {
+  return new StateSignal(config);
+}
+
+// src/creators/computed.ts
+function createComputedSignal(config) {
+  return new ComputedSignal(config);
+}
+
+// src/creators/effect.ts
+function createEffect(config) {
+  return new EffectSignal(config);
+}
+
+// src/operators/debounce.ts
+var import_debounce = require("@alwatr/debounce");
+function createDebouncedSignal(sourceSignal, config) {
+  const signalId = config.signalId ?? `${sourceSignal.signalId}-debounced`;
+  const internalSignal = new StateSignal({
+    signalId: `${signalId}-internal`,
+    initialValue: sourceSignal.value
+  });
+  const debouncer = (0, import_debounce.createDebouncer)({
+    ...config,
+    func: (value) => {
+      internalSignal.set(value);
+    }
+  });
+  const subscription = sourceSignal.subscribe(debouncer.trigger);
+  return createComputedSignal({
+    signalId,
+    deps: [internalSignal],
+    get: () => internalSignal.value,
+    onDestroy: () => {
+      if (internalSignal.isDestroyed) return;
+      subscription.unsubscribe();
+      debouncer.cancel();
+      internalSignal.destroy();
+      config.onDestroy?.();
+      config = null;
+    }
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ComputedSignal,
   EffectSignal,
   EventSignal,
   SignalBase,
-  StateSignal
+  StateSignal,
+  createComputedSignal,
+  createDebouncedSignal,
+  createEffect,
+  createEventSignal,
+  createStateSignal
 });
 //# sourceMappingURL=main.cjs.map