@cplieger/reactive 1.2.4 → 1.3.0

package/src/signal.ts

@@ -1,7 +1,40 @@
 // Reactive signals: signal<T>, effect (with cleanup), batch, computed, untracked.
 // Preact-style doubly-linked source/target edges, pull-based glitch-free refresh,
-// global epoch + per-node version fast-skip, bitfield flags.
-// GPL-3.0-or-later.
+// per-node version fast-skip, bitfield flags.
+// Apache-2.0.
+//
+// Port provenance: graph/scheduler semantics verified against
+// @preact/signals-core@1.14.4 (drift audit 2026-07-17). Deliberate deltas
+// from upstream, pinned by tests: Object.is equality incl. NaN (upstream:
+// `!==`); custom `equals` / `equals: false` options (upstream has none);
+// isolate-and-continue effect error policy via setEffectErrorHandler
+// (upstream disposes-and-rethrows); the cycle guard lives in endBatch's drain
+// and un-notifies the chain it drops (upstream guards ONLY in the signal
+// setter, evaluated before the write, so it never drops a chain); and the drain
+// is re-entrant — `if (--batchDepth > 0) return` lets a write from an effect
+// body start a fresh drain, where upstream's `if (batchDepth > 1) return` plus
+// a post-drain `batchDepth--` keeps one drain per outermost batch.
+//
+// Upstream machinery NOT ported by design:
+//   - watched/unwatched hooks, createModel/action (1.13+);
+//   - the 1.14.x batch-snapshot A->B->A revert optimization — the
+//     version-monotonicity bug its first release carried
+//     (preactjs/signals#947) never existed here;
+//   - the `globalVersion` epoch fast-skip in refreshComputed. All three
+//     refresh call sites pre-check DIRTY, and because this port never
+//     unsubscribes a computed from its sources, notifyTargets always reaches
+//     every dependent computed — so DIRTY is a complete staleness signal.
+//     Upstream needs the epoch for computeds with no subscribers, which have
+//     no live edges. Do NOT try to revive it by deleting the DIRTY pre-checks:
+//     this refreshComputed has neither upstream's TRACKING shortcut nor its
+//     internal needsToRecompute gate, so an epoch miss recomputes
+//     unconditionally and six recompute-gating tests go red.
+//   - upstream's endBatch error capture and rethrow. Effect errors are
+//     isolated inside runEffect (see its contract below), so nothing can throw
+//     out of the drain and there was never anything to capture.
+//
+// Re-audit on upstream releases: diff src/index.ts against this file's
+// mechanisms and harvest engine-internal fixes (see CONTRIBUTING.md).
 
 const SIGNAL_BRAND = Symbol("signal");
 const COMPUTED_BRAND = Symbol("computed");
