@zakkster/lite-signal 1.1.1 → 1.1.2

package/README.md

@@ -476,7 +476,7 @@ The "0 per fire" property for `watch` is deliberate engineering — the inner `u
 
 ### Tree-shaking
 
-All three primitives live in a separate module (`src/watch.js`) and are re-exported from the main entry. If your bundle doesn't import them, they won't appear in the output — modern ESM tree-shaking (Vite, Rollup, esbuild) handles this reliably.
+All three primitives live in a separate module (`Watch.js`) and are re-exported from the main entry (which binds them to its own `effect`/`untrack`, so there is exactly one engine instance). If your bundle doesn't import them, they won't appear in the output — modern ESM tree-shaking (Vite, Rollup, esbuild) handles this reliably.
 
 ---
 
@@ -537,7 +537,7 @@ Three tiers, all reproducible.
 
 ### Tier 1 — Behavior (unit tests, fast)
 
-`npm test` runs the suite in `test/`. 131 tests across 43 suites covering:
+`npm test` runs the suite in `test/`, covering:
 
 - **`01-core.test.mjs`** — signal/computed/effect basics, equality semantics, NaN/±0, subscribe/peek/update, untrack, batch, cleanup ordering, first-run error recovery, nested object reference-identity gotchas.
 - **`02-topology.test.mjs`** — diamond glitch-freedom, 256-deep and 1024-deep computed chains, wide fan-out (1000 effects from one signal), dynamic dependency switching, conditional fan-out, nested effects, cycle detection (`CycleError`).
@@ -705,11 +705,19 @@ function spawnPlugin(pluginCode) {
 
 ## Conformance
 
-lite-signal v1.1.0 was evaluated against the
+lite-signal is evaluated against the
 [reactive-framework-test-suite](https://github.com/johnsoncodehk/reactive-framework-test-suite),
 the most comprehensive behavioral test battery for JavaScript reactive
 libraries.
 
+As of **v1.1.2**, the conformance items that were open at v1.1.0 — batch revert
+detection (#123 / #132 / #147), throw isolation in flush (#121), and
+inner-write propagation through computed chains (#180 / #213) — are **closed**
+(landed in v1.1.1). The remaining gaps are one deliberate design choice (#179,
+below) and the owner-tree items (#209 / #210), which land with the v1.2
+ownership hybrid. The exact post-1.1.1 pass count is being re-run against the
+upstream suite; per-test results and the runner adapter live in `/conformance/`.
+
 **174 of 177 tests pass (98.3%)**, placing lite-signal **in a tie for second place of sixteen**
 evaluated libraries — just behind alien-signals (177).
 
@@ -732,23 +740,9 @@ more useful to library users than a green checkmark.
 - **Auto-unsubscribe** on first-run effect throws — matches preact, reatom,
   solid. Half the field leaks the subscription.
 
-### What v1.1.0 doesn't do yet
-
-10 tests fail. We've categorized them by intent.
-
-**Targeted for v1.2** (6 tests):
+### What lite-signal does NOT do yet
 
-- **Revert detection inside batches** (#147, #132, #123): writes inside a
-  `batch()` that net to no change still mark dependents as dirty. Vue,
-  Solid, Mobx, and roughly half the field share this behavior. v1.2 will
-  capture pre-batch values per signal and skip propagation on revert.
-- **Throw isolation in batch flush** (#121): if an effect throws during
-  flush, lite-signal currently halts the flush. v1.2 will collect errors,
-  finish the flush, then re-throw as `AggregateError`.
-- **Inner-write propagation through computed chains** (#180, #213): two
-  specific propagation paths where lite-signal disagrees with the field.
-  Both are propagation-order bugs in the recursive computed resolver,
-  not zero-GC tradeoffs.
+The remaining open items, by intent.
 
 **Design choices we will not change** (2 tests):
 
@@ -760,13 +754,14 @@ more useful to library users than a green checkmark.
   effect's own implicit batching. Most libraries behave this way. Wrap the
   batch outside the effect for the intended semantics.
 
-**Opt-in feature, deferred** (2 tests):
+**Landing in v1.2** (2 tests):
 
 - **Solid-style cascading disposal of nested effects** (#209, #210):
-  lite-signal does not maintain an owner tree of parent-child effects.
-  This matches preact, vue, mobx, the TC39 polyfill, Angular, Svelte,
-  tansu, and Solid 1.x. Solid 2 / @solidjs/signals, reatom, and anod
-  implement it. If you need it, please open an issue.
+  the baseline 1.1.x engine maintains no owner tree of parent-child
+  effects — matching preact, vue, mobx, the TC39 polyfill, Angular,
+  Svelte, tansu, and Solid 1.x. The v1.2 ownership hybrid adds an
+  owner tree so nested effects/computeds auto-dispose with their parent;
+  the #209 / #210 conformance tests are wired and skipped until then.
 
 Per-test results, the runner adapter, and reproductions live in
 `/conformance/`.

package/Signal.d.ts

@@ -1,7 +1,7 @@
 /**
  * @zakkster/lite-signal — zero-GC reactive graph.
  *
- * Public type surface for the JavaScript implementation in `src/index.js`.
+ * Public type surface for the JavaScript implementation in `Signal.js`.
  */
 
 // ─── Options ──────────────────────────────────────────────────────────────────
@@ -115,7 +115,7 @@ export interface RegistryConfig {
      *  - `"grow"`: double the pool. Links are bounded by `maxLinks * 16`.
      */
     onCapacityExceeded?: "throw" | "grow";
-    /** Max effect-queue drain passes before a {@link CycleError} is thrown. Default: 100. */
+    /** Max effect-queue drain passes before a flush-cycle `Error` (message prefixed `"CycleError:"`) is thrown. Default: 100. */
     maxFlushPasses?: number;
 }
 
@@ -177,24 +177,24 @@ export interface WatchOptions {
     immediate?: boolean;
 }
 
-//**
-* Track a reactive source and run a callback whenever its projected value
-* changes. The callback receives `(newValue, oldValue, stop)` — the third
-* argument is a dispose function that can be called from inside the callback
-* to terminate the watcher.
-*
-* Internal reads inside the callback are untracked.
-*
-* Uses `Object.is` to guard against the raw-getter case where a dep mutation
-* fires the effect but the projected value is unchanged.
-*
-* @param source    Reactive read function.
-* @param callback  Called with the new and previous values plus a stop handle.
-* @param options   `immediate: true` runs the callback once on registration
-*                  with `oldValue = undefined`.
-* @returns Dispose function. Idempotent and safe to call at any time, including
-*          synchronously during the immediate callback.
-*/
+/**
+ * Track a reactive source and run a callback whenever its projected value
+ * changes. The callback receives `(newValue, oldValue, stop)` — the third
+ * argument is a dispose function that can be called from inside the callback
+ * to terminate the watcher.
+ *
+ * Internal reads inside the callback are untracked.
+ *
+ * Uses `Object.is` to guard against the raw-getter case where a dep mutation
+ * fires the effect but the projected value is unchanged.
+ *
+ * @param source    Reactive read function.
+ * @param callback  Called with the new and previous values plus a stop handle.
+ * @param options   `immediate: true` runs the callback once on registration
+ *                  with `oldValue = undefined`.
+ * @returns Dispose function. Idempotent and safe to call at any time, including
+ *          synchronously during the immediate callback.
+ */
 export function watch<T>(
     source: () => T,
     callback: (newValue: T, oldValue: T | undefined, stop: () => void) => void,

package/Signal.js

@@ -1,5 +1,5 @@
 /**
- * @zakkster/lite-signal
+ * @zakkster/lite-signal v1.1.2
  * --------------------
  * Zero-GC reactive graph.
  *
@@ -143,10 +143,10 @@ export function createRegistry(config = {}) {
     const NODE_PTR = Symbol("node_ptr");
     const NODE_GEN = Symbol("node_gen");
 
-    let currentNodesCapacity = config.maxNodes || 1024;
-    let currentLinkCapacity = config.maxLinks || currentNodesCapacity * 4;
-    const policy = config.onCapacityExceeded || "throw";
-    const maxFlushPasses = config.maxFlushPasses || 100;
+    let currentNodesCapacity = config.maxNodes ?? 1024;
+    let currentLinkCapacity = config.maxLinks ?? currentNodesCapacity * 4;
+    const policy = config.onCapacityExceeded ?? "throw";
+    const maxFlushPasses = config.maxFlushPasses ?? 100;
     const maxLinkLimit = currentLinkCapacity * 16;
 
     // --- ZERO-GC OBJECT POOLS ---
@@ -440,19 +440,21 @@ export function createRegistry(config = {}) {
      * @private
      */
     function markDownstream(startNode) {
-        let stackLen = 0 | 0;
-        markStack[stackLen] = startNode;
-        stackLen = (stackLen + 1) | 0;
+        let stackLen = 0;
+        markStack[stackLen++] = startNode;
 
-        while (stackLen > 0) {
-            stackLen = (stackLen - 1) | 0;
-            const n = markStack[stackLen];
+        while (stackLen !== 0) {
+            const n = markStack[--stackLen];
 
             let link = n.headSub;
             while (link !== null) {
                 const t = link.target;
                 if ((t.markEpoch | 0) !== (globalVersion | 0)) {
                     t.markEpoch = globalVersion | 0;
+                    // flags read stays INSIDE the markEpoch guard on purpose: hoisting it
+                    // above the guard would load t.flags for every already-marked revisit
+                    // too, adding work on exactly the dedup-skip path that markEpoch exists
+                    // to make cheap (diamond / shared-computed fan-out).
                     const flags = t.flags | 0;
 
                     if ((flags & FLAG_EFFECT) !== 0) {
@@ -461,14 +463,12 @@ export function createRegistry(config = {}) {
                         // writes (directly or through computed chains). The effect's evalVersion
                         // is bumped to the post-write globalVersion in its executeEffect finally,
                         // so subsequent unrelated writes still propagate normally.
-                        if ((flags & FLAG_QUEUED) === 0 && (flags & FLAG_COMPUTING) === 0) {
+                        if ((flags & (FLAG_QUEUED | FLAG_COMPUTING)) === 0) {
                             t.flags = flags | FLAG_QUEUED;
-                            activeQueue[activeQueueLen] = t;
-                            activeQueueLen = (activeQueueLen + 1) | 0;
+                            activeQueue[activeQueueLen++] = t;
                         }
                     } else {
-                        markStack[stackLen] = t;
-                        stackLen = (stackLen + 1) | 0;
+                        markStack[stackLen++] = t;
                     }
                 }
                 link = link.nextSub;
@@ -732,14 +732,28 @@ export function createRegistry(config = {}) {
      *        Equality predicate. Returning true short-circuits notification.
      * @returns {Signal<T>}
      */
-    function signal(initial, opts = {}) {
+    function signal(initial, opts) {
         const node = createNode(initial, FLAG_SIGNAL);
-        node.equals = opts.equals !== undefined ? opts.equals : Object.is;
+        // Read opts defensively instead of defaulting to `= {}`: the default allocates
+        // a throwaway object on every no-opts call (the common path) — pure nursery
+        // garbage when mounting many signals.
+        node.equals = (opts !== undefined && opts.equals !== undefined) ? opts.equals : Object.is;
         node.version = globalVersion | 0;
         statSignals = (statSignals + 1) | 0;
 
         const read = () => {
-            if (isTrackingDeps && currentObserver !== null) allocateLink(node, currentObserver);
+            if (isTrackingDeps && currentObserver !== null) {
+                // Inlined cursor fast-path: on stable read order this matches every
+                // time, so we skip a call into the (large, non-inlinable) allocateLink
+                // frame entirely. Only a cursor miss falls through to the cold path,
+                // where allocateLink re-reads the cursor for its relink logic.
+                const expected = activeObserverCurrentDep;
+                if (expected !== null && expected.source === node) {
+                    activeObserverCurrentDep = expected.nextDep;
+                } else {
+                    allocateLink(node, currentObserver);
+                }
+            }
             return node.value;
         };
         read.peek = () => node.value;
@@ -774,11 +788,21 @@ export function createRegistry(config = {}) {
         read.update = (fn) => read.set(fn(node.value));
 
         read.subscribe = (fn) => {
-            let captured;
-            const invokeSub = () => fn(captured);
+            // Single-closure subscription: the read is tracked (it establishes the
+            // dependency), then fn runs untracked. untrack() is inlined here to (a) drop
+            // the second per-subscription closure and (b) save an untrack()+wrapper call
+            // on every fire, not just at setup.
+            // COUPLING: this duplicates untrack()'s isTrackingDeps save/restore. If
+            // untrack ever manages additional state (e.g. currentObserver), mirror it here.
             return effect(() => {
-                captured = read();
-                untrack(invokeSub);
+                const val = read();
+                const prevTracking = isTrackingDeps;
+                isTrackingDeps = false;
+                try {
+                    fn(val);
+                } finally {
+                    isTrackingDeps = prevTracking;
+                }
             });
         };
 
@@ -800,24 +824,39 @@ export function createRegistry(config = {}) {
      *        Equality predicate. Returning true blocks propagation downstream.
      * @returns {Computed<T>}
      */
-    function computed(fn, opts = {}) {
+    function computed(fn, opts) {
         const node = createNode(undefined, FLAG_COMPUTED);
         node.computeFn = fn;
-        node.equals = opts.equals !== undefined ? opts.equals : Object.is;
+        // Defensive opts read; avoids the `= {}` per-call allocation. See signal().
+        node.equals = (opts !== undefined && opts.equals !== undefined) ? opts.equals : Object.is;
         statComputeds = (statComputeds + 1) | 0;
 
         const read = () => {
-            if (isTrackingDeps && currentObserver !== null) allocateLink(node, currentObserver);
+            if (isTrackingDeps && currentObserver !== null) {
+                // Inlined cursor fast-path — see signal() read for rationale.
+                const expected = activeObserverCurrentDep;
+                if (expected !== null && expected.source === node) {
+                    activeObserverCurrentDep = expected.nextDep;
+                } else {
+                    allocateLink(node, currentObserver);
+                }
+            }
             return pullComputed(node);
         };
         read.peek = () => pullComputed(node);
 
         read.subscribe = (fn) => {
-            let captured;
-            const invokeSub = () => fn(captured);
+            // Single-closure subscription — see signal() subscribe for rationale and
+            // the untrack-inlining coupling note.
             return effect(() => {
-                captured = read();
-                untrack(invokeSub);
+                const val = read();
+                const prevTracking = isTrackingDeps;
+                isTrackingDeps = false;
+                try {
+                    fn(val);
+                } finally {
+                    isTrackingDeps = prevTracking;
+                }
             });
         };
 
@@ -842,13 +881,15 @@ export function createRegistry(config = {}) {
      * @returns {() => void}         Dispose function. Idempotent. Safe to call
      *                               after registry.destroy().
      */
-    function effect(fn, opts = {}) {
+    function effect(fn, opts) {
         const node = createNode(undefined, FLAG_EFFECT);
         node.computeFn = fn;
-        node.scheduler = opts.scheduler;
+        // Defensive opts read; avoids the `= {}` per-call allocation. Read scheduler once
+        // and reuse the local for the trampoline check below.
+        const scheduler = opts !== undefined ? opts.scheduler : undefined;
+        node.scheduler = scheduler;
         statEffects = (statEffects + 1) | 0;
 
-        const scheduler = opts.scheduler;
         let firstRunError = null;
         if (scheduler) {
             const gen = node.gen | 0;

package/llms.txt

@@ -46,6 +46,15 @@ triggering write — no `queueMicrotask`, no promises, no scheduler ticks.
 - Stable read order: O(1) per dep via cursor reuse.
 - Chaotic/randomized read order: degrades to O(N) per dep due to list re-insertion.
 
+## Version notes
+
+- **1.1.2** (current): hot-path micro-optimizations, no behavior/API change.
+  Inlined cursor fast-path in `signal`/`computed` reads (stable-order reads skip
+  the `allocateLink` call); zero-allocation creation path (`opts` read defensively
+  instead of defaulting to `{}`); single-closure `subscribe`. Owner-tree
+  conformance items #209/#210 are wired but skipped pending the v1.2 ownership
+  hybrid.
+
 ## When to use
 
 - Animation loops, game HUDs, scoreboards, telemetry overlays.
@@ -232,7 +241,7 @@ sandbox.destroy();   // entire reactive world reset
 
 ## File layout
 
-- `Signal.js`              — full implementation, ~500 lines, single file.
+- `Signal.js`              — full implementation, single file.
 - `Signal.d.ts`          — TypeScript declarations for all public API.
 - `test/01-core.test.mjs`     — signal/computed/effect basics, equality, untrack.
 - `test/02-topology.test.mjs` — diamonds, chains, fan-out/in, cycle detection.
@@ -243,7 +252,7 @@ sandbox.destroy();   // entire reactive world reset
 - `test/07-dispose.test.mjs` — universal disposal: registry.dispose(api).
 - `test/08-watch.test.mjs` — new watch reactivity tests.
 - `test/09-conformance.test.mjs` — johnsoncodehk/reactive-framework-test-suite conformance fixes tests.
-- `bench/bench.mjs`           — comparative benchmark vs alien-signals, preact, solid.
+- `bench/benchmark.mjs`       — comparative benchmark vs alien-signals, preact, solid.
 - `demo/index.html`           — interactive visualization of the reactive graph.
 
 ## Install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-signal",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "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",
@@ -10,8 +10,9 @@
   "types": "./Signal.d.ts",
   "exports": {
     ".": {
-      "types": "./Signal.d.ts",
+      "node": "./Signal.js",
       "import": "./Signal.js",
+      "types": "./Signal.d.ts",
       "default": "./Signal.js"
     }
   },
@@ -27,6 +28,7 @@
     "test": "node --test --test-reporter=spec",
     "test:gc": "node --expose-gc --test --test-reporter=spec",
     "bench": "node --expose-gc bench/benchmark.mjs",
+    "bench-reactive": "node --expose-gc bench/benchmarkReactive.mjs",
     "verify": "npm test && npm run bench"
   },
   "keywords": [