@alwatr/signal 5.0.0 → 5.2.0

package/dist/main.cjs

@@ -1,4 +1,4 @@
-/* @alwatr/signal v5.0.0 */
+/* @alwatr/signal v5.2.0 */
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -25,57 +25,56 @@ __export(main_exports, {
   EffectSignal: () => EffectSignal,
   EventSignal: () => EventSignal,
   SignalBase: () => SignalBase,
-  StateSignal: () => StateSignal
+  StateSignal: () => StateSignal,
+  createComputedSignal: () => createComputedSignal,
+  createDebouncedSignal: () => createDebouncedSignal,
+  createEffect: () => createEffect,
+  createEventSignal: () => createEventSignal,
+  createStateSignal: () => createStateSignal
 });
 module.exports = __toCommonJS(main_exports);
 
-// src/signal-base.ts
-var import_package_tracer = require("@alwatr/package-tracer");
-__dev_mode__: import_package_tracer.packageTracer.add("@alwatr/signal", "5.0.0");
+// src/core/signal-base.ts
 var SignalBase = class {
-  /**
-   * Initializes a new `SignalBase`.
-   * @param config The configuration for the signal, containing its `signalId`.
-   */
-  constructor(config) {
+  constructor(config_) {
+    this.config_ = config_;
+    /**
+     * The unique identifier for this signal instance.
+     * Useful for debugging and logging.
+     */
+    this.signalId = this.config_.signalId;
     /**
      * The list of observers (listeners) subscribed to this signal.
      * @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.signalId = config.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);
@@ -99,8 +98,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.
@@ -112,11 +112,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) {
@@ -125,9 +125,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);
@@ -169,21 +167,38 @@ var SignalBase = class {
    */
   destroy() {
     this.logger_.logMethod?.("destroy");
-    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/event-signal.ts
+// src/core/event-signal.ts
 var import_delay = require("@alwatr/delay");
 var import_logger = require("@alwatr/logger");
 var EventSignal = class extends SignalBase {
-  /**
-   * Initializes a new `EventSignal`.
-   * @param config The configuration for the signal, containing its `signalId`.
-   */
   constructor(config) {
     super(config);
+    /**
+     * The logger instance for this signal.
+     * @protected
+     */
     this.logger_ = (0, import_logger.createLogger)(`event-signal: ${this.signalId}`);
     this.logger_.logMethod?.("constructor");
   }
@@ -195,24 +210,22 @@ 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_();
-    import_delay.delay.nextMicrotask().then(() => {
-      this.notify_(payload);
-    });
+    import_delay.delay.nextMicrotask().then(() => this.notify_(payload));
   }
 };
 
-// src/state-signal.ts
+// src/core/state-signal.ts
 var import_delay2 = require("@alwatr/delay");
 var import_logger2 = require("@alwatr/logger");
 var StateSignal = class extends SignalBase {
-  /**
-   * Initializes a new `StateSignal`.
-   * @param config The configuration for the state signal, including `signalId` and `initialValue`.
-   */
   constructor(config) {
     super(config);
+    /**
+     * The logger instance for this signal.
+     * @protected
+     */
     this.logger_ = (0, import_logger2.createLogger)(`state-signal: ${this.signalId}`);
     this.value__ = config.initialValue;
     this.logger_.logMethodArgs?.("constructor", { initialValue: this.value__ });
@@ -247,11 +260,31 @@ 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;
-    import_delay2.delay.nextMicrotask().then(() => {
-      this.notify_(newValue);
-    });
+    import_delay2.delay.nextMicrotask().then(() => this.notify_(newValue));
+  }
+  /**
+   * Updates the signal's value based on its previous value.
+   *
+   * This method is particularly useful for state transitions that depend on the current value,
+   * especially for objects or arrays, as it promotes an immutable update pattern.
+   *
+   * @param updater A function that receives the current value and returns the new value.
+   *
+   * @example
+   * // For a counter
+   * counterSignal.update(current => current + 1);
+   *
+   * // For an object state
+   * userSignal.update(currentUser => ({ ...currentUser, loggedIn: true }));
+   */
+  update(updater) {
+    this.logger_.logMethod?.("update");
+    this.checkDestroyed_();
+    this.set(updater(this.value__));
   }
   /**
    * Subscribes a listener to this signal.
@@ -266,11 +299,8 @@ var StateSignal = class extends SignalBase {
   subscribe(callback, options = {}) {
     this.logger_.logMethodArgs?.("subscribe", { options });
     this.checkDestroyed_();
-    const receivePrevious = options.receivePrevious !== false;
-    if (receivePrevious) {
-      import_delay2.delay.nextMicrotask().then(() => callback(this.value__)).catch((err) => {
-        this.logger_.error("subscribe", "run_callback_immediate_failed", err);
-      });
+    if (options.receivePrevious !== false) {
+      import_delay2.delay.nextMicrotask().then(() => callback(this.value__)).catch((err) => this.logger_.error("subscribe", "immediate_callback_failed", err));
       if (options.once) {
         return { unsubscribe: () => {
         } };
@@ -283,22 +313,25 @@ var StateSignal = class extends SignalBase {
    * This is crucial for memory management to prevent leaks.
    */
   destroy() {
-    super.destroy();
     this.value__ = null;
+    super.destroy();
   }
 };
 
-// src/computed-signal.ts
+// src/core/computed-signal.ts
 var import_delay3 = require("@alwatr/delay");
 var import_logger3 = require("@alwatr/logger");
 var ComputedSignal = class {
-  /**
-   * Initializes a new `ComputedSignal`.
-   * @param config The configuration, including dependencies (`deps`) and the getter function (`get`).
-   */
   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_ = (0, import_logger3.createLogger)(`computed-signal: ${this.signalId}`);
     /**
      * The internal `StateSignal` that holds the computed value.
@@ -306,17 +339,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 }));
     }
   }
   /**
@@ -337,6 +376,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.
    *
@@ -348,15 +406,16 @@ 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;
   }
   /**
@@ -368,23 +427,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 import_delay3.delay.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);
@@ -393,24 +453,40 @@ var ComputedSignal = class {
   }
 };
 
-// src/effect-signal.ts
+// src/core/effect-signal.ts
 var import_delay4 = require("@alwatr/delay");
 var import_logger4 = require("@alwatr/logger");
 var EffectSignal = class {
-  /**
-   * Initializes a new `EffectSignal`.
-   * @param config The configuration, including dependencies (`deps`) and the `run` function.
-   */
   constructor(config_) {
     this.config_ = config_;
-    this.logger_ = (0, import_logger4.createLogger)(`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_ = (0, import_logger4.createLogger)(`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_();
@@ -418,7 +494,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() {
@@ -433,29 +510,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 import_delay4.delay.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.
@@ -471,19 +548,75 @@ 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;
   }
 };
+
+// src/creators/event.ts
+function createEventSignal(config) {
+  return new EventSignal(config);
+}
+
+// src/creators/state.ts
+function createStateSignal(config) {
+  return new StateSignal(config);
+}
+
+// src/creators/computed.ts
+function createComputedSignal(config) {
+  return new ComputedSignal(config);
+}
+
+// src/creators/effect.ts
+function createEffect(config) {
+  return new EffectSignal(config);
+}
+
+// src/operators/debounce.ts
+var import_debounce = require("@alwatr/debounce");
+function createDebouncedSignal(sourceSignal, config) {
+  const signalId = config.signalId ?? `${sourceSignal.signalId}-debounced`;
+  const internalSignal = new StateSignal({
+    signalId: `${signalId}-internal`,
+    initialValue: sourceSignal.value
+  });
+  const debouncer = (0, import_debounce.createDebouncer)({
+    ...config,
+    func: (value) => {
+      internalSignal.set(value);
+    }
+  });
+  const subscription = sourceSignal.subscribe(debouncer.trigger);
+  return createComputedSignal({
+    signalId,
+    deps: [internalSignal],
+    get: () => internalSignal.value,
+    onDestroy: () => {
+      if (internalSignal.isDestroyed) return;
+      subscription.unsubscribe();
+      debouncer.cancel();
+      internalSignal.destroy();
+      config.onDestroy?.();
+      config = null;
+    }
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ComputedSignal,
   EffectSignal,
   EventSignal,
   SignalBase,
-  StateSignal
+  StateSignal,
+  createComputedSignal,
+  createDebouncedSignal,
+  createEffect,
+  createEventSignal,
+  createStateSignal
 });
 //# sourceMappingURL=main.cjs.map