@praxisjs/core 0.4.0 → 0.4.1

package/src/__tests__/persisted-signal.test.ts

@@ -0,0 +1,87 @@
+// @vitest-environment jsdom
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+import { persistedSignal } from "../signal/persisted";
+
+beforeEach(() => {
+  localStorage.clear();
+});
+
+describe("persistedSignal", () => {
+  it("returns initialValue when nothing is stored", () => {
+    const s = persistedSignal("key1", 42);
+    expect(s()).toBe(42);
+  });
+
+  it("reads existing value from localStorage", () => {
+    localStorage.setItem("key2", "99");
+    const s = persistedSignal("key2", 0);
+    expect(s()).toBe(99);
+  });
+
+  it("persists set() to localStorage", () => {
+    const s = persistedSignal("key3", 0);
+    s.set(7);
+    expect(localStorage.getItem("key3")).toBe("7");
+    expect(s()).toBe(7);
+  });
+
+  it("persists update() to localStorage", () => {
+    const s = persistedSignal("key4", 10);
+    s.update((v) => v + 5);
+    expect(localStorage.getItem("key4")).toBe("15");
+    expect(s()).toBe(15);
+  });
+
+  it("removes the key when set to null", () => {
+    const s = persistedSignal<string | null>("key5", "hello");
+    s.set(null);
+    expect(localStorage.getItem("key5")).toBeNull();
+  });
+
+  it("marks __isSignal = true", () => {
+    const s = persistedSignal("key6", 0);
+    expect(s.__isSignal).toBe(true);
+  });
+
+  it("supports custom serialize/deserialize", () => {
+    const s = persistedSignal("key7", { x: 1 }, {
+      serialize: (v) => JSON.stringify(v),
+      deserialize: (raw) => JSON.parse(raw) as { x: number },
+    });
+    s.set({ x: 99 });
+    expect(localStorage.getItem("key7")).toBe('{"x":99}');
+    const s2 = persistedSignal("key7", { x: 0 }, {
+      serialize: JSON.stringify,
+      deserialize: (raw) => JSON.parse(raw) as { x: number },
+    });
+    expect(s2().x).toBe(99);
+  });
+
+  it("falls back to initialValue when deserialization fails", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    localStorage.setItem("key8", "{ bad json");
+    const s = persistedSignal("key8", 42);
+    expect(s()).toBe(42);
+    warn.mockRestore();
+  });
+
+  it("syncs from storage event on other tab", () => {
+    const s = persistedSignal("key9", 1);
+    window.dispatchEvent(
+      new StorageEvent("storage", {
+        key: "key9",
+        newValue: "55",
+        storageArea: localStorage,
+      }),
+    );
+    expect(s()).toBe(55);
+  });
+
+  it("syncTabs=false does not add storage listener", () => {
+    const s = persistedSignal("key10", 1, { syncTabs: false });
+    s.set(5);
+    // Just verify it works without errors
+    expect(s()).toBe(5);
+  });
+});

package/src/__tests__/reactive.test.ts

