@alwatr/signal 6.2.0 → 9.1.0

package/src/core/computed-signal.ts

@@ -0,0 +1,216 @@
+import { delay } from '@alwatr/delay';
+import { createLogger, type AlwatrLogger } from '@alwatr/logger';
+
+import { StateSignal } from './state-signal.js';
+
+import type { ComputedSignalConfig, IReadonlySignal, SubscribeResult, SubscribeOptions } from '../type.js';
+
+/**
+ * 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.
+ *
+ * @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 class ComputedSignal<T> implements IReadonlySignal<T> {
+  /**
+   * The unique identifier for this signal instance.
+   */
+  public 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.
+   * @protected
+   */
+  protected readonly internalSignal_: StateSignal<T>;
+
+  /**
+   * A list of subscriptions to dependency signals.
+   * @private
+   */
+
+  private readonly dependencySubscriptions__: SubscribeResult[] = [];
+
+  /**
+   * A flag to prevent concurrent recalculations.
+   * @private
+   */
+  private isRecalculating__ = false;
+
+  constructor(protected config_: ComputedSignalConfig<T>) {
+    this.name = config_.name;
+    this.logger_ = createLogger(`computed-signal:${this.name}`);
+    this.recalculate_ = this.recalculate_.bind(this);
+
+    this.logger_.logMethod?.('constructor');
+
+    this.internalSignal_ = new StateSignal<T>({
+      name: `compute-${this.name}_`,
+      initialValue: this.config_.get(),
+    });
+
+    // Subscribe to all dependencies to trigger recalculation on change.
+    for (const signal of config_.deps) {
+      this.logger_.logStep?.('constructor', 'subscribing_to_dependency', { signal: signal.name });
+      this.dependencySubscriptions__.push(signal.subscribe(this.recalculate_, { receivePrevious: false }));
+    }
+  }
+
+  /**
+   * The current value of the computed signal.
+   * Accessing this property returns the memoized value and does not trigger a recalculation.
+   *
+   * @returns The current computed value.
+   * @throws {Error} If accessed after the signal has been destroyed.
+   */
+  public get(): T {
+    return this.internalSignal_.get();
+  }
+
+  /**
+   * 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.
+   */
+  public get isDestroyed(): boolean {
+    return this.internalSignal_.isDestroyed;
+  }
+
+  /**
+   * 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.
+   */
+  public subscribe(callback: (value: T) => void, options?: SubscribeOptions): SubscribeResult {
+    return this.internalSignal_.subscribe(callback, options);
+  }
+
+  /**
+   * Returns a Promise that resolves with the next computed value.
+   *
+   * @returns A Promise that resolves with the next value.
+   */
+  public untilNext(): Promise<T> {
+    return this.internalSignal_.untilNext();
+  }
+
+  /**
+   * Permanently disposes of the computed signal.
+   *
+   * This is a critical cleanup step. It unsubscribes from all dependency signals,
+   * stopping future recalculations and allowing the signal to be garbage collected.
+   * Failure to call `destroy()` will result in memory leaks.
+   *
+   * After `destroy()` is called, any attempt to access `.get()` or `.subscribe()` will throw an error.
+   */
+  public destroy(): void {
+    this.logger_.logMethod?.('destroy');
+    /**
+     * If already destroyed, log an incident and return early.
+     */
+    if (this.isDestroyed) {
+      this.logger_.incident?.('destroy', 'already_destroyed');
+      return;
+    }
+
+    // Unsubscribe from all upstream dependencies.
+    for (const subscription of this.dependencySubscriptions__) {
+      subscription.unsubscribe();
+    }
+    this.dependencySubscriptions__.length = 0; // Clear the array of subscriptions.
+
+    this.internalSignal_.destroy(); // Destroy the internal signal.
+    this.config_.onDestroy?.(); // Call the optional onDestroy callback.
+    this.config_ = null as unknown as ComputedSignalConfig<T>; // Release config closure.
+  }
+
+  /**
+   * Schedules a recalculation of the signal's value.
+   *
+   * 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 async recalculate_(): Promise<void> {
+    this.logger_.logMethod?.('recalculate_');
+
+    if (this.internalSignal_.isDestroyed) {
+      // This check is important in case a dependency fires after this signal is destroyed.
+      this.logger_.incident?.('recalculate_', 'recalculate_on_destroyed_signal');
+      return;
+    }
+
+    if (this.isRecalculating__) {
+      // If a recalculation is already scheduled, do nothing.
+      this.logger_.logStep?.('recalculate_', 'skipping_recalculation_already_scheduled');
+      return;
+    }
+
+    this.isRecalculating__ = true;
+
+    try {
+      // Wait for the next macrotask to start the recalculation.
+      // This batches all synchronous dependency updates in the current event loop.
+      await delay.nextMacrotask();
+
+      if (this.isDestroyed) {
+        this.logger_.incident?.('recalculate_', 'destroyed_during_delay');
+        this.isRecalculating__ = false;
+        return;
+      }
+
+      this.logger_.logStep?.('recalculate_', 'recalculating_value');
+
+      // Set the new value on the internal signal, which will notify our subscribers.
+      this.internalSignal_.set(this.config_.get());
+    }
+    catch (err) {
+      this.logger_.error('recalculate_', 'recalculation_failed', err);
+    }
+
+    // Allow the next recalculation to be scheduled.
+    this.isRecalculating__ = false;
+  }
+}

package/src/core/effect-signal.ts

@@ -0,0 +1,176 @@
+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.
+ *
+ * `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.
+ *
+ * @implements {IEffectSignal}
+ *
+ * @example
+ * // --- Create dependency signals ---
+ * const counter = new StateSignal({ initialValue: 0, name: 'counter' });
+ * const user = new StateSignal({ initialValue: 'guest', name: 'user' });
+ *
+ * // --- Create an effect ---
+ * const analyticsEffect = new EffectSignal({
+ *   name: 'analytics-effect',
+ *   deps: [counter, user],
+ *   run: () => {
+ *     console.log(`Analytics: User '${user.get()}' clicked ${counter.get()} 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 class EffectSignal implements IEffectSignal {
+  /**
+   * The unique identifier for this signal instance.
+   */
+  public readonly name: string;
+
+  /**
+   * The logger instance for this signal.
+   * @protected
+   */
+  protected readonly logger_: AlwatrLogger;
+
+  /**
+   * A list of subscriptions to dependency signals.
+   * @private
+   */
+  private readonly dependencySubscriptions__: SubscribeResult[] = [];
+
+  /**
+   * A flag to prevent concurrent executions of the effect.
+   * @private
+   */
+  private isRunning__ = false;
+
+  /**
+   * A flag indicating whether the effect has been destroyed.
+   * @private
+   */
+  private isDestroyed__ = false;
+
+  /**
+   * Indicates whether the effect signal has been destroyed.
+   * A destroyed signal will no longer execute its effect and cannot be reused.
+   *
+   * @returns `true` if the signal is destroyed, `false` otherwise.
+   */
+  public get isDestroyed(): boolean {
+    return this.isDestroyed__;
+  }
+
+  constructor(protected config_: EffectSignalConfig) {
+    this.name = config_.name ?? `[${config_.deps.map((dep) => dep.name).join(', ')}]`;
+    this.logger_ = createLogger(`effect-signal:${this.name}`);
+    this.scheduleExecution_ = this.scheduleExecution_.bind(this);
+
+    this.logger_.logMethod?.('constructor');
+
+    // 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 }));
+    }
+
+    // Run the effect immediately if requested.
+    if (config_.runImmediately === true) {
+      this.logger_.logStep?.('constructor', 'scheduling_initial_execution');
+      // We don't need to await this, let it run in the background.
+      void this.scheduleExecution_();
+    }
+  }
+
+  /**
+   * Schedules the execution of the effect's `run` function.
+   *
+   * This method batches updates using a macrotask (`delay.nextMacrotask`) to ensure the
+   * `run` function executes only once per event loop tick, even if multiple
+   * dependencies change simultaneously.
+   * @protected
+   */
+  protected async scheduleExecution_(): Promise<void> {
+    this.logger_.logMethod?.('scheduleExecution_');
+
+    if (this.isDestroyed__) {
+      this.logger_.incident?.('scheduleExecution_', 'schedule_execution_on_destroyed_signal');
+      return;
+    }
+    if (this.isRunning__) {
+      // If an execution is already scheduled, do nothing.
+      this.logger_.logStep?.('scheduleExecution_', 'skipped_because_already_running');
+      return;
+    }
+
+    this.isRunning__ = true;
+
+    try {
+      // Wait for the next macrotask to batch simultaneous updates.
+      await delay.nextMacrotask();
+      if (this.isDestroyed__) {
+        this.logger_.incident?.('scheduleExecution_', 'destroyed_during_delay');
+        this.isRunning__ = false;
+        return;
+      }
+
+      this.logger_.logStep?.('scheduleExecution_', 'executing_effect');
+      await this.config_.run();
+    }
+    catch (err) {
+      this.logger_.error('scheduleExecution_', 'effect_failed', err);
+    }
+
+    // Reset the flag after the current execution is complete.
+    this.isRunning__ = false;
+  }
+
+  /**
+   * Permanently disposes of the effect signal.
+   *
+   * This is a critical cleanup step. It unsubscribes from all dependency signals,
+   * stopping any future executions of the effect and allowing it to be garbage collected.
+   * Failure to call `destroy()` will result in memory leaks and potentially unwanted side effects.
+   */
+  public destroy(): void {
+    this.logger_.logMethod?.('destroy');
+
+    if (this.isDestroyed__) {
+      this.logger_.incident?.('destroy', 'already_destroyed');
+      return;
+    }
+
+    this.isDestroyed__ = true;
+
+    // Unsubscribe from all upstream dependencies.
+    for (const subscription of this.dependencySubscriptions__) {
+      subscription.unsubscribe();
+    }
+    this.dependencySubscriptions__.length = 0; // Clear the array of subscriptions.
+
+    this.config_.onDestroy?.(); // Call the optional onDestroy callback.
+    this.config_ = null as unknown as EffectSignalConfig; // Release config closure.
+  }
+}

