@alwatr/signal 6.2.0 → 9.1.0

package/src/operators/debounce.ts

@@ -0,0 +1,91 @@
+import {createDebouncer} from '@alwatr/debounce';
+
+import {StateSignal} from '../core/state-signal.js';
+import {createComputedSignal} from '../creators/computed.js';
+
+import type {ComputedSignal} from '../core/computed-signal.js';
+import type {IReadonlySignal, DebounceSignalConfig} from '../type.js';
+
+/**
+ * Creates a new computed signal that debounces updates from a source signal.
+ *
+ * The returned signal is a `ComputedSignal`, meaning it is read-only and its value is
+ * derived from the source. It only updates its value after a specified period of
+ * inactivity from the source signal.
+ *
+ * This operator is essential for handling high-frequency events, such as user input
+ * in a search box, resizing a window, or any other event that fires rapidly.
+ * By debouncing, you can ensure that expensive operations (like API calls or heavy
+ * computations) are only executed once the events have settled.
+ *
+ * @template T The type of the signal's value.
+ *
+ * @param {IReadonlySignal<T>} sourceSignal The original signal to debounce.
+ * It can be a `StateSignal`, `ComputedSignal`, or any signal implementing `IReadonlySignal`.
+ * @param {DebounceSignalConfig} config Configuration object for the debouncer,
+ * including `delay`, `leading`, and `trailing` options from `@alwatr/debounce`.
+ *
+ * @returns {IComputedSignal<T>} A new, read-only computed signal that emits debounced values.
+ * Crucially, you **must** call `.destroy()` on this signal when it's no longer
+ * needed to prevent memory leaks by cleaning up internal subscriptions and timers.
+ *
+ * @example
+ * ```typescript
+ * // Create a source signal for user input.
+ * const searchInput = createStateSignal({
+ *   name: 'search-input',
+ *   initialValue: '',
+ * });
+ *
+ * // Create a debounced signal that waits 300ms after the user stops typing.
+ * const debouncedSearch = createDebouncedSignal(searchInput, { delay: 300 });
+ *
+ * // Use an effect to react to the debounced value.
+ * createEffect({
+ *   deps: [debouncedSearch],
+ *   run: () => {
+ *     if (debouncedSearch.get()) {
+ *       console.log(`🚀 Sending API request for: "${debouncedSearch.get()}"`);
+ *     }
+ *   },
+ * });
+ *
+ * searchInput.set('Alwatr');
+ * searchInput.set('Alwatr Signal');
+ * // (after 300ms of inactivity)
+ * // Logs: "🚀 Sending API request for: "Alwatr Signal""
+ *
+ * // IMPORTANT: Clean up when the component unmounts.
+ * // debouncedSearch.destroy();
+ * ```
+ */
+export function createDebouncedSignal<T>(sourceSignal: IReadonlySignal<T>, config: DebounceSignalConfig): ComputedSignal<T> {
+  const name = config.name ?? `${sourceSignal.name}-debounced`;
+
+  const internalSignal = new StateSignal<T>({
+    name: `${name}-internal`,
+    initialValue: sourceSignal.get(),
+  });
+
+  const debouncer = createDebouncer({
+    ...config,
+    thisContext: internalSignal,
+    func: internalSignal.set,
+  });
+
+  const subscription = sourceSignal.subscribe(debouncer.trigger, {receivePrevious: false});
+
+  return createComputedSignal({
+    name: name,
+    deps: [internalSignal],
+    get: () => internalSignal.get(),
+    onDestroy: () => {
+      if (internalSignal.isDestroyed) return;
+      subscription.unsubscribe();
+      debouncer.cancel();
+      internalSignal.destroy();
+      config.onDestroy?.();
+      config = null as unknown as DebounceSignalConfig;
+    },
+  });
+}

package/src/operators/filter.ts