@@ -0,0 +1,210 @@
+import { describe, it, expect, vi } from "vitest";
+
+import { history } from "../reactive/history";
+import { when, until, debounced } from "../reactive/reactive";
+import { computed } from "../signal/computed";
+import { signal } from "../signal/signal";
+
+// ---------- when ----------
+
+describe("when", () => {
+  it("calls fn immediately when source is already truthy", () => {
+    const s = signal<number>(5);
+    const fn = vi.fn();
+    when(s, fn);
+    expect(fn).toHaveBeenCalledWith(5);
+  });
+
+  it("calls fn once the source becomes truthy", () => {
+    const s = signal<number>(0);
+    const fn = vi.fn();
+    when(s, fn);
+    expect(fn).not.toHaveBeenCalled();
+    s.set(1);
+    expect(fn).toHaveBeenCalledWith(1);
+  });
+
+  it("only fires once, even if source changes again", () => {
+    const s = signal(0);
+    const fn = vi.fn();
+    when(s, fn);
+    s.set(1);
+    s.set(2);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not re-fire after immediate truthy source changes again", () => {
+    // Regression: when source is truthy on first run, stop?.() was a no-op
+    // because `stop` hadn't been assigned yet. The effect must be cancelled
+    // after firing so further source changes do not re-trigger fn.
+    const s = signal(1); // immediately truthy
+    const fn = vi.fn();
+    when(s, fn);
+    expect(fn).toHaveBeenCalledTimes(1);
+    s.set(2);
+    s.set(3);
+    expect(fn).toHaveBeenCalledTimes(1); // must still be 1
+  });
+
+  it("does not call fn when source stays falsy", () => {
+    const s = signal<number>(0);
+    const fn = vi.fn();
+    when(s, fn);
+    s.set(0);
+    expect(fn).not.toHaveBeenCalled();
+  });
+});
+
+// ---------- until ----------
+
+describe("until", () => {
+  it("resolves immediately when source is already truthy", async () => {
+    const s = signal(42);
+    const value = await until(s);
+    expect(value).toBe(42);
+  });
+
+  it("resolves when source becomes truthy", async () => {
+    const s = signal<number>(0);
+    const promise = until(s);
+    s.set(7);
+    expect(await promise).toBe(7);
+  });
+});
+
+// ---------- debounced ----------
+
+describe("debounced", () => {
+  it("returns initial value immediately", () => {
+    vi.useFakeTimers();
+    const s = signal(1);
+    const d = debounced(s, 100);
+    expect(d()).toBe(1);
+    vi.useRealTimers();
+  });
+
+  it("debounces rapid updates", () => {
+    vi.useFakeTimers();
+    const s = signal(1);
+    const d = debounced(s, 100);
+
+    s.set(2);
+    s.set(3);
+    s.set(4);
+
+    expect(d()).toBe(1); // not yet updated
+
+    vi.advanceTimersByTime(100);
+    expect(d()).toBe(4); // settled on last value
+    vi.useRealTimers();
+  });
+
+  it("emits each value when updates are spaced apart", () => {
+    vi.useFakeTimers();
+    const s = signal(0);
+    const d = debounced(s, 50);
+
+    s.set(1);
+    vi.advanceTimersByTime(50);
+    expect(d()).toBe(1);
+
+    s.set(2);
+    vi.advanceTimersByTime(50);
+    expect(d()).toBe(2);
+    vi.useRealTimers();
+  });
+});
+
+// ---------- history ----------
+
+describe("history", () => {
+  it("current reflects signal value", () => {
+    const s = signal("a");
+    const h = history(s);
+    expect(h.current()).toBe("a");
+  });
+
+  it("canUndo is false initially", () => {
+    const s = signal(0);
+    const h = history(s);
+    expect(h.canUndo()).toBe(false);
+  });
+
+  it("canUndo becomes true after a change", () => {
+    const s = signal(0);
+    const h = history(s);
+    s.set(1);
+    expect(h.canUndo()).toBe(true);
+  });
+
+  it("undo reverts to previous value", () => {
+    const s = signal(0);
+    const h = history(s);
+    s.set(1);
+    s.set(2);
+    h.undo();
+    expect(h.current()).toBe(1);
+    expect(s()).toBe(1);
+  });
+
+  it("redo re-applies reverted value", () => {
+    const s = signal(0);
+    const h = history(s);
+    s.set(1);
+    h.undo();
+    expect(h.canRedo()).toBe(true);
+    h.redo();
+    expect(h.current()).toBe(1);
+    expect(s()).toBe(1);
+  });
+
+  it("values() returns full timeline", () => {
+    const s = signal("a");
+    const h = history(s);
+    s.set("b");
+    s.set("c");
+    expect(h.values()).toEqual(["a", "b", "c"]);
+  });
+
+  it("clear removes past and future", () => {
+    const s = signal(0);
+    const h = history(s);
+    s.set(1);
+    s.set(2);
+    h.clear();
+    expect(h.canUndo()).toBe(false);
+    expect(h.canRedo()).toBe(false);
+  });
+
+  it("undo does nothing when there is no history", () => {
+    const s = signal(5);
+    const h = history(s);
+    h.undo();
+    expect(h.current()).toBe(5);
+  });
+
+  it("redo does nothing when there is no future", () => {
+    const s = signal(5);
+    const h = history(s);
+    s.set(10);
+    h.redo();
+    expect(h.current()).toBe(10);
+  });
+
+  it("works with computed source (read-only — no signal.set)", () => {
+    const s = signal(1);
+    const c = computed(() => s() * 2);
+    const h = history(c);
+    s.set(2);
+    expect(h.current()).toBe(4);
+    expect(h.canUndo()).toBe(true);
+  });
+
+  it("respects limit — oldest entries are dropped", () => {
+    const s = signal(0);
+    const h = history(s, 3);
+    for (let i = 1; i <= 5; i++) s.set(i);
+    // past holds at most 3, plus current = 4 values total
+    expect(h.values().length).toBeLessThanOrEqual(4);
+  });
+});