package/src/core/event-signal.ts

@@ -0,0 +1,61 @@
+import { delay } from '@alwatr/delay';
+import { createLogger, type AlwatrLogger } from '@alwatr/logger';
+
+import { SignalBase } from './signal-base.js';
+
+import type { SignalConfig } from '../type.js';
+
+/**
+ * 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. Defaults to `void` for events without a payload.
+ *
+ * @example
+ * // Create a signal for user click events.
+ * const onUserClick = new EventSignal<{ x: number, y: number }>({ name: 'on-user-click' });
+ *
+ * // Subscribe to the event.
+ * onUserClick.subscribe(clickPosition => {
+ *   console.log(`User clicked at: ${clickPosition.x}, ${clickPosition.y}`);
+ * });
+ *
+ * // Dispatch an event.
+ * onUserClick.dispatch({ x: 100, y: 250 }); // Notifies the listener.
+ *
+ * // --- Example with no payload ---
+ * const onAppReady = new EventSignal({ name: 'on-app-ready' });
+ * onAppReady.subscribe(() => console.log('Application is ready!'));
+ * onAppReady.dispatch(); // Notifies the listener.
+ */
+export class EventSignal<T = void> extends SignalBase<T> {
+  /**
+   * The logger instance for this signal.
+   * @protected
+   */
+  protected logger_: AlwatrLogger;
+
+  constructor(config: SignalConfig) {
+    super(config);
+    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.
+   *
+   * @param payload The data 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));
+  }
+}

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

