@alwatr/signal 5.0.0 → 5.2.0

package/CHANGELOG.md

@@ -3,6 +3,69 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [5.2.0](https://github.com/Alwatr/flux/compare/v5.1.0...v5.2.0) (2025-09-15)
+
+### ✨ Features
+
+* Add comprehensive documentation to the repository ([d5569e6](https://github.com/Alwatr/flux/commit/d5569e63acd0aa926c34d9a61b2fff5139b9d3cc))
+* Update EffectSignalConfig to allow optional signalId and add documentation ([6aab97e](https://github.com/Alwatr/flux/commit/6aab97e6e223f822f66cacb78c9d194fa5e2df9d))
+
+### 🐛 Bug Fixes
+
+* Refactor logger initialization and ensure checkDestroyed_ is called in relevant methods ([a17884d](https://github.com/Alwatr/flux/commit/a17884d5df097d62353e5b4110d3a83a5ae093b3))
+
+### 🔨 Code Refactoring
+
+* Ensure isRunning__ is reset when destroyed during delay in EffectSignal ([ff9a590](https://github.com/Alwatr/flux/commit/ff9a5905f7875e7dcb675cbdbb44869b0743e954))
+* Improve signal management by consolidating destruction checks and enhancing logging ([8765ba2](https://github.com/Alwatr/flux/commit/8765ba2f701f10db89ef11a3045065442360d193))
+* Remove unnecessary binding of notify_ in EventSignal constructor ([eb3be32](https://github.com/Alwatr/flux/commit/eb3be3211b13c21aa4f5c16a37f5c9fc59144951))
+* Simplify ComputedSignal implementation and improve logging for lifecycle methods ([bc35e91](https://github.com/Alwatr/flux/commit/bc35e91d5871669cc22c6c92ee2b83c4d940194e))
+* Simplify EffectSignal implementation and improve logging for lifecycle methods ([a5cad04](https://github.com/Alwatr/flux/commit/a5cad04469efd929e2ce7da42b371d4c054e5eaf))
+* Simplify EventSignal logger initialization and constructor ([b515315](https://github.com/Alwatr/flux/commit/b515315428e8ba0c70a7ef5ede49916e899b6fcd))
+* Update logger step identifiers for recalculation in ComputedSignal ([8de799f](https://github.com/Alwatr/flux/commit/8de799f40d90c2cdc3440d90bc1f2b6ce22f7013))
+
+## [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, SubscribeOptions } from '../type.js';
 /**
  * A read-only signal that derives its value from a set of dependency signals.
  *
@@ -11,7 +11,6 @@ import type { ComputedSignalConfig, IComputedSignal, SubscribeResult } from './t
  * needed to prevent memory leaks from its subscriptions to dependency signals.
  *
  * @template T The type of the computed value.
- * @implements {IComputedSignal<T>}
  *
  * @example
  * // --- Create dependency signals ---
@@ -39,9 +38,16 @@ 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>;
+    /**
+     * The unique identifier for this signal instance.
+     */
     readonly signalId: string;
+    /**
+     * The logger instance for this signal.
+     * @protected
+     */
     protected readonly logger_: import("@alwatr/logger").AlwatrLogger;
     /**
      * The internal `StateSignal` that holds the computed value.
@@ -49,12 +55,16 @@ export declare class ComputedSignal<T> implements IComputedSignal<T> {
      * @protected
      */
     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`).
+     * A list of subscriptions to dependency signals.
+     * @private
+     */
+    private readonly dependencySubscriptions__;
+    /**
+     * A flag to prevent concurrent recalculations.
+     * @private
      */
+    private isRecalculating__;
     constructor(config_: ComputedSignalConfig<T>);
     /**
      * The current value of the computed signal.
@@ -70,8 +80,21 @@ 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 untilNext: () => Promise<T>;
+    /**
+     * Subscribes a listener to this signal.
+     * The listener will be called whenever the computed value changes.
+     *
+     * @param callback The function to be called with the new value.
+     * @param options Subscription options.
+     * @returns A `SubscribeResult` object with an `unsubscribe` method.
+     */
+    subscribe(callback: (value: T) => void, options?: SubscribeOptions): SubscribeResult;
+    /**
+     * Returns a Promise that resolves with the next computed value.
+     *
+     * @returns A Promise that resolves with the next value.
+     */
+    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,EAAE,gBAAgB,EAAC,MAAM,YAAY,CAAC;AAEzG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,cAAc,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,CAAC;IAmCvC,SAAS,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAlC7D;;OAEG;IACH,SAAgB,QAAQ,SAAyB;IAEjD;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,wCAAqD;IAE/E;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,eAAe,iBAG/B;IAEH;;;OAGG;IAEH,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAyB;IAEnE;;;OAGG;IACH,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;;;;;;;OAOG;IACI,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,eAAe;IAI3F;;;;OAIG;IACI,SAAS,IAAI,OAAO,CAAC,CAAC,CAAC;IAI9B;;;;;;;;OAQG;IACI,OAAO,IAAI,IAAI;IAqBtB;;;;;;;OAOG;cACa,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;CAwC9C"}

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.
  *
@@ -19,6 +19,7 @@ import type { EffectSignalConfig, IEffectSignal } from './type.js';
  *
  * // --- Create an effect ---
  * const analyticsEffect = new EffectSignal({
+ *   signalId: 'analytics-effect',
  *   deps: [counter, user],
  *   run: () => {
  *     console.log(`Analytics: User '${user.value}' clicked ${counter.value} times.`);
@@ -39,20 +40,37 @@ import type { EffectSignalConfig, IEffectSignal } from './type.js';
  */
 export declare class EffectSignal implements IEffectSignal {
     protected config_: EffectSignalConfig;
+    /**
+     * The unique identifier for this signal instance.
+     */
+    readonly signalId: string;
+    /**
+     * The logger instance for this signal.
+     * @protected
+     */
     protected readonly logger_: import("@alwatr/logger").AlwatrLogger;
-    private readonly subscriptionList__;
+    /**
+     * A list of subscriptions to dependency signals.
+     * @private
+     */
+    private readonly dependencySubscriptions__;
+    /**
+     * A flag to prevent concurrent executions of the effect.
+     * @private
+     */
     private isRunning__;
+    /**
+     * A flag indicating whether the effect has been destroyed.
+     * @private
+     */
     private isDestroyed__;
     /**
      * Indicates whether the effect signal has been destroyed.
-     * A destroyed signal cannot be used and will throw an error if interacted with.
+     * A destroyed signal will no longer execute its effect and cannot be reused.
+     *
      * @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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,YAAa,YAAW,aAAa;IAwC7B,SAAS,CAAC,OAAO,EAAE,kBAAkB;IAvCxD;;OAEG;IACH,SAAgB,QAAQ,SAAkH;IAE1I;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,wCAAmD;IAE7E;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAyB;IAEnE;;;OAGG;IACH,OAAO,CAAC,WAAW,CAAS;IAE5B;;;OAGG;IACH,OAAO,CAAC,aAAa,CAAS;IAE9B;;;;;OAKG;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.
  *
@@ -28,11 +28,11 @@ import type { SignalConfig } from './type.js';
  * onAppReady.dispatch(); // Notifies the listener.
  */
 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`.
+     * The logger instance for this signal.
+     * @protected
      */
+    protected logger_: import("@alwatr/logger").AlwatrLogger;
     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;;;OAGG;IACH,SAAS,CAAC,OAAO,wCAAkD;gBAEhD,MAAM,EAAE,YAAY;IAKvC;;;;;;OAMG;IACI,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI;CAMlC"}

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

@@ -1,39 +1,44 @@
-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.
+ * It provides the core functionality for managing subscriptions (observers).
  *
- * `SignalBase` provides the core functionality for managing subscriptions (observers).
- * It handles adding, removing, and notifying listeners. The responsibility of *when* to notify
- * is left to the concrete subclasses (`StateSignal`, `EventSignal`, etc.).
- *
- * @template T The type of data the signal will handle.
+ * @template T The type of data that the signal holds or dispatches.
  */
 export declare abstract class SignalBase<T> {
+    protected config_: SignalConfig;
     /**
-     * The unique identifier for this signal instance. Useful for debugging.
+     * The unique identifier for this signal instance.
+     * Useful for debugging and logging.
      */
     readonly signalId: string;
+    /**
+     * The logger instance for this signal.
+     * @protected
+     */
     protected abstract logger_: AlwatrLogger;
     /**
      * The list of observers (listeners) subscribed to this signal.
      * @protected
      */
     protected readonly observers_: Observer_<T>[];
-    protected isDestroyed_: boolean;
+    /**
+     * A flag indicating whether the signal has been destroyed.
+     * @private
+     */
+    private isDestroyed__;
     /**
      * 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.
      */
     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.
      * @protected
      */
@@ -85,6 +90,6 @@ export declare abstract class SignalBase<T> {
      * This is a safeguard to prevent interaction with a defunct signal.
      * @protected
      */
-    protected checkDestroyed_: () => void;
+    protected checkDestroyed_(): void;
 }
 //# sourceMappingURL=signal-base.d.ts.map

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;;;;;GAKG;AACH,8BAAsB,UAAU,CAAC,CAAC;IAmCb,SAAS,CAAC,OAAO,EAAE,YAAY;IAlClD;;;OAGG;IACH,SAAgB,QAAQ,SAAyB;IAEjD;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAEzC;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,CAAM;IAEnD;;;OAGG;IACH,OAAO,CAAC,aAAa,CAAS;IAE9B;;;;;OAKG;IACH,IAAW,WAAW,IAAI,OAAO,CAEhC;gBAE4B,OAAO,EAAE,YAAY;IAElD;;;;;OAKG;IACH,SAAS,CAAC,eAAe,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;IAcvD;;;;;;;;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;IA6BjC;;;;;;;;;;;;OAYG;IACI,SAAS,IAAI,OAAO,CAAC,CAAC,CAAC;IAY9B;;;;;;OAMG;IACI,OAAO,IAAI,IAAI;IAYtB;;;;OAIG;IACH,SAAS,CAAC,eAAe,IAAI,IAAI;CAMlC"}

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,23 @@ 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> {
+    /**
+     * The current value of the signal.
+     * @private
+     */
     private value__;
-    protected logger_: import("@alwatr/logger").AlwatrLogger;
     /**
-     * Initializes a new `StateSignal`.
-     * @param config The configuration for the state signal, including `signalId` and `initialValue`.
+     * The logger instance for this signal.
+     * @protected
      */
+    protected logger_: import("@alwatr/logger").AlwatrLogger;
     constructor(config: StateSignalConfig<T>);
     /**
      * Retrieves the current value of the signal.
@@ -63,6 +70,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;;;OAGG;IACH,OAAO,CAAC,OAAO,CAAI;IAEnB;;;OAGG;IACH,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;IAwBzG;;;OAGG;IACa,OAAO,IAAI,IAAI;CAIhC"}

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"}