@alwatr/signal 5.1.0 → 5.2.1

package/dist/main.mjs

@@ -1,11 +1,12 @@
-/* @alwatr/signal v5.1.0 */
+/* @alwatr/signal v5.2.1 */
 
 // 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__ });
@@ -187,9 +202,9 @@ var StateSignal = class extends SignalBase {
    * @returns The current value.
    *
    * @example
-   * console.log(mySignal.value);
+   * console.log(mySignal.get());
    */
-  get value() {
+  get() {
     this.checkDestroyed_();
     return this.value__;
   }
@@ -206,16 +221,16 @@ var StateSignal = class extends SignalBase {
    * mySignal.set(42);
    *
    * // For object types, it's best practice to set an immutable new object.
-   * mySignal.set({ ...mySignal.value, property: 'new-value' });
+   * mySignal.set({ ...mySignal.get(), property: 'new-value' });
    */
   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,25 +290,38 @@ 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.
-     * This is how the computed signal provides `.value` and `.subscribe()` methods.
+     * This is how the computed signal provides `.get()` and `.subscribe()` methods.
      * @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 }));
     }
   }
   /**
@@ -306,8 +331,8 @@ var ComputedSignal = class {
    * @returns The current computed value.
    * @throws {Error} If accessed after the signal has been destroyed.
    */
-  get value() {
-    return this.internalSignal_.value;
+  get() {
+    return this.internalSignal_.get();
   }
   /**
    * Indicates whether the computed signal has been destroyed.
@@ -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.
    *
@@ -324,18 +368,18 @@ var ComputedSignal = class {
    * stopping future recalculations and allowing the signal to be garbage collected.
    * Failure to call `destroy()` will result in memory leaks.
    *
-   * After `destroy()` is called, any attempt to access `.value` or `.subscribe()` will throw an error.
+   * After `destroy()` is called, any attempt to access `.get()` or `.subscribe()` will throw an error.
    */
   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,22 +425,43 @@ 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);
+    this.scheduleExecution_ = this.scheduleExecution_.bind(this);
     for (const signal of config_.deps) {
-      this.subscriptionList__.push(signal.subscribe(this.run_, { receivePrevious: false }));
+      this.dependencySubscriptions__.push(signal.subscribe(this.scheduleExecution_, { receivePrevious: false }));
     }
     if (config_.runImmediately === true) {
-      void this.run_();
+      void this.scheduleExecution_();
     }
   }
   /**
    * 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() {
@@ -409,30 +475,30 @@ var EffectSignal = class {
    * dependencies change simultaneously.
    * @protected
    */
-  async run_() {
+  async scheduleExecution_() {
+    this.logger_.logMethod?.("scheduleExecution_");
     if (this.isDestroyed__) {
-      this.logger_.incident?.("run_", "run_on_destroyed_signal");
+      this.logger_.incident?.("scheduleExecution_", "schedule_execution_on_destroyed_signal");
       return;
     }
     if (this.isRunning__) {
-      this.logger_.logMethod?.("run_//skipped");
+      this.logger_.logStep?.("scheduleExecution_", "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.logger_.incident?.("scheduleExecution_", "destroyed_during_delay");
+        this.isRunning__ = false;
         return;
       }
-      this.logger_.logMethod?.("run_//executing");
+      this.logger_.logStep?.("scheduleExecution_", "executing_effect");
       await this.config_.run();
     } catch (err) {
-      this.logger_.error("run_", "effect_failed", err);
-    } finally {
-      this.isRunning__ = false;
+      this.logger_.error("scheduleExecution_", "effect_failed", err);
     }
+    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;
   }
@@ -483,7 +549,7 @@ function createDebouncedSignal(sourceSignal, config) {
   const signalId = config.signalId ?? `${sourceSignal.signalId}-debounced`;
   const internalSignal = new StateSignal({
     signalId: `${signalId}-internal`,
-    initialValue: sourceSignal.value
+    initialValue: sourceSignal.get()
   });
   const debouncer = createDebouncer({
     ...config,
@@ -495,7 +561,7 @@ function createDebouncedSignal(sourceSignal, config) {
   return createComputedSignal({
     signalId,
     deps: [internalSignal],
-    get: () => internalSignal.value,
+    get: () => internalSignal.get(),
     onDestroy: () => {
       if (internalSignal.isDestroyed) return;
       subscription.unsubscribe();