@alwatr/signal 9.26.0 → 9.29.0

package/src/core/signal-base.ts

@@ -2,40 +2,55 @@ import type {Observer_, SubscribeOptions, SubscribeResult, ListenerCallback, Sig
 import type {AlwatrLogger} from '@alwatr/logger';
 
 /**
- * An abstract base class for signal implementations.
- * It provides the core functionality for managing subscriptions (observers).
+ * An abstract base class for all signal implementations in the `@alwatr/signal` package.
  *
- * @template T The type of data that the signal holds or dispatches.
+ * It provides core subscription management capabilities, including priority observer queues,
+ * microtask/macrotask-friendly updates, type-safe unsubscribes, async promise resolution via `untilNext`,
+ * and safe destruction lifecycles to prevent memory leaks.
+ *
+ * @template T The type of data that the signal holds, dispatches, or streams.
  */
 export abstract class SignalBase<T> {
   /**
    * The unique identifier for this signal instance.
-   * Useful for debugging and logging.
+   * Highly useful for debugging, filtering logs, and tracing data flows.
    */
   public readonly name: string;
 
   /**
    * The logger instance for this signal.
+   * Custom scoped logger based on the signal name and type.
+   *
    * @protected
    */
   protected abstract logger_: AlwatrLogger;
 
   /**
-   * The list of observers (listeners) subscribed to this signal.
+   * High-priority observers that are executed first during notifications.
+   * Allocated lazily upon the first priority subscription to guard heap memory.
+   *
+   * @protected
+   */
+  protected priorityObservers_?: Set<Observer_<T>>;
+
+  /**
+   * Standard-priority observers executed after priority observers.
+   * Allocated lazily upon the first standard subscription to guard heap memory.
+   *
    * @protected
    */
-  protected readonly priorityObservers_ = new Set<Observer_<T>>();
-  protected readonly observers_ = new Set<Observer_<T>>();
+  protected observers_?: Set<Observer_<T>>;
 
   /**
-   * A flag indicating whether the signal has been destroyed.
+   * Internal flag representing 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.
+   * A destroyed signal cannot be subscribed to or dispatched to.
    *
    * @returns `true` if the signal is destroyed, `false` otherwise.
    */
@@ -43,14 +58,19 @@ export abstract class SignalBase<T> {
     return this.isDestroyed__;
   }
 
+  /**
+   * Creates a new instance of the signal base.
+   *
+   * @param config_ Configuration options including the unique signal name and cleanup hooks.
+   */
   constructor(protected config_: SignalConfig) {
     this.name = config_.name;
   }
 
   /**
-   * Removes a specific observer from the observers list.
+   * Removes a specific observer from both the standard and priority observer queues.
    *
-   * @param observer The observer instance to remove.
+   * @param observer The observer wrapper object containing the callback and options to remove.
    * @protected
    */
   protected removeObserver_(observer: Observer_<T>): void {
@@ -61,18 +81,27 @@ export abstract class SignalBase<T> {
       return;
     }
 
-    this.priorityObservers_.delete(observer);
-    this.observers_.delete(observer);
+    if (observer.options?.priority) {
+      this.priorityObservers_?.delete(observer);
+      if (this.priorityObservers_?.size === 0) {
+        this.priorityObservers_ = undefined;
+      }
+    } else {
+      this.observers_?.delete(observer);
+      if (this.observers_?.size === 0) {
+        this.observers_ = undefined;
+      }
+    }
   }
 
   /**
    * 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).
+   * The listener will be called whenever the signal notifies its observers.
    *
-   * @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.
+   * @param callback The function to invoke when the signal dispatches a new value.
+   * @param options Custom options to control priority, immediate callback, or single execution.
+   * @returns An object with an `unsubscribe` method to remove the subscription.
    */
   public subscribe(callback: ListenerCallback<T>, options?: SubscribeOptions): SubscribeResult {
     this.logger_.logMethodArgs?.('subscribe.base', options);
@@ -81,24 +110,24 @@ export abstract class SignalBase<T> {
     const observer: Observer_<T> = {callback, options};
 
     if (options?.priority) {
+      this.priorityObservers_ ??= new Set();
       this.priorityObservers_.add(observer);
     } else {
+      this.observers_ ??= new Set();
       this.observers_.add(observer);
     }
 
-    // The returned unsubscribe function is a closure that calls the internal removal method.
+    // Return an unsubscribe handler as a closure to prevent memory leaks.
     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).
+   * Notifies all registered priority and standard observers with the given value.
+   * Iterates synchronously over current queues.
    *
-   * @param value The new value to notify observers about.
+   * @param value The value to pass to each observer's callback.
    * @protected
    */
   protected notify_(value: T): void {
@@ -109,72 +138,78 @@ export abstract class SignalBase<T> {
       return;
     }
 
-    for (const observer of this.priorityObservers_) {
-      this.executeObserver__(observer, value);
+    // Execute priority observers first
+    if (this.priorityObservers_?.size) {
+      for (const observer of this.priorityObservers_) {
+        this.executeObserver__(observer, value);
+      }
     }
 
-    for (const observer of this.observers_) {
-      this.executeObserver__(observer, value);
+    // Execute standard observers second
+    if (this.observers_?.size) {
+      for (const observer of this.observers_) {
+        this.executeObserver__(observer, value);
+      }
     }
   }
 
   /**
-   * Executes a given observer's callback with the provided value, handling both synchronous and asynchronous callbacks.
+   * Executes a single observer's callback, handles auto-unsubscribing for `once` listeners,
+   * and wraps execution in a try-catch block to prevent observer exceptions from crashing the signal.
+   *
+   * @param observer The observer descriptor to execute.
+   * @param value The value to supply to the observer's callback.
+   * @private
    */
   private executeObserver__(observer: Observer_<T>, value: T): void {
     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}));
-      }
+      observer.callback(value);
     } catch (err) {
       this.logger_.error('notify_', 'sync_callback_failed', err);
     }
   }
 