@@ -46,7 +79,6 @@ interface ComputedNode extends SourceNode, TargetNode {
   _isComputed: true;
   _fn: () => unknown;
   _equals: ((a: unknown, b: unknown) => boolean) | undefined;
-  _globalVersion: number;
 }
 
 interface EffectNode {
@@ -63,7 +95,6 @@ let evalContext: TargetNode | undefined;
 let batchDepth = 0;
 let batchedEffect: EffectNode | undefined;
 let batchIteration = 0;
-let globalVersion = 0;
 
 // Max effect-scheduling passes within one endBatch before assuming a cyclic
 // effect-write loop and bailing with "Cycle detected".
@@ -212,7 +243,22 @@ function notifyTargets(source: SourceNode): void {
     const target = node._target;
     if (target._isComputed) {
       // It's a ComputedNode
-      if (!(target._flags & (NOTIFIED | RUNNING))) {
+      if (target._flags & RUNNING) {
+        // A source written while this computed is mid-evaluation. Mark it stale
+        // so the next read re-runs it — every refresh call site pre-checks
+        // DIRTY, so without this the computed serves its pre-write value
+        // forever — but do NOT recurse: its own version has not moved yet, and
+        // recursing out of a RUNNING node is how a notify ping-pong is built.
+        //
+        // This repairs the PULL side only, deliberately. Two limits the next
+        // reader should not have to rediscover: (1) the computed's own
+        // subscribers are not woken here, so an effect that depends on it will
+        // not re-run until something else notifies it; (2) a computed that
+        // writes its own source unconditionally costs one extra recompute per
+        // read, and inside an effect it degrades into the documented
+        // MAX_BATCH_ITERATIONS "Cycle detected" path rather than hanging.
+        target._flags |= DIRTY;
+      } else if (!(target._flags & NOTIFIED)) {
         target._flags |= DIRTY | NOTIFIED;
         notifyTargets(target as unknown as SourceNode);
         target._flags &= ~NOTIFIED;
@@ -258,12 +304,6 @@ function refreshComputed(comp: ComputedNode): void {
     throw new Error("Cycle detected");
   }
 
-  // Fast-path: nothing changed globally since last check
-  if (comp._globalVersion === globalVersion && !(comp._flags & DIRTY)) {
-    return;
-  }
-  comp._globalVersion = globalVersion;
-
   const prevContext = evalContext;
   evalContext = comp;
   const prevFlags = comp._flags;
@@ -333,14 +373,23 @@ function endBatch(): void {
   if (--batchDepth > 0) {
     return;
   }
-  let error: unknown;
-  let hasError = false;
   while (batchedEffect !== undefined) {
     let eff: EffectNode | undefined = batchedEffect;
     batchedEffect = undefined;
     batchIteration++;
     if (batchIteration > MAX_BATCH_ITERATIONS) {
       batchIteration = 0;
+      // Un-notify the chain we are dropping: notifyTargets skips a NOTIFIED
+      // effect, so an effect left NOTIFIED here could never be queued again —
+      // bailing would silently deafen every effect in flight, including
+      // bystanders that merely share a signal with the cycling one.
+      let drop: EffectNode | undefined = eff;
+      while (drop !== undefined) {
+        const nextDrop: EffectNode | undefined = drop._nextBatchedEffect;
+        drop._nextBatchedEffect = undefined;
+        drop._flags &= ~NOTIFIED;
+        drop = nextDrop;
+      }
       throw new Error("Cycle detected");
     }
     while (eff !== undefined) {
@@ -348,22 +397,12 @@ function endBatch(): void {
       eff._nextBatchedEffect = undefined;
       eff._flags &= ~NOTIFIED;
       if (!(eff._flags & DISPOSED) && needsToRecompute(eff)) {
-        try {
-          runEffect(eff);
-        } catch (e) {
-          if (!hasError) {
-            error = e;
-            hasError = true;
-          }
-        }
+        runEffect(eff);
       }
       eff = next;
     }
   }
   batchIteration = 0;
-  if (hasError) {
-    throw error;
-  }
 }
 
 function runCleanup(eff: EffectNode): void {
@@ -382,6 +421,13 @@ function runCleanup(eff: EffectNode): void {
   }
 }
 
+// Contract: runEffect NEVER throws, and both callers depend on it.
+// Its body and its cleanup each route to safeCallHandler, which swallows even a
+// throwing handler; everything else here is a pointer walk over a well-formed
+// list. endBatch's drain and the effect() factory therefore call it bare. A
+// throw escaping this function would abandon the rest of the queued chain
+// mid-drain — the same shape of failure as the cycle bail's NOTIFIED leak. If
+// you add a statement here that can throw, wrap it HERE, not at the call sites.
 function runEffect(eff: EffectNode): void {
   // Run cleanup first (untracked)
   runCleanup(eff);
@@ -474,7 +520,6 @@ export function signal<T>(initial: T, options?: SignalOptions<T>): Signal<T> {
       }
       node._value = v;
       node._version++;
-      globalVersion++;
       startBatch();
       try {
         notifyTargets(node);
@@ -506,7 +551,6 @@ export function computed<T>(fn: () => T, options?: SignalOptions<T>): ReadonlySi
     _fn: fn,
     _equals:
       eq === false ? () => false : eq ? (a: unknown, b: unknown) => eq(a as T, b as T) : undefined,
-    _globalVersion: -1,
   };
 
   const c = {
@@ -564,11 +608,7 @@ export function effect(fn: () => Cleanup): () => void {
   };
 
   // Run immediately
-  try {
-    runEffect(eff);
-  } catch (e) {
-    safeCallHandler(e);
-  }
+  runEffect(eff);
 
   return () => {
     if (eff._flags & DISPOSED) {
@@ -608,13 +648,19 @@ export function untracked<T>(fn: () => T): T {
   }
 }
 
-/** Subscribe to a signal, calling cb on every change. Returns dispose function. */
+/** Subscribe to a signal, calling cb on every change. Returns dispose function.
+ *  The callback runs untracked: reading other signals inside it does not add
+ *  them as dependencies of the subscription (matches upstream
+ *  preactjs/signals#188 semantics). */
 export function subscribe<T>(
   sig: Signal<T> | ReadonlySignal<T>,
   cb: (value: T) => void,
 ): () => void {
   return effect(() => {
-    cb(sig.value);
+    const value = sig.value;
+    untracked(() => {
+      cb(value);
+    });
     return undefined;
   });
 }

package/src/store.ts

@@ -11,7 +11,7 @@
 //   interface MyMap { count: number; name: string }
 //   const { get, set, subscribe, effect, computed, batch } = createStore<MyMap>();
 
-import { signal, effect, batch, type Signal, type Cleanup } from "./signal.js";
+import { signal, effect, batch, untracked, type Signal, type Cleanup } from "./signal.js";
 
 /** A typed per-key reactive store with auto-tracked effects, computed, and batching. */
 export interface Store<M> {
@@ -19,6 +19,14 @@ export interface Store<M> {
   set<K extends keyof M & string>(key: K, value: M[K]): void;
   subscribe<K extends keyof M & string>(key: K, cb: (value: M[K]) => void): () => void;
   effect(fn: () => Cleanup): () => void;
+  /** Derive `outputKey` from other keys. NOT a lazy engine `computed`: this is
+   *  an EAGER effect that re-runs `fn` on dependency change and WRITES the
+   *  result to `outputKey`. Consequences of that shape: `fn` runs whether or
+   *  not anyone reads `outputKey`; a throwing `fn` is isolated by the effect
+   *  error handler (not cached and rethrown at the read site like an engine
+   *  computed); `set(outputKey, …)` still works between recomputes; and a
+   *  self-reading `fn` behaves as documented on the implementation below.
+   *  Returns the effect's dispose function. */
   computed<K extends keyof M & string>(outputKey: K, fn: () => M[K]): () => void;
   batch(fn: () => void): void;
 }
@@ -57,7 +65,11 @@ export function createStore<M>(): Store<M> {
         primed = true;
         return;
       }
-      cb(v);
+      // Untracked, mirroring the engine's `subscribe`: a callback that reads
+      // other keys must not become a dependency of this subscription.
+      untracked(() => {
+        cb(v);
+      });
     });
   }