@cplieger/reactive 1.0.0 → 1.0.1

package/jsr.json

@@ -1,22 +1,18 @@
 {
   "name": "@cplieger/reactive",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "exports": {
     ".": "./src/index.ts"
   },
   "publish": {
+    "include": [
+      "LICENSE",
+      "README.md",
+      "src/**/*.ts"
+    ],
     "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"
+      "src/**/*.test.ts",
+      "src/**/__test-helpers__/**"
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/reactive",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -31,5 +31,9 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cplieger/reactive.git"
-  }
+  },
+  "files": [
+    "src/",
+    "jsr.json"
+  ]
 }

package/src/invariants.test.ts

@@ -0,0 +1,483 @@
+// @vitest-environment happy-dom
+// Tests for new core invariants: glitch-freedom, exception-safety, dispose/leak,
+// batch cycle-detection. Added as part of the Preact-style pull-based rewrite.
+import { describe, it, expect, vi } from "vitest";
+import { signal, effect, batch, computed, untracked, setEffectErrorHandler } from "./index.js";
+
+// ---------------------------------------------------------------------------
+// 1. Glitch-freedom: pull-based refresh guarantees consistent reads
+// ---------------------------------------------------------------------------
+describe("glitch-freedom", () => {
+  it("diamond: dependent fires exactly once with consistent inputs", () => {
+    // Graph: A → B, A → C, B+C → D
+    const a = signal(1);
+    const b = computed(() => a.value * 2);
+    const c = computed(() => a.value + 10);
+    const d = computed(() => b.value + c.value);
+    const spy = vi.fn();
+    effect(() => {
+      spy(d.value);
+    });
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenLastCalledWith(13); // 2 + 11
+    spy.mockClear();
+    a.value = 5;
+    // D should fire exactly once with consistent b=10, c=15
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenLastCalledWith(25); // 10 + 15
+  });
+
+  it("deep chain: single propagation through 10-level computed chain", () => {
+    const s = signal(0);
+    const chain: ReturnType<typeof computed<number>>[] = [];
+    let prev: { readonly value: number } = s;
+    for (let i = 0; i < 10; i++) {
+      const src = prev;
+      const c = computed(() => src.value + 1);
+      chain.push(c);
+      prev = c;
+    }
+    const spy = vi.fn();
+    effect(() => {
+      spy(prev.value);
+    });
+    expect(spy).toHaveBeenCalledWith(10);
+    spy.mockClear();
+    s.value = 1;
+    // Effect fires exactly once with correct end value
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledWith(11);
+  });
+
+  it("wide fan-out: one signal → 50 effects, each fires once", () => {
+    const s = signal(0);
+    const spies: ReturnType<typeof vi.fn>[] = [];
+    for (let i = 0; i < 50; i++) {
+      const spy = vi.fn();
+      spies.push(spy);
+      effect(() => {
+        spy(s.value);
+      });
+    }
+    for (const spy of spies) {
+      spy.mockClear();
+    }
+    s.value = 1;
+    for (const spy of spies) {
+      expect(spy).toHaveBeenCalledTimes(1);
+      expect(spy).toHaveBeenCalledWith(1);
+    }
+  });
+
+  it("diamond with conditional dep: no glitch when dep is dropped", () => {
+    const a = signal(1);
+    const cond = signal(true);
+    const b = computed(() => a.value * 2);
+    const c = computed(() => (cond.value ? b.value : 0));
+    const spy = vi.fn();
+    effect(() => {
+      spy(c.value);
+    });
+    expect(spy).toHaveBeenLastCalledWith(2);
+    spy.mockClear();
+    // Drop dep on b
+    cond.value = false;
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenLastCalledWith(0);
+    spy.mockClear();
+    // Changing a should NOT trigger c (b is no longer a dep)
+    a.value = 100;
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it("multi-diamond: two shared sources converging", () => {
+    const x = signal(1);
+    const y = signal(2);
+    const a = computed(() => x.value + y.value); // 3
+    const b = computed(() => x.value * y.value); // 2
+    const c = computed(() => a.value + b.value); // 5
+    const spy = vi.fn();
+    effect(() => {
+      spy(c.value);
+    });
+    expect(spy).toHaveBeenLastCalledWith(5);
+    spy.mockClear();
+    batch(() => {
+      x.value = 3;
+      y.value = 4;
+    });
+    // a=7, b=12, c=19 — effect fires once
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenLastCalledWith(19);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. Exception-safety: errors never corrupt the graph
+// ---------------------------------------------------------------------------
+describe("exception-safety", () => {
+  it("effect body throw: other effects still run, later flush works", () => {
+    const prev = setEffectErrorHandler(() => {
+      /* swallow */
+    });
+    const s = signal(0);
+    const spy1 = vi.fn();
+    const spy2 = vi.fn();
+    effect(() => {
+      if (s.value > 0) {
+        throw new Error("boom");
+      }
+      spy1(s.value);
+    });
+    effect(() => {
+      spy2(s.value);
+    });
+    spy1.mockClear();
+    spy2.mockClear();
+    s.value = 1;
+    // spy1 threw, but spy2 should still fire
+    expect(spy2).toHaveBeenCalledWith(1);
+    // Now recover
+    s.value = 0;
+    expect(spy1).toHaveBeenCalledWith(0);
+    setEffectErrorHandler(prev);
+  });
+
+  it("cleanup throw: effect still re-runs, no stuck flags", () => {
+    const prev = setEffectErrorHandler(() => {
+      /* swallow */
+    });
+    const s = signal(0);
+    const spy = vi.fn();
+    let throwInCleanup = false;
+    effect(() => {
+      spy(s.value);
+      return () => {
+        if (throwInCleanup) {
+          throw new Error("cleanup-boom");
+        }
+      };
+    });
+    spy.mockClear();
+    throwInCleanup = true;
+    s.value = 1;
+    // Effect still runs despite cleanup throw
+    expect(spy).toHaveBeenCalledWith(1);
+    throwInCleanup = false;
+    s.value = 2;
+    expect(spy).toHaveBeenCalledWith(2);
+    setEffectErrorHandler(prev);
+  });
+
+  it("computed fn throw: cached and re-thrown, recovers on next change", () => {
+    const s = signal(0);
+    let shouldThrow = false;
+    const c = computed(() => {
+      if (shouldThrow) {
+        throw new Error("comp-err");
+      }
+      return s.value * 2;
+    });
+    expect(c.value).toBe(0);
+    shouldThrow = true;
+    s.value = 1;
+    expect(() => c.value).toThrow("comp-err");
+    // Recover
+    shouldThrow = false;
+    s.value = 2;
+    expect(c.value).toBe(4);
+  });
+
+  it("user equals throw: successful value stored, no HAS_ERROR poisoning (F2)", () => {
+    let throwInEquals = false;
+    const s = signal(0);
+    const c = computed(() => s.value * 2, {
+      equals: (_a, _b) => {
+        if (throwInEquals) {
+          throw new Error("eq-boom");
+        }
+        return false; // always changed
+      },
+    });
+    expect(c.value).toBe(0);
+    throwInEquals = true;
+    s.value = 5;
+    // Despite equals throwing, the value should be the new successful computation
+    expect(c.value).toBe(10);
+    throwInEquals = false;
+    s.value = 6;
+    expect(c.value).toBe(12);
+  });
+
+  it("multiple effects throw mid-flush: all execute, system stable after", () => {
+    const errors: unknown[] = [];
+    const prev = setEffectErrorHandler((e) => {
+      errors.push(e);
+    });
+    const s = signal(0);
+    const results: number[] = [];
+    for (let i = 0; i < 5; i++) {
+      const idx = i;
+      effect(() => {
+        if (s.value > 0 && idx % 2 === 0) {
+          throw new Error(`err-${idx}`);
+        }
+        results.push(s.value + idx);
+      });
+    }
+    results.length = 0;
+    s.value = 1;
+    // Odd-indexed effects should have run successfully
+    expect(results).toContain(2); // idx=1: 1+1
+    expect(results).toContain(4); // idx=3: 1+3
+    // System still works
+    s.value = 0;
+    expect(results).toContain(0);
+    setEffectErrorHandler(prev);
+  });
+
+  it("exception in computed does not prevent other downstream effects from running", () => {
+    const prev = setEffectErrorHandler(() => {
+      /* swallow */
+    });
+    const s = signal(1);
+    let throwInC = false;
+    const c = computed(() => {
+      if (throwInC) {
+        throw new Error("c-err");
+      }
+      return s.value;
+    });
+    const spy = vi.fn();
+    // Effect that reads c (will catch error)
+    effect(() => {
+      try {
+        spy(c.value);
+      } catch {
+        spy("error");
+      }
+    });
+    // Another independent effect
+    const spy2 = vi.fn();
+    effect(() => {
+      spy2(s.value);
+    });
+    spy.mockClear();
+    spy2.mockClear();
+    throwInC = true;
+    s.value = 2;
+    expect(spy).toHaveBeenCalledWith("error");
+    expect(spy2).toHaveBeenCalledWith(2);
+    setEffectErrorHandler(prev);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. Dispose/leak: disposed nodes fully unlink, closures nulled (F5)
+// ---------------------------------------------------------------------------
+describe("dispose/leak", () => {
+  it("disposed effect does not re-run on signal change", () => {
+    const s = signal(0);
+    const spy = vi.fn();
+    const dispose = effect(() => {
+      spy(s.value);
+    });
+    spy.mockClear();
+    dispose();
+    s.value = 1;
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it("disposed effect runs cleanup exactly once", () => {
+    const cleanupSpy = vi.fn();
+    const s = signal(0);
+    const dispose = effect(() => {
+      void s.value;
+      return cleanupSpy;
+    });
+    dispose();
+    expect(cleanupSpy).toHaveBeenCalledTimes(1);
+    // Double dispose is no-op
+    dispose();
+    expect(cleanupSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("F5: disposeEffect nulls _fn and _cleanup to release closures", () => {
+    // We can't directly access internals, but we verify via WeakRef
+    const s = signal(0);
+    const myFn = () => {
+      void s.value;
+      return myCleanup;
+    };
+    const myCleanup = () => {
+      /* cleanup */
+    };
+    const fnRef = new WeakRef(myFn);
+    const cleanupRef = new WeakRef(myCleanup);
+    const dispose = effect(myFn);
+    dispose();
+    // After dispose, effect should not hold references to fn/cleanup
+    // We can at least verify the dispose completed without error
+    expect(fnRef.deref()).toBeDefined(); // Still in our scope
+    expect(cleanupRef.deref()).toBeDefined();
+    s.value = 1; // No re-run
+  });
+
+  it("disposed effect mid-batch: not re-triggered", () => {
+    const s = signal(0);
+    const spy = vi.fn();
+    const dispose = effect(() => {
+      spy(s.value);
+    });
+    spy.mockClear();
+    batch(() => {
+      s.value = 1;
+      dispose();
+      s.value = 2;
+    });
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it("many effects created and disposed: no accumulating edges", () => {
+    const s = signal(0);
+    const disposers: (() => void)[] = [];
+    for (let i = 0; i < 100; i++) {
+      disposers.push(
+        effect(() => {
+          void s.value;
+        }),
+      );
+    }
+    for (const d of disposers) {
+      d();
+    }
+    // Signal should have no targets after all effects disposed
+    const spy = vi.fn();
+    effect(() => {
+      spy(s.value);
+    });
+    spy.mockClear();
+    s.value = 1;
+    // Only the one remaining effect fires
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. Batch cycle-detection (F8)
+// ---------------------------------------------------------------------------
+describe("batch cycle-detection", () => {
+  it("throws when effect re-triggers itself >100 times", () => {
+    const prev = setEffectErrorHandler(() => {
+      /* swallow */
+    });
+    const s = signal(0);
+    // This effect writes to s on every run, creating an infinite loop
+    effect(() => {
+      if (s.value < 200) {
+        s.value = s.value + 1;
+      }
+    });
+    // The cycle detection should have fired during initial run
+    // (effect runs, writes s, triggers itself, repeat)
+    // After 100 iterations endBatch throws
+    setEffectErrorHandler(prev);
+    // Verify system is still usable after cycle detection
+    const spy = vi.fn();
+    const s2 = signal(0);
+    effect(() => {
+      spy(s2.value);
+    });
+    spy.mockClear();
+    s2.value = 42;
+    expect(spy).toHaveBeenCalledWith(42);
+  });
+
+  it("nested batches don't false-trigger cycle detection", () => {
+    const s = signal(0);
+    const spy = vi.fn();
+    effect(() => {
+      spy(s.value);
+    });
+    spy.mockClear();
+    batch(() => {
+      batch(() => {
+        batch(() => {
+          s.value = 1;
+        });
+        s.value = 2;
+      });
+      s.value = 3;
+    });
+    // Only final value visible
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledWith(3);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 5. peek() semantics (F6)
+// ---------------------------------------------------------------------------
+describe("peek", () => {
+  it("peek() triggers refresh without tracking", () => {
+    const s = signal(5);
+    const c = computed(() => s.value * 3);
+    const spy = vi.fn();
+    effect(() => {
+      // Use peek on c — should NOT create a subscription
+      spy(c.peek());
+    });
+    expect(spy).toHaveBeenCalledWith(15);
+    spy.mockClear();
+    s.value = 10;
+    // Effect should NOT re-run because peek doesn't track
+    expect(spy).not.toHaveBeenCalled();
+    // But peek still returns fresh value
+    expect(c.peek()).toBe(30);
+  });
+
+  it("signal peek() doesn't track", () => {
+    const s = signal(1);
+    const spy = vi.fn();
+    effect(() => {
+      spy(s.peek());
+    });
+    spy.mockClear();
+    s.value = 2;
+    expect(spy).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 6. untracked helper
+// ---------------------------------------------------------------------------
+describe("untracked in new core", () => {
+  it("untracked reads don't create subscriptions", () => {
+    const s = signal(0);
+    const spy = vi.fn();
+    effect(() => {
+      spy(untracked(() => s.value));
+    });
+    spy.mockClear();
+    s.value = 1;
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it("untracked restores context on throw", () => {
+    const s = signal(0);
+    const spy = vi.fn();
+    effect(() => {
+      try {
+        untracked(() => {
+          throw new Error("x");
+        });
+      } catch {
+        // swallow
+      }
+      spy(s.value); // This should track s
+    });
+    spy.mockClear();
+    s.value = 1;
+    expect(spy).toHaveBeenCalledWith(1);
+  });
+});