@alwatr/signal 9.26.0 → 9.30.0

package/src/core/derived-signal.ts

@@ -0,0 +1,166 @@
+import {createLogger, 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 class DerivedSignal<S, T> implements IReadonlySignal<T> {
+  /** The unique identifier for this signal instance, useful for debugging and tracing. */
+  public 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__?: SubscribeResult;
+
+  /** Number of active standard/priority listeners currently subscribed to this signal. */
+  private activeConsumerCount__ = 0;
+
+  /**
+   * Creates a new DerivedSignal instance.
+   *
+   * @param config_ Configuration options including name, source, and projector.
+   */
+  constructor(protected config_: DerivedSignalConfig<S, T>) {
+    this.name = this.config_.name;
+    this.logger_ = createLogger(`derived_signal:${this.name}`);
+  }
+
+  untilNext(): Promise<T> {
+    this.logger_.logMethod?.('untilNext');
+    this.checkDestroyed__();
+    return new Promise<T>((resolve) => {
+      this.subscribe(
+        (value) => {
+          resolve(value);
+        },
+        {receivePrevious: false, once: true},
+      );
+    });
+  }
+
+  /**
+   * 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.
+   */
+  public get(): T {
+    this.logger_.logMethod?.('get');
+    this.checkDestroyed__();
+    if (this.activeConsumerCount__ === 0) {
+      return this.config_.projector(this.config_.source.get());
+    }
+    return this.internalSignal_!.get();
+  }
+
+  /**
+   * Indicates whether the signal has been destroyed.
+   */
+  public get isDestroyed(): boolean {
+    return this.config_ === null;
+  }
+
+  /**
+   * 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.
+   */
+  public subscribe(callback: ListenerCallback<T>, options?: SubscribeOptions): SubscribeResult {
+    this.logger_.logMethod?.('subscribe');
+    this.checkDestroyed__();
+    this.activeConsumerCount__++;
+
+    // Wake-up phase: if this is the first active consumer, dynamically clamp to the upstream core source
+    if (this.activeConsumerCount__ === 1) {
+      this.logger_.logMethod?.('wakeUp_');
+      this.internalSignal_ = new StateSignal<T>({
+        name: `derived-internal:${this.name}`,
+        initialValue: this.config_.projector(this.config_.source.get()),
+      });
+      this.sourceSubscription__ = this.config_.source.subscribe(
+        (newValue) => {
+          this.internalSignal_!.set(this.config_.projector(newValue));
+        },
+        {receivePrevious: false},
+      );
+    }
+
+    const sub = this.internalSignal_!.subscribe(callback, options);
+
+    return {
+      unsubscribe: () => {
+        this.logger_.logMethod?.('unsubscribe');
+
+        sub.unsubscribe();
+        this.activeConsumerCount__--;
+
+        // Hibernation phase: unlink tracking dependencies when view elements clear out to preserve processing cycles
+        if (this.activeConsumerCount__ === 0 && this.sourceSubscription__) {
+          this.logger_.logMethod?.('sleepCleanup_');
+          this.sourceSubscription__.unsubscribe();
+          this.sourceSubscription__ = undefined;
+          this.internalSignal_?.destroy();
+          this.internalSignal_ = undefined;
+        }
+      },
+    };
+  }
+
+  /**
+   * Destroys the derived signal and unsubscribes from the source signal if currently awake.
+   */
+  public destroy(): void {
+    this.logger_.logMethod?.('destroy');
+    if (this.isDestroyed) return;
+
+    if (this.sourceSubscription__) {
+      this.sourceSubscription__.unsubscribe();
+      this.sourceSubscription__ = undefined;
+    }
+
+    this.internalSignal_?.destroy();
+    this.config_.onDestroy?.();
+    this.config_ = null as unknown as DerivedSignalConfig<S, T>;
+  }
+
+  /**
+   * Checks if the signal has been destroyed.
+   *
+   * @private
+   * @throws {Error} If destroyed.
+   */
+  private checkDestroyed__(): void {
+    this.logger_.logMethod?.('checkDestroyed__');
+    if (this.isDestroyed) {
+      throw new Error(`Cannot interact with a destroyed signal (id: ${this.name})`);
+    }
+  }
+}

package/src/core/effect-signal.ts

@@ -1,7 +1,6 @@
-import { delay } from '@alwatr/delay';
-import { createLogger, type AlwatrLogger } from '@alwatr/logger';
-
-import type { EffectSignalConfig, IEffectSignal, SubscribeResult } from '../type.js';
+import {delay} from '@alwatr/delay';
+import {createLogger, type AlwatrLogger} from '@alwatr/logger';
+import type {EffectSignalConfig, IEffectSignal, SubscribeResult} from '../type.js';
 
 /**
  * Manages a side-effect that runs in response to changes in dependency signals.
@@ -50,24 +49,30 @@ export class EffectSignal implements IEffectSignal {
 
   /**
    * 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__: SubscribeResult[] = [];
 
   /**
    * A flag to prevent concurrent executions of the effect.
+   * Avoids scheduling multiple runs within the same event loop.
+   *
    * @private
    */
   private isRunning__ = false;
 
   /**
    * A flag indicating whether the effect has been destroyed.
+   *
    * @private
    */
   private isDestroyed__ = false;
@@ -82,6 +87,12 @@ export class EffectSignal implements IEffectSignal {
     return this.isDestroyed__;
   }
 
+  /**
+   * 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(protected config_: EffectSignalConfig) {
     this.name = config_.name ?? `[${config_.deps.map((dep) => dep.name).join(', ')}]`;
     this.logger_ = createLogger(`effect-signal:${this.name}`);
@@ -92,8 +103,8 @@ export class EffectSignal implements IEffectSignal {
     // Subscribe to all dependencies. We don't need the previous value,
     // as the `runImmediately` option controls the initial execution.
     for (const signal of config_.deps) {
-      this.logger_.logStep?.('constructor', 'subscribing_to_dependency', { signal: signal.name });
-      this.dependencySubscriptions__.push(signal.subscribe(this.scheduleExecution_, { receivePrevious: false }));
+      this.logger_.logStep?.('constructor', 'subscribing_to_dependency', {signal: signal.name});
+      this.dependencySubscriptions__.push(signal.subscribe(this.scheduleExecution_, {receivePrevious: false}));
     }
 
     // Run the effect immediately if requested.
@@ -107,10 +118,12 @@ export class EffectSignal implements IEffectSignal {
   /**
    * 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 async scheduleExecution_(): Promise<void> {
     this.logger_.logMethod?.('scheduleExecution_');
@@ -129,7 +142,7 @@ export class EffectSignal implements IEffectSignal {
 
     try {
       // Wait for the next macrotask to batch simultaneous updates.
-      await delay.nextMacrotask();
+      await delay.nextMicrotask();
       if (this.isDestroyed__) {
         this.logger_.incident?.('scheduleExecution_', 'destroyed_during_delay');
         this.isRunning__ = false;
@@ -137,9 +150,8 @@ export class EffectSignal implements IEffectSignal {
       }
 
       this.logger_.logStep?.('scheduleExecution_', 'executing_effect');
-      await this.config_.run();
-    }
-    catch (err) {
+      this.config_.run();
+    } catch (err) {
       this.logger_.error('scheduleExecution_', 'effect_failed', err);
     }
 

package/src/core/event-signal.ts

@@ -1,8 +1,6 @@
-import {delay} from '@alwatr/delay';
+import {queueMicrotask} from '@alwatr/delay';
 import {createLogger, type AlwatrLogger} from '@alwatr/logger';
-
 import {SignalBase} from './signal-base.js';
-
 import type {IBaseSignal, SignalConfig} from '../type.js';
 
 /**
@@ -35,27 +33,34 @@ import type {IBaseSignal, SignalConfig} from '../type.js';
 export 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) {
     super(config);
-    this.logger_ = createLogger(`event-signal:${this.name}`);
+    this.logger_ = createLogger(`event_signal:${this.name}`);
     this.logger_.logMethod?.('constructor');
   }
 
   /**
-   * 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.
    */
   public dispatch(payload: T): void {
     this.logger_.logMethodArgs?.('dispatch', {payload});
     this.checkDestroyed_();
     // Dispatch as a microtask to ensure consistent, non-blocking behavior.
-    delay.nextMicrotask().then(() => this.notify_(payload));
+    queueMicrotask(() => this.notify_(payload));
   }
 }

