@cplieger/reactive 1.0.0

package/README.md

@@ -0,0 +1,120 @@
+# reactive
+
+[![CI](https://github.com/cplieger/reactive/actions/workflows/ci.yaml/badge.svg)](https://github.com/cplieger/reactive/actions/workflows/ci.yaml)
+[![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)
+[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](LICENSE)
+
+> Signals + DOM-reconciliation micro-framework for TypeScript
+
+A standalone reactive primitives library providing fine-grained signals with automatic dependency tracking, synchronous batched effects, keyed-list DOM reconciliation, structural tree-diffing, and a typed per-key reactive store. Zero dependencies beyond the DOM API.
+
+Mirrors semantics from @preact/signals-core and solid-js reactivity.
+
+## Install
+
+```sh
+npx jsr add @cplieger/reactive
+# or
+npm i @cplieger/reactive
+```
+
+## Usage
+
+```typescript
+import {
+  signal,
+  effect,
+  batch,
+  computed,
+  untracked,
+  subscribe,
+  isSignal,
+  isComputed,
+} from "@cplieger/reactive";
+
+const count = signal(0);
+const doubled = computed(() => count.value * 2);
+
+effect(() => {
+  console.log("count:", count.value, "doubled:", doubled.value);
+  return undefined;
+});
+
+batch(() => {
+  count.value = 1;
+  count.value = 2; // effect fires once with value 2, synchronously at batch end
+});
+
+// Read without tracking
+effect(() => {
+  const tracked = count.value;
+  const notTracked = untracked(() => doubled.value);
+  console.log(tracked, notTracked);
+  return undefined;
+});
+
+// Subscribe utility
+const dispose = subscribe(count, (v) => console.log("count changed:", v));
+dispose();
+
+// Type guards
+isSignal(count); // true
+isComputed(doubled); // true
+```
+
+## 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
+- `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 | undefined` — explicit dependency declaration helper (like Solid `on()`). Pass into `effect()` or `computed()`.
+- `subscribe(signal, cb): () => void` — subscribe to a signal, calling cb immediately and on every change
+- `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
+
+### DOM Reconciliation
+
+- `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
+- `reconcileChildren(parent, newChildren)` — low-level child reconciliation against existing DOM
+- `trackHandler(el, key)` — register an `on*` property for handler reconciliation during tree-diff
+
+### Store
+
+- `createStore<M>(): Store<M>` — typed per-key reactive store with `get`, `set`, `subscribe`, `effect`, `computed`, and `batch` methods
+
+## Correctness guarantees
+
+- **Glitch-freedom**: Computed signals use equality dedup (`Object.is`) — 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).
+
+## Design Decisions — Unsupported by Design
+
+The following features are intentionally NOT implemented:
+
+| Feature                                       | Reason                                                                                                             |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| **Effect ownership tree / `createRoot`**      | Consumers manage disposal explicitly. Adding ownership adds ~150 LOC of complexity and 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. No scheduler needed.                                                                         |
+
+## License
+
+GPL-3.0 — see [LICENSE](LICENSE).

package/cliff.toml

@@ -0,0 +1,37 @@
+# Version-bump policy. Stable (1.x+): standard semver.
+# feat -> minor; breaking -> major.
+# Fresh/untagged repos start at v1.0.0 (matches "0.x is the exception" policy).
+[bump]
+features_always_bump_minor = true
+breaking_always_bump_major = true
+initial_tag = "v1.0.0"
+no_increment_regex = "^chore|^ci|^docs|^style|^test"
+
+[changelog]
+header = ""
+body = """
+{% for group, commits in commits | group_by(attribute="group") %}
+### {{ group | upper_first }}
+{% for commit in commits %}
+- {{ commit.message | upper_first }}\
+{% endfor %}
+{% endfor %}
+"""
+trim = true
+
+[git]
+conventional_commits = true
+filter_unconventional = false
+split_commits = false
+protect_breaking_commits = false
+tag_pattern = "v[0-9].*"
+
+commit_parsers = [
+  { message = "^release:", skip = true },
+  { message = "^feat", group = "Added" },
+  { message = "^fix", group = "Fixed" },
+  { message = "^sec", group = "Security" },
+  { message = "^chore\\(deps\\)", group = "Dependencies" },
+  { message = "^chore|^ci|^docs|^style|^refactor|^perf|^test", group = "Changed" },
+  { message = ".*", group = "Changed" },
+]

package/eslint.config.base.mjs

@@ -0,0 +1,187 @@
+// Strict typed-linting config.
+// References:
+//   https://typescript-eslint.io/users/configs/#strict-type-checked
+//   https://typescript-eslint.io/users/configs/#stylistic-type-checked
+//   https://typescript-eslint.io/getting-started/typed-linting
+
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default [
+  // 1. Ignore generated/build outputs and configs that don't need linting.
+  {
+    ignores: [
+      // Dependencies (any depth — vibekit's web/static-src/node_modules nests deep)
+      "**/node_modules/**",
+      // Build output / generated bundles (TS->JS, CSS bundles, etc.)
+      "**/static/**",
+      "**/static-src/dist/**",
+      "**/dist/**",
+      "**/build/**",
+      "**/.next/**",
+      "**/.cache/**",
+      "**/coverage/**",
+      // Minified / generated source
+      "**/*.min.*",
+      "**/*.gen.ts",
+      "**/*.gen.js",
+      "**/wire/*.gen.ts",
+      // Test fixtures that aren't real code
+      "**/test-stubs/**",
+      "**/__mocks__/**",
+    ],
+  },
+  // 2. Strictest official preset combination (typed linting required).
+  js.configs.recommended,
+  ...tseslint.configs.strictTypeChecked,
+  ...tseslint.configs.stylisticTypeChecked,
+
+  // 3. Project setup — projectService auto-discovers tsconfig per file.
+  {
+    languageOptions: {
+      ecmaVersion: 2024,
+      sourceType: "module",
+      parserOptions: {
+        projectService: {
+          allowDefaultProject: ["*.test.ts", "*.property.test.ts", "fc-strict-setup.ts"],
+          maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING: 20,
+        },
+        tsconfigRootDir: import.meta.dirname,
+      },
+      globals: {
+        // Browser
+        window: "readonly",
+        document: "readonly",
+        navigator: "readonly",
+        console: "readonly",
+        fetch: "readonly",
+        URL: "readonly",
+        URLSearchParams: "readonly",
+        setTimeout: "readonly",
+        clearTimeout: "readonly",
+        setInterval: "readonly",
+        clearInterval: "readonly",
+        requestAnimationFrame: "readonly",
+        cancelAnimationFrame: "readonly",
+        queueMicrotask: "readonly",
+        WebSocket: "readonly",
+        EventSource: "readonly",
+        AbortController: "readonly",
+        Headers: "readonly",
+        Request: "readonly",
+        Response: "readonly",
+        FormData: "readonly",
+        Blob: "readonly",
+        File: "readonly",
+        FileReader: "readonly",
+        IntersectionObserver: "readonly",
+        MutationObserver: "readonly",
+        ResizeObserver: "readonly",
+        CustomEvent: "readonly",
+        Event: "readonly",
+        EventTarget: "readonly",
+        TextEncoder: "readonly",
+        TextDecoder: "readonly",
+        crypto: "readonly",
+        btoa: "readonly",
+        atob: "readonly",
+        // Service Worker
+        self: "readonly",
+        ServiceWorkerGlobalScope: "readonly",
+        clients: "readonly",
+        // Test runner globals (vitest auto-injected)
+        describe: "readonly",
+        it: "readonly",
+        test: "readonly",
+        expect: "readonly",
+        beforeAll: "readonly",
+        beforeEach: "readonly",
+        afterAll: "readonly",
+        afterEach: "readonly",
+        vi: "readonly",
+      },
+    },
+    rules: {
+      // Allow `_`-prefixed unused names.
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        {
+          argsIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+          caughtErrorsIgnorePattern: "^_",
+          destructuredArrayIgnorePattern: "^_",
+          ignoreRestSiblings: true,
+        },
+      ],
+      // Enforce `import type {...}` for types.
+      "@typescript-eslint/consistent-type-imports": [
+        "error",
+        { prefer: "type-imports", fixStyle: "inline-type-imports" },
+      ],
+      // Discourage `any`, prefer `unknown`.
+      "@typescript-eslint/no-explicit-any": "error",
+      // Avoid silent fall-through bugs in async event handlers.
+      "@typescript-eslint/no-misused-promises": [
+        "error",
+        { checksVoidReturn: { attributes: false } },
+      ],
+      // Prefer literal numeric/string template parts (catches accidental coercion).
+      "@typescript-eslint/restrict-template-expressions": [
+        "error",
+        { allowNumber: true, allowBoolean: true, allowNullish: false },
+      ],
+      // Console policy.
+      "no-console": ["warn", { allow: ["warn", "error"] }],
+      // Equality: enforce strict ===.
+      eqeqeq: ["error", "always", { null: "ignore" }],
+      curly: ["error", "all"],
+      "no-var": "error",
+      "prefer-const": "error",
+      "no-throw-literal": "error",
+    },
+  },
+
+  // 4. Tests: typed but with relaxed rules (tests deliberately break invariants).
+  {
+    files: [
+      "**/*.test.ts",
+      "**/*.fuzz.test.ts",
+      "**/*.property.test.ts",
+      "**/test-helpers/**",
+      "**/__mocks__/**",
+    ],
+    rules: {
+      "@typescript-eslint/no-non-null-assertion": "off",
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-unsafe-assignment": "off",
+      "@typescript-eslint/no-unsafe-member-access": "off",
+      "@typescript-eslint/no-unsafe-call": "off",
+      "@typescript-eslint/no-unsafe-argument": "off",
+      "@typescript-eslint/no-unsafe-return": "off",
+      "@typescript-eslint/no-extraneous-class": "off",
+      "@typescript-eslint/no-unnecessary-condition": "off",
+      "@typescript-eslint/no-misused-spread": "off",
+      "@typescript-eslint/unbound-method": "off",
+      "@typescript-eslint/require-await": "off",
+      "no-console": "off",
+    },
+  },
+
+  // 5. Generated and config files + tests: drop type-checked rules.
+  {
+    files: [
+      "**/*.gen.ts",
+      "**/wire/*.ts",
+      "vitest.config.ts",
+      "*.config.ts",
+      "*.config.mjs",
+      "*.config.js",
+      "**/*.test.ts",
+      "**/*.fuzz.test.ts",
+      "**/*.property.test.ts",
+      "fc-strict-setup.ts",
+      "test-stubs/**",
+    ],
+    ...tseslint.configs.disableTypeChecked,
+  },
+];

package/jsr.json

@@ -0,0 +1,22 @@
+{
+  "name": "@cplieger/reactive",
+  "version": "1.0.0",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publish": {
+    "exclude": [
+      "**/*.test.ts",
+      "**/__test-helpers__",
+      "**/fc-strict-setup.ts",
+      "eslint.config.mjs",
+      "tsconfig.json",
+      "tsconfig.test.json",
+      "tsconfig.tests.json",
+      "vitest.config.ts",
+      "renovate.json",
+      "package-lock.json",
+      ".prettierrc.json"
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@cplieger/reactive",
+  "version": "1.0.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsgo -p tsconfig.json",
+    "typecheck:tests": "tsgo -p tsconfig.tests.json",
+    "test": "vitest --run"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@vitest/coverage-v8": "4.1.7",
+    "eslint": "10.4.1",
+    "fast-check": "4.8.0",
+    "happy-dom": "20.9.0",
+    "prettier": "3.8.3",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.60.0",
+    "vitest": "4.1.7"
+  },
+  "description": "Signals + DOM-reconciliation reactive core for TypeScript (zero dependencies)",
+  "license": "GPL-3.0-or-later",
+  "types": "./src/index.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cplieger/reactive.git"
+  }
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export {
+  signal,
+  effect,
+  batch,
+  flushSync,
+  setEffectErrorHandler,
+  computed,
+  untracked,
+  subscribe,
+  isSignal,
+  isComputed,
+  on,
+} from "./signal.js";
+export type {
+  Signal,
+  Cleanup,
+  EffectErrorHandler,
+  ReadonlySignal,
+  SignalOptions,
+} from "./signal.js";
+export { createStore } from "./store.js";
+export type { Store } from "./store.js";
+export { reconcile, KEY_ATTR } from "./reconcile.js";
+export type { ReconcileSpec } from "./reconcile.js";
+export { patch, reconcileChildren, trackHandler } from "./reconcile-tree.js";

package/src/reconcile-tree.ts

@@ -0,0 +1,169 @@
+// 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.
+
+const handlerKeysMap = new WeakMap<HTMLElement, Set<string>>();
+
+/** Register an on* handler property key for reconciliation tracking. */
+export function trackHandler(el: HTMLElement, key: string): void {
+  let keys = handlerKeysMap.get(el);
+  if (!keys) {
+    keys = new Set();
+    handlerKeysMap.set(el, keys);
+  }
+  keys.add(key);
+}
+
+/** Replace a parent's children with the given nodes/strings, reconciling against existing DOM. */
+export function patch(
+  parent: Node,
+  ...children: (string | Node | DocumentFragment | null | undefined)[]
+): void {
+  const newChildren: Node[] = [];
+  for (const child of children) {
+    if (child == null) {
+      continue;
+    }
+    if ((child as Node).nodeType === 11) {
+      newChildren.push(...Array.from((child as Node).childNodes));
+    } else if (typeof child === "string") {
+      newChildren.push(document.createTextNode(child));
+    } else {
+      newChildren.push(child);
+    }
+  }
+  reconcileChildren(parent, newChildren);
+}
+
+/** 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>();
+  for (const child of oldChildren) {
+    const key = nodeKey(child);
+    if (key) {
+      oldByKey.set(key, child);
+    }
+  }
+
+  let oldIdx = 0;
+  for (let i = 0; i < newChildren.length; i++) {
+    const newChild = newChildren[i];
+    if (newChild === undefined) {
+      continue;
+    }
+    const newKey = nodeKey(newChild);
+
+    let matched = newKey ? (oldByKey.get(newKey) ?? null) : null;
+    if (matched) {
+      oldByKey.delete(newKey);
+    } else if (!newKey) {
+      while (oldIdx < oldChildren.length) {
+        const oc = oldChildren[oldIdx];
+        if (oc === undefined || nodeKey(oc)) {
+          break;
+        }
+        oldIdx++;
+      }
+      if (oldIdx < oldChildren.length) {
+        matched = oldChildren[oldIdx] ?? null;
+        oldIdx++;
+      }
+    }
+
+    if (!matched) {
+      const ref = parent.childNodes.item(i);
+      parent.insertBefore(newChild, ref);
+      continue;
+    }
+
+    if (!canPatch(matched, newChild)) {
+      parent.replaceChild(newChild, matched);
+      continue;
+    }
+
+    const ref = parent.childNodes.item(i);
+    if (ref !== matched) {
+      parent.insertBefore(matched, ref);
+    }
+
+    if (matched.nodeType === 3) {
+      if (matched.textContent !== newChild.textContent) {
+        matched.textContent = newChild.textContent;
+      }
+    } else if (matched.nodeType === 1) {
+      patchAttrs(matched as HTMLElement, newChild as HTMLElement);
+      reconcileChildren(matched, Array.from(newChild.childNodes));
+    }
+  }
+
+  while (parent.childNodes.length > newChildren.length) {
+    const last = parent.lastChild;
+    if (last === null) {
+      break;
+    }
+    last.remove();
+  }
+}
+
+function canPatch(oldNode: Node, newNode: Node): boolean {
+  if (oldNode.nodeType !== newNode.nodeType) {
+    return false;
+  }
+  if (oldNode.nodeType === 3) {
+    return true;
+  }
+  if (oldNode.nodeType !== 1) {
+    return false;
+  }
+  return oldNode.nodeName === newNode.nodeName;
+}
+
+function nodeKey(node: Node): string {
+  if (node.nodeType !== 1) {
+    return "";
+  }
+  for (const attr of (node as Element).attributes) {
+    if (attr.name.endsWith("-id")) {
+      return `${attr.name}=${attr.value}`;
+    }
+  }
+  return "";
+}
+
+function patchAttrs(oldEl: HTMLElement, newEl: HTMLElement): void {
+  for (const attr of newEl.attributes) {
+    if (oldEl.getAttribute(attr.name) !== attr.value) {
+      oldEl.setAttribute(attr.name, attr.value);
+    }
+  }
+  for (const attr of Array.from(oldEl.attributes)) {
+    if (!newEl.hasAttribute(attr.name)) {
+      oldEl.removeAttribute(attr.name);
+    }
+  }
+  if (oldEl.hidden !== newEl.hidden) {
+    oldEl.hidden = newEl.hidden;
+  }
+
+  // Reconcile on* event handler properties (not reflected as attributes).
+  const newKeys = handlerKeysMap.get(newEl);
+  const oldKeys = handlerKeysMap.get(oldEl);
+  if (oldKeys) {
+    for (const key of oldKeys) {
+      if (!newKeys?.has(key)) {
+        (oldEl as unknown as Record<string, unknown>)[key] = null;
+      }
+    }
+  }
+  if (newKeys) {
+    const oldRec = oldEl as unknown as Record<string, unknown>;
+    const newRec = newEl as unknown as Record<string, unknown>;
+    for (const key of newKeys) {
+      oldRec[key] = newRec[key];
+    }
+    handlerKeysMap.set(oldEl, new Set(newKeys));
+  } else if (oldKeys) {
+    handlerKeysMap.delete(oldEl);
+  }
+}

package/src/reconcile.ts

@@ -0,0 +1,55 @@
+// Keyed-list DOM reconciliation with mount/update/onRemove lifecycle.
+// Identity-preserving: existing elements survive across renders.
+
+/** Attribute name used to store reconciliation keys on elements. */
+export const KEY_ATTR = "data-reconcile-key";
+
+/** Specification for keyed-list reconciliation lifecycle callbacks. */
+export interface ReconcileSpec<T> {
+  key: (item: T) => string;
+  mount: (item: T) => HTMLElement;
+  update?: (el: HTMLElement, item: T) => void;
+  onRemove?: (el: HTMLElement, key: string) => void;
+}
+
+/** Reconcile a keyed list of items into a parent node, preserving existing elements by key. */
+export function reconcile<T>(
+  parent: ParentNode,
+  items: readonly T[],
+  spec: ReconcileSpec<T>,
+): void {
+  const existing = new Map<string, HTMLElement>();
+  for (let n = parent.firstChild; n !== null; n = n.nextSibling) {
+    if (n.nodeType !== 1) {
+      continue;
+    }
+    const el = n as HTMLElement;
+    const k = el.getAttribute(KEY_ATTR);
+    if (k !== null) {
+      existing.set(k, el);
+    }
+  }
+
+  let target: Node | null = null;
+  for (let i = items.length - 1; i >= 0; i--) {
+    const item = items[i] as T;
+    const k = spec.key(item);
+    let el = existing.get(k);
+    if (el === undefined) {
+      el = spec.mount(item);
+      el.setAttribute(KEY_ATTR, k);
+    } else {
+      existing.delete(k);
+      if (spec.update) {
+        spec.update(el, item);
+      }
+    }
+    parent.insertBefore(el, target);
+    target = el;
+  }
+
+  for (const [k, el] of existing) {
+    spec.onRemove?.(el, k);
+    el.remove();
+  }
+}