@alwatr/signal 5.1.0 → 5.2.0

package/dist/main.mjs

@@ -1,11 +1,12 @@
-/* @alwatr/signal v5.1.0 */
+/* @alwatr/signal v5.2.0 */
 
 // src/core/signal-base.ts
 var SignalBase = class {
   constructor(config_) {
     this.config_ = config_;
     /**
-     * The unique identifier for this signal instance. Useful for debugging.
+     * The unique identifier for this signal instance.
+     * Useful for debugging and logging.
      */
     this.signalId = this.config_.signalId;
     /**
@@ -13,38 +14,33 @@ var SignalBase = class {
      * @protected
      */
     this.observers_ = [];
-    this.isDestroyed_ = false;
     /**
-     * Throws an error if the signal has been destroyed.
-     * This is a safeguard to prevent interaction with a defunct signal.
-     * @protected
+     * A flag indicating whether the signal has been destroyed.
+     * @private
      */
-    this.checkDestroyed_ = () => {
-      if (this.isDestroyed_) {
-        this.logger_.accident("checkDestroyed_", "attempt_to_use_destroyed_signal");
-        throw new Error(`Cannot interact with a destroyed signal (id: ${this.signalId})`);
-      }
-    };
+    this.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.
    */
   get isDestroyed() {
-    return this.isDestroyed_;
+    return this.isDestroyed__;
   }
   /**
    * Removes a specific observer from the observers list.
+   *
    * @param observer The observer instance to remove.
    * @protected
    */
   removeObserver_(observer) {
-    if (this.isDestroyed_) {
+    this.logger_.logMethod?.("removeObserver_");
+    if (this.isDestroyed__) {
       this.logger_.incident?.("removeObserver_", "remove_observer_on_destroyed_signal");
       return;
     }
-    this.logger_.logMethod?.("removeObserver_");
     const index = this.observers_.indexOf(observer);
     if (index !== -1) {
       this.observers_.splice(index, 1);
@@ -68,8 +64,9 @@ var SignalBase = class {
     } else {
       this.observers_.push(observer);
     }
-    const unsubscribe = () => this.removeObserver_(observer);
-    return { unsubscribe };
+    return {
+      unsubscribe: () => this.removeObserver_(observer)
+    };
   }
   /**
    * Notifies all registered observers about a new value.
@@ -81,11 +78,11 @@ var SignalBase = class {
    * @protected
    */
   notify_(value) {
-    if (this.isDestroyed_) {
+    this.logger_.logMethodArgs?.("notify_", value);
+    if (this.isDestroyed__) {
       this.logger_.incident?.("notify_", "notify_on_destroyed_signal");
       return;
     }
-    this.logger_.logMethodArgs?.("notify_", value);
     const currentObservers = [...this.observers_];
     for (const observer of currentObservers) {
       if (observer.options?.once) {
@@ -94,9 +91,7 @@ var SignalBase = class {
       try {
         const result = observer.callback(value);
         if (result instanceof Promise) {
-          result.catch((err) => {
-            this.logger_.error("notify_", "async_callback_failed", err, { observer });
-          });
+          result.catch((err) => this.logger_.error("notify_", "async_callback_failed", err, { observer }));
         }
       } catch (err) {
         this.logger_.error("notify_", "sync_callback_failed", err);
@@ -138,12 +133,26 @@ var SignalBase = class {
    */
   destroy() {
     this.logger_.logMethod?.("destroy");
-    if (this.isDestroyed_) return;
-    this.isDestroyed_ = true;
+    if (this.isDestroyed__) {
+      this.logger_.incident?.("destroy_", "double_destroy_attempt");
+      return;
+    }
+    this.isDestroyed__ = true;
     this.observers_.length = 0;
     this.config_.onDestroy?.();
     this.config_ = null;
   }
+  /**
+   * Throws an error if the signal has been destroyed.
+   * This is a safeguard to prevent interaction with a defunct signal.
+   * @protected
+   */
+  checkDestroyed_() {
+    if (this.isDestroyed__) {
+      this.logger_.accident("checkDestroyed_", "attempt_to_use_destroyed_signal");
+      throw new Error(`Cannot interact with a destroyed signal (id: ${this.signalId})`);
+    }
+  }
 };
 
 // src/core/event-signal.ts
@@ -152,6 +161,10 @@ import { createLogger } from "@alwatr/logger";
 var EventSignal = class extends SignalBase {
   constructor(config) {
     super(config);
+    /**
+     * The logger instance for this signal.
+     * @protected
+     */
     this.logger_ = createLogger(`event-signal: ${this.signalId}`);
     this.logger_.logMethod?.("constructor");
   }
@@ -163,11 +176,9 @@ var EventSignal = class extends SignalBase {
    * @param payload The data to send with the event.
    */
   dispatch(payload) {
-    this.logger_.logMethodArgs?.("dispatch", payload);
+    this.logger_.logMethodArgs?.("dispatch", { payload });
     this.checkDestroyed_();
-    delay.nextMicrotask().then(() => {
-      this.notify_(payload);
-    });
+    delay.nextMicrotask().then(() => this.notify_(payload));
   }
 };
 
@@ -177,6 +188,10 @@ import { createLogger as createLogger2 } from "@alwatr/logger";
 var StateSignal = class extends SignalBase {
   constructor(config) {
     super(config);
+    /**
+     * The logger instance for this signal.
+     * @protected
+     */
     this.logger_ = createLogger2(`state-signal: ${this.signalId}`);
     this.value__ = config.initialValue;
     this.logger_.logMethodArgs?.("constructor", { initialValue: this.value__ });
@@ -211,11 +226,11 @@ var StateSignal = class extends SignalBase {
   set(newValue) {
     this.logger_.logMethodArgs?.("set", { newValue });
     this.checkDestroyed_();
-    if (Object.is(this.value__, newValue) && (typeof newValue !== "object" || newValue === null)) return;
+    if (Object.is(this.value__, newValue) && (typeof newValue !== "object" || newValue === null)) {
+      return;
+    }
     this.value__ = newValue;
-    delay2.nextMicrotask().then(() => {
-      this.notify_(newValue);
-    });
+    delay2.nextMicrotask().then(() => this.notify_(newValue));
   }
   /**
    * Updates the signal's value based on its previous value.
@@ -250,11 +265,8 @@ var StateSignal = class extends SignalBase {
   subscribe(callback, options = {}) {
     this.logger_.logMethodArgs?.("subscribe", { options });
     this.checkDestroyed_();
-    const receivePrevious = options.receivePrevious !== false;
-    if (receivePrevious) {
-      delay2.nextMicrotask().then(() => callback(this.value__)).catch((err) => {
-        this.logger_.error("subscribe", "run_callback_immediate_failed", err);
-      });
+    if (options.receivePrevious !== false) {
+      delay2.nextMicrotask().then(() => callback(this.value__)).catch((err) => this.logger_.error("subscribe", "immediate_callback_failed", err));
       if (options.once) {
         return { unsubscribe: () => {
         } };
@@ -278,7 +290,14 @@ import { createLogger as createLogger3 } from "@alwatr/logger";
 var ComputedSignal = class {
   constructor(config_) {
     this.config_ = config_;
+    /**
+     * The unique identifier for this signal instance.
+     */
     this.signalId = this.config_.signalId;
+    /**
+     * The logger instance for this signal.
+     * @protected
+     */
     this.logger_ = createLogger3(`computed-signal: ${this.signalId}`);
     /**
      * The internal `StateSignal` that holds the computed value.
@@ -286,17 +305,23 @@ var ComputedSignal = class {
      * @protected
      */
     this.internalSignal_ = new StateSignal({
-      signalId: this.signalId + "-internal",
+      signalId: `${this.signalId}-internal`,
       initialValue: this.config_.get()
     });
-    this.subscriptionList__ = [];
+    /**
+     * A list of subscriptions to dependency signals.
+     * @private
+     */
+    this.dependencySubscriptions__ = [];
+    /**
+     * A flag to prevent concurrent recalculations.
+     * @private
+     */
     this.isRecalculating__ = false;
-    this.subscribe = this.internalSignal_.subscribe.bind(this.internalSignal_);
-    this.untilNext = this.internalSignal_.untilNext.bind(this.internalSignal_);
     this.logger_.logMethod?.("constructor");
     this.recalculate_ = this.recalculate_.bind(this);
     for (const signal of config_.deps) {
-      this.subscriptionList__.push(signal.subscribe(this.recalculate_, { receivePrevious: false }));
+      this.dependencySubscriptions__.push(signal.subscribe(this.recalculate_, { receivePrevious: false }));
     }
   }
   /**
@@ -317,6 +342,25 @@ var ComputedSignal = class {
   get isDestroyed() {
     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.
+   */
+  subscribe(callback, options) {
+    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.
+   */
+  untilNext() {
+    return this.internalSignal_.untilNext();
+  }
   /**
    * Permanently disposes of the computed signal.
    *
@@ -328,14 +372,14 @@ var ComputedSignal = class {
    */
   destroy() {
     this.logger_.logMethod?.("destroy");
-    if (this.internalSignal_.isDestroyed) {
+    if (this.isDestroyed) {
       this.logger_.incident?.("destroy", "already_destroyed");
       return;
     }
-    for (const subscription of this.subscriptionList__) {
+    for (const subscription of this.dependencySubscriptions__) {
       subscription.unsubscribe();
     }
-    this.subscriptionList__.length = 0;
+    this.dependencySubscriptions__.length = 0;
     this.internalSignal_.destroy();
     this.config_.onDestroy?.();
     this.config_ = null;
@@ -349,23 +393,24 @@ var ComputedSignal = class {
    * @protected
    */
   async recalculate_() {
+    this.logger_.logMethod?.("recalculate_");
     if (this.internalSignal_.isDestroyed) {
-      this.logger_.incident?.("recalculate", "recalculate_on_destroyed_signal");
+      this.logger_.incident?.("recalculate_", "recalculate_on_destroyed_signal");
       return;
     }
     if (this.isRecalculating__) {
-      this.logger_.logMethod?.("recalculate_//skipped");
+      this.logger_.logStep?.("recalculate_", "skipping_recalculation_already_scheduled");
       return;
     }
-    this.logger_.logMethod?.("recalculate_//scheduled");
     this.isRecalculating__ = true;
     try {
       await delay3.nextMacrotask();
-      if (this.internalSignal_.isDestroyed) {
-        this.logger_.incident?.("recalculate", "destroyed_during_delay");
+      if (this.isDestroyed) {
+        this.logger_.incident?.("recalculate_", "destroyed_during_delay");
+        this.isRecalculating__ = false;
         return;
       }
-      this.logger_.logMethod?.("recalculate_//executing");
+      this.logger_.logStep?.("recalculate_", "recalculating_value");
       this.internalSignal_.set(this.config_.get());
     } catch (err) {
       this.logger_.error("recalculate_", "recalculation_failed", err);
@@ -380,14 +425,34 @@ import { createLogger as createLogger4 } from "@alwatr/logger";
 var EffectSignal = class {
   constructor(config_) {
     this.config_ = config_;
-    this.logger_ = createLogger4(`effect-signal`);
-    this.subscriptionList__ = [];
+    /**
+     * The unique identifier for this signal instance.
+     */
+    this.signalId = this.config_.signalId ? this.config_.signalId : `[${this.config_.deps.map((dep) => dep.signalId).join(", ")}]`;
+    /**
+     * The logger instance for this signal.
+     * @protected
+     */
+    this.logger_ = createLogger4(`effect-signal: ${this.signalId}`);
+    /**
+     * A list of subscriptions to dependency signals.
+     * @private
+     */
+    this.dependencySubscriptions__ = [];
+    /**
+     * A flag to prevent concurrent executions of the effect.
+     * @private
+     */
     this.isRunning__ = false;
+    /**
+     * A flag indicating whether the effect has been destroyed.
+     * @private
+     */
     this.isDestroyed__ = false;
     this.logger_.logMethod?.("constructor");
     this.run_ = this.run_.bind(this);
     for (const signal of config_.deps) {
-      this.subscriptionList__.push(signal.subscribe(this.run_, { receivePrevious: false }));
+      this.dependencySubscriptions__.push(signal.subscribe(this.run_, { receivePrevious: false }));
     }
     if (config_.runImmediately === true) {
       void this.run_();
@@ -395,7 +460,8 @@ var EffectSignal = class {
   }
   /**
    * Indicates whether the effect signal has been destroyed.
-   * A destroyed signal cannot be used and will throw an error if interacted with.
+   * A destroyed signal will no longer execute its effect and cannot be reused.
+   *
    * @returns `true` if the signal is destroyed, `false` otherwise.
    */
   get isDestroyed() {
@@ -410,29 +476,29 @@ var EffectSignal = class {
    * @protected
    */
   async run_() {
+    this.logger_.logMethod?.("run_");
     if (this.isDestroyed__) {
       this.logger_.incident?.("run_", "run_on_destroyed_signal");
       return;
     }
     if (this.isRunning__) {
-      this.logger_.logMethod?.("run_//skipped");
+      this.logger_.logStep?.("run_", "skipped_because_already_running");
       return;
     }
-    this.logger_.logMethod?.("run_//scheduled");
     this.isRunning__ = true;
     try {
       await delay4.nextMacrotask();
       if (this.isDestroyed__) {
         this.logger_.incident?.("run_", "destroyed_during_delay");
+        this.isRunning__ = false;
         return;
       }
-      this.logger_.logMethod?.("run_//executing");
+      this.logger_.logStep?.("run_", "executing_effect");
       await this.config_.run();
     } catch (err) {
       this.logger_.error("run_", "effect_failed", err);
-    } finally {
-      this.isRunning__ = false;
     }
+    this.isRunning__ = false;
   }
   /**
    * Permanently disposes of the effect signal.
@@ -448,10 +514,10 @@ var EffectSignal = class {
       return;
     }
     this.isDestroyed__ = true;
-    for (const subscription of this.subscriptionList__) {
+    for (const subscription of this.dependencySubscriptions__) {
       subscription.unsubscribe();
     }
-    this.subscriptionList__.length = 0;
+    this.dependencySubscriptions__.length = 0;
     this.config_.onDestroy?.();
     this.config_ = null;
   }

package/dist/main.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/core/signal-base.ts", "../src/core/event-signal.ts", "../src/core/state-signal.ts", "../src/core/computed-signal.ts", "../src/core/effect-signal.ts", "../src/creators/event.ts", "../src/creators/state.ts", "../src/creators/computed.ts", "../src/creators/effect.ts", "../src/operators/debounce.ts"],
-  "sourcesContent": ["import type {Observer_, SubscribeOptions, SubscribeResult, ListenerCallback, SignalConfig} from '../type.js';\nimport type {AlwatrLogger} from '@alwatr/logger';\nimport type {} from '@alwatr/nano-build';\n\n/**\n * An abstract base class for signal implementations.\n *\n * `SignalBase` provides the core functionality for managing subscriptions (observers).\n * It handles adding, removing, and notifying listeners. The responsibility of *when* to notify\n * is left to the concrete subclasses (`StateSignal`, `EventSignal`, etc.).\n *\n * @template T The type of data the signal will handle.\n */\nexport abstract class SignalBase<T> {\n  /**\n   * The unique identifier for this signal instance. Useful for debugging.\n   */\n  public readonly signalId: string = this.config_.signalId;\n\n  protected abstract logger_: AlwatrLogger;\n\n  /**\n   * The list of observers (listeners) subscribed to this signal.\n   * @protected\n   */\n  protected readonly observers_: Observer_<T>[] = [];\n\n  protected isDestroyed_ = false;\n\n  /**\n   * Indicates whether the signal has been destroyed.\n   * A destroyed signal cannot be used and will throw an error if interacted with.\n   * @returns `true` if the signal is destroyed, `false` otherwise.\n   */\n  public get isDestroyed(): boolean {\n    return this.isDestroyed_;\n  }\n\n  public constructor(protected config_: SignalConfig) {}\n\n  /**\n   * Removes a specific observer from the observers list.\n   * @param observer The observer instance to remove.\n   * @protected\n   */\n  protected removeObserver_(observer: Observer_<T>): void {\n    if (this.isDestroyed_) {\n      this.logger_.incident?.('removeObserver_', 'remove_observer_on_destroyed_signal');\n      return;\n    }\n    this.logger_.logMethod?.('removeObserver_');\n    const index = this.observers_.indexOf(observer);\n    if (index !== -1) {\n      this.observers_.splice(index, 1);\n    }\n  }\n\n  /**\n   * Subscribes a listener function to this signal.\n   *\n   * The listener will be called whenever the signal is notified (e.g., when `dispatch` or `set` is called).\n   *\n   * @param callback The function to be called when the signal is dispatched.\n   * @param options Subscription options to customize the behavior (e.g., `once`, `priority`).\n   * @returns A `SubscribeResult` object with an `unsubscribe` method to remove the listener.\n   */\n  public subscribe(callback: ListenerCallback<T>, options?: SubscribeOptions): SubscribeResult {\n    this.logger_.logMethodArgs?.('subscribe.base', {options});\n    this.checkDestroyed_();\n\n    const observer: Observer_<T> = {callback, options};\n\n    if (options?.priority) {\n      // High-priority observers are added to the front of the queue.\n      this.observers_.unshift(observer);\n    }\n    else {\n      this.observers_.push(observer);\n    }\n\n    // The returned unsubscribe function is a closure that calls the internal removal method.\n    const unsubscribe = (): void => this.removeObserver_(observer);\n\n    return {unsubscribe};\n  }\n\n  /**\n   * Notifies all registered observers about a new value.\n   *\n   * This method iterates through a snapshot of the current observers to prevent issues\n   * with subscriptions changing during notification (e.g., an observer unsubscribing itself).\n   *\n   * @param value The new value to notify observers about.\n   * @protected\n   */\n  protected notify_(value: T): void {\n    if (this.isDestroyed_) {\n      this.logger_.incident?.('notify_', 'notify_on_destroyed_signal');\n      return;\n    }\n\n    this.logger_.logMethodArgs?.('notify_', value);\n\n    // Create a snapshot of the observers array to iterate over.\n    // This prevents issues if the observers_ array is modified during the loop.\n    const currentObservers = [...this.observers_];\n\n    for (const observer of currentObservers) {\n      if (observer.options?.once) {\n        this.removeObserver_(observer);\n      }\n\n      try {\n        // Fire the callback, but don't await it.\n        // If the callback returns a promise, it's up to the callback's author to handle it.\n        const result = observer.callback(value);\n        if (result instanceof Promise) {\n          // Log unhandled promise rejections from listeners.\n          result.catch((err) => {\n            this.logger_.error('notify_', 'async_callback_failed', err, {observer});\n          });\n        }\n      }\n      catch (err) {\n        this.logger_.error('notify_', 'sync_callback_failed', err);\n      }\n    }\n  }\n\n  /**\n   * Returns a Promise that resolves with the next value dispatched by the signal.\n   * This provides an elegant way to wait for a single, future event using `async/await`.\n   *\n   * @returns A Promise that resolves with the next dispatched value.\n   *\n   * @example\n   * async function onButtonClick() {\n   *   console.log('Waiting for the next signal...');\n   *   const nextValue = await mySignal.untilNext();\n   *   console.log('Signal received:', nextValue);\n   * }\n   */\n  public untilNext(): Promise<T> {\n    this.logger_.logMethod?.('untilNext');\n    this.checkDestroyed_();\n    return new Promise((resolve) => {\n      this.subscribe(resolve, {\n        once: true,\n        priority: true, // Resolve the promise before other listeners are called.\n        receivePrevious: false, // We only want the *next* value, not the current one.\n      });\n    });\n  }\n\n  /**\n   * Destroys the signal, clearing all its listeners and making it inactive.\n   *\n   * After destruction, any interaction with the signal (like `subscribe` or `untilNext`)\n   * will throw an error. This is crucial for preventing memory leaks by allowing\n   * garbage collection of the signal and its observers.\n   */\n  public destroy(): void {\n    this.logger_.logMethod?.('destroy');\n    if (this.isDestroyed_) return;\n    this.isDestroyed_ = true;\n    this.observers_.length = 0; // Clear all observers.\n    this.config_.onDestroy?.(); // Call the optional onDestroy callback.\n    this.config_ = null as unknown as SignalConfig; // Help GC by breaking references.\n  }\n\n  /**\n   * Throws an error if the signal has been destroyed.\n   * This is a safeguard to prevent interaction with a defunct signal.\n   * @protected\n   */\n  protected checkDestroyed_ = (): void => {\n    if (this.isDestroyed_) {\n      this.logger_.accident('checkDestroyed_', 'attempt_to_use_destroyed_signal');\n      throw new Error(`Cannot interact with a destroyed signal (id: ${this.signalId})`);\n    }\n  };\n}\n", "import {delay} from '@alwatr/delay';\nimport {createLogger} from '@alwatr/logger';\n\nimport {SignalBase} from './signal-base.js';\n\nimport type {SignalConfig} from '../type.js';\n\n/**\n * A stateless signal for dispatching transient events.\n *\n * `EventSignal` is ideal for broadcasting events that do not have a persistent state.\n * Unlike `StateSignal`, it does not hold a value. Listeners are only notified of new\n * events as they are dispatched. This makes it suitable for modeling user interactions,\n * system notifications, or any one-off message.\n *\n * @template T The type of the payload for the events. Defaults to `void` for events without a payload.\n *\n * @example\n * // Create a signal for user click events.\n * const onUserClick = new EventSignal<{ x: number, y: number }>({ signalId: 'on-user-click' });\n *\n * // Subscribe to the event.\n * onUserClick.subscribe(clickPosition => {\n *   console.log(`User clicked at: ${clickPosition.x}, ${clickPosition.y}`);\n * });\n *\n * // Dispatch an event.\n * onUserClick.dispatch({ x: 100, y: 250 }); // Notifies the listener.\n *\n * // --- Example with no payload ---\n * const onAppReady = new EventSignal({ signalId: 'on-app-ready' });\n * onAppReady.subscribe(() => console.log('Application is ready!'));\n * onAppReady.dispatch(); // Notifies the listener.\n */\nexport class EventSignal<T = void> extends SignalBase<T> {\n  protected logger_ = createLogger(`event-signal: ${this.signalId}`);\n\n  public constructor(config: SignalConfig) {\n    super(config);\n    this.logger_.logMethod?.('constructor');\n  }\n\n  /**\n   * Dispatches an event with an optional payload to all active listeners.\n   * The notification is scheduled as a microtask to prevent blocking and ensure\n   * a consistent, non-blocking flow.\n   *\n   * @param payload The data to send with the event.\n   */\n  public dispatch(payload: T): void {\n    this.logger_.logMethodArgs?.('dispatch', payload);\n    this.checkDestroyed_();\n    // Dispatch as a microtask to ensure consistent, non-blocking behavior.\n    delay.nextMicrotask().then(() => {\n      this.notify_(payload);\n    });\n  }\n}\n", "import {delay} from '@alwatr/delay';\nimport {createLogger} from '@alwatr/logger';\n\nimport {SignalBase} from './signal-base.js';\n\nimport type {StateSignalConfig, ListenerCallback, SubscribeOptions, SubscribeResult, IReadonlySignal} from '../type.js';\n\n/**\n * A stateful signal that holds a value and notifies listeners when the value changes.\n *\n * `StateSignal` is the core of the signal library, representing a piece of mutable state.\n * It always has a value, and new subscribers immediately receive the current value by default.\n *\n * @template T The type of the state it holds.\n * @implements {IReadonlySignal<T>}\n *\n * @example\n * // Create a new state signal with an initial value.\n * const counter = new StateSignal<number>({\n *   signalId: 'counter-signal',\n *   initialValue: 0,\n * });\n *\n * // Get the current value.\n * console.log(counter.value); // Outputs: 0\n *\n * // Subscribe to changes.\n * const subscription = counter.subscribe(newValue => {\n *   console.log(`Counter changed to: ${newValue}`);\n * });\n *\n * // Set a new value, which triggers the notification.\n * counter.set(1); // Outputs: \"Counter changed to: 1\"\n *\n * // Update value based on the previous value.\n * counter.update(current => current + 1); // Outputs: \"Counter changed to: 2\"\n *\n * // Unsubscribe when no longer needed.\n * subscription.unsubscribe();\n */\nexport class StateSignal<T> extends SignalBase<T> implements IReadonlySignal<T> {\n  private value__: T;\n  protected logger_ = createLogger(`state-signal: ${this.signalId}`);\n\n  public constructor(config: StateSignalConfig<T>) {\n    super(config);\n    this.value__ = config.initialValue;\n    this.logger_.logMethodArgs?.('constructor', {initialValue: this.value__});\n  }\n\n  /**\n   * Retrieves the current value of the signal.\n   *\n   * @returns The current value.\n   *\n   * @example\n   * console.log(mySignal.value);\n   */\n  public get value(): T {\n    this.checkDestroyed_();\n    return this.value__;\n  }\n\n  /**\n   * Updates the signal's value and notifies all active listeners.\n   *\n   * The notification is scheduled as a microtask, which means the update is deferred\n   * slightly to batch multiple synchronous changes.\n   *\n   * @param newValue The new value to set.\n   *\n   * @example\n   * // For primitive types\n   * mySignal.set(42);\n   *\n   * // For object types, it's best practice to set an immutable new object.\n   * mySignal.set({ ...mySignal.value, property: 'new-value' });\n   */\n  public set(newValue: T): void {\n    this.logger_.logMethodArgs?.('set', {newValue});\n    this.checkDestroyed_();\n\n    // For primitives (including null), do not notify if the value is the same.\n    if (Object.is(this.value__, newValue) && (typeof newValue !== 'object' || newValue === null)) return;\n\n    this.value__ = newValue;\n\n    // Dispatch as a microtask to ensure consistent, non-blocking behavior.\n    delay.nextMicrotask().then(() => {\n      this.notify_(newValue);\n    });\n  }\n\n  /**\n   * Updates the signal's value based on its previous value.\n   *\n   * This method is particularly useful for state transitions that depend on the current value,\n   * especially for objects or arrays, as it promotes an immutable update pattern.\n   *\n   * @param updater A function that receives the current value and returns the new value.\n   *\n   * @example\n   * // For a counter\n   * counterSignal.update(current => current + 1);\n   *\n   * // For an object state\n   * userSignal.update(currentUser => ({ ...currentUser, loggedIn: true }));\n   */\n  public update(updater: (previousValue: T) => T): void {\n    this.logger_.logMethod?.('update');\n    this.checkDestroyed_();\n    // The updater function is called with the current value to compute the new value,\n    // which is then passed to the `set` method.\n    this.set(updater(this.value__));\n  }\n\n  /**\n   * Subscribes a listener to this signal.\n   *\n   * By default, the listener is immediately called with the signal's current value (`receivePrevious: true`).\n   * This behavior can be customized via the `options` parameter.\n   *\n   * @param callback The function to be called when the signal's value changes.\n   * @param options Subscription options, including `receivePrevious` and `once`.\n   * @returns An object with an `unsubscribe` method to remove the listener.\n   */\n  public override subscribe(callback: ListenerCallback<T>, options: SubscribeOptions = {}): SubscribeResult {\n    this.logger_.logMethodArgs?.('subscribe', {options});\n    this.checkDestroyed_();\n\n    // By default, new subscribers to a StateSignal should receive the current value.\n    const receivePrevious = options.receivePrevious !== false;\n\n    if (receivePrevious) {\n      // Immediately (but asynchronously) call the listener with the current value.\n      // This is done in a microtask to ensure it happens after the subscription is fully registered.\n      delay\n        .nextMicrotask()\n        .then(() => callback(this.value__))\n        .catch((err) => {\n          this.logger_.error('subscribe', 'run_callback_immediate_failed', err);\n        });\n\n      // If it's a 'once' subscription that receives the previous value, it's now fulfilled.\n      // We don't need to add it to the observers list for future updates.\n      if (options.once) {\n        // eslint-disable-next-line @typescript-eslint/no-empty-function\n        return {unsubscribe: () => {}};\n      }\n    }\n\n    return super.subscribe(callback, options);\n  }\n\n  /**\n   * Destroys the signal, clearing its value and all listeners.\n   * This is crucial for memory management to prevent leaks.\n   */\n  public override destroy(): void {\n    // Clear the value to allow for garbage collection.\n    this.value__ = null as T;\n    super.destroy();\n  }\n}\n", "import {delay} from '@alwatr/delay';\nimport {createLogger} from '@alwatr/logger';\n\nimport {StateSignal} from './state-signal.js';\n\nimport type {ComputedSignalConfig, IReadonlySignal, SubscribeResult} from '../type.js';\n\n/**\n * A read-only signal that derives its value from a set of dependency signals.\n *\n * `ComputedSignal` is a powerful tool for creating values that reactively update when their underlying\n * data sources change. Its value is memoized, meaning the `get` function is only re-evaluated when\n * one of its dependencies has actually changed.\n *\n * A key feature is its lifecycle management: a `ComputedSignal` **must** be destroyed when no longer\n * needed to prevent memory leaks from its subscriptions to dependency signals.\n *\n * @template T The type of the computed value.\n * @implements {IComputedSignal<T>}\n *\n * @example\n * // --- Create dependency signals ---\n * const firstName = new StateSignal({ signalId: 'firstName', initialValue: 'John' });\n * const lastName = new StateSignal({ signalId: 'lastName', initialValue: 'Doe' });\n *\n * // --- Create a computed signal ---\n * const fullName = new ComputedSignal({\n *   signalId: 'fullName',\n *   deps: [firstName, lastName],\n *   get: () => `${firstName.value} ${lastName.value}`,\n * });\n *\n * console.log(fullName.value); // Outputs: \"John Doe\"\n *\n * // --- Subscribe to the computed value ---\n * fullName.subscribe(newFullName => {\n *   console.log(`Name changed to: ${newFullName}`);\n * });\n *\n * // --- Update a dependency ---\n * lastName.set('Smith'); // Recalculates and logs: \"Name changed to: John Smith\"\n * console.log(fullName.value); // Outputs: \"John Smith\"\n *\n * // --- IMPORTANT: Clean up when done ---\n * fullName.destroy();\n */\nexport class ComputedSignal<T> implements IReadonlySignal<T> {\n  public readonly signalId = this.config_.signalId;\n\n  protected readonly logger_ = createLogger(`computed-signal: ${this.signalId}`);\n\n  /**\n   * The internal `StateSignal` that holds the computed value.\n   * This is how the computed signal provides `.value` and `.subscribe()` methods.\n   * @protected\n   */\n  protected readonly internalSignal_ = new StateSignal<T>({\n    signalId: this.signalId + '-internal',\n    initialValue: this.config_.get(),\n  });\n\n  private readonly subscriptionList__: SubscribeResult[] = [];\n  private isRecalculating__ = false;\n\n  public constructor(protected config_: ComputedSignalConfig<T>) {\n    this.logger_.logMethod?.('constructor');\n    this.recalculate_ = this.recalculate_.bind(this);\n\n    // Subscribe to all dependencies to trigger recalculation on change.\n    for (const signal of config_.deps) {\n      this.subscriptionList__.push(signal.subscribe(this.recalculate_, {receivePrevious: false}));\n    }\n  }\n\n  /**\n   * The current value of the computed signal.\n   * Accessing this property returns the memoized value and does not trigger a recalculation.\n   *\n   * @returns The current computed value.\n   * @throws {Error} If accessed after the signal has been destroyed.\n   */\n  public get value(): T {\n    return this.internalSignal_.value;\n  }\n\n  /**\n   * Indicates whether the computed signal has been destroyed.\n   * A destroyed signal cannot be used and will throw an error if interacted with.\n   * @returns `true` if the signal is destroyed, `false` otherwise.\n   */\n  public get isDestroyed(): boolean {\n    return this.internalSignal_.isDestroyed;\n  }\n\n  public readonly subscribe = this.internalSignal_.subscribe.bind(this.internalSignal_);\n\n  public readonly untilNext = this.internalSignal_.untilNext.bind(this.internalSignal_);\n\n  /**\n   * Permanently disposes of the computed signal.\n   *\n   * This is a critical cleanup step. It unsubscribes from all dependency signals,\n   * stopping future recalculations and allowing the signal to be garbage collected.\n   * Failure to call `destroy()` will result in memory leaks.\n   *\n   * After `destroy()` is called, any attempt to access `.value` or `.subscribe()` will throw an error.\n   */\n  public destroy(): void {\n    this.logger_.logMethod?.('destroy');\n\n    if (this.internalSignal_.isDestroyed) {\n      this.logger_.incident?.('destroy', 'already_destroyed');\n      return;\n    }\n\n    // Unsubscribe from all upstream dependencies.\n    for (const subscription of this.subscriptionList__) {\n      subscription.unsubscribe();\n    }\n    this.subscriptionList__.length = 0; // Clear the array of subscriptions.\n\n    // Destroy the internal signal to clean up its resources and mark it as destroyed.\n    this.internalSignal_.destroy();\n\n    this.config_.onDestroy?.(); // Call the optional onDestroy callback.\n\n    this.config_ = null as unknown as ComputedSignalConfig<T>; // Release config closure.\n  }\n\n  /**\n   * Schedules a recalculation of the signal's value.\n   *\n   * This method batches updates using a macrotask (`delay.nextMacrotask`) to ensure the\n   * `get` function runs only once per event loop tick, even if multiple dependencies\n   * change in the same synchronous block of code.\n   * @protected\n   */\n  protected async recalculate_(): Promise<void> {\n    if (this.internalSignal_.isDestroyed) {\n      // This check is important in case a dependency fires after this signal is destroyed.\n      this.logger_.incident?.('recalculate', 'recalculate_on_destroyed_signal');\n      return;\n    }\n\n    if (this.isRecalculating__) {\n      // If a recalculation is already scheduled, do nothing.\n      this.logger_.logMethod?.('recalculate_//skipped');\n      return;\n    }\n\n    this.logger_.logMethod?.('recalculate_//scheduled');\n    this.isRecalculating__ = true;\n\n    try {\n      // Wait for the next macrotask to start the recalculation.\n      // This batches all synchronous dependency updates in the current event loop.\n      await delay.nextMacrotask();\n\n      if (this.internalSignal_.isDestroyed) {\n        this.logger_.incident?.('recalculate', 'destroyed_during_delay');\n        return;\n      }\n\n      this.logger_.logMethod?.('recalculate_//executing');\n      // Set the new value on the internal signal, which will notify our subscribers.\n      this.internalSignal_.set(this.config_.get());\n    }\n    catch (err) {\n      this.logger_.error('recalculate_', 'recalculation_failed', err);\n    }\n\n    // Allow the next recalculation to be scheduled.\n    this.isRecalculating__ = false;\n  }\n}\n", "import {delay} from '@alwatr/delay';\nimport {createLogger} from '@alwatr/logger';\n\nimport type {EffectSignalConfig, IEffectSignal, SubscribeResult} from '../type.js';\n\n/**\n * Manages a side-effect that runs in response to changes in dependency signals.\n *\n * `EffectSignal` is designed for running logic that interacts with the \"outside world\"—such as\n * logging, network requests, or DOM manipulation—whenever its dependencies are updated.\n * It encapsulates the subscription and cleanup logic, providing a robust and memory-safe\n * way to handle reactive side-effects.\n *\n * A key feature is its lifecycle management: an `EffectSignal` **must** be destroyed when no longer\n * needed to prevent memory leaks and stop the effect from running unnecessarily.\n *\n * @implements {IEffectSignal}\n *\n * @example\n * // --- Create dependency signals ---\n * const counter = new StateSignal({ initialValue: 0, signalId: 'counter' });\n * const user = new StateSignal({ initialValue: 'guest', signalId: 'user' });\n *\n * // --- Create an effect ---\n * const analyticsEffect = new EffectSignal({\n *   deps: [counter, user],\n *   run: () => {\n *     console.log(`Analytics: User '${user.value}' clicked ${counter.value} times.`);\n *   },\n *   runImmediately: true, // Optional: run once on creation\n * });\n * // Immediately logs: \"Analytics: User 'guest' clicked 0 times.\"\n *\n * // --- Trigger the effect by updating a dependency ---\n * counter.set(1);\n * // After a macrotask, logs: \"Analytics: User 'guest' clicked 1 times.\"\n *\n * // --- IMPORTANT: Clean up when the effect is no longer needed ---\n * analyticsEffect.destroy();\n *\n * // Further updates will not trigger the effect.\n * counter.set(2); // Nothing is logged.\n */\nexport class EffectSignal implements IEffectSignal {\n  protected readonly logger_ = createLogger(`effect-signal`);\n\n  private readonly subscriptionList__: SubscribeResult[] = [];\n  private isRunning__ = false;\n  private isDestroyed__ = false;\n\n  /**\n   * Indicates whether the effect signal has been destroyed.\n   * A destroyed signal cannot be used and will throw an error if interacted with.\n   * @returns `true` if the signal is destroyed, `false` otherwise.\n   */\n  public get isDestroyed(): boolean {\n    return this.isDestroyed__;\n  }\n\n  public constructor(protected config_: EffectSignalConfig) {\n    this.logger_.logMethod?.('constructor');\n    this.run_ = this.run_.bind(this);\n\n    // Subscribe to all dependencies. We don't need the previous value,\n    // as the `runImmediately` option controls the initial execution.\n    for (const signal of config_.deps) {\n      this.subscriptionList__.push(signal.subscribe(this.run_, {receivePrevious: false}));\n    }\n\n    // Run the effect immediately if requested.\n    if (config_.runImmediately === true) {\n      // We don't need to await this, let it run in the background.\n      void this.run_();\n    }\n  }\n\n  /**\n   * Schedules the execution of the effect's `run` function.\n   *\n   * This method batches updates using a macrotask (`delay.nextMacrotask`) to ensure the\n   * `run` function executes only once per event loop tick, even if multiple\n   * dependencies change simultaneously.\n   * @protected\n   */\n  protected async run_(): Promise<void> {\n    if (this.isDestroyed__) {\n      this.logger_.incident?.('run_', 'run_on_destroyed_signal');\n      return;\n    }\n    if (this.isRunning__) {\n      // If an execution is already scheduled, do nothing.\n      this.logger_.logMethod?.('run_//skipped');\n      return;\n    }\n\n    this.logger_.logMethod?.('run_//scheduled');\n    this.isRunning__ = true;\n\n    try {\n      // Wait for the next macrotask to batch simultaneous updates.\n      await delay.nextMacrotask();\n\n      if (this.isDestroyed__) {\n        this.logger_.incident?.('run_', 'destroyed_during_delay');\n        return;\n      }\n\n      this.logger_.logMethod?.('run_//executing');\n      await this.config_.run();\n    }\n    catch (err) {\n      this.logger_.error('run_', 'effect_failed', err);\n    }\n    finally {\n      // Reset the flag after the current execution is complete.\n      this.isRunning__ = false;\n    }\n  }\n\n  /**\n   * Permanently disposes of the effect signal.\n   *\n   * This is a critical cleanup step. It unsubscribes from all dependency signals,\n   * stopping any future executions of the effect and allowing it to be garbage collected.\n   * Failure to call `destroy()` will result in memory leaks and potentially unwanted side effects.\n   */\n  public destroy(): void {\n    this.logger_.logMethod?.('destroy');\n\n    if (this.isDestroyed__) {\n      this.logger_.incident?.('destroy', 'already_destroyed');\n      return;\n    }\n    this.isDestroyed__ = true;\n\n    // Unsubscribe from all upstream dependencies.\n    for (const subscription of this.subscriptionList__) {\n      subscription.unsubscribe();\n    }\n    this.subscriptionList__.length = 0; // Clear the array of subscriptions.\n\n    this.config_.onDestroy?.(); // Call the optional onDestroy callback.\n\n    this.config_ = null as unknown as EffectSignalConfig; // Release config closure.\n  }\n}\n", "import {EventSignal} from '../core/event-signal.js';\n\nimport type {SignalConfig} from '../type.js';\n\n/**\n * Creates a stateless signal for dispatching transient events.\n *\n * `EventSignal` is ideal for broadcasting events that do not have a persistent state.\n * Unlike `StateSignal`, it does not hold a value. Listeners are only notified of new\n * events as they are dispatched. This makes it suitable for modeling user interactions,\n * system notifications, or any one-off message.\n *\n * @template T The type of the payload for the events.\n *\n * @param config The configuration for the event signal.\n * @returns A new instance of EventSignal.\n *\n * @example\n * const onUserClick = createEventSignal<{ x: number, y: number }>({\n *   signalId: 'on-user-click'\n * });\n *\n * onUserClick.subscribe(pos => {\n *   console.log(`User clicked at: ${pos.x}, ${pos.y}`);\n * });\n *\n * onUserClick.dispatch({ x: 100, y: 250 });\n */\nexport function createEventSignal<T = void>(config: SignalConfig): EventSignal<T> {\n  return new EventSignal<T>(config);\n}\n", "import {StateSignal} from '../core/state-signal.js';\n\nimport type {StateSignalConfig} from '../type.js';\n\n/**\n * Creates a stateful signal that holds a value and notifies listeners when the value changes.\n *\n * `StateSignal` is the core of the signal library, representing a piece of mutable state.\n * It always has a value, and new subscribers immediately receive the current value by default.\n *\n * @template T The type of the state it holds.\n *\n * @param config The configuration for the state signal.\n * @returns A new instance of StateSignal.\n *\n * @example\n * const counter = createStateSignal({\n *   signalId: 'counter-signal',\n *   initialValue: 0,\n * });\n *\n * console.log(counter.value); // Outputs: 0\n * counter.set(1);\n * console.log(counter.value); // Outputs: 1\n */\nexport function createStateSignal<T>(config: StateSignalConfig<T>): StateSignal<T> {\n  return new StateSignal(config);\n}\n", "import {ComputedSignal} from '../core/computed-signal.js';\n\nimport type {ComputedSignalConfig} from '../type.js';\n\n/**\n * Creates a read-only signal that derives its value from a set of dependency signals.\n *\n * `ComputedSignal` is a powerful tool for creating values that reactively update when their underlying\n * data sources change. Its value is memoized, meaning the `get` function is only re-evaluated when\n * one of its dependencies has actually changed.\n *\n * A key feature is its lifecycle management: a `ComputedSignal` **must** be destroyed when no longer\n * needed to prevent memory leaks from its subscriptions to dependency signals.\n *\n * @template T The type of the computed value.\n *\n * @param config The configuration for the computed signal.\n * @returns A new, read-only computed signal.\n *\n * @example\n * const firstName = createStateSignal({ signalId: 'firstName', initialValue: 'John' });\n * const lastName = createStateSignal({ signalId: 'lastName', initialValue: 'Doe' });\n *\n * const fullName = createComputedSignal({\n *   signalId: 'fullName',\n *   deps: [firstName, lastName],\n *   get: () => `${firstName.value} ${lastName.value}`,\n * });\n *\n * console.log(fullName.value); // \"John Doe\"\n *\n * // IMPORTANT: Always destroy a computed signal when no longer needed.\n * // fullName.destroy();\n */\nexport function createComputedSignal<T>(config: ComputedSignalConfig<T>): ComputedSignal<T> {\n  return new ComputedSignal(config);\n}\n", "import {EffectSignal} from '../core/effect-signal.js';\n\nimport type {EffectSignalConfig} from '../type.js';\n\n/**\n * Creates a side-effect that runs in response to changes in dependency signals.\n *\n * `EffectSignal` is designed for running logic that interacts with the \"outside world\"—such as\n * logging, network requests, or DOM manipulation—whenever its dependencies are updated.\n * It encapsulates the subscription and cleanup logic, providing a robust and memory-safe\n * way to handle reactive side-effects.\n *\n * A key feature is its lifecycle management: an `EffectSignal` **must** be destroyed when no longer\n * needed to prevent memory leaks and stop the effect from running unnecessarily.\n *\n * @param config The configuration for the effect.\n * @returns An object with a `destroy` method to stop the effect.\n *\n * @example\n * // --- Create dependency signals ---\n * const counter = createStateSignal({ initialValue: 0, signalId: 'counter' });\n * const user = createStateSignal({ initialValue: 'guest', signalId: 'user' });\n *\n * // --- Create an effect ---\n * const analyticsEffect = createEffect({\n *   deps: [counter, user],\n *   run: () => {\n *     console.log(`Analytics: User '${user.value}' clicked ${counter.value} times.`);\n *   },\n *   runImmediately: true, // Optional: run once on creation\n * });\n * // Immediately logs: \"Analytics: User 'guest' clicked 0 times.\"\n *\n * // --- Trigger the effect by updating a dependency ---\n * counter.set(1);\n * // After a macrotask, logs: \"Analytics: User 'guest' clicked 1 times.\"\n *\n * // --- IMPORTANT: Clean up when the effect is no longer needed ---\n * analyticsEffect.destroy();\n *\n * // Further updates will not trigger the effect.\n * counter.set(2); // Nothing is logged.\n */\nexport function createEffect(config: EffectSignalConfig): EffectSignal {\n  return new EffectSignal(config);\n}\n", "import {createDebouncer} from '@alwatr/debounce';\n\nimport {StateSignal} from '../core/state-signal.js';\nimport {createComputedSignal} from '../creators/computed.js';\n\nimport type {ComputedSignal} from '../core/computed-signal.js';\nimport type {IReadonlySignal, DebounceSignalConfig} from '../type.js';\n\n/**\n * Creates a new computed signal that debounces updates from a source signal.\n *\n * The returned signal is a `ComputedSignal`, meaning it is read-only and its value is\n * derived from the source. It only updates its value after a specified period of\n * inactivity from the source signal.\n *\n * This operator is essential for handling high-frequency events, such as user input\n * in a search box, resizing a window, or any other event that fires rapidly.\n * By debouncing, you can ensure that expensive operations (like API calls or heavy\n * computations) are only executed once the events have settled.\n *\n * @template T The type of the signal's value.\n *\n * @param {IReadonlySignal<T>} sourceSignal The original signal to debounce.\n * It can be a `StateSignal`, `ComputedSignal`, or any signal implementing `IReadonlySignal`.\n * @param {DebounceSignalConfig} config Configuration object for the debouncer,\n * including `delay`, `leading`, and `trailing` options from `@alwatr/debounce`.\n *\n * @returns {IComputedSignal<T>} A new, read-only computed signal that emits debounced values.\n * Crucially, you **must** call `.destroy()` on this signal when it's no longer\n * needed to prevent memory leaks by cleaning up internal subscriptions and timers.\n *\n * @example\n * ```typescript\n * // Create a source signal for user input.\n * const searchInput = createStateSignal({\n *   signalId: 'search-input',\n *   initialValue: '',\n * });\n *\n * // Create a debounced signal that waits 300ms after the user stops typing.\n * const debouncedSearch = createDebouncedSignal(searchInput, { delay: 300 });\n *\n * // Use an effect to react to the debounced value.\n * createEffect({\n *   deps: [debouncedSearch],\n *   run: () => {\n *     if (debouncedSearch.value) {\n *       console.log(`🚀 Sending API request for: \"${debouncedSearch.value}\"`);\n *     }\n *   },\n * });\n *\n * searchInput.set('Alwatr');\n * searchInput.set('Alwatr Signal');\n * // (after 300ms of inactivity)\n * // Logs: \"🚀 Sending API request for: \"Alwatr Signal\"\"\n *\n * // IMPORTANT: Clean up when the component unmounts.\n * // debouncedSearch.destroy();\n * ```\n */\nexport function createDebouncedSignal<T>(sourceSignal: IReadonlySignal<T>, config: DebounceSignalConfig): ComputedSignal<T> {\n  const signalId = config.signalId ?? `${sourceSignal.signalId}-debounced`;\n\n  const internalSignal = new StateSignal<T>({\n    signalId: `${signalId}-internal`,\n    initialValue: sourceSignal.value,\n  });\n\n  const debouncer = createDebouncer({\n    ...config,\n    func: (value: T): void => {\n      internalSignal.set(value);\n    },\n  });\n\n  const subscription = sourceSignal.subscribe(debouncer.trigger);\n\n  return createComputedSignal({\n    signalId,\n    deps: [internalSignal],\n    get: () => internalSignal.value,\n    onDestroy: () => {\n      if (internalSignal.isDestroyed) return;\n      subscription.unsubscribe();\n      debouncer.cancel();\n      internalSignal.destroy();\n      config.onDestroy?.();\n      config = null as unknown as DebounceSignalConfig;\n    },\n  });\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import type {Observer_, SubscribeOptions, SubscribeResult, ListenerCallback, SignalConfig} from '../type.js';\nimport type {AlwatrLogger} from '@alwatr/logger';\nimport type {} from '@alwatr/nano-build';\n\n/**\n * An abstract base class for signal implementations.\n * It provides the core functionality for managing subscriptions (observers).\n *\n * @template T The type of data that the signal holds or dispatches.\n */\nexport abstract class SignalBase<T> {\n  /**\n   * The unique identifier for this signal instance.\n   * Useful for debugging and logging.\n   */\n  public readonly signalId = this.config_.signalId;\n\n  /**\n   * The logger instance for this signal.\n   * @protected\n   */\n  protected abstract logger_: AlwatrLogger;\n\n  /**\n   * The list of observers (listeners) subscribed to this signal.\n   * @protected\n   */\n  protected readonly observers_: Observer_<T>[] = [];\n\n  /**\n   * A flag indicating whether the signal has been destroyed.\n   * @private\n   */\n  private isDestroyed__ = false;\n\n  /**\n   * Indicates whether the signal has been destroyed.\n   * A destroyed signal cannot be used and will throw an error if interacted with.\n   *\n   * @returns `true` if the signal is destroyed, `false` otherwise.\n   */\n  public get isDestroyed(): boolean {\n    return this.isDestroyed__;\n  }\n\n  public constructor(protected config_: SignalConfig) {}\n\n  /**\n   * Removes a specific observer from the observers list.\n   *\n   * @param observer The observer instance to remove.\n   * @protected\n   */\n  protected removeObserver_(observer: Observer_<T>): void {\n    this.logger_.logMethod?.('removeObserver_');\n\n    if (this.isDestroyed__) {\n      this.logger_.incident?.('removeObserver_', 'remove_observer_on_destroyed_signal');\n      return;\n    }\n\n    const index = this.observers_.indexOf(observer);\n    if (index !== -1) {\n      this.observers_.splice(index, 1);\n    }\n  }\n\n  /**\n   * Subscribes a listener function to this signal.\n   *\n   * The listener will be called whenever the signal is notified (e.g., when `dispatch` or `set` is called).\n   *\n   * @param callback The function to be called when the signal is dispatched.\n   * @param options Subscription options to customize the behavior (e.g., `once`, `priority`).\n   * @returns A `SubscribeResult` object with an `unsubscribe` method to remove the listener.\n   */\n  public subscribe(callback: ListenerCallback<T>, options?: SubscribeOptions): SubscribeResult {\n    this.logger_.logMethodArgs?.('subscribe.base', {options});\n    this.checkDestroyed_();\n\n    const observer: Observer_<T> = {callback, options};\n\n    if (options?.priority) {\n      // High-priority observers are added to the front of the queue.\n      this.observers_.unshift(observer);\n    }\n    else {\n      this.observers_.push(observer);\n    }\n\n    // The returned unsubscribe function is a closure that calls the internal removal method.\n    return {\n      unsubscribe: (): void => this.removeObserver_(observer),\n    };\n  }\n\n  /**\n   * Notifies all registered observers about a new value.\n   *\n   * This method iterates through a snapshot of the current observers to prevent issues\n   * with subscriptions changing during notification (e.g., an observer unsubscribing itself).\n   *\n   * @param value The new value to notify observers about.\n   * @protected\n   */\n  protected notify_(value: T): void {\n    this.logger_.logMethodArgs?.('notify_', value);\n\n    if (this.isDestroyed__) {\n      this.logger_.incident?.('notify_', 'notify_on_destroyed_signal');\n      return;\n    }\n\n    // Create a snapshot of the observers array to iterate over.\n    // This prevents issues if the observers_ array is modified during the loop.\n    const currentObservers = [...this.observers_];\n\n    for (const observer of currentObservers) {\n      if (observer.options?.once) {\n        this.removeObserver_(observer);\n      }\n\n      try {\n        const result = observer.callback(value);\n        if (result instanceof Promise) {\n          result.catch((err) => this.logger_.error('notify_', 'async_callback_failed', err, {observer}));\n        }\n      }\n      catch (err) {\n        this.logger_.error('notify_', 'sync_callback_failed', err);\n      }\n    }\n  }\n\n  /**\n   * Returns a Promise that resolves with the next value dispatched by the signal.\n   * This provides an elegant way to wait for a single, future event using `async/await`.\n   *\n   * @returns A Promise that resolves with the next dispatched value.\n   *\n   * @example\n   * async function onButtonClick() {\n   *   console.log('Waiting for the next signal...');\n   *   const nextValue = await mySignal.untilNext();\n   *   console.log('Signal received:', nextValue);\n   * }\n   */\n  public untilNext(): Promise<T> {\n    this.logger_.logMethod?.('untilNext');\n    this.checkDestroyed_();\n    return new Promise((resolve) => {\n      this.subscribe(resolve, {\n        once: true,\n        priority: true, // Resolve the promise before other listeners are called.\n        receivePrevious: false, // We only want the *next* value, not the current one.\n      });\n    });\n  }\n\n  /**\n   * Destroys the signal, clearing all its listeners and making it inactive.\n   *\n   * After destruction, any interaction with the signal (like `subscribe` or `untilNext`)\n   * will throw an error. This is crucial for preventing memory leaks by allowing\n   * garbage collection of the signal and its observers.\n   */\n  public destroy(): void {\n    this.logger_.logMethod?.('destroy');\n    if (this.isDestroyed__) {\n      this.logger_.incident?.('destroy_', 'double_destroy_attempt');\n      return;\n    }\n    this.isDestroyed__ = true;\n    this.observers_.length = 0; // Clear all observers.\n    this.config_.onDestroy?.(); // Call the optional onDestroy callback.\n    this.config_ = null as unknown as SignalConfig; // Help GC by breaking references.\n  }\n\n  /**\n   * Throws an error if the signal has been destroyed.\n   * This is a safeguard to prevent interaction with a defunct signal.\n   * @protected\n   */\n  protected checkDestroyed_(): void {\n    if (this.isDestroyed__) {\n      this.logger_.accident('checkDestroyed_', 'attempt_to_use_destroyed_signal');\n      throw new Error(`Cannot interact with a destroyed signal (id: ${this.signalId})`);\n    }\n  }\n}\n", "import {delay} from '@alwatr/delay';\nimport {createLogger} from '@alwatr/logger';\n\nimport {SignalBase} from './signal-base.js';\n\nimport type {SignalConfig} from '../type.js';\n\n/**\n * A stateless signal for dispatching transient events.\n *\n * `EventSignal` is ideal for broadcasting events that do not have a persistent state.\n * Unlike `StateSignal`, it does not hold a value. Listeners are only notified of new\n * events as they are dispatched. This makes it suitable for modeling user interactions,\n * system notifications, or any one-off message.\n *\n * @template T The type of the payload for the events. Defaults to `void` for events without a payload.\n *\n * @example\n * // Create a signal for user click events.\n * const onUserClick = new EventSignal<{ x: number, y: number }>({ signalId: 'on-user-click' });\n *\n * // Subscribe to the event.\n * onUserClick.subscribe(clickPosition => {\n *   console.log(`User clicked at: ${clickPosition.x}, ${clickPosition.y}`);\n * });\n *\n * // Dispatch an event.\n * onUserClick.dispatch({ x: 100, y: 250 }); // Notifies the listener.\n *\n * // --- Example with no payload ---\n * const onAppReady = new EventSignal({ signalId: 'on-app-ready' });\n * onAppReady.subscribe(() => console.log('Application is ready!'));\n * onAppReady.dispatch(); // Notifies the listener.\n */\nexport class EventSignal<T = void> extends SignalBase<T> {\n  /**\n   * The logger instance for this signal.\n   * @protected\n   */\n  protected logger_ = createLogger(`event-signal: ${this.signalId}`);\n\n  public constructor(config: SignalConfig) {\n    super(config);\n    this.logger_.logMethod?.('constructor');\n  }\n\n  /**\n   * Dispatches an event with an optional payload to all active listeners.\n   * The notification is scheduled as a microtask to prevent blocking and ensure\n   * a consistent, non-blocking flow.\n   *\n   * @param payload The data to send with the event.\n   */\n  public dispatch(payload: T): void {\n    this.logger_.logMethodArgs?.('dispatch', {payload});\n    this.checkDestroyed_();\n    // Dispatch as a microtask to ensure consistent, non-blocking behavior.\n    delay.nextMicrotask().then(() => this.notify_(payload));\n  }\n}\n", "import {delay} from '@alwatr/delay';\nimport {createLogger} from '@alwatr/logger';\n\nimport {SignalBase} from './signal-base.js';\n\nimport type {StateSignalConfig, ListenerCallback, SubscribeOptions, SubscribeResult, IReadonlySignal} from '../type.js';\n\n/**\n * A stateful signal that holds a value and notifies listeners when the value changes.\n *\n * `StateSignal` is the core of the signal library, representing a piece of mutable state.\n * It always has a value, and new subscribers immediately receive the current value by default.\n *\n * @template T The type of the state it holds.\n * @implements {IReadonlySignal<T>}\n *\n * @example\n * // Create a new state signal with an initial value.\n * const counter = new StateSignal<number>({\n *   signalId: 'counter-signal',\n *   initialValue: 0,\n * });\n *\n * // Get the current value.\n * console.log(counter.value); // Outputs: 0\n *\n * // Subscribe to changes.\n * const subscription = counter.subscribe(newValue => {\n *   console.log(`Counter changed to: ${newValue}`);\n * });\n *\n * // Set a new value, which triggers the notification.\n * counter.set(1); // Outputs: \"Counter changed to: 1\"\n *\n * // Update value based on the previous value.\n * counter.update(current => current + 1); // Outputs: \"Counter changed to: 2\"\n *\n * // Unsubscribe when no longer needed.\n * subscription.unsubscribe();\n */\nexport class StateSignal<T> extends SignalBase<T> implements IReadonlySignal<T> {\n  /**\n   * The current value of the signal.\n   * @private\n   */\n  private value__: T;\n\n  /**\n   * The logger instance for this signal.\n   * @protected\n   */\n  protected logger_ = createLogger(`state-signal: ${this.signalId}`);\n\n  public constructor(config: StateSignalConfig<T>) {\n    super(config);\n    this.value__ = config.initialValue;\n    this.logger_.logMethodArgs?.('constructor', {initialValue: this.value__});\n  }\n\n  /**\n   * Retrieves the current value of the signal.\n   *\n   * @returns The current value.\n   *\n   * @example\n   * console.log(mySignal.value);\n   */\n  public get value(): T {\n    this.checkDestroyed_();\n    return this.value__;\n  }\n\n  /**\n   * Updates the signal's value and notifies all active listeners.\n   *\n   * The notification is scheduled as a microtask, which means the update is deferred\n   * slightly to batch multiple synchronous changes.\n   *\n   * @param newValue The new value to set.\n   *\n   * @example\n   * // For primitive types\n   * mySignal.set(42);\n   *\n   * // For object types, it's best practice to set an immutable new object.\n   * mySignal.set({ ...mySignal.value, property: 'new-value' });\n   */\n  public set(newValue: T): void {\n    this.logger_.logMethodArgs?.('set', {newValue});\n    this.checkDestroyed_();\n\n    // For primitives (including null), do not notify if the value is the same.\n    if (Object.is(this.value__, newValue) && (typeof newValue !== 'object' || newValue === null)) {\n      return;\n    }\n\n    this.value__ = newValue;\n\n    // Dispatch as a microtask to ensure consistent, non-blocking behavior.\n    delay.nextMicrotask().then(() => this.notify_(newValue));\n  }\n\n  /**\n   * Updates the signal's value based on its previous value.\n   *\n   * This method is particularly useful for state transitions that depend on the current value,\n   * especially for objects or arrays, as it promotes an immutable update pattern.\n   *\n   * @param updater A function that receives the current value and returns the new value.\n   *\n   * @example\n   * // For a counter\n   * counterSignal.update(current => current + 1);\n   *\n   * // For an object state\n   * userSignal.update(currentUser => ({ ...currentUser, loggedIn: true }));\n   */\n  public update(updater: (previousValue: T) => T): void {\n    this.logger_.logMethod?.('update');\n    this.checkDestroyed_();\n    // The updater function is called with the current value to compute the new value,\n    // which is then passed to the `set` method.\n    this.set(updater(this.value__));\n  }\n\n  /**\n   * Subscribes a listener to this signal.\n   *\n   * By default, the listener is immediately called with the signal's current value (`receivePrevious: true`).\n   * This behavior can be customized via the `options` parameter.\n   *\n   * @param callback The function to be called when the signal's value changes.\n   * @param options Subscription options, including `receivePrevious` and `once`.\n   * @returns An object with an `unsubscribe` method to remove the listener.\n   */\n  public override subscribe(callback: ListenerCallback<T>, options: SubscribeOptions = {}): SubscribeResult {\n    this.logger_.logMethodArgs?.('subscribe', {options});\n    this.checkDestroyed_();\n\n    // By default, new subscribers to a StateSignal should receive the current value.\n    if (options.receivePrevious !== false) {\n      // Immediately (but asynchronously) call the listener with the current value.\n      // This is done in a microtask to ensure it happens after the subscription is fully registered.\n      delay\n        .nextMicrotask()\n        .then(() => callback(this.value__))\n        .catch((err) => this.logger_.error('subscribe', 'immediate_callback_failed', err));\n\n      // If it's a 'once' subscription that receives the previous value, it's now fulfilled.\n      // We don't need to add it to the observers list for future updates.\n      if (options.once) {\n        // eslint-disable-next-line @typescript-eslint/no-empty-function\n        return {unsubscribe: () => {}};\n      }\n    }\n\n    return super.subscribe(callback, options);\n  }\n\n  /**\n   * Destroys the signal, clearing its value and all listeners.\n   * This is crucial for memory management to prevent leaks.\n   */\n  public override destroy(): void {\n    this.value__ = null as T; // Clear the value to allow for garbage collection.\n    super.destroy();\n  }\n}\n", "import {delay} from '@alwatr/delay';\nimport {createLogger} from '@alwatr/logger';\n\nimport {StateSignal} from './state-signal.js';\n\nimport type {ComputedSignalConfig, IReadonlySignal, SubscribeResult, SubscribeOptions} from '../type.js';\n\n/**\n * A read-only signal that derives its value from a set of dependency signals.\n *\n * `ComputedSignal` is a powerful tool for creating values that reactively update when their underlying\n * data sources change. Its value is memoized, meaning the `get` function is only re-evaluated when\n * one of its dependencies has actually changed.\n *\n * A key feature is its lifecycle management: a `ComputedSignal` **must** be destroyed when no longer\n * needed to prevent memory leaks from its subscriptions to dependency signals.\n *\n * @template T The type of the computed value.\n *\n * @example\n * // --- Create dependency signals ---\n * const firstName = new StateSignal({ signalId: 'firstName', initialValue: 'John' });\n * const lastName = new StateSignal({ signalId: 'lastName', initialValue: 'Doe' });\n *\n * // --- Create a computed signal ---\n * const fullName = new ComputedSignal({\n *   signalId: 'fullName',\n *   deps: [firstName, lastName],\n *   get: () => `${firstName.value} ${lastName.value}`,\n * });\n *\n * console.log(fullName.value); // Outputs: \"John Doe\"\n *\n * // --- Subscribe to the computed value ---\n * fullName.subscribe(newFullName => {\n *   console.log(`Name changed to: ${newFullName}`);\n * });\n *\n * // --- Update a dependency ---\n * lastName.set('Smith'); // Recalculates and logs: \"Name changed to: John Smith\"\n * console.log(fullName.value); // Outputs: \"John Smith\"\n *\n * // --- IMPORTANT: Clean up when done ---\n * fullName.destroy();\n */\nexport class ComputedSignal<T> implements IReadonlySignal<T> {\n  /**\n   * The unique identifier for this signal instance.\n   */\n  public readonly signalId = this.config_.signalId;\n\n  /**\n   * The logger instance for this signal.\n   * @protected\n   */\n  protected readonly logger_ = createLogger(`computed-signal: ${this.signalId}`);\n\n  /**\n   * The internal `StateSignal` that holds the computed value.\n   * This is how the computed signal provides `.value` and `.subscribe()` methods.\n   * @protected\n   */\n  protected readonly internalSignal_ = new StateSignal<T>({\n    signalId: `${this.signalId}-internal`,\n    initialValue: this.config_.get(),\n  });\n\n  /**\n   * A list of subscriptions to dependency signals.\n   * @private\n   */\n\n  private readonly dependencySubscriptions__: SubscribeResult[] = [];\n\n  /**\n   * A flag to prevent concurrent recalculations.\n   * @private\n   */\n  private isRecalculating__ = false;\n\n  public constructor(protected config_: ComputedSignalConfig<T>) {\n    this.logger_.logMethod?.('constructor');\n    this.recalculate_ = this.recalculate_.bind(this);\n\n    // Subscribe to all dependencies to trigger recalculation on change.\n    for (const signal of config_.deps) {\n      this.dependencySubscriptions__.push(signal.subscribe(this.recalculate_, {receivePrevious: false}));\n    }\n  }\n\n  /**\n   * The current value of the computed signal.\n   * Accessing this property returns the memoized value and does not trigger a recalculation.\n   *\n   * @returns The current computed value.\n   * @throws {Error} If accessed after the signal has been destroyed.\n   */\n  public get value(): T {\n    return this.internalSignal_.value;\n  }\n\n  /**\n   * Indicates whether the computed signal has been destroyed.\n   * A destroyed signal cannot be used and will throw an error if interacted with.\n   * @returns `true` if the signal is destroyed, `false` otherwise.\n   */\n  public get isDestroyed(): boolean {\n    return this.internalSignal_.isDestroyed;\n  }\n\n  /**\n   * Subscribes a listener to this signal.\n   * The listener will be called whenever the computed value changes.\n   *\n   * @param callback The function to be called with the new value.\n   * @param options Subscription options.\n   * @returns A `SubscribeResult` object with an `unsubscribe` method.\n   */\n  public subscribe(callback: (value: T) => void, options?: SubscribeOptions): SubscribeResult {\n    return this.internalSignal_.subscribe(callback, options);\n  }\n\n  /**\n   * Returns a Promise that resolves with the next computed value.\n   *\n   * @returns A Promise that resolves with the next value.\n   */\n  public untilNext(): Promise<T> {\n    return this.internalSignal_.untilNext();\n  }\n\n  /**\n   * Permanently disposes of the computed signal.\n   *\n   * This is a critical cleanup step. It unsubscribes from all dependency signals,\n   * stopping future recalculations and allowing the signal to be garbage collected.\n   * Failure to call `destroy()` will result in memory leaks.\n   *\n   * After `destroy()` is called, any attempt to access `.value` or `.subscribe()` will throw an error.\n   */\n  public destroy(): void {\n    this.logger_.logMethod?.('destroy');\n    /**\n     * If already destroyed, log an incident and return early.\n     */\n    if (this.isDestroyed) {\n      this.logger_.incident?.('destroy', 'already_destroyed');\n      return;\n    }\n\n    // Unsubscribe from all upstream dependencies.\n    for (const subscription of this.dependencySubscriptions__) {\n      subscription.unsubscribe();\n    }\n    this.dependencySubscriptions__.length = 0; // Clear the array of subscriptions.\n\n    this.internalSignal_.destroy(); // Destroy the internal signal.\n    this.config_.onDestroy?.(); // Call the optional onDestroy callback.\n    this.config_ = null as unknown as ComputedSignalConfig<T>; // Release config closure.\n  }\n\n  /**\n   * Schedules a recalculation of the signal's value.\n   *\n   * This method batches updates using a macrotask (`delay.nextMacrotask`) to ensure the\n   * `get` function runs only once per event loop tick, even if multiple dependencies\n   * change in the same synchronous block of code.\n   * @protected\n   */\n  protected async recalculate_(): Promise<void> {\n    this.logger_.logMethod?.('recalculate_');\n\n    if (this.internalSignal_.isDestroyed) {\n      // This check is important in case a dependency fires after this signal is destroyed.\n      this.logger_.incident?.('recalculate_', 'recalculate_on_destroyed_signal');\n      return;\n    }\n\n    if (this.isRecalculating__) {\n      // If a recalculation is already scheduled, do nothing.\n      this.logger_.logStep?.('recalculate_', 'skipping_recalculation_already_scheduled');\n      return;\n    }\n\n    this.isRecalculating__ = true;\n\n    try {\n      // Wait for the next macrotask to start the recalculation.\n      // This batches all synchronous dependency updates in the current event loop.\n      await delay.nextMacrotask();\n      \n      if (this.isDestroyed) {\n        this.logger_.incident?.('recalculate_', 'destroyed_during_delay');\n        this.isRecalculating__ = false;\n        return;\n      }\n\n      this.logger_.logStep?.('recalculate_', 'recalculating_value');\n\n      // Set the new value on the internal signal, which will notify our subscribers.\n      this.internalSignal_.set(this.config_.get());\n    }\n    catch (err) {\n      this.logger_.error('recalculate_', 'recalculation_failed', err);\n    }\n\n    // Allow the next recalculation to be scheduled.\n    this.isRecalculating__ = false;\n  }\n}\n", "import {delay} from '@alwatr/delay';\nimport {createLogger} from '@alwatr/logger';\n\nimport type {EffectSignalConfig, IEffectSignal, SubscribeResult} from '../type.js';\n\n/**\n * Manages a side-effect that runs in response to changes in dependency signals.\n *\n * `EffectSignal` is designed for running logic that interacts with the \"outside world\"—such as\n * logging, network requests, or DOM manipulation—whenever its dependencies are updated.\n * It encapsulates the subscription and cleanup logic, providing a robust and memory-safe\n * way to handle reactive side-effects.\n *\n * A key feature is its lifecycle management: an `EffectSignal` **must** be destroyed when no longer\n * needed to prevent memory leaks and stop the effect from running unnecessarily.\n *\n * @implements {IEffectSignal}\n *\n * @example\n * // --- Create dependency signals ---\n * const counter = new StateSignal({ initialValue: 0, signalId: 'counter' });\n * const user = new StateSignal({ initialValue: 'guest', signalId: 'user' });\n *\n * // --- Create an effect ---\n * const analyticsEffect = new EffectSignal({\n *   signalId: 'analytics-effect',\n *   deps: [counter, user],\n *   run: () => {\n *     console.log(`Analytics: User '${user.value}' clicked ${counter.value} times.`);\n *   },\n *   runImmediately: true, // Optional: run once on creation\n * });\n * // Immediately logs: \"Analytics: User 'guest' clicked 0 times.\"\n *\n * // --- Trigger the effect by updating a dependency ---\n * counter.set(1);\n * // After a macrotask, logs: \"Analytics: User 'guest' clicked 1 times.\"\n *\n * // --- IMPORTANT: Clean up when the effect is no longer needed ---\n * analyticsEffect.destroy();\n *\n * // Further updates will not trigger the effect.\n * counter.set(2); // Nothing is logged.\n */\nexport class EffectSignal implements IEffectSignal {\n  /**\n   * The unique identifier for this signal instance.\n   */\n  public readonly signalId = this.config_.signalId ? this.config_.signalId : `[${this.config_.deps.map((dep) => dep.signalId).join(', ')}]`;\n\n  /**\n   * The logger instance for this signal.\n   * @protected\n   */\n  protected readonly logger_ = createLogger(`effect-signal: ${this.signalId}`);\n\n  /**\n   * A list of subscriptions to dependency signals.\n   * @private\n   */\n  private readonly dependencySubscriptions__: SubscribeResult[] = [];\n\n  /**\n   * A flag to prevent concurrent executions of the effect.\n   * @private\n   */\n  private isRunning__ = false;\n\n  /**\n   * A flag indicating whether the effect has been destroyed.\n   * @private\n   */\n  private isDestroyed__ = false;\n\n  /**\n   * Indicates whether the effect signal has been destroyed.\n   * A destroyed signal will no longer execute its effect and cannot be reused.\n   *\n   * @returns `true` if the signal is destroyed, `false` otherwise.\n   */\n  public get isDestroyed(): boolean {\n    return this.isDestroyed__;\n  }\n\n  public constructor(protected config_: EffectSignalConfig) {\n    this.logger_.logMethod?.('constructor');\n    this.run_ = this.run_.bind(this);\n\n    // Subscribe to all dependencies. We don't need the previous value,\n    // as the `runImmediately` option controls the initial execution.\n    for (const signal of config_.deps) {\n      this.dependencySubscriptions__.push(signal.subscribe(this.run_, {receivePrevious: false}));\n    }\n\n    // Run the effect immediately if requested.\n    if (config_.runImmediately === true) {\n      // We don't need to await this, let it run in the background.\n      void this.run_();\n    }\n  }\n\n  /**\n   * Schedules the execution of the effect's `run` function.\n   *\n   * This method batches updates using a macrotask (`delay.nextMacrotask`) to ensure the\n   * `run` function executes only once per event loop tick, even if multiple\n   * dependencies change simultaneously.\n   * @protected\n   */\n  protected async run_(): Promise<void> {\n    this.logger_.logMethod?.('run_');\n\n    if (this.isDestroyed__) {\n      this.logger_.incident?.('run_', 'run_on_destroyed_signal');\n      return;\n    }\n    if (this.isRunning__) {\n      // If an execution is already scheduled, do nothing.\n      this.logger_.logStep?.('run_', 'skipped_because_already_running');\n      return;\n    }\n\n    this.isRunning__ = true;\n\n    try {\n      // Wait for the next macrotask to batch simultaneous updates.\n      await delay.nextMacrotask();\n      if (this.isDestroyed__) {\n        this.logger_.incident?.('run_', 'destroyed_during_delay');\n        this.isRunning__ = false;\n        return;\n      }\n\n      this.logger_.logStep?.('run_', 'executing_effect');\n      await this.config_.run();\n    }\n    catch (err) {\n      this.logger_.error('run_', 'effect_failed', err);\n    }\n\n    // Reset the flag after the current execution is complete.\n    this.isRunning__ = false;\n  }\n\n  /**\n   * Permanently disposes of the effect signal.\n   *\n   * This is a critical cleanup step. It unsubscribes from all dependency signals,\n   * stopping any future executions of the effect and allowing it to be garbage collected.\n   * Failure to call `destroy()` will result in memory leaks and potentially unwanted side effects.\n   */\n  public destroy(): void {\n    this.logger_.logMethod?.('destroy');\n\n    if (this.isDestroyed__) {\n      this.logger_.incident?.('destroy', 'already_destroyed');\n      return;\n    }\n\n    this.isDestroyed__ = true;\n\n    // Unsubscribe from all upstream dependencies.\n    for (const subscription of this.dependencySubscriptions__) {\n      subscription.unsubscribe();\n    }\n    this.dependencySubscriptions__.length = 0; // Clear the array of subscriptions.\n\n    this.config_.onDestroy?.(); // Call the optional onDestroy callback.\n    this.config_ = null as unknown as EffectSignalConfig; // Release config closure.\n  }\n}\n", "import {EventSignal} from '../core/event-signal.js';\n\nimport type {SignalConfig} from '../type.js';\n\n/**\n * Creates a stateless signal for dispatching transient events.\n *\n * `EventSignal` is ideal for broadcasting events that do not have a persistent state.\n * Unlike `StateSignal`, it does not hold a value. Listeners are only notified of new\n * events as they are dispatched. This makes it suitable for modeling user interactions,\n * system notifications, or any one-off message.\n *\n * @template T The type of the payload for the events.\n *\n * @param config The configuration for the event signal.\n * @returns A new instance of EventSignal.\n *\n * @example\n * const onUserClick = createEventSignal<{ x: number, y: number }>({\n *   signalId: 'on-user-click'\n * });\n *\n * onUserClick.subscribe(pos => {\n *   console.log(`User clicked at: ${pos.x}, ${pos.y}`);\n * });\n *\n * onUserClick.dispatch({ x: 100, y: 250 });\n */\nexport function createEventSignal<T = void>(config: SignalConfig): EventSignal<T> {\n  return new EventSignal<T>(config);\n}\n", "import {StateSignal} from '../core/state-signal.js';\n\nimport type {StateSignalConfig} from '../type.js';\n\n/**\n * Creates a stateful signal that holds a value and notifies listeners when the value changes.\n *\n * `StateSignal` is the core of the signal library, representing a piece of mutable state.\n * It always has a value, and new subscribers immediately receive the current value by default.\n *\n * @template T The type of the state it holds.\n *\n * @param config The configuration for the state signal.\n * @returns A new instance of StateSignal.\n *\n * @example\n * const counter = createStateSignal({\n *   signalId: 'counter-signal',\n *   initialValue: 0,\n * });\n *\n * console.log(counter.value); // Outputs: 0\n * counter.set(1);\n * console.log(counter.value); // Outputs: 1\n */\nexport function createStateSignal<T>(config: StateSignalConfig<T>): StateSignal<T> {\n  return new StateSignal(config);\n}\n", "import {ComputedSignal} from '../core/computed-signal.js';\n\nimport type {ComputedSignalConfig} from '../type.js';\n\n/**\n * Creates a read-only signal that derives its value from a set of dependency signals.\n *\n * `ComputedSignal` is a powerful tool for creating values that reactively update when their underlying\n * data sources change. Its value is memoized, meaning the `get` function is only re-evaluated when\n * one of its dependencies has actually changed.\n *\n * A key feature is its lifecycle management: a `ComputedSignal` **must** be destroyed when no longer\n * needed to prevent memory leaks from its subscriptions to dependency signals.\n *\n * @template T The type of the computed value.\n *\n * @param config The configuration for the computed signal.\n * @returns A new, read-only computed signal.\n *\n * @example\n * const firstName = createStateSignal({ signalId: 'firstName', initialValue: 'John' });\n * const lastName = createStateSignal({ signalId: 'lastName', initialValue: 'Doe' });\n *\n * const fullName = createComputedSignal({\n *   signalId: 'fullName',\n *   deps: [firstName, lastName],\n *   get: () => `${firstName.value} ${lastName.value}`,\n * });\n *\n * console.log(fullName.value); // \"John Doe\"\n *\n * // IMPORTANT: Always destroy a computed signal when no longer needed.\n * // fullName.destroy();\n */\nexport function createComputedSignal<T>(config: ComputedSignalConfig<T>): ComputedSignal<T> {\n  return new ComputedSignal(config);\n}\n", "import {EffectSignal} from '../core/effect-signal.js';\n\nimport type {EffectSignalConfig} from '../type.js';\n\n/**\n * Creates a side-effect that runs in response to changes in dependency signals.\n *\n * `EffectSignal` is designed for running logic that interacts with the \"outside world\"—such as\n * logging, network requests, or DOM manipulation—whenever its dependencies are updated.\n * It encapsulates the subscription and cleanup logic, providing a robust and memory-safe\n * way to handle reactive side-effects.\n *\n * A key feature is its lifecycle management: an `EffectSignal` **must** be destroyed when no longer\n * needed to prevent memory leaks and stop the effect from running unnecessarily.\n *\n * @param config The configuration for the effect.\n * @returns An object with a `destroy` method to stop the effect.\n *\n * @example\n * // --- Create dependency signals ---\n * const counter = createStateSignal({ initialValue: 0, signalId: 'counter' });\n * const user = createStateSignal({ initialValue: 'guest', signalId: 'user' });\n *\n * // --- Create an effect ---\n * const analyticsEffect = createEffect({\n *   deps: [counter, user],\n *   run: () => {\n *     console.log(`Analytics: User '${user.value}' clicked ${counter.value} times.`);\n *   },\n *   runImmediately: true, // Optional: run once on creation\n * });\n * // Immediately logs: \"Analytics: User 'guest' clicked 0 times.\"\n *\n * // --- Trigger the effect by updating a dependency ---\n * counter.set(1);\n * // After a macrotask, logs: \"Analytics: User 'guest' clicked 1 times.\"\n *\n * // --- IMPORTANT: Clean up when the effect is no longer needed ---\n * analyticsEffect.destroy();\n *\n * // Further updates will not trigger the effect.\n * counter.set(2); // Nothing is logged.\n */\nexport function createEffect(config: EffectSignalConfig): EffectSignal {\n  return new EffectSignal(config);\n}\n", "import {createDebouncer} from '@alwatr/debounce';\n\nimport {StateSignal} from '../core/state-signal.js';\nimport {createComputedSignal} from '../creators/computed.js';\n\nimport type {ComputedSignal} from '../core/computed-signal.js';\nimport type {IReadonlySignal, DebounceSignalConfig} from '../type.js';\n\n/**\n * Creates a new computed signal that debounces updates from a source signal.\n *\n * The returned signal is a `ComputedSignal`, meaning it is read-only and its value is\n * derived from the source. It only updates its value after a specified period of\n * inactivity from the source signal.\n *\n * This operator is essential for handling high-frequency events, such as user input\n * in a search box, resizing a window, or any other event that fires rapidly.\n * By debouncing, you can ensure that expensive operations (like API calls or heavy\n * computations) are only executed once the events have settled.\n *\n * @template T The type of the signal's value.\n *\n * @param {IReadonlySignal<T>} sourceSignal The original signal to debounce.\n * It can be a `StateSignal`, `ComputedSignal`, or any signal implementing `IReadonlySignal`.\n * @param {DebounceSignalConfig} config Configuration object for the debouncer,\n * including `delay`, `leading`, and `trailing` options from `@alwatr/debounce`.\n *\n * @returns {IComputedSignal<T>} A new, read-only computed signal that emits debounced values.\n * Crucially, you **must** call `.destroy()` on this signal when it's no longer\n * needed to prevent memory leaks by cleaning up internal subscriptions and timers.\n *\n * @example\n * ```typescript\n * // Create a source signal for user input.\n * const searchInput = createStateSignal({\n *   signalId: 'search-input',\n *   initialValue: '',\n * });\n *\n * // Create a debounced signal that waits 300ms after the user stops typing.\n * const debouncedSearch = createDebouncedSignal(searchInput, { delay: 300 });\n *\n * // Use an effect to react to the debounced value.\n * createEffect({\n *   deps: [debouncedSearch],\n *   run: () => {\n *     if (debouncedSearch.value) {\n *       console.log(`🚀 Sending API request for: \"${debouncedSearch.value}\"`);\n *     }\n *   },\n * });\n *\n * searchInput.set('Alwatr');\n * searchInput.set('Alwatr Signal');\n * // (after 300ms of inactivity)\n * // Logs: \"🚀 Sending API request for: \"Alwatr Signal\"\"\n *\n * // IMPORTANT: Clean up when the component unmounts.\n * // debouncedSearch.destroy();\n * ```\n */\nexport function createDebouncedSignal<T>(sourceSignal: IReadonlySignal<T>, config: DebounceSignalConfig): ComputedSignal<T> {\n  const signalId = config.signalId ?? `${sourceSignal.signalId}-debounced`;\n\n  const internalSignal = new StateSignal<T>({\n    signalId: `${signalId}-internal`,\n    initialValue: sourceSignal.value,\n  });\n\n  const debouncer = createDebouncer({\n    ...config,\n    func: (value: T): void => {\n      internalSignal.set(value);\n    },\n  });\n\n  const subscription = sourceSignal.subscribe(debouncer.trigger);\n\n  return createComputedSignal({\n    signalId,\n    deps: [internalSignal],\n    get: () => internalSignal.value,\n    onDestroy: () => {\n      if (internalSignal.isDestroyed) return;\n      subscription.unsubscribe();\n      debouncer.cancel();\n      internalSignal.destroy();\n      config.onDestroy?.();\n      config = null as unknown as DebounceSignalConfig;\n    },\n  });\n}\n"],
+  "mappings": ";;;AAUO,IAAe,aAAf,MAA6B;AAAA,EAmC3B,YAAsB,SAAuB;AAAvB;AA9B7B;AAAA;AAAA;AAAA;AAAA,SAAgB,WAAW,KAAK,QAAQ;AAYxC;AAAA;AAAA;AAAA;AAAA,SAAmB,aAA6B,CAAC;AAMjD;AAAA;AAAA;AAAA;AAAA,SAAQ,gBAAgB;AAAA,EAY6B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAJrD,IAAW,cAAuB;AAChC,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUU,gBAAgB,UAA8B;AACtD,SAAK,QAAQ,YAAY,iBAAiB;AAE1C,QAAI,KAAK,eAAe;AACtB,WAAK,QAAQ,WAAW,mBAAmB,qCAAqC;AAChF;AAAA,IACF;AAEA,UAAM,QAAQ,KAAK,WAAW,QAAQ,QAAQ;AAC9C,QAAI,UAAU,IAAI;AAChB,WAAK,WAAW,OAAO,OAAO,CAAC;AAAA,IACjC;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWO,UAAU,UAA+B,SAA6C;AAC3F,SAAK,QAAQ,gBAAgB,kBAAkB,EAAC,QAAO,CAAC;AACxD,SAAK,gBAAgB;AAErB,UAAM,WAAyB,EAAC,UAAU,QAAO;AAEjD,QAAI,SAAS,UAAU;AAErB,WAAK,WAAW,QAAQ,QAAQ;AAAA,IAClC,OACK;AACH,WAAK,WAAW,KAAK,QAAQ;AAAA,IAC/B;AAGA,WAAO;AAAA,MACL,aAAa,MAAY,KAAK,gBAAgB,QAAQ;AAAA,IACxD;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWU,QAAQ,OAAgB;AAChC,SAAK,QAAQ,gBAAgB,WAAW,KAAK;AAE7C,QAAI,KAAK,eAAe;AACtB,WAAK,QAAQ,WAAW,WAAW,4BAA4B;AAC/D;AAAA,IACF;AAIA,UAAM,mBAAmB,CAAC,GAAG,KAAK,UAAU;AAE5C,eAAW,YAAY,kBAAkB;AACvC,UAAI,SAAS,SAAS,MAAM;AAC1B,aAAK,gBAAgB,QAAQ;AAAA,MAC/B;AAEA,UAAI;AACF,cAAM,SAAS,SAAS,SAAS,KAAK;AACtC,YAAI,kBAAkB,SAAS;AAC7B,iBAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ,MAAM,WAAW,yBAAyB,KAAK,EAAC,SAAQ,CAAC,CAAC;AAAA,QAC/F;AAAA,MACF,SACO,KAAK;AACV,aAAK,QAAQ,MAAM,WAAW,wBAAwB,GAAG;AAAA,MAC3D;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAeO,YAAwB;AAC7B,SAAK,QAAQ,YAAY,WAAW;AACpC,SAAK,gBAAgB;AACrB,WAAO,IAAI,QAAQ,CAAC,YAAY;AAC9B,WAAK,UAAU,SAAS;AAAA,QACtB,MAAM;AAAA,QACN,UAAU;AAAA;AAAA,QACV,iBAAiB;AAAA;AAAA,MACnB,CAAC;AAAA,IACH,CAAC;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASO,UAAgB;AACrB,SAAK,QAAQ,YAAY,SAAS;AAClC,QAAI,KAAK,eAAe;AACtB,WAAK,QAAQ,WAAW,YAAY,wBAAwB;AAC5D;AAAA,IACF;AACA,SAAK,gBAAgB;AACrB,SAAK,WAAW,SAAS;AACzB,SAAK,QAAQ,YAAY;AACzB,SAAK,UAAU;AAAA,EACjB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOU,kBAAwB;AAChC,QAAI,KAAK,eAAe;AACtB,WAAK,QAAQ,SAAS,mBAAmB,iCAAiC;AAC1E,YAAM,IAAI,MAAM,gDAAgD,KAAK,QAAQ,GAAG;AAAA,IAClF;AAAA,EACF;AACF;;;AC7LA,SAAQ,aAAY;AACpB,SAAQ,oBAAmB;AAiCpB,IAAM,cAAN,cAAoC,WAAc;AAAA,EAOhD,YAAY,QAAsB;AACvC,UAAM,MAAM;AAHd;AAAA;AAAA;AAAA;AAAA,SAAU,UAAU,aAAa,iBAAiB,KAAK,QAAQ,EAAE;AAI/D,SAAK,QAAQ,YAAY,aAAa;AAAA,EACxC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASO,SAAS,SAAkB;AAChC,SAAK,QAAQ,gBAAgB,YAAY,EAAC,QAAO,CAAC;AAClD,SAAK,gBAAgB;AAErB,UAAM,cAAc,EAAE,KAAK,MAAM,KAAK,QAAQ,OAAO,CAAC;AAAA,EACxD;AACF;;;AC3DA,SAAQ,SAAAA,cAAY;AACpB,SAAQ,gBAAAC,qBAAmB;AAuCpB,IAAM,cAAN,cAA6B,WAA4C;AAAA,EAavE,YAAY,QAA8B;AAC/C,UAAM,MAAM;AAHd;AAAA;AAAA;AAAA;AAAA,SAAU,UAAUC,cAAa,iBAAiB,KAAK,QAAQ,EAAE;AAI/D,SAAK,UAAU,OAAO;AACtB,SAAK,QAAQ,gBAAgB,eAAe,EAAC,cAAc,KAAK,QAAO,CAAC;AAAA,EAC1E;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,IAAW,QAAW;AACpB,SAAK,gBAAgB;AACrB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiBO,IAAI,UAAmB;AAC5B,SAAK,QAAQ,gBAAgB,OAAO,EAAC,SAAQ,CAAC;AAC9C,SAAK,gBAAgB;AAGrB,QAAI,OAAO,GAAG,KAAK,SAAS,QAAQ,MAAM,OAAO,aAAa,YAAY,aAAa,OAAO;AAC5F;AAAA,IACF;AAEA,SAAK,UAAU;AAGf,IAAAC,OAAM,cAAc,EAAE,KAAK,MAAM,KAAK,QAAQ,QAAQ,CAAC;AAAA,EACzD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiBO,OAAO,SAAwC;AACpD,SAAK,QAAQ,YAAY,QAAQ;AACjC,SAAK,gBAAgB;AAGrB,SAAK,IAAI,QAAQ,KAAK,OAAO,CAAC;AAAA,EAChC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYgB,UAAU,UAA+B,UAA4B,CAAC,GAAoB;AACxG,SAAK,QAAQ,gBAAgB,aAAa,EAAC,QAAO,CAAC;AACnD,SAAK,gBAAgB;AAGrB,QAAI,QAAQ,oBAAoB,OAAO;AAGrC,MAAAA,OACG,cAAc,EACd,KAAK,MAAM,SAAS,KAAK,OAAO,CAAC,EACjC,MAAM,CAAC,QAAQ,KAAK,QAAQ,MAAM,aAAa,6BAA6B,GAAG,CAAC;AAInF,UAAI,QAAQ,MAAM;AAEhB,eAAO,EAAC,aAAa,MAAM;AAAA,QAAC,EAAC;AAAA,MAC/B;AAAA,IACF;AAEA,WAAO,MAAM,UAAU,UAAU,OAAO;AAAA,EAC1C;AAAA;AAAA;AAAA;AAAA;AAAA,EAMgB,UAAgB;AAC9B,SAAK,UAAU;AACf,UAAM,QAAQ;AAAA,EAChB;AACF;;;ACvKA,SAAQ,SAAAC,cAAY;AACpB,SAAQ,gBAAAC,qBAAmB;AA4CpB,IAAM,iBAAN,MAAsD;AAAA,EAmCpD,YAAsB,SAAkC;AAAlC;AA/B7B;AAAA;AAAA;AAAA,SAAgB,WAAW,KAAK,QAAQ;AAMxC;AAAA;AAAA;AAAA;AAAA,SAAmB,UAAUC,cAAa,oBAAoB,KAAK,QAAQ,EAAE;AAO7E;AAAA;AAAA;AAAA;AAAA;AAAA,SAAmB,kBAAkB,IAAI,YAAe;AAAA,MACtD,UAAU,GAAG,KAAK,QAAQ;AAAA,MAC1B,cAAc,KAAK,QAAQ,IAAI;AAAA,IACjC,CAAC;AAOD;AAAA;AAAA;AAAA;AAAA,SAAiB,4BAA+C,CAAC;AAMjE;AAAA;AAAA;AAAA;AAAA,SAAQ,oBAAoB;AAG1B,SAAK,QAAQ,YAAY,aAAa;AACtC,SAAK,eAAe,KAAK,aAAa,KAAK,IAAI;AAG/C,eAAW,UAAU,QAAQ,MAAM;AACjC,WAAK,0BAA0B,KAAK,OAAO,UAAU,KAAK,cAAc,EAAC,iBAAiB,MAAK,CAAC,CAAC;AAAA,IACnG;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,IAAW,QAAW;AACpB,WAAO,KAAK,gBAAgB;AAAA,EAC9B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,IAAW,cAAuB;AAChC,WAAO,KAAK,gBAAgB;AAAA,EAC9B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUO,UAAU,UAA8B,SAA6C;AAC1F,WAAO,KAAK,gBAAgB,UAAU,UAAU,OAAO;AAAA,EACzD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,YAAwB;AAC7B,WAAO,KAAK,gBAAgB,UAAU;AAAA,EACxC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWO,UAAgB;AACrB,SAAK,QAAQ,YAAY,SAAS;AAIlC,QAAI,KAAK,aAAa;AACpB,WAAK,QAAQ,WAAW,WAAW,mBAAmB;AACtD;AAAA,IACF;AAGA,eAAW,gBAAgB,KAAK,2BAA2B;AACzD,mBAAa,YAAY;AAAA,IAC3B;AACA,SAAK,0BAA0B,SAAS;AAExC,SAAK,gBAAgB,QAAQ;AAC7B,SAAK,QAAQ,YAAY;AACzB,SAAK,UAAU;AAAA,EACjB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,MAAgB,eAA8B;AAC5C,SAAK,QAAQ,YAAY,cAAc;AAEvC,QAAI,KAAK,gBAAgB,aAAa;AAEpC,WAAK,QAAQ,WAAW,gBAAgB,iCAAiC;AACzE;AAAA,IACF;AAEA,QAAI,KAAK,mBAAmB;AAE1B,WAAK,QAAQ,UAAU,gBAAgB,0CAA0C;AACjF;AAAA,IACF;AAEA,SAAK,oBAAoB;AAEzB,QAAI;AAGF,YAAMC,OAAM,cAAc;AAE1B,UAAI,KAAK,aAAa;AACpB,aAAK,QAAQ,WAAW,gBAAgB,wBAAwB;AAChE,aAAK,oBAAoB;AACzB;AAAA,MACF;AAEA,WAAK,QAAQ,UAAU,gBAAgB,qBAAqB;AAG5D,WAAK,gBAAgB,IAAI,KAAK,QAAQ,IAAI,CAAC;AAAA,IAC7C,SACO,KAAK;AACV,WAAK,QAAQ,MAAM,gBAAgB,wBAAwB,GAAG;AAAA,IAChE;AAGA,SAAK,oBAAoB;AAAA,EAC3B;AACF;;;ACjNA,SAAQ,SAAAC,cAAY;AACpB,SAAQ,gBAAAC,qBAAmB;AA2CpB,IAAM,eAAN,MAA4C;AAAA,EAwC1C,YAAsB,SAA6B;AAA7B;AApC7B;AAAA;AAAA;AAAA,SAAgB,WAAW,KAAK,QAAQ,WAAW,KAAK,QAAQ,WAAW,IAAI,KAAK,QAAQ,KAAK,IAAI,CAAC,QAAQ,IAAI,QAAQ,EAAE,KAAK,IAAI,CAAC;AAMtI;AAAA;AAAA;AAAA;AAAA,SAAmB,UAAUA,cAAa,kBAAkB,KAAK,QAAQ,EAAE;AAM3E;AAAA;AAAA;AAAA;AAAA,SAAiB,4BAA+C,CAAC;AAMjE;AAAA;AAAA;AAAA;AAAA,SAAQ,cAAc;AAMtB;AAAA;AAAA;AAAA;AAAA,SAAQ,gBAAgB;AAatB,SAAK,QAAQ,YAAY,aAAa;AACtC,SAAK,OAAO,KAAK,KAAK,KAAK,IAAI;AAI/B,eAAW,UAAU,QAAQ,MAAM;AACjC,WAAK,0BAA0B,KAAK,OAAO,UAAU,KAAK,MAAM,EAAC,iBAAiB,MAAK,CAAC,CAAC;AAAA,IAC3F;AAGA,QAAI,QAAQ,mBAAmB,MAAM;AAEnC,WAAK,KAAK,KAAK;AAAA,IACjB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAnBA,IAAW,cAAuB;AAChC,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA2BA,MAAgB,OAAsB;AACpC,SAAK,QAAQ,YAAY,MAAM;AAE/B,QAAI,KAAK,eAAe;AACtB,WAAK,QAAQ,WAAW,QAAQ,yBAAyB;AACzD;AAAA,IACF;AACA,QAAI,KAAK,aAAa;AAEpB,WAAK,QAAQ,UAAU,QAAQ,iCAAiC;AAChE;AAAA,IACF;AAEA,SAAK,cAAc;AAEnB,QAAI;AAEF,YAAMD,OAAM,cAAc;AAC1B,UAAI,KAAK,eAAe;AACtB,aAAK,QAAQ,WAAW,QAAQ,wBAAwB;AACxD,aAAK,cAAc;AACnB;AAAA,MACF;AAEA,WAAK,QAAQ,UAAU,QAAQ,kBAAkB;AACjD,YAAM,KAAK,QAAQ,IAAI;AAAA,IACzB,SACO,KAAK;AACV,WAAK,QAAQ,MAAM,QAAQ,iBAAiB,GAAG;AAAA,IACjD;AAGA,SAAK,cAAc;AAAA,EACrB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASO,UAAgB;AACrB,SAAK,QAAQ,YAAY,SAAS;AAElC,QAAI,KAAK,eAAe;AACtB,WAAK,QAAQ,WAAW,WAAW,mBAAmB;AACtD;AAAA,IACF;AAEA,SAAK,gBAAgB;AAGrB,eAAW,gBAAgB,KAAK,2BAA2B;AACzD,mBAAa,YAAY;AAAA,IAC3B;AACA,SAAK,0BAA0B,SAAS;AAExC,SAAK,QAAQ,YAAY;AACzB,SAAK,UAAU;AAAA,EACjB;AACF;;;AC9IO,SAAS,kBAA4B,QAAsC;AAChF,SAAO,IAAI,YAAe,MAAM;AAClC;;;ACLO,SAAS,kBAAqB,QAA8C;AACjF,SAAO,IAAI,YAAY,MAAM;AAC/B;;;ACOO,SAAS,qBAAwB,QAAoD;AAC1F,SAAO,IAAI,eAAe,MAAM;AAClC;;;ACOO,SAAS,aAAa,QAA0C;AACrE,SAAO,IAAI,aAAa,MAAM;AAChC;;;AC7CA,SAAQ,uBAAsB;AA6DvB,SAAS,sBAAyB,cAAkC,QAAiD;AAC1H,QAAM,WAAW,OAAO,YAAY,GAAG,aAAa,QAAQ;AAE5D,QAAM,iBAAiB,IAAI,YAAe;AAAA,IACxC,UAAU,GAAG,QAAQ;AAAA,IACrB,cAAc,aAAa;AAAA,EAC7B,CAAC;AAED,QAAM,YAAY,gBAAgB;AAAA,IAChC,GAAG;AAAA,IACH,MAAM,CAAC,UAAmB;AACxB,qBAAe,IAAI,KAAK;AAAA,IAC1B;AAAA,EACF,CAAC;AAED,QAAM,eAAe,aAAa,UAAU,UAAU,OAAO;AAE7D,SAAO,qBAAqB;AAAA,IAC1B;AAAA,IACA,MAAM,CAAC,cAAc;AAAA,IACrB,KAAK,MAAM,eAAe;AAAA,IAC1B,WAAW,MAAM;AACf,UAAI,eAAe,YAAa;AAChC,mBAAa,YAAY;AACzB,gBAAU,OAAO;AACjB,qBAAe,QAAQ;AACvB,aAAO,YAAY;AACnB,eAAS;AAAA,IACX;AAAA,EACF,CAAC;AACH;",
   "names": ["delay", "createLogger", "createLogger", "delay", "delay", "createLogger", "createLogger", "delay", "delay", "createLogger"]
 }