@alwatr/signal 4.1.0 → 5.0.0

package/dist/computed-signal.d.ts

@@ -0,0 +1,95 @@
+import { StateSignal } from './state-signal.js';
+import type { ComputedSignalConfig, IComputedSignal, SubscribeResult } from './type.js';
+/**
+ * A read-only signal that derives its value from a set of dependency signals.
+ *
+ * `ComputedSignal` is a powerful tool for creating values that reactively update when their underlying
+ * data sources change. Its value is memoized, meaning the `get` function is only re-evaluated when
+ * one of its dependencies has actually changed.
+ *
+ * A key feature is its lifecycle management: a `ComputedSignal` **must** be destroyed when no longer
+ * needed to prevent memory leaks from its subscriptions to dependency signals.
+ *
+ * @template T The type of the computed value.
+ * @implements {IComputedSignal<T>}
+ *
+ * @example
+ * // --- Create dependency signals ---
+ * const firstName = new StateSignal({ signalId: 'firstName', initialValue: 'John' });
+ * const lastName = new StateSignal({ signalId: 'lastName', initialValue: 'Doe' });
+ *
+ * // --- Create a computed signal ---
+ * const fullName = new ComputedSignal({
+ *   signalId: 'fullName',
+ *   deps: [firstName, lastName],
+ *   get: () => `${firstName.value} ${lastName.value}`,
+ * });
+ *
+ * console.log(fullName.value); // Outputs: "John Doe"
+ *
+ * // --- Subscribe to the computed value ---
+ * fullName.subscribe(newFullName => {
+ *   console.log(`Name changed to: ${newFullName}`);
+ * });
+ *
+ * // --- Update a dependency ---
+ * lastName.set('Smith'); // Recalculates and logs: "Name changed to: John Smith"
+ * console.log(fullName.value); // Outputs: "John Smith"
+ *
+ * // --- IMPORTANT: Clean up when done ---
+ * fullName.destroy();
+ */
+export declare class ComputedSignal<T> implements IComputedSignal<T> {
+    protected config_: ComputedSignalConfig<T>;
+    readonly signalId: string;
+    protected readonly logger_: import("@alwatr/logger").AlwatrLogger;
+    /**
+     * The internal `StateSignal` that holds the computed value.
+     * This is how the computed signal provides `.value` and `.subscribe()` methods.
+     * @protected
+     */
+    protected readonly internalSignal_: StateSignal<T>;
+    private readonly subscriptionList__;
+    private isRecalculating__;
+    /**
+     * Initializes a new `ComputedSignal`.
+     * @param config The configuration, including dependencies (`deps`) and the getter function (`get`).
+     */
+    constructor(config_: ComputedSignalConfig<T>);
+    /**
+     * The current value of the computed signal.
+     * Accessing this property returns the memoized value and does not trigger a recalculation.
+     *
+     * @returns The current computed value.
+     * @throws {Error} If accessed after the signal has been destroyed.
+     */
+    get value(): T;
+    /**
+     * Indicates whether the computed 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(): boolean;
+    readonly subscribe: (callback: import("./type.js").ListenerCallback<T>, options?: import("./type.js").SubscribeOptions) => SubscribeResult;
+    readonly untilNext: () => Promise<T>;
+    /**
+     * Permanently disposes of the computed signal.
+     *
+     * This is a critical cleanup step. It unsubscribes from all dependency signals,
+     * 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.
+     */
+    destroy(): void;
+    /**
+     * Schedules a recalculation of the signal's value.
+     *
+     * This method batches updates using a macrotask (`delay.nextMacrotask`) to ensure the
+     * `get` function runs only once per event loop tick, even if multiple dependencies
+     * change in the same synchronous block of code.
+     * @protected
+     */
+    protected recalculate_(): Promise<void>;
+}
+//# sourceMappingURL=computed-signal.d.ts.map

