@xaendar/signals 0.0.4 → 0.1.6

package/src/lib/models/watcher.ts

@@ -1,229 +0,0 @@
-import { NoArgsVoidFunction } from '@xaendar/common';
-import { GLOBAL_STATE } from '../globals';
-import { PRIVATE, assertPrivateContext } from '../private-symbol';
-import { WatcherState } from '../types/watcher-state.type';
-import { Computed } from './computed';
-import { State } from './state';
-
-/**
- * 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'
- */
-export class Watcher {
-  /**
-   * The current state of the Watcher.
-   *
-   * - `~waiting~`  — newly created, or `notify` has already been called since
-   *                  the last `watch` call. Not actively observing changes.
-   * - `~watching~` — actively watching; no dependency has changed yet.
-   * - `~pending~`  — a dependency has changed but `notify` has not yet run.
-   *
-   * @internalSlot
-   * @see Signal algorithms — 'Signal.subtle.Watcher State machine'
-   */
-  #state: WatcherState;
-  /**
-   * The ordered set of Signals this Watcher is currently watching.
-   * May contain both `State` and `Computed` instances.
-   *
-   * @internalSlot
-   * @see Signal algorithms — 'Signal.subtle.Watcher internal slots'
-   */
-  #signals: Set<State<unknown> | Computed<unknown>>;
-  /**
-   * Returns a snapshot of the current watched signals set for introspection.
-   *
-   * @param symbol - Private access symbol; rejects calls from outside the library.
-   * @returns An array of `State` and `Computed` instances that this Watcher is watching.
-   * @internal
-   */
-  public getSources(symbol: symbol): (State<unknown> | Computed<unknown>)[] {
-    assertPrivateContext(symbol);
-    return [...this.#signals];
-  }
-  /**
-   * The callback invoked synchronously when a watched Signal (or one of its
-   * recursive dependencies) changes for the first time since the last
-   * `watch` call.
-   *
-   * Receives the Watcher itself as `this`. No Signals may be read or written
-   * during its execution (`frozen` is `true` for its entire duration).
-   *
-   * @internalSlot
-   * @see Signal algorithms — 'Signal.subtle.Watcher internal slots'
-   */
-  #notifyCallback: NoArgsVoidFunction;
-
-  /**
-   * 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) {
-    this.#state = 'waiting';
-    this.#signals = new Set;
-    this.#notifyCallback = notifyCallback;
-  }
-
-  /**
-   * 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()'
-   */
-  public getPending(): Computed<unknown>[] {
-    return [...this.#signals].filter((signal): signal is Computed<unknown> => {
-      if (!(signal instanceof Computed)) {
-        return false;
-      }
-
-      const state = signal.getState(PRIVATE);
-      return state === 'dirty' || state === 'checked';
-    });
-  }
-
-  /**
-   * 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)'
-   */
-  public watch(...signals: (State | Computed)[]) {
-    if (GLOBAL_STATE.frozen) {
-      throw new Error('Cannot watch signals while frozen');
-    }
-
-    signals.forEach(signal => {
-      if (this.#signals.has(signal)) {
-        throw new Error('Cannot watch a signal that is already being watched');
-      }
-
-      this.#signals.add(signal)
-      signal.addSink(this, PRIVATE);
-    });
-
-
-    if (this.#state === 'waiting') {
-      this.#state = 'watching';
-    }
-  }
-
-  /**
-   * 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)'
-   */
-  public unwatch(...signals: (State | Computed)[]) {
-    if (GLOBAL_STATE.frozen) {
-      throw new Error('Cannot unwatch signals while frozen');
-    }
-
-    signals.forEach(signal => {
-      if (this.#signals.has(signal)) {
-        throw new Error('Cannot unwatch a signal that is not being watched');
-      }
-
-      this.#signals.delete(signal)
-      signal.removeSink(this, PRIVATE);
-    });
-
-    if (!this.#signals.size && this.#state === 'watching') {
-      this.#state = 'waiting';
-    }
-  }
-
-  /**
-   * Get the current state of the Watcher.
-   * @param symbol - The private symbol for prevent external calls.
-   */
-  public getState(symbol: symbol): WatcherState {
-    assertPrivateContext(symbol);
-    return this.#state;
-  }
-
-  /**
-   * 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.
-   */
-  public setState(newState: WatcherState, symbol: symbol): void {
-    assertPrivateContext(symbol);
-
-    if (this.#state !== newState && this.#isValidTransition(this.#state, newState)) {
-      this.#state = newState;
-    }
-  }
-
-  /**
-   * Invoce the notify callback when a watched dependency changes
-   * @param symbol - The private symbol for prevent external calls.
-   */
-  public notify(symbol: symbol): void {
-    assertPrivateContext(symbol);
-
-    this.#state = 'pending';
-
-    GLOBAL_STATE.frozen = true;
-    try {
-      this.#notifyCallback.call(this);
-    } finally {
-      this.#state = 'waiting'; 
-      GLOBAL_STATE.frozen = false;
-    }
-  }
-
-  #isValidTransition(from: WatcherState, to: WatcherState): boolean {
-    switch (from) {
-      case 'waiting':
-        return to === 'watching';
-      case 'watching':
-        return to === 'pending' || to === 'waiting';
-      case 'pending':
-        return to === 'waiting';
-    }
-  }
-}

