@zakkster/lite-signal 1.0.4 → 1.0.6

package/README.md

@@ -448,6 +448,34 @@ npm run verify   # test + test:gc + a sanity bench
 
 ---
 
+## Performance Trade-offs & Topology Scaling
+
+`lite-signal` was built with a strict mandate: **absolute zero garbage collection**. By packing the dependency graph into a flat, pre-allocated memory arena, we eliminate the Scavenger GC pauses that plague 120fps Canvas/WebGL loops.
+
+However, flat arrays come with a mathematical trade-off. While memory allocation is $O(1)$, modifying a flat array during dynamic dependency churn requires $O(N)$ linear scans. 
+
+**Andrii Volynets** (author of the phenomenal [Alien Signals](https://github.com/stackblitz/alien-signals)) generously ran `lite-signal` through his advanced topology matrix. The results clearly highlight where the zero-GC flat-array architecture excels, and where pointer-based graphs (like Alien/Reflex) take the lead:
+
+#### 1. Stable Topologies (Fan-in / Fan-out / Broadcast)
+In stable environments (typical of game engines, particle systems, and visualizers), `lite-signal` is blisteringly fast and maintains a near-zero allocation profile, keeping frame times perfectly flat.
+
+#### 2. Dynamic Topologies (Web Apps / Layered DAGs)
+In highly chaotic graphs with branch switching, selective reads, and wide dense churn (typical of large DOM-based web frameworks like Vue or React), the $O(N)$ edge traversal cost of flat arrays becomes the dominant bottleneck.
+
+*Andrii's benchmark results for dynamic topologies:*
+| Scenario | alien-signals | reflex | lite-signal |
+| :--- | :--- | :--- | :--- |
+| **1000x12 (4 sources, dynamic)** | 184ms | 194ms | 2031ms |
+| **1000x5 (25 sources, wide/dense)** | 304ms | 303ms | 1746ms |
+| **64x6 (selective dynamic DAG)** | 181ms | 196ms | 559ms |
+
+**The Takeaway:** "Zero-GC" and "topology scalability" are orthogonal dimensions. If you are building a DOM framework with massive dynamic `v-if` churn, use Alien Signals. If you are building a 120fps Canvas game with a stable scene graph where any GC pause is a dropped frame, use `lite-signal`.
+
+### Roadmap: v1.1
+We are actively working on a v1.1 architectural update to address this topology degradation while maintaining the zero-GC contract. By moving to a version-stamped dependency reconciliation pass (`lastSeenInEval`) with a pre-allocated scratch buffer, we expect to drop dynamic read costs to $O(1)$ unconditionally.
+
+---
+
 ## What this is not
 
 - **A virtual DOM, JSX runtime, or rendering library.** It's the substrate. Plug it under whatever rendering layer you like.

package/Signal.d.ts

@@ -165,3 +165,37 @@ export function batch<T>(fn: () => T): T;
 export function untrack<T>(fn: () => T): T;
 export function onCleanup(fn: () => void): void;
 export function stats(): RegistryStats;
+
+
+/**
+ * Configuration options for the watch utility.
+ */
+export interface WatchOptions {
+    /** * If true, fires the callback immediately upon registration
+     * with `oldValue` set to `undefined`.
+     */
+    immediate?: boolean;
+}
+
+/**
+ * Track a reactive source and run a callback whenever its evaluated value changes.
+ *
+ * Models Vue's `watch(source, callback)` and MobX's `reaction(predicate, effect)`.
+ * Internal reads inside the callback are untracked — they do not create reactive
+ * dependencies.
+ *
+ * @example
+ * const count = signal(0);
+ * const stop = watch(() => count() * 2, (next, prev) => {
+ * console.log(`Doubled count changed: ${prev} -> ${next}`);
+ * });
+ * * @param source    A function that reads reactive values (e.g., a signal/computed getter).
+ * @param callback  Fired when the source's value changes. Receives the new and previous values.
+ * @param options   Optional configuration (e.g., `{ immediate: true }`).
+ * @returns         Dispose function — call to stop watching and release the effect.
+ */
+export function watch<T>(
+    source: () => T,
+    callback: (newValue: T, oldValue: T | undefined) => void,
+    options?: WatchOptions
+): () => void;

package/Signal.js

@@ -1004,4 +1004,10 @@ export function onCleanup(fn) {
 /** @type {Registry["stats"]} */
 export function stats() {
     return defaultRegistry.stats();
-}
+}
+
+/**
+ * Re-export of the user-land watch utility.
+ * @see {@link watch} in Watch.js for full implementation details.
+ */
+export {watch} from "./Watch.js"

package/Watch.js

@@ -0,0 +1,72 @@
+import { effect, untrack } from "./Signal.js";
+
+/**
+ * Sentinel for "first run" — distinguishes a legitimate `undefined` source value
+ * from the uninitialized state. Using `Symbol` instead of `undefined` ensures a
+ * source like `signal(undefined)` correctly fires `callback(undefined, undefined)`
+ * on first change rather than being treated as never-changed.
+ * @private
+ */
+const UNINITIALIZED = Symbol("watch.uninitialized");
+
+/**
+ * Track a reactive source and run a callback whenever its value changes.
+ *
+ * Models Vue's `watch(source, callback)` and MobX's `reaction(predicate, effect)`.
+ * The callback is invoked with `(newValue, oldValue)`. Internal reads inside the
+ * callback are untracked — they don't create reactive dependencies — so a callback
+ * that reads other signals to perform a side-effect won't re-fire when those
+ * unrelated signals change.
+ *
+ * Disposing the returned function detaches the underlying effect and stops the
+ * watcher.
+ *
+ * @example
+ *   const count = signal(0);
+ *   const stop = watch(count, (next, prev) => {
+ *       console.log(`count changed: ${prev} -> ${next}`);
+ *   });
+ *   count.set(1);  // logs: "count changed: 0 -> 1"
+ *   count.set(2);  // logs: "count changed: 1 -> 2"
+ *   stop();
+ *   count.set(3);  // no log
+ *
+ * @example
+ *   // Immediate fires the callback once on registration with `oldValue = undefined`
+ *   watch(count, (next, prev) => console.log(next), { immediate: true });
+ *
+ * @param {() => T} source        A function that reads reactive values (typically a
+ *                                signal/computed getter, or a closure combining several).
+ * @param {(newValue: T, oldValue: T | undefined) => void} callback
+ *                                Called when the source's value changes. Receives the
+ *                                new and previous values. Internal reads are untracked.
+ * @param {{ immediate?: boolean }} [options]
+ *                                `immediate: true` runs the callback once on registration
+ *                                with `oldValue = undefined`. Defaults to false.
+ * @returns {() => void}          Dispose function — call to stop watching.
+ * @template T
+ */
+export function watch(source, callback, options) {
+    const immediate = options !== undefined && options.immediate === true;
+    let oldValue = UNINITIALIZED;
+
+    return effect(() => {
+        // Track the source — this read registers the dependency.
+        const newValue = source();
+
+        // Invoke the callback without registering further dependencies.
+        untrack(() => {
+            if (oldValue === UNINITIALIZED) {
+                if (immediate) callback(newValue, undefined);
+            } else if (!Object.is(newValue, oldValue)) {
+                // Guard for raw inline getters: the effect re-runs whenever any read
+                // dep changes, but the projected source value may be unchanged. Vue's
+                // `watch` and MobX's `reaction` both short-circuit here. Wrapping the
+                // source in a `computed` would also suppress this via the equality
+                // check inside computed itself; the guard makes that wrapping optional.
+                callback(newValue, oldValue);
+            }
+            oldValue = newValue;
+        });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-signal",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Zero-GC reactive graph. Monomorphic object pool, versioned push-pull propagation, 32-bit modular versioning. Built for hot paths and long-running processes.",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "license": "MIT",
@@ -18,6 +18,7 @@
   "files": [
     "Signal.js",
     "Signal.d.ts",
+    "Watch.js",
     "README.md",
     "llms.txt",
     "LICENSE.txt"