package/dist/computed-signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"computed-signal.d.ts","sourceRoot":"","sources":["../src/computed-signal.ts"],"names":[],"mappings":"AAGA,OAAO,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAE9C,OAAO,KAAK,EAAC,oBAAoB,EAAE,eAAe,EAAE,eAAe,EAAC,MAAM,WAAW,CAAC;AAEtF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,cAAc,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,CAAC;IAsBvC,SAAS,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC;IArB7D,SAAgB,QAAQ,SAAyB;IAEjD,SAAS,CAAC,QAAQ,CAAC,OAAO,wCAAqD;IAE/E;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,eAAe,iBAG/B;IAEH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAyB;IAC5D,OAAO,CAAC,iBAAiB,CAAS;IAElC;;;OAGG;gBAC0B,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAU7D;;;;;;OAMG;IACH,IAAW,KAAK,IAAI,CAAC,CAEpB;IAED;;;;OAIG;IACH,IAAW,WAAW,IAAI,OAAO,CAEhC;IAED,SAAgB,SAAS,yHAA6D;IAEtF,SAAgB,SAAS,mBAA6D;IAEtF;;;;;;;;OAQG;IACI,OAAO,IAAI,IAAI;IAmBtB;;;;;;;OAOG;cACa,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;CAqC9C"}

package/dist/effect-signal.d.ts