@@ -0,0 +1,98 @@
+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';
+
+/**
+ * A stateful signal that persists its value in the browser's localStorage.
+ *
+ * It extends the functionality of a standard `StateSignal` by automatically reading
+ * its initial value from localStorage and writing back any subsequent changes.
+ *
+ * @template T The type of the state it holds.
+ */
+export class PersistentStateSignal<T extends JsonValue> extends StateSignal<T> {
+  /**
+   * The underlying storage provider instance.
+   * @private
+   */
+  private readonly storageProvider__: LocalStorageProvider<T>;
+
+  /**
+   * Debouncer to limit how often we write to localStorage.
+   * @private
+   */
+  private readonly storageDebouncer__;
+
+  /**
+   * 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__;
+
+  constructor(config: PersistentStateSignalConfig<T>) {
+    const {name, storageKey = name, saveDebounceDelay = 500, initialValue, onDestroy, schemaVersion} = config;
+
+    const storageProvider = createLocalStorageProvider<T>({
+      name: storageKey,
+      schemaVersion,
+    });
+
+    super({
+      name,
+      initialValue: storageProvider.read() ?? initialValue,
+      onDestroy,
+    });
+
+    this.logger_.logMethodArgs?.('constructor', config);
+
+    this.storageProvider__ = storageProvider;
+
+    this.storageDebouncer__ = createDebouncer({
+      delay: saveDebounceDelay,
+      leading: false,
+      trailing: true,
+      thisContext: this,
+      func: this.syncStorage__,
+    });
+
+    this.storageSyncSubscription__ = this.subscribe(this.storageDebouncer__.trigger, {receivePrevious: false});
+  }
+
+  /**
+   * Syncs the new value to storage.
+   * @param newValue The new value to sync to storage.
+   */
+  private syncStorage__(newValue: T): void {
+    this.logger_.logMethodArgs?.('syncStorage__', newValue);
+    this.storageProvider__.write(newValue);
+  }
+
+  /**
+   * Removes the value from localStorage.
+   * This provides a clean way to clear persisted data.
+   */
+  public remove(): void {
+    this.checkDestroyed_();
+    this.logger_.logMethod?.('remove');
+    // Remove from storage.
+    this.storageProvider__.remove();
+  }
+
+  /**
+   * Overrides the destroy method to also clean up the storage sync subscription.
+   */
+  public override destroy(): void {
+    this.logger_.logMethod?.('destroy');
+    // Flush any pending storage writes before destroying.
+    this.storageDebouncer__.flush();
+    // Unsubscribe from the sync listener to prevent memory leaks.
+    this.storageSyncSubscription__.unsubscribe();
+    super.destroy();
+  }
+}

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