package/src/core/persistent-state-signal.ts

@@ -1,8 +1,6 @@
 import {createDebouncer} from '@alwatr/debounce';
 import {createLocalStorageProvider} from '@alwatr/local-storage';
-
 import {StateSignal} from './state-signal.js';
-
 import type {PersistentStateSignalConfig} from '../type.js';
 import type {LocalStorageProvider} from '@alwatr/local-storage';
 
@@ -50,12 +48,16 @@ import type {LocalStorageProvider} from '@alwatr/local-storage';
 export 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__: LocalStorageProvider<T>;
 
   /**
    * Debouncer to limit how often we write to localStorage.
+   * Reduces performance overhead from excessive disk writes.
+   *
    * @private
    */
   private readonly storageDebouncer__;
@@ -64,12 +66,15 @@ export 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_ = (): void => {
@@ -78,6 +83,8 @@ export class PersistentStateSignal<T> extends StateSignal<T> {
 
   /**
    * 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_ = (event: PageTransitionEvent): void => {
@@ -90,6 +97,13 @@ export class PersistentStateSignal<T> extends StateSignal<T> {
     }
   };
 
+  /**
+   * 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>) {
     const {
       name,
@@ -137,7 +151,10 @@ export class PersistentStateSignal<T> extends StateSignal<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__(newValue: T): void {
     this.logger_.logMethodArgs?.('syncStorage__', newValue);
@@ -156,7 +173,7 @@ export class PersistentStateSignal<T> extends StateSignal<T> {
   }
 
   /**
-   * 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.
    */
   public override destroy(): void {
     this.logger_.logMethod?.('destroy');

package/src/core/session-state-signal.ts

@@ -1,8 +1,6 @@
 import {createDebouncer} from '@alwatr/debounce';
 import {createSessionStorageProvider} from '@alwatr/session-storage';
-
 import {StateSignal} from './state-signal.js';
-
 import type {SessionStateSignalConfig} from '../type.js';
 import type {SessionStorageProvider} from '@alwatr/session-storage';
 
@@ -44,7 +42,7 @@ import type {SessionStorageProvider} from '@alwatr/session-storage';
  *
  * // 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(),
@@ -62,24 +60,31 @@ import type {SessionStorageProvider} from '@alwatr/session-storage';
 export class SessionStateSignal<T> extends StateSignal<T> {
   /**
    * The underlying session storage provider instance.
+   *
    * @private
    */
   private readonly storageProvider__: SessionStorageProvider<T>;
 
   /**
    * 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__ = (): void => {
@@ -88,6 +93,8 @@ export class SessionStateSignal<T> extends StateSignal<T> {
 
   /**
    * 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__ = (event: PageTransitionEvent): void => {
@@ -100,6 +107,13 @@ export class SessionStateSignal<T> extends StateSignal<T> {
     }
   };
 
+  /**
+   * 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>) {
     const {name, storageKey = name, saveDebounceDelay = 1000, initialValue, onDestroy, parse, stringify} = config;
 
@@ -140,6 +154,7 @@ export class SessionStateSignal<T> extends StateSignal<T> {
    * Called automatically by the debouncer after each state change.
    *
    * @param newValue The new value to sync.
+   * @private
    */
   private syncStorage__(newValue: T): void {
     this.logger_.logMethodArgs?.('syncStorage__', newValue);
@@ -165,7 +180,7 @@ export class SessionStateSignal<T> extends StateSignal<T> {
   }
 
   /**
-   * 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.