@alwatr/signal 9.26.0 → 9.30.0

package/dist/core/channel-signal.d.ts

@@ -1,58 +1,6 @@
-import type { Awaitable } from '@alwatr/type-helper';
 import { type AlwatrLogger } from '@alwatr/logger';
 import { SignalBase } from './signal-base.js';
-import type { SignalConfig, SubscribeOptions, SubscribeResult, ListenerCallback } from '../type.js';
-/**
- * Determines whether the payload argument for a given channel message is
- * required or optional, based solely on the declared type in `TMap`.
- *
- * - `void | undefined` → payload is optional (second arg may be omitted).
- * - anything else      → payload is **required** (omitting it is a compile error).
- *
- * This is used to build the rest-parameter tuple for `dispatch()` so that
- * TypeScript enforces the correct call signature at every dispatch site.
- *
- * @template TMap A record mapping message names to their payload types.
- * @template K    The specific message name key.
- *
- * @example
- * ```ts
- * // ActionRecord: { 'logout': void; 'add-to-cart': {productId: number} }
- * type A = DispatchArgs<ActionRecord, 'logout'>;       // [name: 'logout', payload?: void]
- * type B = DispatchArgs<ActionRecord, 'add-to-cart'>;  // [name: 'add-to-cart', payload: {productId: number}]
- * ```
- */
-export type DispatchArgs<TMap extends object, K extends keyof TMap> = TMap[K] extends void | undefined ? [name: K, payload?: TMap[K]] : [name: K, payload: TMap[K]];
-/**
- * A single message dispatched through a `ChannelSignal`.
- *
- * `name` identifies the message type (e.g. `'open-drawer'`, `'add-to-cart'`).
- * `payload` carries the associated data, whose type is determined by the generic `TMap` based on the `name`.
- *
- * @template TMap A record mapping message names to their payload types.
- * @template K    The specific message name key (inferred, not set manually).
- */
-export type ChannelMessage<TMap extends object, K extends keyof TMap = keyof TMap> = {
-    name: K;
-    payload: TMap[K];
-};
-/**
- * A typed handler for a specific named message on a `ChannelSignal`.
- * Receives only the `payload` — the name is already known at subscription time.
- *
- * The payload type mirrors `DispatchArgs`: it is `TMap[K] | undefined` only
- * when the declared type is `void | undefined`; otherwise it is exactly `TMap[K]`
- * (non-optional) so handlers do not need unnecessary null-guards.
- *
- * @template TMap A record mapping message names to their payload types.
- * @template K    The specific message name key.
- */
-export type ChannelHandler<TMap extends object, K extends keyof TMap = keyof TMap> = (payload: TMap[K]) => Awaitable<void>;
-/**
- * Configuration for creating a `ChannelSignal`.
- */
-export interface ChannelSignalConfig extends SignalConfig {
-}
+import type { SubscribeOptions, SubscribeResult, ListenerCallback, ChannelHandler, ChannelMessage, ChannelSignalConfig, DispatchArgs } from '../type.js';
 /**
  * A stateless multi-channel signal that acts as a typed O(1) message bus.
  *
@@ -100,6 +48,7 @@ export interface ChannelSignalConfig extends SignalConfig {
 export declare class ChannelSignal<TMap extends object> extends SignalBase<ChannelMessage<TMap>> {
     /**
      * The logger instance for this signal.
+     *
      * @protected
      */
     protected logger_: AlwatrLogger;
@@ -117,6 +66,11 @@ export declare class ChannelSignal<TMap extends object> extends SignalBase<Chann
      * @private
      */
     private readonly namedHandlers__;
+    /**
+     * Creates a new ChannelSignal instance.
+     *
+     * @param config Configuration options including the unique channel name and cleanup hook.
+     */
     constructor(config: ChannelSignalConfig);
     /**
      * Dispatches a named message to:
@@ -141,6 +95,7 @@ export declare class ChannelSignal<TMap extends object> extends SignalBase<Chann
      * channel.dispatch('logout', undefined);            // ✅ also fine
      * ```
      *
+     * @template K The specific message name key.
      * @param args Tuple of `[name, payload]` — payload optionality is enforced
      *             by `DispatchArgs<TMap, K>` based on the declared type.
      */