@@ -0,0 +1,75 @@
+import type { EffectSignalConfig, IEffectSignal } from './type.js';
+/**
+ * Manages a side-effect that runs in response to changes in dependency signals.
+ *
+ * `EffectSignal` is designed for running logic that interacts with the "outside world"—such as
+ * logging, network requests, or DOM manipulation—whenever its dependencies are updated.
+ * It encapsulates the subscription and cleanup logic, providing a robust and memory-safe
+ * way to handle reactive side-effects.
+ *
+ * A key feature is its lifecycle management: an `EffectSignal` **must** be destroyed when no longer
+ * needed to prevent memory leaks and stop the effect from running unnecessarily.
+ *
+ * @implements {IEffectSignal}
+ *
+ * @example
+ * // --- Create dependency signals ---
+ * const counter = new StateSignal({ initialValue: 0, signalId: 'counter' });
+ * const user = new StateSignal({ initialValue: 'guest', signalId: 'user' });
+ *
+ * // --- Create an effect ---
+ * const analyticsEffect = new EffectSignal({
+ *   deps: [counter, user],
+ *   run: () => {
+ *     console.log(`Analytics: User '${user.value}' clicked ${counter.value} times.`);
+ *   },
+ *   runImmediately: true, // Optional: run once on creation
+ * });
+ * // Immediately logs: "Analytics: User 'guest' clicked 0 times."
+ *
+ * // --- Trigger the effect by updating a dependency ---
+ * counter.set(1);
+ * // After a macrotask, logs: "Analytics: User 'guest' clicked 1 times."
+ *
+ * // --- IMPORTANT: Clean up when the effect is no longer needed ---
+ * analyticsEffect.destroy();
+ *
+ * // Further updates will not trigger the effect.
+ * counter.set(2); // Nothing is logged.
+ */
+export declare class EffectSignal implements IEffectSignal {
+    protected config_: EffectSignalConfig;
+    protected readonly logger_: import("@alwatr/logger").AlwatrLogger;
+    private readonly subscriptionList__;
+    private isRunning__;
+    private isDestroyed__;
+    /**
+     * Indicates whether the effect 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(): boolean;
+    /**
+     * Initializes a new `EffectSignal`.
+     * @param config The configuration, including dependencies (`deps`) and the `run` function.
+     */
+    constructor(config_: EffectSignalConfig);
+    /**
+     * Schedules the execution of the effect's `run` function.
+     *
+     * This method batches updates using a macrotask (`delay.nextMacrotask`) to ensure the
+     * `run` function executes only once per event loop tick, even if multiple
+     * dependencies change simultaneously.
+     * @protected
+     */
+    protected run_(): Promise<void>;
+    /**
+     * Permanently disposes of the effect signal.
+     *
+     * This is a critical cleanup step. It unsubscribes from all dependency signals,
+     * stopping any future executions of the effect and allowing it to be garbage collected.
+     * Failure to call `destroy()` will result in memory leaks and potentially unwanted side effects.
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=effect-signal.d.ts.map

package/dist/effect-signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect-signal.d.ts","sourceRoot":"","sources":["../src/effect-signal.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,kBAAkB,EAAE,aAAa,EAAkB,MAAM,WAAW,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,YAAa,YAAW,aAAa;IAoB7B,SAAS,CAAC,OAAO,EAAE,kBAAkB;IAnBxD,SAAS,CAAC,QAAQ,CAAC,OAAO,wCAAiC;IAE3D,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAyB;IAC5D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,aAAa,CAAS;IAE9B;;;;OAIG;IACH,IAAW,WAAW,IAAI,OAAO,CAEhC;IAED;;;OAGG;gBAC0B,OAAO,EAAE,kBAAkB;IAiBxD;;;;;;;OAOG;cACa,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAmCrC;;;;;;OAMG;IACI,OAAO,IAAI,IAAI;CAgBvB"}

package/dist/event-signal.d.ts

@@ -0,0 +1,46 @@
+import { SignalBase } from './signal-base.js';
+import type { SignalConfig } from './type.js';
+/**
+ * A stateless signal for dispatching transient events.
+ *
+ * `EventSignal` is ideal for broadcasting events that do not have a persistent state.
+ * Unlike `StateSignal`, it does not hold a value. Listeners are only notified of new
+ * events as they are dispatched. This makes it suitable for modeling user interactions,
+ * system notifications, or any one-off message.
+ *
+ * @template T The type of the payload for the events. Defaults to `void` for events without a payload.
+ *
+ * @example
+ * // Create a signal for user click events.
+ * const onUserClick = new EventSignal<{ x: number, y: number }>({ signalId: 'on-user-click' });
+ *
+ * // Subscribe to the event.
+ * onUserClick.subscribe(clickPosition => {
+ *   console.log(`User clicked at: ${clickPosition.x}, ${clickPosition.y}`);
+ * });
+ *
+ * // Dispatch an event.
+ * onUserClick.dispatch({ x: 100, y: 250 }); // Notifies the listener.
+ *
+ * // --- Example with no payload ---
+ * const onAppReady = new EventSignal({ signalId: 'on-app-ready' });
+ * onAppReady.subscribe(() => console.log('Application is ready!'));
+ * onAppReady.dispatch(); // Notifies the listener.
+ */
+export declare class EventSignal<T = void> extends SignalBase<T> {
+    protected logger_: import("@alwatr/logger").AlwatrLogger;
+    /**
+     * Initializes a new `EventSignal`.
+     * @param config The configuration for the signal, containing its `signalId`.
+     */
+    constructor(config: SignalConfig);
+    /**
+     * Dispatches an event with an optional payload to all active listeners.
+     * The notification is scheduled as a microtask to prevent blocking and ensure
+     * a consistent, non-blocking flow.
+     *
+     * @param payload The data to send with the event.
+     */
+    dispatch(payload: T): void;
+}
+//# sourceMappingURL=event-signal.d.ts.map

package/dist/event-signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-signal.d.ts","sourceRoot":"","sources":["../src/event-signal.ts"],"names":[],"mappings":"AAGA,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAE5C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,WAAW,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,WAAW,CAAC,CAAC,GAAG,IAAI,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAC;IACtD,SAAS,CAAC,OAAO,wCAAkD;IAEnE;;;OAGG;gBACgB,MAAM,EAAE,YAAY;IAKvC;;;;;;OAMG;IACI,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI;CAQlC"}