@alwatr/signal 6.2.0 → 9.1.0

package/src/core/signal-base.ts

@@ -0,0 +1,191 @@
+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).
+ *
+ * @template T The type of data that the signal holds or dispatches.
+ */
+export abstract class SignalBase<T> {
+  /**
+   * The unique identifier for this signal instance.
+   * Useful for debugging and logging.
+   */
+  public readonly name: 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>[] = [];
+
+  /**
+   * A flag indicating whether the signal has been destroyed.
+   * @private
+   */
+  private isDestroyed__ = false;
+
+  /**
+   * 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.
+   */
+  public get isDestroyed(): boolean {
+    return this.isDestroyed__;
+  }
+
+  constructor(protected config_: SignalConfig) {
+    this.name = config_.name;
+  }
+
+  /**
+   * Removes a specific observer from the observers list.
+   *
+   * @param observer The observer instance to remove.
+   * @protected
+   */
+  protected removeObserver_(observer: Observer_<T>): void {
+    this.logger_.logMethod?.('removeObserver_');
+
+    if (this.isDestroyed__) {
+      this.logger_.incident?.('removeObserver_', 'remove_observer_on_destroyed_signal');
+      return;
+    }
+
+    const index = this.observers_.indexOf(observer);
+    if (index !== -1) {
+      this.observers_.splice(index, 1);
+    }
+  }
+
+  /**
+   * Subscribes a listener function to this signal.
+   *
+   * The listener will be called whenever the signal is notified (e.g., when `dispatch` or `set` is called).
+   *
+   * @param callback The function to be called when the signal is dispatched.
+   * @param options Subscription options to customize the behavior (e.g., `once`, `priority`).
+   * @returns A `SubscribeResult` object with an `unsubscribe` method to remove the listener.
+   */
+  public subscribe(callback: ListenerCallback<T>, options?: SubscribeOptions): SubscribeResult {
+    this.logger_.logMethodArgs?.('subscribe.base', options);
+    this.checkDestroyed_();
+
+    const observer: Observer_<T> = {callback, options};
+
+    if (options?.priority) {
+      // High-priority observers are added to the front of the queue.
+      this.observers_.unshift(observer);
+    }
+    else {
+      this.observers_.push(observer);
+    }
+
+    // The returned unsubscribe function is a closure that calls the internal removal method.
+    return {
+      unsubscribe: (): void => this.removeObserver_(observer),
+    };
+  }
+
+  /**
+   * Notifies all registered observers about a new value.
+   *
+   * This method iterates through a snapshot of the current observers to prevent issues
+   * with subscriptions changing during notification (e.g., an observer unsubscribing itself).
+   *
+   * @param value The new value to notify observers about.
+   * @protected
+   */
+  protected notify_(value: T): void {
+    this.logger_.logMethodArgs?.('notify_', value);
+
+    if (this.isDestroyed__) {
+      this.logger_.incident?.('notify_', 'notify_on_destroyed_signal');
+      return;
+    }
+
+    // Create a snapshot of the observers array to iterate over.
+    // This prevents issues if the observers_ array is modified during the loop.
+    const currentObservers = [...this.observers_];
+
+    for (const observer of currentObservers) {
+      if (observer.options?.once) {
+        this.removeObserver_(observer);
+      }
+
+      try {
+        const result = observer.callback(value);
+        if (result instanceof Promise) {
+          result.catch((err) => this.logger_.error('notify_', 'async_callback_failed', err, {observer}));
+        }
+      }
+      catch (err) {
+        this.logger_.error('notify_', 'sync_callback_failed', err);
+      }
+    }
+  }
+
+  /**
+   * Returns a Promise that resolves with the next value dispatched by the signal.
+   * This provides an elegant way to wait for a single, future event using `async/await`.
+   *
+   * @returns A Promise that resolves with the next dispatched value.
+   *
+   * @example
+   * async function onButtonClick() {
+   *   console.log('Waiting for the next signal...');
+   *   const nextValue = await mySignal.untilNext();
+   *   console.log('Signal received:', nextValue);
+   * }
+   */
+  public untilNext(): Promise<T> {
+    this.logger_.logMethod?.('untilNext');
+    this.checkDestroyed_();
+    return new Promise((resolve) => {
+      this.subscribe(resolve, {
+        once: true,
+        priority: true, // Resolve the promise before other listeners are called.
+        receivePrevious: false, // We only want the *next* value, not the current one.
+      });
+    });
+  }
+
+  /**
+   * Destroys the signal, clearing all its listeners and making it inactive.
+   *
+   * After destruction, any interaction with the signal (like `subscribe` or `untilNext`)
+   * will throw an error. This is crucial for preventing memory leaks by allowing
+   * garbage collection of the signal and its observers.
+   */
+  public destroy(): void {
+    this.logger_.logMethod?.('destroy');
+    if (this.isDestroyed__) {
+      this.logger_.incident?.('destroy_', 'double_destroy_attempt');
+      return;
+    }
+    this.isDestroyed__ = true;
+    this.observers_.length = 0; // Clear all observers.
+    this.config_.onDestroy?.(); // Call the optional onDestroy callback.
+    this.config_ = null as unknown as SignalConfig; // Help GC by breaking references.
+  }
+
+  /**
+   * Throws an error if the signal has been destroyed.
+   * This is a safeguard to prevent interaction with a defunct signal.
+   * @protected
+   */
+  protected checkDestroyed_(): void {
+    if (this.isDestroyed__) {
+      this.logger_.accident('checkDestroyed_', 'attempt_to_use_destroyed_signal');
+      throw new Error(`Cannot interact with a destroyed signal (id: ${this.name})`);
+    }
+  }
+}