package/src/__tests__/resource.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect, vi } from "vitest";
+
+import { resource, createResource } from "../async/resource";
+import { signal } from "../signal/signal";
+
+describe("resource", () => {
+  it("starts as pending and resolves to success", async () => {
+    const r = resource(() => Promise.resolve("hello"));
+    expect(r.status()).toBe("pending");
+    await vi.waitFor(() => r.status() === "success");
+    expect(r.data()).toBe("hello");
+    expect(r.pending()).toBe(false);
+    expect(r.error()).toBeNull();
+  });
+
+  it("transitions to error on rejection", async () => {
+    const r = resource(() => Promise.reject(new Error("oops")));
+    await new Promise((res) => setTimeout(res, 0));
+    expect(r.status()).toBe("error");
+    expect((r.error() as Error).message).toBe("oops");
+    expect(r.data()).toBeNull();
+  });
+
+  it("wraps non-Error rejections in Error", async () => {
+    const r = resource(() => Promise.reject("plain string"));
+    await new Promise((res) => setTimeout(res, 0));
+    expect(r.status()).toBe("error");
+    expect(r.error()).toBeInstanceOf(Error);
+  });
+
+  it("immediate=false does not fetch on creation", () => {
+    const fetcher = vi.fn(() => Promise.resolve(1));
+    const r = resource(fetcher, { immediate: false });
+    expect(fetcher).not.toHaveBeenCalled();
+    expect(r.status()).toBe("idle");
+  });
+
+  it("refetch() re-runs the fetcher", async () => {
+    let count = 0;
+    const r = resource(() => Promise.resolve(++count));
+    await vi.waitFor(() => r.status() === "success");
+    expect(r.data()).toBe(1);
+    r.refetch();
+    await vi.waitFor(() => r.data() === 2);
+    expect(r.data()).toBe(2);
+  });
+
+  it("cancel() sets status back to idle and ignores in-flight result", async () => {
+    let resolve!: (v: number) => void;
+    const r = resource(() => new Promise<number>((res) => { resolve = res; }));
+    r.cancel();
+    expect(r.status()).toBe("idle");
+    resolve(99);
+    await new Promise((r) => setTimeout(r, 10));
+    expect(r.data()).toBeNull(); // stale result ignored
+  });
+
+  it("mutate() sets data directly", async () => {
+    const r = resource(() => Promise.resolve(1));
+    await vi.waitFor(() => r.status() === "success");
+    r.mutate(999);
+    expect(r.data()).toBe(999);
+    expect(r.status()).toBe("success");
+    expect(r.error()).toBeNull();
+  });
+
+  it("initialData is visible when immediate=false", () => {
+    const r = resource(
+      () => new Promise<string>(() => {}),
+      { initialData: "cached", immediate: false },
+    );
+    expect(r.data()).toBe("cached");
+    expect(r.status()).toBe("idle");
+  });
+
+  it("keepPreviousData=true preserves old data during refetch", async () => {
+    let call = 0;
+    const r = resource(() => Promise.resolve(++call), { keepPreviousData: true });
+    await vi.waitFor(() => r.data() === 1);
+    r.refetch();
+    // data should still be 1 while pending
+    expect(r.data()).toBe(1);
+    await vi.waitFor(() => r.data() === 2);
+  });
+});
+
+describe("createResource", () => {
+  it("re-fetches when the param signal changes", async () => {
+    const id = signal(1);
+    const fetcher = vi.fn((n: number) => Promise.resolve(n * 10));
+    const r = createResource(id, fetcher);
+    await vi.waitFor(() => r.data() === 10);
+    id.set(2);
+    await vi.waitFor(() => r.data() === 20);
+    expect(fetcher).toHaveBeenCalledTimes(2);
+  });
+});