package/src/lib/private-symbol.ts

@@ -1,24 +0,0 @@
-/**
- * Symbol not available in public API,
- * used to call internal methods of `State` and `Computed` from `Watcher` without exposing them in the public API.
- *
- * @internal
- */
-export const PRIVATE = Symbol('signals-private');
-
-/**
- * Asserts that the provided symbol matches the internal {@link PRIVATE} symbol,
- * ensuring the caller has access to internal APIs.
- *
- * Throws if the symbol does not match, preventing external code from
- * invoking methods intended for internal use only.
- *
- * @param symbol - The symbol to validate against {@link PRIVATE}.
- * @throws {Error} If `symbol` does not match {@link PRIVATE}.
- * @internal
- */
-export function assertPrivateContext(symbol: symbol): void {
-  if (symbol !== PRIVATE) {
-    throw new Error('Invalid symbol');
-  }
-}

package/src/lib/subtle.ts

@@ -1,79 +0,0 @@
-import { GLOBAL_STATE } from './globals';
-import { Computed } from './models/computed';
-import { State } from './models/state';
-import { Watcher } from './models/watcher';
-import { PRIVATE } from './private-symbol';
-
-/**
- * Executes a function without tracking any dependencies.
- * @param fn - The function to execute without tracking.
- * @returns The result of the function execution.
- */
-export function untrack<T>(fn: () => T): T {
-  const prevComputing = GLOBAL_STATE.computing;
-  GLOBAL_STATE.computing = null;
-
-  try {
-    return fn();
-  } finally {
-    GLOBAL_STATE.computing = prevComputing;
-  }
-}
-
-/**
- * Returns the currently active `Computed` instance being evaluated, or `null`
- * @returns The currently active `Computed` instance, or `null` if none is being evaluated.
- */
-export function currentComputed(): Computed | null {
-  return GLOBAL_STATE.computing;
-}
-
-/**
- * Returns the ordered list of all Signals which the given `Computed` or
- * `Watcher` referenced during its last evaluation.
- *
- * - For a `Computed`, these are the Signals read inside its callback.
- * - For a `Watcher`, these are the Signals it is currently watching.
- *
- * @param s - The `Computed` or `Watcher` to introspect.
- * @returns An array of `State` and `Computed` instances.
- */
-export function introspectSources(s: Computed | Watcher): (State | Computed)[] {
-  return s.getSources(PRIVATE);
-}
-
-/**
- * Returns the direct dependents of the given Signal — Watchers that contain
- * it, plus any `Computed` Signals which read it during their last evaluation
- * (if that `Computed` is recursively watched).
- *
- * @param signal - The `State` or `Computed` Signal to introspect.
- * @returns An array of `Computed` and `Watcher` instances.
- */
-export function introspectSinks(signal: State | Computed): (Computed | Watcher)[] {
-  return signal.getSinks(PRIVATE);
-}
-
-/**
- * Returns `true` if the given Signal is 'live' — i.e. it is watched by a
- * `Watcher`, or it is read by a `Computed` Signal which is (recursively)
- * live.
- *
- * @param signal - The `State` or `Computed` Signal to check.
- * @returns `true` if the Signal has at least one sink.
- */
-export function hasSinks(signal: State | Computed): boolean {
-  return signal.getSinks(PRIVATE).length > 0;
-}
-
-/**
- * Returns `true` if the given node is 'reactive' — i.e. it depends on some
- * other Signal. A `Computed` where `hasSources` is `false` will always
- * return the same constant.
- *
- * @param signal - The `Computed` or `Watcher` to check.
- * @returns `true` if the node has at least one source.
- */
-export function hasSources(signal: Computed | Watcher): boolean {
-  return signal.getSources(PRIVATE).length > 0;
-}