package/src/core/state-signal.ts

@@ -0,0 +1,178 @@
+import { delay } from '@alwatr/delay';
+import { createLogger, type AlwatrLogger } from '@alwatr/logger';
+
+import { SignalBase } from './signal-base.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.
+ *
+ * `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.
+ * @implements {IReadonlySignal<T>}
+ *
+ * @example
+ * // Create a new state signal with an initial value.
+ * const counter = new StateSignal<number>({
+ *   name: 'counter-signal',
+ *   initialValue: 0,
+ * });
+ *
+ * // Get the current value.
+ * console.log(counter.get()); // Outputs: 0
+ *
+ * // Subscribe to changes.
+ * const subscription = counter.subscribe(newValue => {
+ *   console.log(`Counter changed to: ${newValue}`);
+ * });
+ *
+ * // 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 class StateSignal<T> extends SignalBase<T> implements IReadonlySignal<T> {
+  /**
+   * The current value of the signal.
+   * @private
+   */
+  private value__: T;
+
+  /**
+   * The logger instance for this signal.
+   * @protected
+   */
+  protected logger_: AlwatrLogger;
+
+  constructor(config: StateSignalConfig<T>) {
+    super({
+      name: config.name,
+      onDestroy: config.onDestroy,
+    });
+    this.logger_ = createLogger(`state-signal:${this.name}`);
+    this.value__ = config.initialValue;
+    this.logger_.logMethodArgs?.('constructor', { initialValue: this.value__ });
+  }
+
+  /**
+   * Retrieves the current value of the signal.
+   *
+   * @returns The current value.
+   *
+   * @example
+   * console.log(mySignal.get());
+   */
+  public get(): T {
+    this.checkDestroyed_();
+    return this.value__;
+  }
+
+  /**
+   * Updates the signal's value and notifies all active listeners.
+   *
+   * The notification is scheduled as a microtask, which means the update is deferred
+   * slightly to batch multiple synchronous changes.
+   *
+   * @param newValue The new value to set.
+   *
+   * @example
+   * // For primitive types
+   * mySignal.set(42);
+   *
+   * // For object types, it's best practice to set an immutable new object.
+   * mySignal.set({ ...mySignal.get(), property: 'new-value' });
+   */
+  public set(newValue: T): void {
+    this.logger_.logMethodArgs?.('set', { newValue });
+    this.checkDestroyed_();
+
+    // For primitives (including null), do not notify if the value is the same.
+    if (Object.is(this.value__, newValue) && (typeof newValue !== 'object' || newValue === null)) {
+      return;
+    }
+
+    this.value__ = newValue;
+
+    // Dispatch as a microtask to ensure consistent, non-blocking behavior.
+    delay.nextMicrotask().then(() => this.notify_(newValue));
+  }
+
+  /**
+   * Updates the signal's value based on its previous value.
+   *
+   * This method is particularly useful for state transitions that depend on the current value,
+   * especially for objects or arrays, as it promotes an immutable update pattern.
+   *
+   * @param updater A function that receives the current value and returns the new value.
+   *
+   * @example
+   * // For a counter
+   * counterSignal.update(current => current + 1);
+   *
+   * // For an object state
+   * userSignal.update(currentUser => ({ ...currentUser, loggedIn: true }));
+   */
+  public update(updater: (previousValue: T) => T): void {
+    this.checkDestroyed_();
+    const newValue = updater(this.value__);
+    this.logger_.logMethodFull?.('update', this.value__, newValue);
+    this.set(newValue);
+  }
+
+  /**
+   * Subscribes a listener to this signal.
+   *
+   * By default, the listener is immediately called with the signal's current value (`receivePrevious: true`).
+   * This behavior can be customized via the `options` parameter.
+   *
+   * @param callback The function to be called when the signal's value changes.
+   * @param options Subscription options, including `receivePrevious` and `once`.
+   * @returns An object with an `unsubscribe` method to remove the listener.
+   */
+  public override subscribe(callback: ListenerCallback<T>, options: SubscribeOptions = {}): SubscribeResult {
+    this.logger_.logMethodArgs?.('subscribe', options);
+    this.checkDestroyed_();
+
+    // By default, new subscribers to a StateSignal should receive the current value.
+    if (options.receivePrevious !== false) {
+      // Immediately (but asynchronously) call the listener with the current value.
+      // This is done in a microtask to ensure it happens after the subscription is fully registered.
+      delay
+        .nextMicrotask()
+        .then(() => {
+          this.logger_.logStep?.('subscribe', 'immediate_callback');
+          callback(this.value__);
+        })
+        .catch((err) => this.logger_.error('subscribe', 'immediate_callback_failed', err));
+
+      // If it's a 'once' subscription that receives the previous value, it's now fulfilled.
+      // We don't need to add it to the observers list for future updates.
+      if (options.once) {
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
+        return { unsubscribe: () => { } };
+      }
+    }
+
+    return super.subscribe(callback, options);
+  }
+
+  /**
+   * Destroys the signal, clearing its value and all listeners.
+   * This is crucial for memory management to prevent leaks.
+   */
+  public override destroy(): void {
+    this.value__ = null as T; // Clear the value to allow for garbage collection.
+    super.destroy();
+  }
+
+  public asReadonly(): IReadonlySignal<T> {
+    return this;
+  }
+}

package/src/creators/computed.ts

@@ -0,0 +1,37 @@
+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({ name: 'firstName', initialValue: 'John' });
+ * const lastName = createStateSignal({ name: 'lastName', initialValue: 'Doe' });
+ *
+ * const fullName = createComputedSignal({
+ *   name: 'fullName',
+ *   deps: [firstName, lastName],
+ *   get: () => `${firstName.get()} ${lastName.get()}`,
+ * });
+ *
+ * console.log(fullName.get()); // "John Doe"
+ *
+ * // IMPORTANT: Always destroy a computed signal when no longer needed.
+ * // fullName.destroy();
+ */
+export function createComputedSignal<T>(config: ComputedSignalConfig<T>): ComputedSignal<T> {
+  return new ComputedSignal(config);
+}

package/src/creators/effect.ts

@@ -0,0 +1,46 @@
+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, name: 'counter' });
+ * const user = createStateSignal({ initialValue: 'guest', name: 'user' });
+ *
+ * // --- Create an effect ---
+ * const analyticsEffect = createEffect({
+ *   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 function createEffect(config: EffectSignalConfig): EffectSignal {
+  return new EffectSignal(config);
+}

package/src/creators/event.ts

@@ -0,0 +1,31 @@
+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 }>({
+ *   name: 'on-user-click'
+ * });
+ *
+ * onUserClick.subscribe(pos => {
+ *   console.log(`User clicked at: ${pos.x}, ${pos.y}`);
+ * });
+ *
+ * onUserClick.dispatch({ x: 100, y: 250 });
+ */
+export function createEventSignal<T = void>(config: SignalConfig): EventSignal<T> {
+  return new EventSignal<T>(config);
+}

package/src/creators/persistent-state.ts

@@ -0,0 +1,33 @@
+import {PersistentStateSignal} from '../core/persistent-state-signal.js';
+
+import type {PersistentStateSignalConfig} from '../type.js';
+
+/**
+ * Creates a stateful signal that persists its value in localStorage.
+ *
+ * This function provides a clean, declarative API for creating state that
+ * survives page reloads. It automatically handles reading the initial state
+ * from localStorage and saving subsequent updates.
+ *
+ * @template T The type of the state it holds.
+ *
+ * @param {PersistentStateSignalConfig<T>} config The configuration for the persistent state signal.
+ * @returns {PersistentStateSignal<T>} A new instance of PersistentStateSignal.
+ *
+ * @example
+ * // Create a signal to store user's preferred theme.
+ * const userThemeSignal = createPersistentStateSignal<string>({
+ *   name: 'user-theme',
+ *   schemaVersion: 1,
+ *   initialValue: 'light',
+ * });
+ *
+ * // The initial value is read from localStorage, or 'light' if not present.
+ * console.log(userThemeSignal.get());
+ *
+ * // Setting a new value updates the in-memory state and writes to localStorage.
+ * userThemeSignal.set('dark');
+ */
+export function createPersistentStateSignal<T extends JsonValue>(config: PersistentStateSignalConfig<T>): PersistentStateSignal<T> {
+  return new PersistentStateSignal(config);
+}

package/src/creators/session-state.ts

@@ -0,0 +1,42 @@
+import { SessionStateSignal } from '../core/session-state-signal.js';
+
+import type { SessionStateSignalConfig } from '../type.js';
+
+/**
+ * Creates a stateful signal that persists its value in `sessionStorage`.
+ *
+ * The stored data survives soft navigations and page refreshes within the same browser tab,
+ * but is automatically cleared when the tab or window is closed.
+ *
+ * Use this for transient UI state such as:
+ * - Multi-step wizard progress
+ * - Unsaved form drafts
+ * - Scroll position or active tab indices
+ *
+ * @template T The type of the state it holds. Must be JSON-serializable.
+ *
+ * @param {SessionStateSignalConfig<T>} config The configuration for the session state signal.
+ * @returns {SessionStateSignal<T>} A new `SessionStateSignal` instance.
+ *
+ * @example
+ * ```typescript
+ * import {createSessionStateSignal} from '@alwatr/signal';
+ *
+ * const checkoutWizard = createSessionStateSignal<{step: number}>({
+ *   name: 'checkout-wizard',
+ *   initialValue: {step: 1},
+ * });
+ *
+ * // State is restored from sessionStorage if it exists.
+ * console.log(checkoutWizard.get()); // {step: 1} or last saved value
+ *
+ * // Update state — automatically saved to sessionStorage.
+ * checkoutWizard.set({step: 2});
+ *
+ * // Cleanup when no longer needed.
+ * checkoutWizard.destroy();
+ * ```
+ */
+export function createSessionStateSignal<T extends JsonValue>(config: SessionStateSignalConfig<T>): SessionStateSignal<T> {
+  return new SessionStateSignal(config);
+}

package/src/creators/state.ts

@@ -0,0 +1,28 @@
+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({
+ *   name: 'counter-signal',
+ *   initialValue: 0,
+ * });
+ *
+ * console.log(counter.get()); // Outputs: 0
+ * counter.set(1);
+ * console.log(counter.get()); // Outputs: 1
+ */
+export function createStateSignal<T>(config: StateSignalConfig<T>): StateSignal<T> {
+  return new StateSignal(config);
+}

package/src/main.ts

@@ -0,0 +1,20 @@
+export * from './core/signal-base.js';
+export * from './core/event-signal.js';
+export * from './core/state-signal.js';
+export * from './core/computed-signal.js';
+export * from './core/effect-signal.js';
+export * from './core/persistent-state-signal.js';
+export * from './core/session-state-signal.js';
+
+export * from './creators/event.js';
+export * from './creators/state.js';
+export * from './creators/computed.js';
+export * from './creators/effect.js';
+export * from './creators/persistent-state.js';
+export * from './creators/session-state.js';
+
+export * from './operators/debounce.js';
+export * from './operators/filter.js';
+export * from './operators/map.js';
+
+export type * from './type.js';