@xaendar/signals 0.3.31 → 0.3.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xaendar/signals",
-  "version": "0.3.31",
+  "version": "0.3.34",
   "description": "A library for managing signals in web applications",
   "sideEffects": false,
   "type": "module",
@@ -16,7 +16,7 @@
     }
   },
   "dependencies": {
-    "@xaendar/common": "0.3.31",
-    "@xaendar/types": "0.3.31"
+    "@xaendar/common": "0.3.34",
+    "@xaendar/types": "0.3.34"
   }
 }

package/xaendar-signals.es.d.ts

@@ -194,6 +194,74 @@ export { };
 
 import { NoArgsVoidFunction } from '@xaendar/types';
 
+/**
+ * A read-only Signal whose value is derived lazily from other Signals.
+ *
+ * The value is recomputed only when explicitly read and only if one or more
+ * of its (recursive) dependencies have changed since the last evaluation.
+ * The result is cached and reused until the Signal becomes stale again.
+ *
+ * @template T The type of the computed value.
+ *
+ * @see Signal algorithms — "The Signal.Computed class"
+ */
+declare class Computed<T = any> {
+    #private;
+    /* Excluded from this release type: getSources */
+    /* Excluded from this release type: getSinks */
+    /**
+     * Creates a new `Computed` signal.
+     *
+     * The Signal starts in the `~dirty~` state with an uninitialised value, so
+     * `#callback` will be invoked on the first `get()`.
+     *
+     * @param cb - Pure function evaluated lazily to produce the value.
+     *   Receives the `Computed` instance as `this`.
+     * @param options - Optional configuration:
+     *   - `equals` — custom equality function; defaults to `Object.is`.
+     *
+     * @see Signal algorithms — "Signal.Computed Constructor"
+     */
+    constructor(cb: (this: Computed<T>) => T, options?: SignalOptions<T>);
+    /**
+     * Returns the current value of this Signal, re-evaluating `#callback` if
+     * the cached value may be stale.
+     *
+     * Registers this Signal as a source of any outer `Computed` currently
+     * being evaluated (automatic dependency tracking).
+     *
+     * If the state is `~dirty~` or `~checked~`, walks the source graph
+     * depth-first to find and recalculate the deepest stale `Computed` first,
+     * then re-checks upward until this Signal is `~clean~`.
+     *
+     * @returns The current computed value, or a boxed error object if the last
+     *   evaluation threw.
+     * @throws If `frozen` is `true`.
+     * @throws If the Signal is in the `~computing~` state (cyclic dependency).
+     *
+     * @see Signal algorithms — "Method: Signal.Computed.prototype.get"
+     */
+    get(): T | {
+        isError: true;
+        value: Error;
+    };
+    /* Excluded from this release type: addSource */
+    /* Excluded from this release type: getState */
+    /* Excluded from this release type: setState */
+    /* Excluded from this release type: addSink */
+    /* Excluded from this release type: removeSink */
+}
+
+/**
+ * Rapresents the state of a computed signal.
+ * The state can be one of the following:
+ * - `dirty`: the computed signal is dirty and needs to be recomputed.
+ * - `checked`: the computed signal is checked and needs to be recomputed.
+ * - `computing`: the computed signal is currently being computed.
+ * - `clean`: the computed signal is clean and does not need to be recomputed.
+ */
+declare type ComputedState = 'dirty' | 'checked' | 'computing' | 'clean';
+
 /**
  * Runs a side-effectful function and automatically re-runs it whenever any
  * Signal read during its execution changes.
@@ -251,4 +319,176 @@ export declare function loadSignals(options?: {
     devMode?: boolean;
 }): void;
 
+/**
+ * A function that compares two values of type `T` and returns `true` if they are considered equal, or `false` otherwise.
+ * This function is used to determine if a signal's value has changed and if dependent computations need to be re-evaluated.
+ */
+export declare type SignalEqual<T> = (this: State<T> | Computed<T>, t: any, t2: any) => boolean;
+
+export declare type SignalOptions<T> = {
+    /**
+     * Custom comparison function between old and new value. Default: Object.is.
+     * The signal is passed in as the this value for context.
+     */
+    equals?: SignalEqual<T>;
+    /**
+     * Callback called when isWatched becomes true, if it was previously false
+     */
+    watched?: (this: State<T> | Computed<T>) => void;
+    /**
+     * Callback called whenever isWatched becomes false, if it was previously true
+     */
+    unwatched?: (this: State<T> | Computed<T>) => void;
+};
+
+declare class State<T = any> {
+    #private;
+    /* Excluded from this release type: getSinks */
+    /**
+     * Creates a new `State` signal.
+     *
+     * @param initialValue - The initial value of the signal.
+     * @param options - Optional configuration:
+     *   - `equals` — custom equality function; defaults to `Object.is`.
+     *   - `watched` — called when the signal gains its first sink.
+     *   - `unwatched` — called when the signal loses its last sink.
+     *
+     * @see Signal algorithms — 'Constructor: Signal.State(initialValue, options)'
+     */
+    constructor(initialValue: T, options?: SignalOptions<T>);
+    /**
+     * Returns the current value of the signal, registering this Signal as a
+     * source of the innermost `Computed` currently being evaluated (if any).
+     *
+     * @throws If `frozen` is `true` — reads are forbidden while a protected
+     * callback (`notify`, `watched`, `unwatched`) is executing.
+     *
+     * @see Signal algorithms — 'Method: Signal.State.prototype.get()'
+     */
+    get(): T;
+    /**
+     * Updates the signal's value and propagates changes to all dependent
+     * sinks.
+     *
+     * If `equals(currentValue, newValue)` returns `true` the call is a no-op
+     * and no propagation occurs. Otherwise `#value` is updated, all direct
+     * `Computed` sinks are marked `~dirty~`, indirect ones `~checked~`, and
+     * each reachable `Watcher` has its `notify` callback invoked synchronously
+     * (with `frozen = true`).
+     *
+     * @param newValue - The new value to set.
+     * @throws If `frozen` is `true` — writes are forbidden while a protected
+     * callback is executing.
+     *
+     * @see Signal algorithms — 'Method: Signal.State.prototype.set(newValue)'
+     * @see Algorithm — 'Set Signal value'
+     */
+    set(newValue: T): void;
+    /* Excluded from this release type: addSink */
+    /* Excluded from this release type: removeSink */
+}
+
+/**
+ * A `Watcher` observes a set of Signals and fires a `notify` callback
+ * synchronously when any of their (recursive) dependencies change.
+ *
+ * It is the low-level primitive on top of which frameworks implement
+ * effects and scheduling. It does not hold a value and has no generic
+ * type parameter.
+ *
+ * @see Signal algorithms — 'The `Signal.subtle.Watcher` class'
+ */
+declare class Watcher {
+    #private;
+    /* Excluded from this release type: getSources */
+    /**
+     * Creates a new Watcher.
+     *
+     * The Watcher starts in the `~waiting~` state with an empty signals set.
+     *
+     * @param notifyCallback - Called synchronously (with `frozen = true`) the
+     * first time a watched dependency changes after each `watch` call. No
+     * Signals may be read or written inside this callback.
+     *
+     * @see Signal algorithms — 'Constructor: new Signal.subtle.Watcher(callback)'
+     */
+    constructor(notifyCallback: NoArgsVoidFunction);
+    /**
+     * Returns the subset of watched Signals that are `Computed` instances
+     * currently in a `~dirty~` or `~checked~` state, meaning they may have a
+     * stale value that has not yet been re-evaluated.
+     *
+     * Typically called inside the microtask scheduled by the `notify` callback
+     * to know which Signals need to be pulled.
+     *
+     * @returns An array of `Computed` signals that are dirty or checked.
+     *
+     * @see Signal algorithms — 'Method: Signal.subtle.Watcher.prototype.getPending()'
+     */
+    getPending(): Computed<unknown>[];
+    /**
+     * Adds the given Signals to the watched set and transitions the Watcher to
+     * the `~watching~` state.
+     *
+     * For each newly-watched Signal, the Watcher is registered as a sink and —
+     * if it is the first sink — the sink registration is propagated recursively
+     * up through the Signal's sources, building the live dependency chain.
+     *
+     * The `watched` callback of each Signal (if any) is called with
+     * `frozen = true`.
+     *
+     * @param signals - One or more `State` signals to start watching.
+     * @throws If `frozen` is `true` at the time of the call.
+     *
+     * @see Signal algorithms — 'Method: Signal.subtle.Watcher.prototype.watch(...signals)'
+     */
+    watch(...signals: (State | Computed)[]): void;
+    /**
+     * Removes the given Signals from the watched set.
+     *
+     * For each removed Signal, the Watcher is unregistered as a sink. If the
+     * Signal's sink set becomes empty as a result, the removal is propagated
+     * recursively up through its sources, tearing down the live dependency
+     * chain and allowing garbage collection of unwatched nodes.
+     *
+     * The `unwatched` callback of each Signal (if any) is called with
+     * `frozen = true`.
+     *
+     * If no Signals remain in the watched set, the Watcher transitions back to
+     * the `~waiting~` state.
+     *
+     * @param signals - One or more `State` signals to stop watching.
+     * @throws If `frozen` is `true` at the time of the call.
+     * @throws If any of the given Signals is not currently being watched.
+     *
+     * @see Signal algorithms — 'Method: Signal.subtle.Watcher.prototype.unwatch(...signals)'
+     */
+    unwatch(...signals: (State | Computed)[]): void;
+    /**
+     * Get the current state of the Watcher.
+     * @param symbol - The private symbol for prevent external calls.
+     */
+    getState(symbol: symbol): WatcherState;
+    /**
+     * Set the current state of the Watcher.
+     * @param newState - The new state to set.
+     * @param symbol - The private symbol for prevent external calls.
+     * @throws If the transition from `pending` to `watching` is attempted.
+     */
+    setState(newState: WatcherState, symbol: symbol): void;
+    /**
+     * Invoce the notify callback when a watched dependency changes
+     * @param symbol - The private symbol for prevent external calls.
+     */
+    notify(symbol: symbol): void;
+}
+
+/**
+ * Type of the state of a watcher.
+ * - `waiting`: The watcher is waiting for its dependencies to change.
+ * - `watching`: The watcher is currently watching its dependencies for changes.
+ * - `pending`: The watcher has been notified of a change and is pending re-evaluation.
+ */
+declare type WatcherState = 'waiting' | 'watching' | 'pending';
+
 export { }