package/src/lib/types/computed-state.type.ts

@@ -1,9 +0,0 @@
-/**
- * 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.
- */
-export type ComputedState = 'dirty' | 'checked' | 'computing' | 'clean';

package/src/lib/types/global-state.type.ts

@@ -1,42 +0,0 @@
-import { Computed } from '../models/computed';
-
-export type GlobalState = {
-  /**
-   * The innermost `Signal.Computed` (or effect Signal) currently being
-   * re-evaluated as a side-effect of a `.get()` call.
-   *
-   * All Signal reads that occur while this is non-null will register
-   * themselves as sources of this computed, enabling automatic dependency
-   * tracking.
-   *
-   * Set to `null` when no computed is being evaluated (i.e. a 'root' read).
-   *
-   * @see Signal algorithms — 'Hidden global state'
-   */
-  computing: Computed | null;
-  /**
- * Whether a callback is currently executing that requires the Signal graph
- * to remain unmodified for the duration of its execution.
- *
- * When `true`, any attempt to read or write a Signal will throw an exception.
- * This prevents the graph from being mutated while it is being traversed,
- * which would risk exposing inconsistent or half-processed state.
- *
- * Set to `true` immediately before invoking:
- * - The `notify` callback of a `Signal.subtle.Watcher` (during `State.prototype.set`)
- * - The `watched` callback (during `Watcher.prototype.watch`)
- * - The `unwatched` callback (during `Watcher.prototype.unwatch`)
- *
- * Restored to `false` in a `finally` block after each such callback returns
- * (or throws), guaranteeing the flag is never left permanently set.
- *
- * Note: `Signal.subtle.untrack` does NOT clear this flag — frozen is always
- * respected regardless of tracking context.
- *
- * @see Signal algorithms — 'Hidden global state'
- * @see Method: `Signal.State.prototype.set`
- * @see Method: `Signal.subtle.Watcher.prototype.watch`
- * @see Method: `Signal.subtle.Watcher.prototype.unwatch`
- */
-  frozen: boolean;
-};

package/src/lib/types/signal-equal.type.ts

@@ -1,8 +0,0 @@
-import { Computed } from "../models/computed";
-import { State } from "../models/state";
-
-/**
- * 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 type SignalEqual<T> = (this: State<T> | Computed<T>, t: T, t2: T) => boolean;

package/src/lib/types/signal-options.type.ts

@@ -1,19 +0,0 @@
-import { Computed } from '../models/computed';
-import { State } from '../models/state';
-import { SignalEqual } from './signal-equal.type';
-
-export 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;
-}

package/src/lib/types/watcher-state.type.ts

@@ -1,7 +0,0 @@
-/**
- * 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.
- */
-export type WatcherState = 'waiting' | 'watching' | 'pending';

package/src/public-api.ts

@@ -1 +0,0 @@
-export * from './lib/load-signals';

package/tsconfig.json

@@ -1,3 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-}

package/vite.config.ts

@@ -1,16 +0,0 @@
-import { readFileSync, writeFileSync } from 'node:fs';
-import { defineConfig } from 'vite';
-import getViteConfig from '../../vite-config';
-
-export default defineConfig(getViteConfig('@xaendar/signals', __dirname, {
-  plugins: [
-    {
-      name: 'types',
-      writeBundle() {
-        const content = readFileSync('../packages/signals/src/globals.d.ts', 'utf-8');
-        const dtsContent = readFileSync('../dist/@xaendar/signals/xaendar-signals.es.d.ts', 'utf-8');
-        writeFileSync('../dist/@xaendar/signals/xaendar-signals.es.d.ts', `${content}\n\n${dtsContent}`);
-      }
-    }
-  ]
-}));