-  private pendingRejects__ = new Set<(reason?: any) => void>();
-
   /**
-   * 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`.
+   * Holds the promise rejection functions of any pending `untilNext` invocations
+   * to reject them if the signal is destroyed.
    *
-   * @returns A Promise that resolves with the next dispatched value.
+   * @private
+   */
+  private pendingRejects__?: Set<(reason?: any) => void>;
+
+  /**
+   * Returns a Promise that resolves with the next value/payload dispatched by the signal.
+   * Use this for async orchestration (e.g. `await signal.untilNext()`).
    *
-   * @example
-   * async function onButtonClick() {
-   *   console.log('Waiting for the next signal...');
-   *   const nextValue = await mySignal.untilNext();
-   *   console.log('Signal received:', nextValue);
-   * }
+   * @returns A Promise that resolves with the next value dispatched by the signal.
    */
   public untilNext(): Promise<T> {
     this.logger_.logMethod?.('untilNext');
     this.checkDestroyed_();
     return new Promise((resolve, reject) => {
+      this.pendingRejects__ ??= new Set();
       this.pendingRejects__.add(reject);
       this.subscribe(
         (value) => {
-          this.pendingRejects__.delete(reject);
+          this.pendingRejects__?.delete(reject);
           resolve(value);
         },
         {
           once: true,
-          priority: true, // Resolve the promise before other listeners are called.
-          receivePrevious: false, // We only want the *next* value, not the current one.
+          priority: true, // Internal promise resolution is prioritized over normal observers.
+          receivePrevious: false, // Wait only for the next value change.
         },
       );
     });
   }
 
   /**
-   * 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.
+   * Permanently destroys the signal instance.
+   * Clears all observers, rejects pending `untilNext` promises with a 'signal_destroyed' error,
+   * invokes the optional `onDestroy` config hook, and breaks internal references to facilitate GC.
    */
   public destroy(): void {
     this.logger_.logMethod?.('destroy');
@@ -182,25 +217,27 @@ export abstract class SignalBase<T> {
       this.logger_.incident?.('destroy_', 'double_destroy_attempt');
       return;
     }
-    this.isDestroyed__ = true; // Mark the signal as destroyed.
-    // Reject all pending promises.
-    if (this.pendingRejects__.size) {
+    this.isDestroyed__ = true;
+
+    // Reject all pending promises to prevent hang-ups.
+    if (this.pendingRejects__?.size) {
       const error = new Error('signal_destroyed');
       for (const reject of this.pendingRejects__) {
         reject(error);
       }
-      this.pendingRejects__.clear(); // Clear all pending rejects.
+      this.pendingRejects__.clear();
     }
-    this.priorityObservers_.clear(); // Clear all priority observers.
-    this.observers_.clear(); // Clear all normal observers.
-    this.config_.onDestroy?.(); // Call the optional onDestroy callback.
-    this.config_ = null as unknown as SignalConfig; // Help GC by breaking references.
+    this.priorityObservers_?.clear();
+    this.observers_?.clear();
+    this.config_.onDestroy?.();
+    this.config_ = null as unknown as SignalConfig;
   }
 
   /**
-   * Throws an error if the signal has been destroyed.
-   * This is a safeguard to prevent interaction with a defunct signal.
+   * Checks if the signal has been destroyed. If so, throws an error and logs an accident.
+   *
    * @protected
+   * @throws {Error} If the signal has been destroyed.
    */
   protected checkDestroyed_(): void {
     if (this.isDestroyed__) {

package/src/core/state-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 {StateSignalConfig, ListenerCallback, SubscribeOptions, SubscribeResult, IReadonlySignal} from '../type.js';
 
 /**
@@ -41,34 +39,45 @@ import type {StateSignalConfig, ListenerCallback, SubscribeOptions, SubscribeRes
 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;
 
   /**
    * Indicates if a notification is already scheduled.
+   * Helps batch multiple synchronous `set` operations into a single microtask notification.
+   *
    * @private
    */
   private notifyPending__ = false;
 
   /**
-   * The version of the last notification.
+   * The version of the last notification. Incrementing on every state update.
+   * Used to guard immediate subscriber execution when updates happen within the same tick.
+   *
    * @private
    */
   private notifyVersion__ = 0;
 
+  /**
+   * Creates a new StateSignal instance.
+   *
+   * @param config Configuration options including name, initialValue, and custom cleanup hooks.
+   */
   constructor(config: StateSignalConfig<T>) {
     super({
       name: config.name,
       onDestroy: config.onDestroy,
     });
-    this.logger_ = createLogger(`state-signal:${this.name}`);
+    this.logger_ = createLogger(`state_signal:${this.name}`);
     this.value__ = config.initialValue;
     this.logger_.logMethodArgs?.('constructor', {initialValue: this.value__});
   }
@@ -77,6 +86,7 @@ export class StateSignal<T> extends SignalBase<T> implements IReadonlySignal<T>
    * Retrieves the current value of the signal.
    *
    * @returns The current value.
+   * @throws {Error} If the signal has been destroyed.
    *
    * @example
    * console.log(mySignal.get());
@@ -87,10 +97,11 @@ export class StateSignal<T> extends SignalBase<T> implements IReadonlySignal<T>
   }
 
   /**
-   * Updates the signal's value and notifies all active listeners.
+   * Updates the signal's value and schedules notifications for all active listeners.
    *
-   * The notification is scheduled as a microtask, which means the update is deferred
-   * slightly to batch multiple synchronous changes.
+   * Primitives are comparison-checked via `Object.is`. If unchanged, the update is ignored.
+   * The notification is scheduled as a microtask, allowing multiple synchronous updates
+   * to be batched and executed once.
    *
    * @param newValue The new value to set.
    *
@@ -115,9 +126,10 @@ export class StateSignal<T> extends SignalBase<T> implements IReadonlySignal<T>
   }
 
   /**
-   * Notifies all listeners about the current value, even if it hasn't changed.
+   * Forcefully schedules a notification of the current value to all subscribers.
    *
-   * This method is useful when you change the value instance directly (e.g., mutating an object) and want to inform listeners about the change.
+   * Useful when mutating properties within object states directly without assigning a new reference.
+   * Notification is queued as a microtask for batching.
    */
   public notifyChange(): void {
     this.logger_.logMethod?.('notifyChange');
@@ -128,7 +140,7 @@ export class StateSignal<T> extends SignalBase<T> implements IReadonlySignal<T>
     this.notifyPending__ = true;
 
     // Dispatch as a microtask to ensure consistent, non-blocking behavior.
-    delay.nextMicrotask().then(() => {
+    queueMicrotask(() => {
       this.notifyPending__ = false;
       this.notify_(this.value__);
     });
@@ -137,10 +149,9 @@ export class StateSignal<T> extends SignalBase<T> implements IReadonlySignal<T>
   /**
    * 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.
+   * A functional update pattern that retrieves the current value, computes the next, and sets it.
    *
-   * @param updater A function that receives the current value and returns the new value.
+   * @param updater A callback function that receives the current value and returns the new value.
    *
    * @example
    * // For a counter
@@ -157,13 +168,13 @@ export class StateSignal<T> extends SignalBase<T> implements IReadonlySignal<T>
   }
 
   /**
-   * Subscribes a listener to this signal.
+   * Subscribes a listener function to this state 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.
+   * This immediate call is queued as a microtask to match the asynchronous flow of signals.
    *
-   * @param callback The function to be called when the signal's value changes.
-   * @param options Subscription options, including `receivePrevious` and `once`.
+   * @param callback The function to invoke when the state changes.
+   * @param options Custom options, such as `receivePrevious: false` to only listen to future updates.
    * @returns An object with an `unsubscribe` method to remove the listener.
    */
   public override subscribe(callback: ListenerCallback<T>, options: SubscribeOptions = {}): SubscribeResult {
@@ -176,30 +187,38 @@ export class StateSignal<T> extends SignalBase<T> implements IReadonlySignal<T>
     if (this.notifyPending__) return result; // If a notification is already pending, the callback will be called with the latest value when the notification is processed.
 
     const subscribeVersion = this.notifyVersion__;
-    delay
-      .nextMicrotask()
-      .then((): void => {
-        this.logger_.logStep?.('subscribe', 'immediate_callback');
-        if (this.notifyVersion__ !== subscribeVersion) return; // A notification occurred after subscribing, so skip the immediate callback.
-        if (options.once) {
-          result.unsubscribe();
-        }
+
+    queueMicrotask((): void => {
+      this.logger_.logStep?.('subscribe', 'immediate_callback');
+      if (this.notifyVersion__ !== subscribeVersion) return; // A notification occurred after subscribing, so skip the immediate callback.
+      if (options.once) {
+        result.unsubscribe();
+      }
+      try {
         callback(this.value__);
-      })
-      .catch((err) => this.logger_.error('subscribe', 'immediate_callback_failed', err));
+      } catch (err) {
+        this.logger_.error('subscribe', 'immediate_callback_failed', err);
+      }
+    });
 
     return result;
   }
 
   /**
    * Destroys the signal, clearing its value and all listeners.
-   * This is crucial for memory management to prevent leaks.
+   * Breaks references for garbage collection.
    */
   public override destroy(): void {
     this.value__ = null as T; // Clear the value to allow for garbage collection.
     super.destroy();
   }
 
+  /**
+   * Returns this signal cast to the `IReadonlySignal<T>` interface.
+   * Limits access so external callers can only subscribe/read but not set/update state.
+   *
+   * @returns A readonly representation of this signal.
+   */
   public asReadonly(): IReadonlySignal<T> {
     return this;
   }

package/src/creators/channel.ts

@@ -1,6 +1,5 @@
 import {ChannelSignal} from '../core/channel-signal.js';
-
-import type {ChannelSignalConfig} from '../core/channel-signal.js';
+import type {ChannelSignalConfig} from '../type.js';
 
 /**
  * Creates a stateless multi-channel signal that acts as a typed message bus.

package/src/creators/derived.ts

@@ -0,0 +1,34 @@
+import {DerivedSignal} from '../core/derived-signal.js';
+
+import type {DerivedSignalConfig} from '../type.js';
+
+/**
+ * Creates a read-only signal mapping exactly 1-to-1 over a single upstream source.
+ *
+ * `createDerivedSignal` is a utility function to instantiate `DerivedSignal` without using the `new` keyword.
+ * A derived signal wraps a source signal and maps its value to a new representation using a projector function.
+ * It uses the "Cold Awakening Lifecycle" pattern, which avoids subscribing to the source signal until the derived
+ * signal has at least one subscriber of its own, saving processing cycles.
+ *
+ * @template S The type of the source signal's state.
+ * @template T The type of the projected derived state.
+ *
+ * @param config Configuration options including name, source, and projector.
+ * @returns A new, readonly derived signal.
+ *
+ * @example
+ * ```typescript
+ * const countSignal = createStateSignal({ name: 'count', initialValue: 5 });
+ *
+ * const isEvenSignal = createDerivedSignal({
+ *   name: 'is-even-signal',
+ *   source: countSignal,
+ *   projector: (count) => count % 2 === 0
+ * });
+ *
+ * console.log(isEvenSignal.get()); // false
+ * ```
+ */
+export function createDerivedSignal<S, T>(config: DerivedSignalConfig<S, T>): DerivedSignal<S, T> {
+  return new DerivedSignal(config);
+}

package/src/main.ts

@@ -2,6 +2,7 @@ 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/derived-signal.js';
 export * from './core/effect-signal.js';
 export * from './core/persistent-state-signal.js';
 export * from './core/session-state-signal.js';
@@ -10,6 +11,7 @@ export * from './core/channel-signal.js';
 export * from './creators/event.js';
 export * from './creators/state.js';
 export * from './creators/computed.js';
+export * from './creators/derived.js';
 export * from './creators/effect.js';
 export * from './creators/persistent-state.js';
 export * from './creators/session-state.js';
@@ -17,6 +19,5 @@ export * from './creators/channel.js';
 
 export * from './operators/debounce.js';
 export * from './operators/filter.js';
-export * from './operators/map.js';
 
 export type * from './type.js';

package/src/operators/debounce.ts

@@ -1,9 +1,5 @@
 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';
 
 /**
@@ -20,7 +16,7 @@ import type {IReadonlySignal, DebounceSignalConfig} from '../type.js';
  *
  * @template T The type of the signal's value.
  *
- * @param {IReadonlySignal<T>} sourceSignal The original signal to debounce.
+ * @param {IReadonlySignal<T>} source 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`.
@@ -59,12 +55,18 @@ import type {IReadonlySignal, DebounceSignalConfig} from '../type.js';
  * // debouncedSearch.destroy();
  * ```
  */
-export function createDebouncedSignal<T>(sourceSignal: IReadonlySignal<T>, config: DebounceSignalConfig): ComputedSignal<T> {
-  const name = config.name ?? `${sourceSignal.name}-debounced`;
+export function createDebouncedSignal<T>(source: IReadonlySignal<T>, config: DebounceSignalConfig): IReadonlySignal<T> {
+  const name = config.name ?? `${source.name}_debounced`;
 
   const internalSignal = new StateSignal<T>({
-    name: `${name}-internal`,
-    initialValue: sourceSignal.get(),
+    name,
+    initialValue: source.get(),
+    onDestroy() {
+      subscription.unsubscribe();
+      debouncer.cancel();
+      config.onDestroy?.();
+      config = null as unknown as DebounceSignalConfig;
+    },
   });
 
   const debouncer = createDebouncer({
@@ -73,19 +75,7 @@ export function createDebouncedSignal<T>(sourceSignal: IReadonlySignal<T>, confi
     func: internalSignal.set,
   });
 
-  const subscription = sourceSignal.subscribe(debouncer.trigger, {receivePrevious: false});
+  const subscription = source.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;
-    },
-  });
+  return internalSignal;
 }