@cplieger/reactive 1.2.4 → 1.2.5

package/README.md

@@ -3,6 +3,7 @@
 [![npm](https://img.shields.io/npm/v/@cplieger/reactive)](https://www.npmjs.com/package/@cplieger/reactive)
 [![JSR](https://jsr.io/badges/@cplieger/reactive)](https://jsr.io/@cplieger/reactive)
 [![Test coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cplieger/reactive/badges/coverage.json)](https://github.com/cplieger/reactive/actions/workflows/coverage.yml)
+[![Mutation (TS)](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cplieger/reactive/badges/mutation-ts.json)](https://github.com/cplieger/reactive/issues?q=label%3Astryker-tracker)
 [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13218/badge)](https://www.bestpractices.dev/projects/13218)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/cplieger/reactive/badge)](https://scorecard.dev/viewer/?uri=github.com/cplieger/reactive)
 
@@ -75,7 +76,7 @@ isComputed(doubled); // true
 - `flushSync()` — synchronously drain pending effects (no-op inside batch)
 - `untracked<T>(fn): T` — run fn without tracking signal reads (like Preact `untracked()` / Solid `untrack()`)
 - `on(deps, fn, options?): () => U` — explicit dependency declaration helper (like Solid `on()`). Returns `() => U`; with `{ defer: true }` the accessor returns `() => U | undefined` (the deferred first call yields `undefined`). A single accessor `() => T` types `value`/`prev` as `T`; an array of accessors types them as `unknown[]`. Pass into `effect()` or `computed()`.
-- `subscribe(signal, cb): () => void` — subscribe to a signal, calling cb immediately and on every change
+- `subscribe(signal, cb): () => void` — subscribe to a signal, calling cb immediately and on every change. The callback runs untracked: signals read inside it do not become dependencies of the subscription
 - `isSignal(value): boolean` — type guard for signals created by `signal()`
 - `isComputed(value): boolean` — type guard for computed signals
 - `setEffectErrorHandler(handler): EffectErrorHandler` — set global error handler for effects; returns the previous handler
@@ -84,7 +85,7 @@ isComputed(doubled); // true
 
 - `el(tag, attrs?, ...children)` — CSP-safe element factory (the build half; `reconcile`/`patch` are the commit half). `className` → class; `on*` → handler property + `trackHandler` (so `patch` reconciles handlers); boolean DOM props (`hidden`/`disabled`/`checked`/`selected`/…) and `value`/`colSpan`/`rowSpan`/`tabIndex`/`htmlFor` → properties; everything else (`data-*`, `aria-*`, `style`, `id`) → `setAttribute`. String children become text nodes (never parsed as HTML); null/undefined attrs and children are skipped.
 - `reconcile<T>(parent, items, spec)` — keyed-list DOM reconciliation with mount/update/onRemove lifecycle
-- `patch(parent, ...children)` — structural tree-diff, replacing a parent's children with reconciled new nodes. Element nodes are keyed by their first `data-col` or `*-id` attribute (so reorders/re-patches reuse the matched node); unkeyed nodes match by position.
+- `patch(parent, ...children)` — structural tree-diff, replacing a parent's children with reconciled new nodes. Element nodes are keyed by a `*-id` attribute (specific entity id — takes precedence) or, failing that, `data-col` (so reorders/re-patches reuse the matched node); duplicate-key siblings match in document order; unkeyed nodes match by position.
 - `reconcileChildren(parent, newChildren)` — low-level child reconciliation against existing DOM
 - `trackHandler(el, key)` — register an `on*` property for handler reconciliation during tree-diff
 
@@ -92,7 +93,7 @@ isComputed(doubled); // true
 
 `createStore` and `SignalMap` are thin facades over the one signal engine — there is no second reactivity implementation. `createStore` lazily backs each key with a signal; `SignalMap` is a registry of signals keyed by a runtime string id.
 
-- `createStore<M>(): Store<M>` — typed, fixed-key reactive store with `get`, `set`, `subscribe`, `effect`, `computed`, and `batch`. `subscribe` notifies on change only (not immediately on subscribe). A `computed` key whose fn reads its own output does not loop unbounded: a self-read that keeps yielding new values trips the engine's batch-iteration guard and surfaces `Error("Cycle detected")` through the effect error handler (effects isolate errors, so it is not rethrown to the caller), while a stable self-read settles via `Object.is` dedup.
+- `createStore<M>(): Store<M>` — typed, fixed-key reactive store with `get`, `set`, `subscribe`, `effect`, `computed`, and `batch`. `subscribe` notifies on change only (not immediately on subscribe), and its callback runs untracked. `computed(outputKey, fn)` is an EAGER effect that writes `outputKey` on every dependency change — not a lazy engine computed — so `fn` runs whether or not anyone reads the key, a throwing `fn` routes to the effect error handler instead of being cached and rethrown at the read site, and `set(outputKey, …)` still works between recomputes. A `computed` key whose fn reads its own output does not loop unbounded: a self-read that keeps yielding new values trips the engine's batch-iteration guard and surfaces `Error("Cycle detected")` through the effect error handler (effects isolate errors, so it is not rethrown to the caller), while a stable self-read settles via `Object.is` dedup.
 - `SignalMap<V>` — dynamic per-id signal registry: `get(id)`, `ensure(id, initial)`, `clear(id)`, `clearAll()`. For reactive state whose key set isn't known at the type level (per-message streaming text, per-row state, …); complements `createStore`'s fixed key set.
 
 ### Collections
@@ -100,7 +101,7 @@ isComputed(doubled); // true
 A reactive ordered collection of keyed entities — the data half of the two-tier list pattern. A per-entity content update touches only that entity's subscribers; add/remove/reorder bumps the structure signal (`ids`). Built on `signal` + `SignalMap`.
 
 - `createCollection<T>(keyOf: (item: T) => string): Collection<T>` — returns a collection with:
-  - `setAll(items)` — replace everything (same-order replacement does not bump `ids`)
+  - `setAll(items)` — replace everything (same-order replacement does not bump `ids`; duplicate keys deduplicate — first occurrence keeps the position, last value wins)
   - `upsert(item)` — add/replace one (appends new ids); `prepend(items)` — add to the front (scroll-up/load-older pagination)
   - `update(id, next | updater)` / `remove(id)` / `clear()`
   - `get(id)` / `has(id)` (untracked), `signalFor(id)` (reactive per-entity), `size`
@@ -109,7 +110,7 @@ A reactive ordered collection of keyed entities — the data half of the two-tie
 
 ### List rendering
 
-- `bindList<T>(parent, source, spec): () => void` — two-tier render binding. `source` is a `ListSource<T>` = `{ ids, signalFor }`; a `Collection` satisfies it directly, and a filtered/sorted/paginated view is just `{ ids: computed(...), signalFor: collection.signalFor }` (pagination = a sliced view, not a separate primitive). One structural effect tracks `source.ids` and `reconcile`s the row list; each row owns a private effect tracking only its own entity signal, so a per-entity change repaints just that row with no structural reconcile. `spec`: `{ mount(item, id) => HTMLElement; update?(el, item, id); onRemove?(el, id) }` (`update` runs at mount and on every later change). Returns a dispose that tears down the structural effect and every row effect.
+- `bindList<T>(parent, source, spec): () => void` — two-tier render binding. `source` is a `ListSource<T>` = `{ ids, signalFor }`; a `Collection` satisfies it directly, and a filtered/sorted/paginated view is just `{ ids: computed(...), signalFor: collection.signalFor }` (pagination = a sliced view, not a separate primitive). One structural effect tracks `source.ids` and `reconcile`s the row list; each row owns a private effect tracking only its own entity signal, so a per-entity change repaints just that row with no structural reconcile. An id whose `signalFor` is `undefined` (an inconsistent source) is skipped rather than rendered. `spec`: `{ mount(item, id) => HTMLElement; update?(el, item, id); onRemove?(el, id) }` (`update` runs at mount and on every later change). Returns a dispose that tears down the structural effect and every row effect.
 
 ### Event bus
 

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/reactive",
-  "version": "1.2.4",
+  "version": "1.2.5",
   "exports": {
     ".": "./src/index.ts"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/reactive",
-  "version": "1.2.4",
+  "version": "1.2.5",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -13,14 +13,17 @@
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
+    "@stryker-mutator/core": "9.6.1",
+    "@stryker-mutator/typescript-checker": "9.6.1",
+    "@stryker-mutator/vitest-runner": "9.6.1",
     "@typescript/native": "npm:typescript@7.0.2",
     "@vitest/coverage-v8": "4.1.10",
-    "eslint": "10.6.0",
-    "fast-check": "4.8.0",
+    "eslint": "10.7.0",
+    "fast-check": "4.9.0",
     "happy-dom": "20.10.6",
-    "prettier": "3.9.4",
+    "prettier": "3.9.5",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.63.0",
+    "typescript-eslint": "8.64.0",
     "vitest": "4.1.10"
   },
   "description": "Signals + DOM-reconciliation reactive core for TypeScript (zero dependencies)",

package/src/bind-list.ts

@@ -19,7 +19,9 @@ import { effect, type ReadonlySignal } from "./signal.js";
 
 /** The minimal reactive surface `bindList` renders: a structure signal (the
  *  ordered ids) and a per-id content-signal lookup. `Collection<T>` satisfies
- *  this; so does `{ ids: computed(...), signalFor: collection.signalFor }`. */
+ *  this; so does `{ ids: computed(...), signalFor: collection.signalFor }`.
+ *  An id with no matching signal (an inconsistent source) is skipped — no row
+ *  is rendered for it until the source becomes consistent. */
 export interface ListSource<T> {
   readonly ids: ReadonlySignal<readonly string[]>;
   signalFor(id: string): ReadonlySignal<T> | undefined;
@@ -51,12 +53,23 @@ export function bindList<T>(
   const rowDisposers = new Map<string, () => void>();
 
   const disposeStructural = effect(() => {
-    const ids = source.ids.value; // structure tier: re-runs on add/remove/reorder only
+    // Structure tier: re-runs on add/remove/reorder only. An id whose entity
+    // signal is missing (an inconsistent ListSource) is skipped instead of
+    // mounting a row with a manufactured `undefined as T` value; it renders
+    // once the source becomes consistent (the next `ids` change).
+    const ids = source.ids.value.filter((id) => source.signalFor(id) !== undefined);
     reconcile<string>(parent, ids, {
       key: (id) => id,
       mount: (id) => {
         const sig = source.signalFor(id);
-        const el = spec.mount((sig === undefined ? undefined : sig.peek()) as T, id);
+        if (sig === undefined) {
+          // Unreachable via the structural filter above (same synchronous
+          // pass); reachable only by a source whose signalFor is not stable
+          // within one read — surface that loudly instead of manufacturing
+          // an entity value. Routed to the effect error handler.
+          throw new Error(`bindList: no entity signal for id "${id}"`);
+        }
+        const el = spec.mount(sig.peek(), id);
         if (spec.update !== undefined) {
           const update = spec.update;
           // content tier: isolated per-row effect; runs now (fills content)

package/src/collection.ts

@@ -12,7 +12,10 @@ import { SignalMap } from "./signal-map.js";
 /** A reactive, ordered, keyed collection of entities of type T. */
 export interface Collection<T> {
   /** Replace the whole collection (e.g. initial load). Entities no longer
-   *  present are dropped; the order becomes exactly `items`. */
+   *  present are dropped; the order becomes `items`, deduplicated by key
+   *  (first occurrence keeps the position, the last value wins — Map
+   *  semantics), so the order tier can never list an id twice while the
+   *  entity tier holds a single signal for it. */
   setAll(items: readonly T[]): void;
   /** Add a new entity or replace an existing one (keyed by `keyOf`). New
    *  entities are appended to the order. */
@@ -65,8 +68,13 @@ export function createCollection<T>(keyOf: (item: T) => string): Collection<T> {
       const seen = new Set<string>();
       for (const item of items) {
         const id = keyOf(item);
-        ids.push(id);
-        seen.add(id);
+        // Deduplicate repeated keys (first occurrence keeps the position, the
+        // last value wins) so the structure and entity tiers cannot disagree:
+        // one signal per id, one order entry per id.
+        if (!seen.has(id)) {
+          seen.add(id);
+          ids.push(id);
+        }
         sigs.ensure(id, item).value = item;
       }
       for (const id of order.peek()) {

package/src/reconcile-tree.ts

@@ -1,6 +1,8 @@
 // Structural tree-diff: reconcile a parent's children against new nodes.
 // Handles attribute patching, text node updates, element reordering,
-// and recursive child reconciliation. Keying via data-* or *-id attrs.
+// and recursive child reconciliation. Keying: a specific `*-id` attribute
+// wins over the generic `data-col`; duplicate-key siblings match in
+// document order.
 
 const handlerKeysMap = new WeakMap<HTMLElement, Set<string>>();
 
@@ -38,11 +40,19 @@ export function patch(
 /** Reconcile a parent node's children against a new set of child nodes, patching in place. */
 export function reconcileChildren(parent: Node, newChildren: Node[]): void {
   const oldChildren = Array.from(parent.childNodes);
-  const oldByKey = new Map<string, Node>();
+  // Per-key FIFO queues: siblings sharing a key (e.g. two `data-col="meta"`
+  // cells in one row) match in document order (first↔first, second↔second)
+  // instead of a last-wins map entry mispairing them and churning nodes.
+  const oldByKey = new Map<string, Node[]>();
   for (const child of oldChildren) {
     const key = nodeKey(child);
     if (key) {
-      oldByKey.set(key, child);
+      const queue = oldByKey.get(key);
+      if (queue === undefined) {
+        oldByKey.set(key, [child]);
+      } else {
+        queue.push(child);
+      }
     }
   }
 
@@ -54,10 +64,16 @@ export function reconcileChildren(parent: Node, newChildren: Node[]): void {
     }
     const newKey = nodeKey(newChild);
 
-    let matched = newKey ? (oldByKey.get(newKey) ?? null) : null;
-    if (matched) {
-      oldByKey.delete(newKey);
-    } else if (!newKey) {
+    let matched: Node | null = null;
+    if (newKey) {
+      const queue = oldByKey.get(newKey);
+      if (queue !== undefined) {
+        matched = queue.shift() ?? null;
+        if (queue.length === 0) {
+          oldByKey.delete(newKey);
+        }
+      }
+    } else {
       // Unkeyed new node: match the next UNKEYED old node by position, advancing
       // past keyed old nodes (which are reserved for key-based matching) and any
       // already-consumed slots. This mirrors the documented contract ("unkeyed
@@ -139,12 +155,20 @@ function nodeKey(node: Node): string {
   if (node.nodeType !== 1) {
     return "";
   }
+  // A specific entity id (`*-id`, e.g. data-cov-id / data-act-id) takes
+  // precedence over the generic column key (`data-col`), so an element
+  // carrying both keys by its entity identity — a generic first-in-attribute-
+  // order `data-col` must not shadow it.
+  let colKey = "";
   for (const attr of (node as Element).attributes) {
-    if (attr.name === "data-col" || attr.name.endsWith("-id")) {
+    if (attr.name.endsWith("-id")) {
       return `${attr.name}=${attr.value}`;
     }
+    if (colKey === "" && attr.name === "data-col") {
+      colKey = `${attr.name}=${attr.value}`;
+    }
   }
-  return "";
+  return colKey;
 }
 
 function patchAttrs(oldEl: HTMLElement, newEl: HTMLElement): void {

package/src/signal.ts

@@ -2,6 +2,19 @@
 // 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.
+//
+// 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); cycle guard in endBatch (upstream also
+// guards in the signal setter). Upstream machinery NOT ported by design:
+// watched/unwatched hooks, createModel/action (1.13+), and 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.
+// 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");
@@ -608,13 +621,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);
+      });
     });
   }