@@ -0,0 +1,145 @@
+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';
+
+/**
+ * A stateful signal that persists its value in the browser's `sessionStorage`.
+ *
+ * It extends `StateSignal` by automatically reading its initial value from `sessionStorage`
+ * and writing back any subsequent changes. Unlike `PersistentStateSignal`, the data is cleared
+ * automatically when the browser tab or window is closed — it does not survive full page reloads
+ * in a new session.
+ *
+ * This is ideal for transient UI state that should survive soft navigations and refreshes
+ * within the same browser tab (e.g., wizard steps, unsaved form drafts, scroll position).
+ *
+ * @template T The type of the state it holds. Must be JSON-serializable.
+ *
+ * @example
+ * ```typescript
+ * import {SessionStateSignal} from '@alwatr/signal';
+ *
+ * interface WizardState {
+ *   step: number;
+ *   answers: Record<string, string>;
+ * }
+ *
+ * const wizardSignal = new SessionStateSignal<WizardState>({
+ *   name: 'checkout-wizard',
+ *   initialValue: { step: 1, answers: {} },
+ * });
+ *
+ * // On first load: reads from sessionStorage (or uses initialValue if not found).
+ * console.log(wizardSignal.get()); // { step: 1, answers: {} }
+ *
+ * // Update state — written to sessionStorage automatically (debounced).
+ * wizardSignal.set({ step: 2, answers: { q1: 'yes' } });
+ *
+ * // After a soft page reload, the state is restored from sessionStorage.
+ *
+ * // Clear the persisted session data without destroying the signal.
+ * wizardSignal.remove();
+ *
+ * // Clean up when the component/page is unmounted.
+ * wizardSignal.destroy();
+ * ```
+ */
+export class SessionStateSignal<T extends JsonValue> extends StateSignal<T> {
+  /**
+   * The underlying session storage provider instance.
+   * @private
+   */
+  private readonly storageProvider__: SessionStorageProvider<T>;
+
+  /**
+   * Debouncer to limit how often we write to sessionStorage.
+   * @private
+   */
+  private readonly storageDebouncer__;
+
+  /**
+   * Subscription to the signal's own changes for sessionStorage sync.
+   * @private
+   */
+  private readonly storageSyncSubscription__;
+
+  constructor(config: SessionStateSignalConfig<T>) {
+    const { name, storageKey = name, saveDebounceDelay = 500, initialValue, onDestroy } = config;
+
+    const storageProvider = createSessionStorageProvider<T>({ name: storageKey });
+
+    super({
+      name,
+      initialValue: storageProvider.read() ?? initialValue,
+      onDestroy,
+    });
+
+    this.logger_.logMethodArgs?.('constructor', config);
+
+    this.storageProvider__ = storageProvider;
+
+    this.storageDebouncer__ = createDebouncer({
+      delay: saveDebounceDelay,
+      leading: false,
+      trailing: true,
+      thisContext: this,
+      func: this.syncStorage__,
+    });
+
+    this.storageSyncSubscription__ = this.subscribe(this.storageDebouncer__.trigger, { receivePrevious: false });
+  }
+
+  /**
+   * Syncs the new value to sessionStorage.
+   * Called automatically by the debouncer after each state change.
+   *
+   * @param newValue The new value to sync.
+   */
+  private syncStorage__(newValue: T): void {
+    this.logger_.logMethodArgs?.('syncStorage__', newValue);
+    this.storageProvider__.write(newValue);
+  }
+
+  /**
+   * Removes the stored value from sessionStorage without destroying the signal.
+   *
+   * After calling this, the signal continues to hold its current in-memory value;
+   * only the sessionStorage entry is cleared.
+   *
+   * @example
+   * ```typescript
+   * // User logs out — clear transient session data.
+   * wizardSignal.remove();
+   * ```
+   */
+  public remove(): void {
+    this.checkDestroyed_();
+    this.logger_.logMethod?.('remove');
+    this.storageProvider__.remove();
+  }
+
+  /**
+   * Destroys the signal, flushing pending writes and cleaning up all resources.
+   *
+   * Always call this when the signal is no longer needed (e.g., on component unmount)
+   * to prevent memory leaks.
+   *
+   * @example
+   * ```typescript
+   * // In a component teardown:
+   * wizardSignal.destroy();
+   * ```
+   */
+  public override destroy(): void {
+    this.logger_.logMethod?.('destroy');
+    // Flush any pending debounced writes before destroying.
+    this.storageDebouncer__.flush();
+    // Unsubscribe the storage sync listener to prevent memory leaks.
+    this.storageSyncSubscription__.unsubscribe();
+    super.destroy();
+  }
+}