@@ -0,0 +1,78 @@
+import {createComputedSignal} from '../creators/computed.js';
+import {createStateSignal} from '../creators/state.js';
+
+import type {ComputedSignal} from '../core/computed-signal.js';
+import type {IReadonlySignal} from '../type.js';
+
+/**
+ * Creates a new computed signal that only emits values from a source signal
+ * that satisfy a predicate function.
+ *
+ * This operator is analogous to `Array.prototype.filter`. It is particularly
+ * useful for creating effects or other computed signals that should only react
+ * to a specific subset of state changes.
+ *
+ * Note: The resulting signal's value will be `undefined` until the source
+ * emits a value that passes the filter.
+ *
+ * @template T The type of the signal's value.
+ *
+ * @param sourceSignal The original signal to filter.
+ * @param predicate A function that returns `true` if the value should be passed.
+ * @param name An optional, unique identifier for the new signal for debugging. default: `${sourceSignal.name}-filtered`
+ *
+ * @returns A new computed signal that emits filtered values.
+ *
+ * @example
+ * const numberSignal = createStateSignal({ name: 'number', initialValue: 0 });
+ *
+ * const evenNumberSignal = createFilteredSignal(
+ * numberSignal,
+ * (num) => num % 2 === 0,
+ * );
+ *
+ * createEffect({
+ * deps: [evenNumberSignal],
+ * run: () => {
+ * // This effect only runs for even numbers.
+ * // The value can be `undefined` on the first run if initialValue is not even.
+ * if (evenNumberSignal.get() !== undefined) {
+ * console.log(`Even number detected: ${evenNumberSignal.get()}`);
+ * }
+ * },
+ * runImmediately: true,
+ * });
+ * // Logs: "Even number detected: 0"
+ *
+ * numberSignal.set(1); // Effect does not run
+ * numberSignal.set(2); // Logs: "Even number detected: 2"
+ */
+export function createFilteredSignal<T>(
+  sourceSignal: IReadonlySignal<T>,
+  predicate: (value: T) => boolean,
+  name = `${sourceSignal.name}-filtered`,
+): ComputedSignal<T | undefined> {
+  const sourceValue = sourceSignal.get();
+  const initialValue = predicate(sourceValue) ? sourceValue : undefined;
+
+  const internalSignal = createStateSignal({
+    name: `${name}-internal`,
+    initialValue,
+  });
+
+  const subscription = sourceSignal.subscribe((newValue) => {
+    if (predicate(newValue)) {
+      internalSignal.set(newValue);
+    }
+  });
+
+  return createComputedSignal({
+    name: name,
+    deps: [internalSignal],
+    get: () => internalSignal.get(),
+    onDestroy: () => {
+      subscription.unsubscribe();
+      internalSignal.destroy();
+    },
+  });
+}

package/src/operators/map.ts

@@ -0,0 +1,48 @@
+import {createComputedSignal} from '../creators/computed.js';
+
+import type {ComputedSignal} from '../core/computed-signal.js';
+import type {IReadonlySignal} from '../type.js';
+
+/**
+ * Creates a new read-only computed signal that transforms the value of a source
+ * signal using a projection function.
+ *
+ * This operator is analogous to `Array.prototype.map`. It applies a function to
+ * each value emitted by the source signal and emits the result.
+ *
+ * @template T The type of the source signal's value.
+ * @template R The type of the projected value.
+ *
+ * @param sourceSignal The original signal to transform.
+ * @param projectFunction A function to apply to each value from the source signal.
+ * @param [name] An optional, unique identifier for the new signal for debugging. default: `${sourceSignal.name}-mapped`
+ *
+ * @returns A new, read-only computed signal with the transformed values.
+ *
+ * @example
+ * const userSignal = createStateSignal({
+ *   name: 'user',
+ *   initialValue: { name: 'John', age: 30 },
+ * });
+ *
+ * const userNameSignal = createMappedSignal(
+ *   userSignal,
+ *   (user) => user.name,
+ * );
+ *
+ * console.log(userNameSignal.get()); // Outputs: "John"
+ * // in next macro-task ...
+ * userSignal.set({ name: 'Jane', age: 32 });
+ * console.log(userNameSignal.get()); // Outputs: "Jane"
+ */
+export function createMappedSignal<T, R>(
+  sourceSignal: IReadonlySignal<T>,
+  projectFunction: (value: T) => R,
+  name = `${sourceSignal.name}-mapped`,
+): ComputedSignal<R> {
+  return createComputedSignal({
+    name: name,
+    deps: [sourceSignal],
+    get: () => projectFunction(sourceSignal.get()),
+  });
+}

package/src/type.ts