package/src/__tests__/signal.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from "vitest";
+
+import { signal } from "../signal/signal";
+
+describe("signal", () => {
+  it("returns initial value", () => {
+    const s = signal(42);
+    expect(s()).toBe(42);
+  });
+
+  it("updates value with set", () => {
+    const s = signal(0);
+    s.set(10);
+    expect(s()).toBe(10);
+  });
+
+  it("updates value with update fn", () => {
+    const s = signal(5);
+    s.update((v) => v * 2);
+    expect(s()).toBe(10);
+  });
+
+  it("skips update when value is identical", () => {
+    const s = signal(1);
+    const calls: number[] = [];
+    s.subscribe((v) => calls.push(v));
+    const before = calls.length;
+    s.set(1); // same value
+    expect(calls.length).toBe(before);
+  });
+
+  it("subscribe fires immediately with current value", () => {
+    const s = signal("hello");
+    const received: string[] = [];
+    s.subscribe((v) => received.push(v));
+    expect(received).toEqual(["hello"]);
+  });
+
+  it("subscribe fires on subsequent updates", () => {
+    const s = signal(0);
+    const received: number[] = [];
+    s.subscribe((v) => received.push(v));
+    s.set(1);
+    s.set(2);
+    expect(received).toEqual([0, 1, 2]);
+  });
+
+  it("unsubscribe stops receiving updates", () => {
+    const s = signal(0);
+    const received: number[] = [];
+    const unsub = s.subscribe((v) => received.push(v));
+    unsub();
+    s.set(99);
+    expect(received).toEqual([0]);
+  });
+
+  it("marks __isSignal = true", () => {
+    const s = signal(0);
+    expect(s.__isSignal).toBe(true);
+  });
+
+  it("supports object values", () => {
+    const s = signal<{ name: string }>({ name: "Alice" });
+    s.set({ name: "Bob" });
+    expect(s().name).toBe("Bob");
+  });
+
+  it("supports null and undefined", () => {
+    const s = signal<null | number>(null);
+    expect(s()).toBeNull();
+    s.set(5);
+    expect(s()).toBe(5);
+  });
+});

package/src/__tests__/track.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect, vi } from "vitest";
+
+import { track, runEffect, activeEffect } from "../signal/effect";
+import { signal } from "../signal/signal";
+
+describe("track", () => {
+  it("runs the effect immediately", () => {
+    const fn = vi.fn();
+    track(fn);
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it("sets activeEffect during execution, resets after", () => {
+    let during: unknown = "not-set";
+    track(() => {
+      during = activeEffect;
+    });
+    expect(during).toBeTypeOf("function");
+    expect(activeEffect).toBeNull();
+  });
+
+  it("supports nested track calls — restores outer effect", () => {
+    const outer = vi.fn();
+    const inner = vi.fn();
+    let outerActive: unknown;
+    let innerActive: unknown;
+
+    track(() => {
+      outer();
+      outerActive = activeEffect;
+      track(() => {
+        inner();
+        innerActive = activeEffect;
+      });
+      // after inner track, activeEffect should be back to outer
+      expect(activeEffect).toBe(outerActive);
+    });
+
+    expect(outer).toHaveBeenCalledOnce();
+    expect(inner).toHaveBeenCalledOnce();
+    expect(innerActive).not.toBe(outerActive);
+  });
+
+  it("subscribes the tracked effect to signals read inside it", () => {
+    const s = signal(1);
+    const values: number[] = [];
+    track(() => values.push(s()));
+    s.set(2);
+    expect(values).toEqual([1, 2]);
+  });
+});
+
+describe("runEffect", () => {
+  it("sets activeEffect to the given value", () => {
+    const fn = () => {};
+    runEffect(fn);
+    expect(activeEffect).toBe(fn);
+    runEffect(null);
+    expect(activeEffect).toBeNull();
+  });
+});

package/src/reactive/reactive.ts

@@ -8,16 +8,24 @@ export function when<T>(
   fn: (value: NonNullable<T>) => void,
 ) {
   let disposed = false;
+  const ref = { cancel: undefined as (() => void) | undefined };
 
   const stop = effect(() => {
     const value = source();
     if (!value || disposed) return;
 
     disposed = true;
-    stop();
+    ref.cancel?.();
     fn(value);
   });
 
+  ref.cancel = stop;
+
+  // If source was truthy on the first synchronous run, ref.cancel?.() above
+  // was a no-op because it hadn't been assigned yet. Cancel the effect now.
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (disposed) stop();
+
   return stop;
 }
 

package/src/signal/persisted.ts

@@ -60,20 +60,18 @@ export function persistedSignal<T>(
 
   if (syncTabs) {
     window.addEventListener("storage", (event) => {
-      if (event.key === key || event.storageArea !== localStorage) return;
-      {
-        try {
-          const newValue = event.newValue
-            ? deserialize(event.newValue)
-            : initialValue;
-          inner.set(newValue);
-        } catch (e) {
-          console.warn(
-            `Failed to deserialize value for key "${key}" from storage event:`,
-            e,
-          );
-          inner.set(initialValue);
-        }
+      if (event.key !== key || event.storageArea !== localStorage) return;
+      try {
+        const newValue = event.newValue
+          ? deserialize(event.newValue)
+          : initialValue;
+        inner.set(newValue);
+      } catch (e) {
+        console.warn(
+          `Failed to deserialize value for key "${key}" from storage event:`,
+          e,
+        );
+        inner.set(initialValue);
       }
     });
   }