@cplieger/reactive 2.1.2 → 2.2.0-dev.1

package/README.md

@@ -2,56 +2,20 @@
 
 [![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) [![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)
 
-> Signals + collections + DOM-reconciliation micro-framework for TypeScript
+reactive lets you build a framework-free TypeScript browser UI with signals, keyed list rendering and in-place DOM updates, in one package with no runtime dependencies.
 
-A standalone reactive app-skeleton:
+It replaces the change listeners, list re-renders and element builder you would otherwise write between state and the page. It ships as ESM TypeScript source rather than compiled JavaScript, so it needs a bundler or runtime that compiles TypeScript. Releases follow semantic versioning, and it is licensed under Apache-2.0.
 
-- fine-grained signals with automatic dependency tracking and synchronous batched effects
-- a typed per-key reactive store
-- a dynamic per-id signal registry (`SignalMap`)
-- a reactive ordered keyed `Collection`
-- a two-tier list render binding (`bindList`)
-- a CSP-safe element factory (`el`)
-- keyed-list DOM reconciliation
-- structural tree-diffing
-- a typed event bus (`createBus`)
+## Why use it
 
-The store, `SignalMap`, and `Collection` are thin facades over a single signal engine: one reactive core, not several. Zero dependencies beyond the DOM API.
+reactive is built for a small browser app in plain TypeScript that needs no component framework.
 
-> **What needs a DOM:** the render half, `el`, `bindList`, `reconcile`, `patch` and `trackHandler`. The engine and the state tiers do not: `signal`, `effect`, `computed`, `batch`, `untracked`, `createStore`, `SignalMap`, `createCollection` and `createBus`. Nothing touches the DOM at import time, so importing the package under Node, Deno, Bun or Workers succeeds and only the DOM functions throw when called.
+- Signals, computed values and effects track their dependencies on their own. When a write returns, every effect that depends on it has already run.
+- `createCollection` and `bindList` render a keyed list. Changing one item repaints only its row, and a reorder keeps the existing rows.
+- `el` builds elements without HTML strings, so it works under a strict Content Security Policy. `patch` updates a subtree by reusing the elements on the page, so focus and scroll position survive a re-render.
+- The signals, stores, collections and event bus need no DOM, so they also run under Node, Deno, Bun or Workers.
 
-Mirrors semantics from @preact/signals-core and solid-js reactivity.
-
-## Flush model
-
-One phase, and this is the whole of it.
-
-**A write flushes.** When `sig.value = x` returns, every effect that depends on
-`sig` has already re-run. The setter notifies and drains before it returns, so
-there is no pending-effect state a caller can observe and no queue to drain. Read
-the DOM on the next statement and you are reading what the effects wrote. Same
-contract as [@preact/signals-core](https://github.com/preactjs/signals/blob/main/packages/core/README.md),
-this engine's baseline.
-
-**`batch(fn)` is the only deferral.** Inside a batch, writes coalesce and effects
-are held; they run once, synchronously, when the _outermost_ batch returns. A
-nested batch defers to its outermost, and a throwing body still flushes.
-
-**Deferral beyond that is yours.** To get effects on a later task, write on a
-later task:
-
-```typescript
-queueMicrotask(() => {
-  count.value = next; // effects run inside this microtask
-});
-```
-
-There is deliberately **no flush barrier** — no `flushSync()`, no `nextTick()`.
-A barrier is the API a _deferred_ model owes its callers (Vue's `nextTick`,
-React's `flushSync`); an eager model never holds work, so it has nothing to
-report on and nothing to force. `flushSync()` existed through v1.x, could never
-find work pending, and refused to act when work was pending inside a batch; it
-was removed in v2.0.0. If you were calling it, delete the call — it was a no-op.
+Consider [Solid](https://github.com/solidjs/solid) if you want a full UI framework, with components, JSX, Suspense for async data and server-side rendering.
 
 ## Install
 
@@ -63,132 +27,132 @@ npm i @cplieger/reactive
 
 ## Usage
 
+A signal holds a value, a computed value derives from signals, and an effect re-runs when what it read changes:
+
 ```typescript
-import {
-  signal,
-  effect,
-  batch,
-  computed,
-  untracked,
-  subscribe,
-  isSignal,
-  isComputed,
-} from "@cplieger/reactive";
+import { signal, computed, effect, batch } from "@cplieger/reactive";
 
 const count = signal(0);
 const doubled = computed(() => count.value * 2);
 
-effect(() => {
-  console.log("count:", count.value, "doubled:", doubled.value);
-  return undefined;
+const dispose = effect(() => {
+  console.log(count.value, doubled.value);
+  return undefined; // an effect returns undefined or a cleanup function
 });
 
 batch(() => {
   count.value = 1;
-  count.value = 2; // effect fires once with value 2, synchronously at batch end
+  count.value = 2;
+}); // the effect ran once, with 2 and 4, before batch returned
+
+dispose();
+```
+
+A collection and `bindList` render a list. Updating one item repaints only its row:
+
+```typescript
+import { bindList, createCollection, el } from "@cplieger/reactive";
+
+interface Todo {
+  id: string;
+  title: string;
+  done: boolean;
+}
+
+const todos = createCollection<Todo>((todo) => todo.id);
+const list = el("ul");
+document.body.append(list);
+
+bindList(list, todos, {
+  mount: () => el("li"),
+  update: (row, todo) => {
+    row.textContent = todo.done ? `${todo.title} (done)` : todo.title;
+  },
 });
 
-// Read without tracking
+todos.setAll([
+  { id: "a", title: "Write docs", done: false },
+  { id: "b", title: "Ship", done: false },
+]);
+todos.update("a", (todo) => ({ ...todo, done: true })); // only the first row repaints
+```
+
+`patch` takes freshly built elements and applies them to a subtree, keeping the elements already on the page:
+
+```typescript
+import { effect, el, patch, signal } from "@cplieger/reactive";
+
+const name = signal("world");
+const header = el("header");
+document.body.append(header);
+
 effect(() => {
-  const tracked = count.value;
-  const notTracked = untracked(() => doubled.value);
-  console.log(tracked, notTracked);
+  patch(header, el("h1", { className: "title" }, `Hello, ${name.value}`));
   return undefined;
 });
 
-// Subscribe utility
-const dispose = subscribe(count, (v) => console.log("count changed:", v));
-dispose();
-
-// Type guards
-isSignal(count); // true
-isComputed(doubled); // true
+name.value = "reactive"; // the same <h1> stays on the page with its new text
 ```
 
 ## API
 
-### Signals
-
-- `signal<T>(initial, options?): Signal<T>`: reactive value with `.value` getter/setter and `.peek()`. Options: `{ equals?: false | ((prev, next) => boolean) }`
-- `computed<T>(fn, options?): ReadonlySignal<T>`: lazy cached derived signal (glitch-free, equality-deduped). Options: `{ equals?: false | ((prev, next) => boolean) }`
-- `effect(fn: () => Cleanup): () => void`: auto-tracking side-effect with cleanup support. `fn` must return `undefined` or a cleanup function.
-- `batch(fn)`: coalesce signal writes; effects flush synchronously at end of outermost batch. The only deferral — see [Flush model](#flush-model)
-- `untracked<T>(fn): T`: run fn without tracking signal reads (like Preact `untracked()` / Solid `untrack()`)
-- `touch(...signals): void`: read signals for their tracking effect alone, discarding the values — the complement of `peek()` (`peek` reads without subscribing, `touch` subscribes without keeping). `undefined` entries are skipped, so a per-key lookup that may miss (`Collection.signalFor(id)`, `SignalMap.get(id)`) can be passed straight in. Use it where a scope must re-run on a signal whose value it has no use for: most often a two-tier read, where a computed or effect takes per-entity values through `signalFor` and so must depend on the structure signal (`Collection.ids`) separately to re-derive when the id set changes. Unlike `on()` it ADDS a dependency and leaves every other read in the scope tracked
-- `on(deps, fn, options?): () => U`: explicit dependency declaration helper (like Solid `on()`); pass into `effect()` or `computed()`. Its body runs untracked, so the declared deps are the scope's ONLY dependencies — reach for `touch()` instead when the rest of the scope should stay tracked. Passed to `effect()`, the body owes an explicit `return undefined` (or a cleanup function) like any effect callback, since a body with no return statement infers `() => void`, which the `Cleanup` contract rejects. With `{ defer: true }` the accessor returns `() => U | undefined`: the deferred first call yields `undefined`.
-- `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
+- Signals: `signal`, `computed`, `effect`, `batch`, `untracked`, `touch`, `on`, `subscribe`, `isSignal`, `isComputed` and `setEffectErrorHandler`.
+- State: `createStore` for a fixed set of typed keys, `SignalMap` for keys known only at run time, and `createCollection` for an ordered list of keyed items.
+- DOM: `el` builds elements, `reconcile` and `bindList` render keyed lists, and `patch` updates a subtree in place. `trackHandler` registers an `on*` handler on an element you built without `el`, so `patch` keeps it in step.
+- Events: `createBus` for typed events that hold no value.
 
-### DOM building & reconciliation
+The full reference is on [JSR](https://jsr.io/@cplieger/reactive/doc). [Signals, stores and collections](docs/signals.md) and [Building and updating the DOM](docs/dom.md) describe how each one behaves.
 
-- `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. Correspondence between a child the parent has and a child you asked for is decided strongest-first: the same **node** (you handed back a node that is already a child of `parent` — it is placed at the index you passed it at, unmodified, so handing a parent its own children reordered is supported), then the same **key** (a `*-id` attribute, a specific entity id which takes precedence, or failing that `data-col`; duplicate-key siblings match in document order), then the same **position**. Any node that is not already a child of `parent` is a TEMPLATE: its shape may be copied into a reused child and the node itself never inserted. A reused element takes the new node's attributes, its tracked `on*` handlers, and the unreflected live properties the attribute pass cannot reach: `checked` (input), `selected` (option) and the `value` of an `input`/`textarea`. Those reflect to `defaultChecked`/`defaultSelected`/`defaultValue`, so without this a re-render could never turn a checkbox off or replace the text in a field. Syncing `value` overwrites what a user has typed and moves the caret to the end, which is correct only where a re-render cannot land mid-keystroke: a form re-rendered by a click is safe, one re-rendered by a timer or a server push is not, and that shape must drive the field from an effect instead (see [Unsupported by Design](#unsupported-by-design)).
-- `trackHandler(el, key)`: register an `on*` property for handler reconciliation during tree-diff
+## A write runs its effects before it returns
 
-### Store
+When `count.value = 1` returns, every effect that depends on `count` has already run, so the next line reads the DOM those effects wrote. There is no queue and no pending state to wait for.
 
-`createStore` and `SignalMap` are thin facades over the one signal engine. `createStore` lazily backs each key with a signal; `SignalMap` is a registry of signals keyed by a runtime string id.
+`batch(fn)` is the only way to defer. Writes inside it coalesce, and the held effects run once, synchronously, when the outermost batch returns, even when the body throws. To run effects on a later task, make the write on a later task:
 
-- `createStore<M>(): Store<M>`: typed, fixed-key reactive store with `get`, `set`, `subscribe`, and `computed`. A member exists here only where it does something the engine's namesake does not, so `effect` and `batch` are **not** on the store (removed in v2.0.0) — import them from the package root; `store.batch(…)` read as "batch this store's writes" while batching the whole graph. `subscribe` notifies on change only (not immediately on subscribe), and its callback runs untracked. `computed(outputKey, fn)` is an eager effect, not a lazy engine computed: it writes `outputKey` on every dependency change. 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; `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 surfaces `Error("Cycle detected")` through the effect error handler, while a stable self-read settles. The guard re-arms per write: a key that is still cyclic reports again on the next write to it rather than reporting once and going quiet, and effects merely queued alongside the cycle (a `subscribe` on the same key, say) stay reactive.
-- `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.
+```typescript
+queueMicrotask(() => {
+  count.value = next; // effects run inside this microtask
+});
+```
 
-### Collections
+This is the contract [@preact/signals-core](https://github.com/preactjs/signals/blob/main/packages/core/README.md) documents too. The package has no `flushSync()` or `nextTick()`, because it never holds work, so there is nothing to flush.
 
-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`.
+## Correctness guarantees
 
-- `createCollection<T>(keyOf: (item: T) => string): Collection<T>`: returns a collection with:
-  - `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`
-  - `ids: ReadonlySignal<readonly string[]>`: structure tier (add/remove/reorder only)
-  - `items()`: ordered reactive snapshot (tracks order + every entity)
+- Effects downstream of a `computed` run only when its value changes, compared with `Object.is` unless you pass `equals`. A diamond-shaped dependency graph never shows a half-updated value.
+- Reading a `computed` while it is computing throws `Error("Cycle detected")`.
+- When a computed function throws, every read rethrows that error until a dependency changes.
+- Setting `.value` on a `computed` throws `Error("Cannot set a computed signal")`.
+- `batch()` runs the held effects synchronously at the end of the outermost batch, as @preact/signals-core and solid-js do.
 
-### List rendering
+## Unsupported by design
 
-- `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 is a sliced view, not a separate primitive). A structural effect tracks `source.ids` and reconciles the row list; each row's own effect tracks only its 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.
+The package leaves these out on purpose. [Non-goals](docs/non-goals.md) gives the reason for each.
 
-### Event bus
+- An ownership tree or `createRoot`, and automatic disposal of nested effects.
+- Lazy activation and an `onMount` lifecycle.
+- `Signal.subtle.Watcher` and notify-on-dirty.
+- Introspection APIs, and explicit disposal of a computed.
+- Server-side rendering and per-request isolation.
+- Async signals and resources.
+- Transactions, a custom scheduler, and a flush barrier such as `flushSync` or `nextTick`.
+- Controlled form inputs. `patch` syncs form values, so if a view can re-render while a user types, drive that field from an effect instead.
+- Writing a signal from inside a computed. The computed's own subscribers are not woken, so make that write in an effect.
 
-State lives in signals; discrete events go on a bus. `createBus` is the typed event primitive (not reactive state; no retained value).
+## Documentation
 
-- `createBus<EventMap>(options?): Bus<EventMap>`: `on`/`once`/`off`/`emit`/`clear`. Handlers are snapshot-cached (rebuilt only on mutation; a handler unsubscribed mid-emit still fires for that emit). Events whose payload type is `undefined` emit with no payload argument. A throwing handler is isolated via `options.onError` (default `console.error`).
+- [Signals, stores and collections](docs/signals.md) covers the flush model, effects, stores, collections and the event bus, for a reader writing state code.
+- [Building and updating the DOM](docs/dom.md) covers how `el`, `reconcile`, `bindList` and `patch` decide what to keep, for a reader rendering with them.
+- [Non-goals](docs/non-goals.md) lists what the package leaves out and why.
 
-## Correctness guarantees
+## Credits
 
-- **Glitch-freedom**: Computed signals use equality dedup (`Object.is`), so downstream effects only fire when the computed value actually changes. Diamond dependency graphs are handled correctly.
-- **Cycle detection**: Reading a computed that is currently being computed throws `Error("Cycle detected")`.
-- **Error caching**: If a computed's fn throws, the error is cached and rethrown on subsequent reads until dependencies change.
-- **Computed is read-only**: Setting `.value` on a computed throws `Error("Cannot set a computed signal")`.
-- **Synchronous batch**: `batch()` flushes effects synchronously at the end of the outermost batch (matching @preact/signals-core and solid-js). It is the only deferral the library has; a bare write flushes before it returns. See [Flush model](#flush-model).
-
-## Unsupported by Design
-
-The following features are intentionally NOT implemented:
-
-| Feature                                           | Reason                                                                                                                                                                                                                                                                                                                         |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Effect ownership tree / `createRoot`**          | Consumers manage disposal explicitly. Adding ownership changes the mental model.                                                                                                                                                                                                                                               |
-| **Nested effect auto-disposal**                   | Each effect is independent and returns its own dispose function. Compose with arrays or helper functions.                                                                                                                                                                                                                      |
-| **Lazy activation / `onMount` lifecycle**         | Signals are always active. Resource management is the consumer's responsibility.                                                                                                                                                                                                                                               |
-| **`Signal.subtle.Watcher` / notify-on-dirty**     | This library IS the framework layer. The Watcher pattern is for frameworks that sit on top of a signals primitive.                                                                                                                                                                                                             |
-| **Introspection APIs**                            | Dev-tools concern. Not needed for production.                                                                                                                                                                                                                                                                                  |
-| **Explicit computed disposal**                    | Computed signals are GC'd when unreferenced. No explicit teardown needed.                                                                                                                                                                                                                                                      |
-| **SSR / server-side isolation**                   | Client-side library. Server usage should instantiate fresh signal graphs per request.                                                                                                                                                                                                                                          |
-| **Async signals / resources**                     | Out of scope. Use effects + manual signal writes for async data loading.                                                                                                                                                                                                                                                       |
-| **Transactions**                                  | Framework-level concern. Not a signals primitive.                                                                                                                                                                                                                                                                              |
-| **Custom scheduler / `setScheduler()`**           | Batch is synchronous and a write flushes before it returns, so there is no queue to schedule. Deferral is the caller's: write on a later task. See [Flush model](#flush-model).                                                                                                                                                |
-| **A flush barrier (`flushSync`, `nextTick`)**     | A barrier is what a deferred model owes its callers; this model never holds work, so a barrier has nothing to report on. `flushSync()` shipped through v1.x and was a no-op from every position a caller could occupy; removed in v2.0.0.                                                                                      |
-| **Controlled form inputs**                        | `patch()` syncs `checked`, `selected` and `input`/`textarea` `value`, so the render owns them. It has no change routing or state ownership, so a surface re-rendered while a user types must own the field itself.                                                                                                             |
-| **Waking subscribers of a self-writing computed** | A computed that writes a signal it reads is re-read correctly (it is marked stale so the next read re-runs it), but its own subscribers are not woken, so an effect depending on it does not re-run until something else notifies it. Writing a source from a computed body is outside the intended shape; do it in an effect. |
+- The signal engine follows the design of [@preact/signals-core](https://github.com/preactjs/signals) in its dependency graph, its glitch-free computed refresh, its run-on-write effects and its untracked `subscribe` callback.
+- The `on()` helper follows [Solid](https://github.com/solidjs/solid)'s `on()`, and `untracked()` is Solid's `untrack()` under the name Preact gives it.
 
 ## Contributing
 
-Issues and PRs are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the
-conventions and how to run the checks locally.
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Disclaimer
 

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/reactive",
-  "version": "2.1.2",
+  "version": "2.2.0-dev.1",
   "license": "Apache-2.0",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/reactive",
-  "version": "2.1.2",
+  "version": "2.2.0-dev.1",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -21,17 +21,15 @@
     "@stryker-mutator/typescript-checker": "10.0.0",
     "@stryker-mutator/vitest-runner": "10.0.0",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/browser": "5.0.1",
-    "@vitest/browser-playwright": "5.0.1",
-    "@vitest/coverage-v8": "5.0.1",
-    "eslint": "10.10.0",
-    "fast-check": "4.10.1",
-    "knip": "6.36.0",
+    "@vitest/browser-playwright": "5.0.3",
+    "eslint": "10.12.0",
+    "fast-check": "4.10.2",
+    "knip": "6.39.0",
     "playwright": "1.63.0",
-    "prettier": "3.9.7",
+    "prettier": "3.9.9",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.70.0",
-    "vitest": "5.0.1"
+    "typescript-eslint": "8.71.0",
+    "vitest": "5.0.3"
   },
   "overrides": {
     "qs": "^6.15.2"

package/src/signal.ts

@@ -682,9 +682,8 @@ export function untracked<T>(fn: () => T): T {
  *  This exists because the two-tier shape `createCollection` and `bindList` are
  *  built on produces it: a scope reads per-entity values through `signalFor`,
  *  so it must depend on the structure signal separately to re-run when the id
- *  set changes, and that dependency has no value the body wants. Spelling it as
- *  a discarded expression left the intent to a comment, and `undefined` entries
- *  are accepted so a per-key lookup that may miss (`signalFor(id)`,
+ *  set changes, and that dependency has no value the body wants. `undefined`
+ *  entries are accepted so a per-key lookup that may miss (`signalFor(id)`,
  *  `SignalMap.get(id)`) can be passed straight in.
  *
  *  Not a substitute for `on()`, which declares an exhaustive dependency list
@@ -698,8 +697,7 @@ export function touch(
   }
 }
 
-// Named so the read is a call rather than a discarded expression: the value is
-// deliberately unused, and returning it is what keeps that legible.
+// deadset:ignore DS1803 -- returning the value keeps the tracking read from being a discarded expression; typescript-eslint rejects void on a property read
 function readForDependency(sig: Signal<unknown> | ReadonlySignal<unknown> | undefined): unknown {
   return sig?.value;
 }