@@ -0,0 +1,357 @@
+import type {DebouncerConfig} from '@alwatr/debounce';
+import type {LocalStorageProviderConfig} from '@alwatr/local-storage';
+
+/**
+ * @package @alwatr/signal
+ *
+ * The callback function signature for a signal listener. It's a function that receives a value of type `T`
+ * and returns `void` or `Promise<void>`.
+ *
+ * @template T The type of the value that the signal holds or dispatches.
+ */
+export type ListenerCallback<T> = (value: T) => Awaitable<void>;
+
+/**
+ * Options for fine-tuning the behavior of a subscription to a signal.
+ */
+export interface SubscribeOptions {
+  /**
+   * If `true`, the listener will be called only once and then automatically unsubscribed.
+   * This is useful for scenarios where you only need to react to the next change.
+   *
+   * @default false
+   *
+   * @example
+   * // The listener will be removed after the first click.
+   * onUserClick.subscribe(() => console.log('User clicked!'), { once: true });
+   */
+  once?: boolean;
+
+  /**
+   * If `true`, the listener will be placed at the beginning of the notification queue and will be called before
+   * other, non-priority listeners.
+   *
+   * @default false
+   *
+   * @example
+   * // This listener will run before the others.
+   * mySignal.subscribe(() => console.log('High-priority action'), { priority: true });
+   */
+  priority?: boolean;
+
+  /**
+   * **For `StateSignal` only.** If `true` (the default), the listener will be called immediately with the
+   * signal's current value upon subscription. Set to `false` if you only want to be notified of *future* changes.
+   *
+   * @default true
+   *
+   * @example
+   * const counter = new StateSignal({initialValue: 10});
+   *
+   * // This will log "Current value: 10" immediately.
+   * counter.subscribe(value => console.log(`Current value: ${value}`));
+   *
+   * // This will *not* log immediately, only when the counter is next updated.
+   * counter.subscribe(value => console.log(`New value: ${value}`), { receivePrevious: false });
+   */
+  receivePrevious?: boolean;
+}
+
+/**
+ * The object returned from a `subscribe` call, which contains the `unsubscribe` method.
+ * This allows for easy removal of the subscription when it's no longer needed.
+ */
+export interface SubscribeResult {
+  /**
+   * A function that, when called, removes the listener from the signal, preventing future notifications.
+   * It's crucial to call this to avoid memory leaks when a component or listener is destroyed.
+   *
+   * @example
+   * const subscription = mySignal.subscribe(value => console.log(value));
+   * // ... later ...
+   * subscription.unsubscribe(); // The listener is now removed.
+   */
+  unsubscribe: () => void;
+}
+
+/**
+ * Internal representation of an observer, containing the listener's callback and its subscription options.
+ * @internal
+ */
+export interface Observer_<T> {
+  /**
+   * The listener's callback function.
+   */
+  callback: ListenerCallback<T>;
+
+  /**
+   * Subscription options for the observer.
+   */
+  options?: SubscribeOptions;
+}
+
+/**
+ * Basic configuration for creating any signal.
+ */
+export interface SignalConfig {
+  /**
+   * A unique identifier for the signal. This is crucial for debugging, logging, and differentiating signals,
+   * especially in large applications.
+   *
+   * @example
+   * 'user-profile-signal'
+   * 'app-theme-signal'
+   */
+  name: string;
+
+  /**
+   * An optional callback function that will be executed when the signal's `destroy` method is called.
+   * This is useful for cleaning up additional resources used by the signal,
+   * such as subscriptions or timers created in operators.
+   */
+  onDestroy?: () => void;
+}
+
+/**
+ * Configuration specifically for creating a `StateSignal`.
+ * @template T The type of the state held by the signal.
+ */
+export interface StateSignalConfig<T> extends SignalConfig {
+  /**
+   * The initial value of the `StateSignal`. A `StateSignal` must always have a value.
+   */
+  readonly initialValue: T;
+}
+
+/**
+ * Represents a signal that can be read from but not written to.
+ * Both `StateSignal` and `ComputedSignal` implement this interface, allowing them to be used
+ * as dependencies in other signals without exposing their `set` or `dispatch` methods.
+ *
+ * @template T The type of the signal's value.
+ */
+export interface IReadonlySignal<T> {
+  /**
+   * The unique identifier for this signal instance. Useful for debugging.
+   */
+  readonly name: string;
+
+  /**
+   * The current value of the signal.
+   */
+  get: () => T;
+
+  /**
+   * 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.
+   */
+  readonly isDestroyed: boolean;
+
+  /**
+   * Subscribes a listener to this signal.
+   *
+   * @param callback The function to be called when the signal's value changes.
+   * @param options Optional settings for the subscription.
+   * @returns An object with an `unsubscribe` method for cleanup.
+   */
+  subscribe(callback: ListenerCallback<T>, options?: SubscribeOptions): SubscribeResult;
+
+  /**
+   * 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);
+   * }
+   */
+  untilNext(): Promise<T>;
+
+  /**
+   * 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.
+   */
+  destroy(): void;
+}
+
+/**
+ * A list of `IReadonlySignal` instances that a computed or effect signal depends on.
+ * This ensures that dependencies can be read from but not modified by the dependent signal.
+ */
+export type DependencyList = readonly IReadonlySignal<unknown>[];
+
+/**
+ * Configuration for creating a `ComputedSignal`.
+ * @template T The type of the value computed by the signal.
+ */
+export interface ComputedSignalConfig<T> extends SignalConfig {
+  /**
+   * An array of dependency signals (`StateSignal` or other `ComputedSignal` instances).
+   * The `ComputedSignal` will automatically re-evaluate its value whenever any of these dependencies change.
+   */
+  deps: DependencyList;
+
+  /**
+   * The function that computes the signal's value.
+   * It is executed once initially and then again whenever a dependency changes.
+   * This function should be pure and not have side effects.
+   *
+   * @example
+   * // A computed signal that derives a boolean from a number.
+   * const counter = new StateSignal({initialValue: 0});
+   * const isEven = new ComputedSignal({
+   *   deps: [counter],
+   *   get: () => counter.get() % 2 === 0,
+   * });
+   */
+  get: () => T;
+}
+
+/**
+ * Configuration for creating an `EffectSignal`.
+ */
+export interface EffectSignalConfig {
+  /**
+   * A unique identifier for the signal. This is crucial for debugging, logging, and differentiating signals,
+   * especially in large applications.
+   * @default auto-generated based on dependencies
+   *
+   * @example
+   * 'user-profile-signal'
+   * 'app-theme-signal'
+   */
+  name?: string;
+
+  /**
+   * An array of dependency signals (`StateSignal` or `ComputedSignal` instances).
+   * The effect's `run` function will be executed whenever any of these signals change.
+   */
+  readonly deps: DependencyList;
+
+  /**
+   * The function to execute as the side-effect (e.g., logging, DOM updates, network requests).
+   * It can be synchronous or asynchronous.
+   *
+   * @example
+   * // An effect that logs the counter's value to the console.
+   * const counter = new StateSignal({initialValue: 0});
+   * new EffectSignal({
+   *   deps: [counter],
+   *   run: () => console.log(`The counter is now: ${counter.get()}`),
+   * });
+   */
+  run: () => Awaitable<void>;
+
+  /**
+   * If `true`, the effect's `run` function will be executed once immediately upon initialization.
+   * @default false
+   */
+  runImmediately?: boolean;
+
+  /**
+   * An optional callback function that will be executed when the signal's `destroy` method is called.
+   * This is useful for cleaning up additional resources used by the signal,
+   * such as subscriptions or timers created in operators.
+   */
+  onDestroy?: () => void;
+}
+
+/**
+ * The public interface for an `EffectSignal`, which provides a `destroy` method for cleanup.
+ */
+export interface IEffectSignal {
+  /**
+   * The unique identifier for this signal instance.
+   */
+  name: string;
+
+  /**
+   * Permanently disposes of the effect, unsubscribing from all dependencies
+   * and stopping any future executions. This is crucial for preventing memory leaks
+   * and unwanted side effects from running.
+   */
+  destroy: () => void;
+
+  /**
+   * 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.
+   */
+  readonly isDestroyed: boolean;
+}
+
+/**
+ * Configuration for creating a debounced signal using `createDebouncedSignal`.
+ *
+ * @see {@link createDebouncedSignal}
+ * @see {@link DebouncerConfig}
+ */
+export interface DebounceSignalConfig extends Omit<DebouncerConfig<never>, 'func' | 'thisContext'> {
+  /**
+   * A unique identifier for the signal. This is crucial for debugging and differentiating signals.
+   * @default `${sourceSignal.name}-debounced`
+   */
+  name?: string;
+
+  /**
+   * An optional callback executed when the signal's `destroy` method is called.
+   * Useful for cleaning up resources tied to the debounced signal.
+   */
+  onDestroy?: () => void;
+}
+
+/**
+ * Configuration for a persistent state signal.
+ * It combines the core signal configuration with the necessary options for local storage persistence.
+ *
+ * @template T The type of the state it holds.
+ */
+export interface PersistentStateSignalConfig<T extends JsonValue> extends StateSignalConfig<T>, LocalStorageProviderConfig {
+  /**
+   * The key under which to store the signal's state in localStorage.
+   * @default `signal-name`
+   */
+  storageKey?: string;
+
+  /**
+   * The debounce delay (in milliseconds) for saving changes to localStorage.
+   * This helps to reduce the frequency of write operations, which can be costly in terms of performance.
+   * @default 500
+   */
+  saveDebounceDelay?: number;
+}
+
+/**
+ * Configuration for a session state signal.
+ * The state is persisted in `sessionStorage` and cleared when the tab closes.
+ *
+ * @template T The type of the state it holds.
+ */
+export interface SessionStateSignalConfig<T extends JsonValue> extends StateSignalConfig<T> {
+  /**
+   * The key used to store data in `sessionStorage`.
+   * Defaults to the signal's `name` if not provided.
+   *
+   * @default `name`
+   *
+   * @example
+   * 'checkout-wizard-state'
+   */
+  storageKey?: string;
+
+  /**
+   * The debounce delay in milliseconds for writing changes to `sessionStorage`.
+   * A lower value than `PersistentStateSignal` is used because session writes are less costly.
+   *
+   * @default 500
+   */
+  saveDebounceDelay?: number;
+}