@@ -155,6 +110,7 @@ export declare class ChannelSignal<TMap extends object> extends SignalBase<Chann
      * envelope) — since the name is already known at subscription time, passing
      * it again would be redundant.
      *
+     * @template K    The specific message name key.
      * @param name    The message name to listen for.
      * @param handler Callback invoked with the payload each time the named message
      *                is dispatched.
@@ -200,6 +156,9 @@ export declare class ChannelSignal<TMap extends object> extends SignalBase<Chann
      * 2. Invokes each handler, removing `once` entries after their first call.
      * 3. Notifies raw-stream subscribers via `SignalBase.notify_()`.
      *
+     * @template K The specific message name key.
+     * @param name The message name to route.
+     * @param payload The payload associated with the message name.
      * @private
      */
     private route__;

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

@@ -1 +1 @@
-{"version":3,"file":"channel-signal.d.ts","sourceRoot":"","sources":["../../src/core/channel-signal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAAe,KAAK,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAE/D,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAE5C,OAAO,KAAK,EAAC,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAC,MAAM,YAAY,CAAC;AAIlG;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,YAAY,CAAC,IAAI,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,IAAI,IAChE,IAAI,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,SAAS,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAEhG;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,CAAC,IAAI,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,IAAI,GAAG,MAAM,IAAI,IAAI;IAAC,IAAI,EAAE,CAAC,CAAC;IAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;CAAC,CAAC;AAEjH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,CAAC,IAAI,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,IAAI,GAAG,MAAM,IAAI,IAAI,CACnF,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,KACb,SAAS,CAAC,IAAI,CAAC,CAAC;AAerB;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,YAAY;CAAG;AAI5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,aAAa,CAAC,IAAI,SAAS,MAAM,CAAE,SAAQ,UAAU,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IACtF;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,YAAY,CAAC;IAEhC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyE;gBAE7F,MAAM,EAAE,mBAAmB;IAMvC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACI,QAAQ,CAAC,CAAC,SAAS,MAAM,IAAI,EAAE,GAAG,IAAI,EAAE,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI;IAO3E;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACI,EAAE,CAAC,CAAC,SAAS,MAAM,IAAI,EAC5B,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC,EAChC,OAAO,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,GACvC,eAAe;IAyBlB;;;;;;;;;;;;;;;;;;OAkBG;IACa,SAAS,CACvB,QAAQ,EAAE,gBAAgB,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,EAChD,OAAO,CAAC,EAAE,gBAAgB,GACzB,eAAe;IAKlB;;;;;;;;OAQG;IACH,OAAO,CAAC,OAAO;IAyBf;;OAEG;IACa,OAAO,IAAI,IAAI;CAIhC"}
+{"version":3,"file":"channel-signal.d.ts","sourceRoot":"","sources":["../../src/core/channel-signal.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAC5C,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,YAAY,EACb,MAAM,YAAY,CAAC;AAiBpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,aAAa,CAAC,IAAI,SAAS,MAAM,CAAE,SAAQ,UAAU,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IACtF;;;;OAIG;IACH,SAAS,CAAC,OAAO,EAAE,YAAY,CAAC;IAEhC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyE;IAEzG;;;;OAIG;gBACS,MAAM,EAAE,mBAAmB;IAMvC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACI,QAAQ,CAAC,CAAC,SAAS,MAAM,IAAI,EAAE,GAAG,IAAI,EAAE,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI;IAO3E;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACI,EAAE,CAAC,CAAC,SAAS,MAAM,IAAI,EAC5B,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC,EAChC,OAAO,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,GACvC,eAAe;IAyBlB;;;;;;;;;;;;;;;;;;OAkBG;IACa,SAAS,CACvB,QAAQ,EAAE,gBAAgB,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,EAChD,OAAO,CAAC,EAAE,gBAAgB,GACzB,eAAe;IAKlB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,OAAO;IAsBf;;OAEG;IACa,OAAO,IAAI,IAAI;CAIhC"}

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

@@ -1,6 +1,6 @@
 import { type AlwatrLogger } from '@alwatr/logger';
 import { StateSignal } from './state-signal.js';
-import type { ComputedSignalConfig, IReadonlySignal, SubscribeResult, SubscribeOptions } from '../type.js';
+import type { ComputedSignalConfig, IReadonlySignal, SubscribeOptions, SubscribeResult, ListenerCallback } from '../type.js';
 /**
  * A read-only signal that derives its value from a set of dependency signals.
  *
@@ -12,32 +12,6 @@ import type { ComputedSignalConfig, IReadonlySignal, SubscribeResult, SubscribeO
  * needed to prevent memory leaks from its subscriptions to dependency signals.
  *
  * @template T The type of the computed value.
- *
- * @example
- * // --- Create dependency signals ---
- * const firstName = new StateSignal({ name: 'firstName', initialValue: 'John' });
- * const lastName = new StateSignal({ name: 'lastName', initialValue: 'Doe' });
- *
- * // --- Create a computed signal ---
- * const fullName = new ComputedSignal({
- *   name: 'fullName',
- *   deps: [firstName, lastName],
- *   get: () => `${firstName.get()} ${lastName.get()}`,
- * });
- *
- * console.log(fullName.get()); // Outputs: "John Doe"
- *
- * // --- Subscribe to the computed value ---
- * fullName.subscribe(newFullName => {
- *   console.log(`Name changed to: ${newFullName}`);
- * });
- *
- * // --- Update a dependency ---
- * lastName.set('Smith'); // Recalculates and logs: "Name changed to: John Smith"
- * console.log(fullName.get()); // Outputs: "John Smith"
- *
- * // --- IMPORTANT: Clean up when done ---
- * fullName.destroy();
  */
 export declare class ComputedSignal<T> implements IReadonlySignal<T> {
     protected config_: ComputedSignalConfig<T>;
@@ -47,25 +21,38 @@ export declare class ComputedSignal<T> implements IReadonlySignal<T> {
     readonly name: string;
     /**
      * The logger instance for this signal.
+     *
      * @protected
      */
     protected readonly logger_: AlwatrLogger;
     /**
      * The internal `StateSignal` that holds the computed value.
      * This is how the computed signal provides `.get()` and `.subscribe()` methods.
+     * Enforces COMPOSITION over inheritance.
+     *
      * @protected
      */
     protected readonly internalSignal_: StateSignal<T>;
     /**
      * A list of subscriptions to dependency signals.
+     * Used to unsubscribe from dependencies when this signal is destroyed.
+     *
      * @private
      */
     private readonly dependencySubscriptions__;
     /**
      * A flag to prevent concurrent recalculations.
+     * Avoids queuing multiple updates in the event loop.
+     *
      * @private
      */
     private isRecalculating__;
+    /**
+     * Creates a new ComputedSignal instance.
+     * Subscribes to all dependency signals to trigger recalculations.
+     *
+     * @param config_ Configuration options including dependencies, evaluation getter, and cleanup hook.
+     */
     constructor(config_: ComputedSignalConfig<T>);
     /**
      * The current value of the computed signal.
@@ -78,6 +65,7 @@ export declare class ComputedSignal<T> implements IReadonlySignal<T> {
     /**
      * Indicates whether the computed 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;
@@ -89,7 +77,7 @@ export declare class ComputedSignal<T> implements IReadonlySignal<T> {
      * @param options Subscription options.
      * @returns A `SubscribeResult` object with an `unsubscribe` method.
      */
-    subscribe(callback: (value: T) => void, options?: SubscribeOptions): SubscribeResult;
+    subscribe(callback: ListenerCallback<T>, options?: SubscribeOptions): SubscribeResult;
     /**
      * Returns a Promise that resolves with the next computed value.
      *
@@ -107,13 +95,11 @@ export declare class ComputedSignal<T> implements IReadonlySignal<T> {
      */
     destroy(): void;
     /**
-     * Schedules a recalculation of the signal's value.
+     * Recalculates the derived value.
+     * Centralized microtask batcher coordination avoids internal loop crashes.
      *
-     * This method batches updates using a macrotask (`delay.nextMacrotask`) to ensure the
-     * `get` function runs only once per event loop tick, even if multiple dependencies
-     * change in the same synchronous block of code.
      * @protected
      */
-    protected recalculate_(): Promise<void>;
+    protected recalculate_(): void;
 }
 //# sourceMappingURL=computed-signal.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"computed-signal.d.ts","sourceRoot":"","sources":["../../src/core/computed-signal.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEjE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE3G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,cAAc,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,CAAC;IAgC9C,SAAS,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC;IA/BtD;;OAEG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAEzC;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IAEnD;;;OAGG;IAEH,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAyB;IAEnE;;;OAGG;IACH,OAAO,CAAC,iBAAiB,CAAS;gBAEZ,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAmBtD;;;;;;OAMG;IACI,GAAG,IAAI,CAAC;IAIf;;;;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"}
+{"version":3,"file":"computed-signal.d.ts","sourceRoot":"","sources":["../../src/core/computed-signal.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EACV,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;GAWG;AACH,qBAAa,cAAc,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,CAAC;IA4C9C,SAAS,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC;IA3CtD;;OAEG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAEzC;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IAEnD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAyB;IAEnE;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB,CAAS;IAElC;;;;;OAKG;gBACmB,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAoBtD;;;;;;OAMG;IACI,GAAG,IAAI,CAAC;IAIf;;;;;OAKG;IACH,IAAW,WAAW,IAAI,OAAO,CAEhC;IAED;;;;;;;OAOG;IACI,SAAS,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,eAAe;IAI5F;;;;OAIG;IACI,SAAS,IAAI,OAAO,CAAC,CAAC,CAAC;IAI9B;;;;;;;;OAQG;IACI,OAAO,IAAI,IAAI;IAiBtB;;;;;OAKG;IACH,SAAS,CAAC,YAAY,IAAI,IAAI;CA8B/B"}

package/dist/core/derived-signal.d.ts

@@ -0,0 +1,71 @@
+import { type AlwatrLogger } from '@alwatr/logger';
+import { StateSignal } from './state-signal.js';
+import type { IReadonlySignal, DerivedSignalConfig, ListenerCallback, SubscribeOptions, SubscribeResult } from '../type.js';
+/**
+ * Ultra-performance read-only signal mapping exactly 1-to-1 over a single upstream source.
+ *
+ * COMPOSITION DESIGN PATTERN (HAS-A):
+ * Instead of extending the heavyweight Base class and duplicating tracking structures, it wraps
+ * an internal StateSignal instance. It features a "Cold Awakening Lifecycle": it consumes exactly
+ * ZERO stream overhead from the source until it receives its own first consumer subscription.
+ * If all consumers disconnect, it goes back to sleep (hibernation phase) to save performance.
+ *
+ * @template S The type of the source signal state.
+ * @template T The type of the derived/projected signal state.
+ */
+export declare class DerivedSignal<S, T> implements IReadonlySignal<T> {
+    protected config_: DerivedSignalConfig<S, T>;
+    /** The unique identifier for this signal instance, useful for debugging and tracing. */
+    readonly name: string;
+    /** Scoped logger for tracking derived operations. */
+    protected readonly logger_: AlwatrLogger;
+    /** Wrapped internal state carrier - Enforcing COMPOSITION over inheritance, allocated lazily */
+    protected internalSignal_?: StateSignal<T> | null;
+    /** Subscription handle to the upstream source signal, active only when awake. */
+    private sourceSubscription__?;
+    /** Number of active standard/priority listeners currently subscribed to this signal. */
+    private activeConsumerCount__;
+    /**
+     * Creates a new DerivedSignal instance.
+     *
+     * @param config_ Configuration options including name, source, and projector.
+     */
+    constructor(config_: DerivedSignalConfig<S, T>);
+    untilNext(): Promise<T>;
+    /**
+     * Retrieves the current value of the derived signal.
+     *
+     * If there are no active subscribers (cold state), it re-computes dynamically
+     * on demand to ensure strict data freshness.
+     *
+     * @returns The current projected value.
+     */
+    get(): T;
+    /**
+     * Indicates whether the signal has been destroyed.
+     */
+    get isDestroyed(): boolean;
+    /**
+     * Subscribes a listener to updates of this derived signal.
+     *
+     * In case of first subscription, it triggers the "Cold Awakening Lifecycle"
+     * to subscribe to the source signal.
+     *
+     * @param callback Subscription callback function.
+     * @param options Subscription configurations.
+     * @returns Unsubscribe handle object.
+     */
+    subscribe(callback: ListenerCallback<T>, options?: SubscribeOptions): SubscribeResult;
+    /**
+     * Destroys the derived signal and unsubscribes from the source signal if currently awake.
+     */
+    destroy(): void;
+    /**
+     * Checks if the signal has been destroyed.
+     *
+     * @private
+     * @throws {Error} If destroyed.
+     */
+    private checkDestroyed__;
+}
+//# sourceMappingURL=derived-signal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"derived-signal.d.ts","sourceRoot":"","sources":["../../src/core/derived-signal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EACV,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;GAWG;AACH,qBAAa,aAAa,CAAC,CAAC,EAAE,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,CAAC;IAqBhD,SAAS,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC;IApBxD,wFAAwF;IACxF,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,qDAAqD;IACrD,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAEzC,gGAAgG;IAChG,SAAS,CAAC,eAAe,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAElD,iFAAiF;IACjF,OAAO,CAAC,oBAAoB,CAAC,CAAkB;IAE/C,wFAAwF;IACxF,OAAO,CAAC,qBAAqB,CAAK;IAElC;;;;OAIG;gBACmB,OAAO,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC;IAKxD,SAAS,IAAI,OAAO,CAAC,CAAC,CAAC;IAavB;;;;;;;OAOG;IACI,GAAG,IAAI,CAAC;IASf;;OAEG;IACH,IAAW,WAAW,IAAI,OAAO,CAEhC;IAED;;;;;;;;;OASG;IACI,SAAS,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,eAAe;IAyC5F;;OAEG;IACI,OAAO,IAAI,IAAI;IActB;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;CAMzB"}

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

@@ -47,21 +47,27 @@ export declare class EffectSignal implements IEffectSignal {
     readonly name: string;
     /**
      * The logger instance for this signal.
+     *
      * @protected
      */
     protected readonly logger_: AlwatrLogger;
     /**
      * A list of subscriptions to dependency signals.
+     * Used to unsubscribe from dependencies when this signal is destroyed.
+     *
      * @private
      */
     private readonly dependencySubscriptions__;
     /**
      * A flag to prevent concurrent executions of the effect.
+     * Avoids scheduling multiple runs within the same event loop.
+     *
      * @private
      */
     private isRunning__;
     /**
      * A flag indicating whether the effect has been destroyed.
+     *
      * @private
      */
     private isDestroyed__;
@@ -72,14 +78,22 @@ export declare class EffectSignal implements IEffectSignal {
      * @returns `true` if the signal is destroyed, `false` otherwise.
      */
     get isDestroyed(): boolean;
+    /**
+     * Creates a new EffectSignal instance.
+     * Subscribes to all dependency signals to listen for updates.
+     *
+     * @param config_ Configuration options including dependencies, side-effect runner callback, and immediate execution flag.
+     */
     constructor(config_: EffectSignalConfig);
     /**
      * Schedules the execution of the effect's `run` function.
      *
-     * This method batches updates using a macrotask (`delay.nextMacrotask`) to ensure the
+     * This method batches updates using a macrotask (`delay.nextMicrotask`) to ensure the
      * `run` function executes only once per event loop tick, even if multiple
      * dependencies change simultaneously.
+     *
      * @protected
+     * @returns A promise that resolves when the execution schedules or runs.
      */
     protected scheduleExecution_(): Promise<void>;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"effect-signal.d.ts","sourceRoot":"","sources":["../../src/core/effect-signal.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAmB,MAAM,YAAY,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,YAAa,YAAW,aAAa;IAwCpC,SAAS,CAAC,OAAO,EAAE,kBAAkB;IAvCjD;;OAEG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAEzC;;;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;gBAEqB,OAAO,EAAE,kBAAkB;IAsBjD;;;;;;;OAOG;cACa,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAmCnD;;;;;;OAMG;IACI,OAAO,IAAI,IAAI;CAmBvB"}
+{"version":3,"file":"effect-signal.d.ts","sourceRoot":"","sources":["../../src/core/effect-signal.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC/D,OAAO,KAAK,EAAC,kBAAkB,EAAE,aAAa,EAAkB,MAAM,YAAY,CAAC;AAEnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,YAAa,YAAW,aAAa;IAoDpC,SAAS,CAAC,OAAO,EAAE,kBAAkB;IAnDjD;;OAEG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAEzC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAyB;IAEnE;;;;;OAKG;IACH,OAAO,CAAC,WAAW,CAAS;IAE5B;;;;OAIG;IACH,OAAO,CAAC,aAAa,CAAS;IAE9B;;;;;OAKG;IACH,IAAW,WAAW,IAAI,OAAO,CAEhC;IAED;;;;;OAKG;gBACmB,OAAO,EAAE,kBAAkB;IAsBjD;;;;;;;;;OASG;cACa,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAkCnD;;;;;;OAMG;IACI,OAAO,IAAI,IAAI;CAmBvB"}

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

@@ -31,16 +31,23 @@ import type { IBaseSignal, SignalConfig } from '../type.js';
 export declare class EventSignal<T = void> extends SignalBase<T> implements IBaseSignal<T> {
     /**
      * The logger instance for this signal.
+     *
      * @protected
      */
     protected logger_: AlwatrLogger;
+    /**
+     * Creates a new EventSignal instance.
+     *
+     * @param config Configuration options including the unique event name and custom cleanup hooks.
+     */
     constructor(config: SignalConfig);
     /**
-     * Dispatches an event with an optional payload to all active listeners.
-     * The notification is scheduled as a microtask to prevent blocking and ensure
-     * a consistent, non-blocking flow.
+     * Dispatches an event with the specified payload to all active listeners.
+     *
+     * To prevent blocking of the main thread and ensure consistent execution order,
+     * the notification execution is scheduled as a microtask using `queueMicrotask`.
      *
-     * @param payload The data to send with the event.
+     * @param payload The data payload to send with the event.
      */
     dispatch(payload: T): void;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"event-signal.d.ts","sourceRoot":"","sources":["../../src/core/event-signal.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAE/D,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAE,YAAY,EAAC,MAAM,YAAY,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,WAAW,CAAC,CAAC,GAAG,IAAI,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAE,YAAW,WAAW,CAAC,CAAC,CAAC;IAChF;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,YAAY,CAAC;gBAEpB,MAAM,EAAE,YAAY;IAMhC;;;;;;OAMG;IACI,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI;CAMlC"}
+{"version":3,"file":"event-signal.d.ts","sourceRoot":"","sources":["../../src/core/event-signal.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAC5C,OAAO,KAAK,EAAC,WAAW,EAAE,YAAY,EAAC,MAAM,YAAY,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,WAAW,CAAC,CAAC,GAAG,IAAI,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAE,YAAW,WAAW,CAAC,CAAC,CAAC;IAChF;;;;OAIG;IACH,SAAS,CAAC,OAAO,EAAE,YAAY,CAAC;IAEhC;;;;OAIG;gBACS,MAAM,EAAE,YAAY;IAMhC;;;;;;;OAOG;IACI,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI;CAMlC"}

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

@@ -44,11 +44,15 @@ import type { PersistentStateSignalConfig } from '../type.js';
 export declare class PersistentStateSignal<T> extends StateSignal<T> {
     /**
      * The underlying storage provider instance.
+     * Handles read, write, and schema version management under the hood.
+     *
      * @private
      */
     private readonly storageProvider__;
     /**
      * Debouncer to limit how often we write to localStorage.
+     * Reduces performance overhead from excessive disk writes.
+     *
      * @private
      */
     private readonly storageDebouncer__;
@@ -56,23 +60,38 @@ export declare class PersistentStateSignal<T> extends StateSignal<T> {
      * The subscription to the signal's own changes to sync with storage.
      * We subscribe to our own signal. When the value is set from anywhere,
      * this listener will trigger and write it to localStorage.
+     *
      * @private
      */
     private readonly storageSyncSubscription__;
     /**
      * Listener for the browser's pagehide events to flush pending saves.
+     * Ensures that pending changes are saved before the page unloading.
+     *
      * @private
      */
     private readonly windowPageHideListener_;
     /**
      * Listener for the browser's pageshow events to sync from storage when restored from BFCache.
+     * Refreshes the in-memory value if retrieved from the Back/Forward Cache.
+     *
      * @private
      */
     private readonly windowPageShowListener_;
+    /**
+     * Creates a new PersistentStateSignal instance.
+     * Restores initial value from storage if it exists, otherwise uses default initialValue.
+     * Sets up window page visibility and BFCache listeners to guarantee write flushes.
+     *
+     * @param config Configuration options including storage keys, debounce delays, schema, parse, and stringify overrides.
+     */
     constructor(config: PersistentStateSignalConfig<T>);
     /**
      * Syncs the new value to storage.
-     * @param newValue The new value to sync to storage.
+     * Invoked automatically by the debouncer.
+     *
+     * @param newValue The new value to write to storage.
+     * @private
      */
     private syncStorage__;
     /**
@@ -81,7 +100,7 @@ export declare class PersistentStateSignal<T> extends StateSignal<T> {
      */
     remove(): void;
     /**
-     * Overrides the destroy method to also clean up the storage sync subscription.
+     * Overrides the destroy method to also clean up the storage sync subscription and event listeners.
      */
     destroy(): void;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"persistent-state-signal.d.ts","sourceRoot":"","sources":["../../src/core/persistent-state-signal.ts"],"names":[],"mappings":"AAGA,OAAO,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAE9C,OAAO,KAAK,EAAC,2BAA2B,EAAC,MAAM,YAAY,CAAC;AAG5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBAAa,qBAAqB,CAAC,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAC;IAC1D;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA0B;IAE5D;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IAEpC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAC;IAE3C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAEtC;IAEF;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAQtC;gBAEU,MAAM,EAAE,2BAA2B,CAAC,CAAC,CAAC;IA6ClD;;;OAGG;IACH,OAAO,CAAC,aAAa;IAKrB;;;OAGG;IACI,MAAM,IAAI,IAAI;IAOrB;;OAEG;IACa,OAAO,IAAI,IAAI;CAYhC"}
+{"version":3,"file":"persistent-state-signal.d.ts","sourceRoot":"","sources":["../../src/core/persistent-state-signal.ts"],"names":[],"mappings":"AAEA,OAAO,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EAAC,2BAA2B,EAAC,MAAM,YAAY,CAAC;AAG5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBAAa,qBAAqB,CAAC,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAC;IAC1D;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA0B;IAE5D;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IAEpC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAC;IAE3C;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAEtC;IAEF;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAQtC;IAEF;;;;;;OAMG;gBACS,MAAM,EAAE,2BAA2B,CAAC,CAAC,CAAC;IA6ClD;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAKrB;;;OAGG;IACI,MAAM,IAAI,IAAI;IAOrB;;OAEG;IACa,OAAO,IAAI,IAAI;CAYhC"}

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

@@ -38,7 +38,7 @@ import type { SessionStateSignalConfig } from '../type.js';
  *
  * // Example 2: Custom state type with parse and stringify
  * const dateSignal = new SessionStateSignal<Date>({
- *   name: 'last-interaction',
+ *   name: 'timestamp-signal',
  *   initialValue: new Date(),
  *   parse: (str: string) => new Date(str),
  *   stringify: (date: Date) => date.toISOString(),
@@ -56,35 +56,52 @@ import type { SessionStateSignalConfig } from '../type.js';
 export declare class SessionStateSignal<T> extends StateSignal<T> {
     /**
      * The underlying session storage provider instance.
+     *
      * @private
      */
     private readonly storageProvider__;
     /**
      * Debouncer to limit how often we write to sessionStorage.
+     * Helps reduce synchronous overhead from session storage updates.
+     *
      * @private
      */
     private readonly storageDebouncer__;
     /**
      * Subscription to the signal's own changes for sessionStorage sync.
+     * Writes the value to sessionStorage after a debounce delay.
+     *
      * @private
      */
     private readonly storageSyncSubscription__;
     /**
      * Listener for the browser's pagehide events to flush pending saves.
+     * Ensures pending state changes are flushed to sessionStorage before leaving the page.
+     *
      * @private
      */
     private readonly windowPageHideListener__;
     /**
      * Listener for the browser's pageshow events to sync from storage when restored from BFCache.
+     * Ensures in-memory sync when restored from the back-forward cache.
+     *
      * @private
      */
     private readonly windowPageShowListener__;
+    /**
+     * Creates a new SessionStateSignal instance.
+     * Loads initial value from sessionStorage if found, otherwise uses config's initialValue.
+     * Sets up page hide/show lifecycle handlers.
+     *
+     * @param config Configuration options including storageKeys, custom parse/stringify, and debounce delay.
+     */
     constructor(config: SessionStateSignalConfig<T>);
     /**
      * Syncs the new value to sessionStorage.
      * Called automatically by the debouncer after each state change.
      *
      * @param newValue The new value to sync.
+     * @private
      */
     private syncStorage__;
     /**
@@ -101,7 +118,7 @@ export declare class SessionStateSignal<T> extends StateSignal<T> {
      */
     remove(): void;
     /**
-     * Destroys the signal, flushing pending writes and cleaning up all resources.
+     * Destroys the signal, flushing pending writes and cleaning up all resources and events.
      *
      * Always call this when the signal is no longer needed (e.g., on component unmount)
      * to prevent memory leaks.

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

@@ -1 +1 @@
-{"version":3,"file":"session-state-signal.d.ts","sourceRoot":"","sources":["../../src/core/session-state-signal.ts"],"names":[],"mappings":"AAGA,OAAO,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAE9C,OAAO,KAAK,EAAC,wBAAwB,EAAC,MAAM,YAAY,CAAC;AAGzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,qBAAa,kBAAkB,CAAC,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAC;IACvD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4B;IAE9D;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IAEpC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAC;IAE3C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAEvC;IAEF;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAQvC;gBAEU,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC;IAmC/C;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAKrB;;;;;;;;;;;OAWG;IACI,MAAM,IAAI,IAAI;IAMrB;;;;;;;;;;;OAWG;IACa,OAAO,IAAI,IAAI;CAYhC"}
+{"version":3,"file":"session-state-signal.d.ts","sourceRoot":"","sources":["../../src/core/session-state-signal.ts"],"names":[],"mappings":"AAEA,OAAO,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EAAC,wBAAwB,EAAC,MAAM,YAAY,CAAC;AAGzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,qBAAa,kBAAkB,CAAC,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAC;IACvD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4B;IAE9D;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IAEpC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAC;IAE3C;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAEvC;IAEF;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAQvC;IAEF;;;;;;OAMG;gBACS,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC;IAmC/C;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAKrB;;;;;;;;;;;OAWG;IACI,MAAM,IAAI,IAAI;IAMrB;;;;;;;;;;;OAWG;IACa,OAAO,IAAI,IAAI;CAYhC"}