@praxisjs/core 2.1.0 → 2.2.0

package/src/__tests__/computed.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi } from "vitest";
 
 import { computed, writableComputed } from "../signal/computed";
+import { effect } from "../signal/effect";
 import { signal } from "../signal/signal";
 
 describe("computed", () => {
@@ -288,3 +289,45 @@ describe("writableComputed", () => {
     expect(wc()).toBe(14);
   });
 });
+
+describe("computed.dispose", () => {
+  type Disposable<T> = (() => T) & { dispose(): void };
+
+  it("does nothing while an effect still depends on it", async () => {
+    const s = signal(1);
+    const c = computed(() => s() * 2) as unknown as Disposable<number>;
+    let seen = 0;
+    effect(() => {
+      seen = c();
+    });
+    c.dispose();
+    s.set(2);
+    await Promise.resolve();
+    expect(seen).toBe(4);
+  });
+
+  it("does nothing while another computed depends on it", () => {
+    const s = signal(1);
+    const inner = computed(() => s() * 2) as unknown as Disposable<number>;
+    const outer = computed(() => inner() + 1);
+    expect(outer()).toBe(3);
+    inner.dispose();
+    s.set(2);
+    expect(outer()).toBe(5);
+  });
+
+  it("recomputes from scratch when read again after disposal", () => {
+    const getter = vi.fn(() => 42);
+    const c = computed(getter) as unknown as Disposable<number>;
+    c();
+    c.dispose();
+    expect(c()).toBe(42);
+    expect(getter).toHaveBeenCalledTimes(2);
+  });
+
+  it("is safe on a computed that was never read", () => {
+    const c = computed(() => 1) as unknown as Disposable<number>;
+    expect(() => { c.dispose(); }).not.toThrow();
+    expect(c()).toBe(1);
+  });
+});

package/src/__tests__/effect.test.ts

@@ -194,6 +194,21 @@ describe("effect", () => {
     expect(unmatchedArrayHolder.subs).toEqual([other]);
   });
 
+  it("cleanupEffectDeps handles Set dependency holders, emptying them to null", () => {
+    const tracked = vi.fn();
+    const other = vi.fn();
+    const sharedHolder: SubscriberHolder = { subs: new Set([tracked, other]) };
+    const soleHolder: SubscriberHolder = { subs: new Set([tracked]) };
+
+    recordDependency(tracked, sharedHolder);
+    recordDependency(tracked, soleHolder);
+
+    cleanupEffectDeps(tracked);
+
+    expect([...(sharedHolder.subs as Set<() => void>)]).toEqual([other]);
+    expect(soleHolder.subs).toBeNull();
+  });
+
   it("exception inside nested track() restores outer activeEffect", () => {
     const s = signal(0);
     const outer = vi.fn();

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

@@ -1,5 +1,5 @@
 // @vitest-environment jsdom
-import { describe, it, expect, beforeEach, vi } from "vitest";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 
 import { persistedSignal } from "../signal/persisted";
 
@@ -191,4 +191,115 @@ describe("persistedSignal", () => {
     // Should stay at 20 since the event is from sessionStorage, not localStorage
     expect(s()).toBe(20);
   });
+
+  it("close() stops storage-event syncing but keeps the signal working locally", () => {
+    const s = persistedSignal("close-key", 0);
+    s.close();
+    window.dispatchEvent(
+      new StorageEvent("storage", { key: "close-key", newValue: "5", storageArea: localStorage }),
+    );
+    expect(s()).toBe(0);
+    s.set(3);
+    expect(s()).toBe(3);
+    expect(localStorage.getItem("close-key")).toBe("3");
+  });
+
+  it("close() removes the window listener and is safe to call twice", () => {
+    const remove = vi.spyOn(window, "removeEventListener");
+    const s = persistedSignal("close-twice", 0);
+    s.close();
+    s.close();
+    expect(remove.mock.calls.filter(([type]) => type === "storage")).toHaveLength(1);
+    remove.mockRestore();
+  });
+
+  it("close() is a no-op when syncTabs is false", () => {
+    const remove = vi.spyOn(window, "removeEventListener");
+    const s = persistedSignal("close-nosync", 0, { syncTabs: false });
+    expect(() => { s.close(); }).not.toThrow();
+    expect(remove.mock.calls.filter(([type]) => type === "storage")).toHaveLength(0);
+    remove.mockRestore();
+  });
+});
+
+describe("persistedSignal writeDelay", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("writes immediately by default", () => {
+    const s = persistedSignal("wd-default", 0);
+    s.set(1);
+    expect(localStorage.getItem("wd-default")).toBe("1");
+  });
+
+  it("holds writes back and flushes the latest value once the delay elapses", () => {
+    vi.useFakeTimers();
+    const setItem = vi.spyOn(Storage.prototype, "setItem");
+    const s = persistedSignal("wd-burst", 0, { writeDelay: 100 });
+    s.set(1);
+    s.set(2);
+    s.update((n) => n + 1);
+    expect(s()).toBe(3);
+    expect(localStorage.getItem("wd-burst")).toBeNull();
+    vi.advanceTimersByTime(100);
+    expect(localStorage.getItem("wd-burst")).toBe("3");
+    expect(setItem.mock.calls.filter(([k]) => k === "wd-burst")).toHaveLength(1);
+    setItem.mockRestore();
+  });
+
+  it("starts a new window for writes after a flush", () => {
+    vi.useFakeTimers();
+    const s = persistedSignal("wd-next", 0, { writeDelay: 50 });
+    s.set(1);
+    vi.advanceTimersByTime(50);
+    s.set(2);
+    expect(localStorage.getItem("wd-next")).toBe("1");
+    vi.advanceTimersByTime(50);
+    expect(localStorage.getItem("wd-next")).toBe("2");
+  });
+
+  it("flushes pending data on pagehide", () => {
+    vi.useFakeTimers();
+    const s = persistedSignal("wd-hide", 0, { writeDelay: 1000 });
+    s.set(5);
+    window.dispatchEvent(new Event("pagehide"));
+    expect(localStorage.getItem("wd-hide")).toBe("5");
+    vi.advanceTimersByTime(1000);
+    expect(localStorage.getItem("wd-hide")).toBe("5");
+  });
+
+  it("close() flushes pending data and stops listening for pagehide", () => {
+    vi.useFakeTimers();
+    const s = persistedSignal("wd-close", 0, { writeDelay: 1000 });
+    s.set(7);
+    s.close();
+    expect(localStorage.getItem("wd-close")).toBe("7");
+    s.set(8);
+    window.dispatchEvent(new Event("pagehide"));
+    expect(localStorage.getItem("wd-close")).toBe("7");
+  });
+
+  it("a value arriving from another tab discards the pending local write", () => {
+    vi.useFakeTimers();
+    const s = persistedSignal("wd-remote", 0, { writeDelay: 100 });
+    s.set(1);
+    localStorage.setItem("wd-remote", "9");
+    window.dispatchEvent(
+      new StorageEvent("storage", { key: "wd-remote", newValue: "9", storageArea: localStorage }),
+    );
+    vi.advanceTimersByTime(100);
+    expect(s()).toBe(9);
+    expect(localStorage.getItem("wd-remote")).toBe("9");
+  });
+
+  it("removes null and undefined values when the write is flushed", () => {
+    vi.useFakeTimers();
+    const s = persistedSignal<number | null>("wd-null", 1, { writeDelay: 10 });
+    s.set(2);
+    vi.advanceTimersByTime(10);
+    s.set(null);
+    vi.advanceTimersByTime(10);
+    expect(localStorage.getItem("wd-null")).toBeNull();
+  });
 });

package/src/__tests__/reactive.test.ts

@@ -303,3 +303,41 @@ describe("history", () => {
     expect(snapshot1).not.toBe(snapshot2);
   });
 });
+
+describe("history.destroy", () => {
+  it("stops recording changes but keeps what was recorded", () => {
+    const s = signal(0);
+    const h = history(s);
+    s.set(1);
+    h.destroy();
+    s.set(2);
+    s.set(3);
+    expect(h.values()).toEqual([0, 1]);
+    expect(h.current()).toBe(1);
+  });
+
+  it("can still undo recorded entries after destroy", () => {
+    const s = signal(0);
+    const h = history(s);
+    s.set(1);
+    h.destroy();
+    h.undo();
+    expect(s()).toBe(0);
+  });
+});
+
+describe("history with a computed source", () => {
+  it("undo and redo move the tracked value without writing back to the read-only source", async () => {
+    const s = signal(0);
+    const source = computed(() => s());
+    const h = history(source);
+    s.set(1);
+    await Promise.resolve();
+    h.undo();
+    expect(h.current()).toBe(0);
+    expect(s()).toBe(1);
+    h.redo();
+    expect(h.current()).toBe(1);
+    expect(s()).toBe(1);
+  });
+});

package/src/__tests__/signal.test.ts

@@ -1,6 +1,8 @@
 import { describe, it, expect } from "vitest";
 
 import { batch } from "../signal/batch";
+import { SUBS_SET_THRESHOLD } from "../signal/effect";
+import { effect } from "../signal/effect";
 import { signal, addSub, removeSub, type SubList } from "../signal/signal";
 import type { Effect } from "../signal/effect";
 
@@ -211,3 +213,79 @@ describe("signal", () => {
     expect(calls.length).toBe(before);
   });
 });
+
+describe("large subscriber lists", () => {
+  function fns(count: number): Array<() => void> {
+    return Array.from({ length: count }, () => () => {});
+  }
+
+  it("keeps an array up to the threshold and promotes to a Set past it, preserving order", () => {
+    const holder: { subs: SubList } = { subs: null };
+    const list = fns(SUBS_SET_THRESHOLD);
+    for (const fn of list) addSub(holder, fn);
+    expect(Array.isArray(holder.subs)).toBe(true);
+
+    const extra = () => {};
+    addSub(holder, extra);
+    expect(holder.subs).toBeInstanceOf(Set);
+    expect([...(holder.subs as Set<() => void>)]).toEqual([...list, extra]);
+  });
+
+  it("addSub on a Set holder adds new subscribers and ignores duplicates", () => {
+    const list = fns(SUBS_SET_THRESHOLD + 1);
+    const holder: { subs: SubList } = { subs: new Set(list) };
+    addSub(holder, list[0]);
+    expect((holder.subs as Set<() => void>).size).toBe(list.length);
+    const extra = () => {};
+    addSub(holder, extra);
+    expect((holder.subs as Set<() => void>).size).toBe(list.length + 1);
+  });
+
+  it("removeSub on a Set holder removes one subscriber, ignores unknown ones, and normalizes to null when emptied", () => {
+    const [a, b, stranger] = fns(3);
+    const holder: { subs: SubList } = { subs: new Set([a, b]) };
+    removeSub(holder, stranger);
+    expect((holder.subs as Set<() => void>).size).toBe(2);
+    removeSub(holder, a);
+    expect([...(holder.subs as Set<() => void>)]).toEqual([b]);
+    removeSub(holder, b);
+    expect(holder.subs).toBeNull();
+  });
+
+  it("many effects on one signal all re-run once per change, in subscription order", () => {
+    const count = SUBS_SET_THRESHOLD * 3;
+    const s = signal(0);
+    const order: number[] = [];
+    const stops = Array.from({ length: count }, (_, i) =>
+      effect(() => {
+        void s();
+        order.push(i);
+      }),
+    );
+    order.length = 0;
+    s.set(1);
+    expect(order).toEqual(Array.from({ length: count }, (_, i) => i));
+    order.length = 0;
+    s.set(2);
+    expect(order).toEqual(Array.from({ length: count }, (_, i) => i));
+    stops.forEach((stop) => { stop(); });
+    order.length = 0;
+    s.set(3);
+    expect(order).toEqual([]);
+  });
+
+  it("an effect stopped while the signal holds a Set no longer runs, the others still do", () => {
+    const s = signal(0);
+    const runs = new Map<number, number>();
+    const stops = Array.from({ length: SUBS_SET_THRESHOLD + 4 }, (_, i) =>
+      effect(() => {
+        void s();
+        runs.set(i, (runs.get(i) ?? 0) + 1);
+      }),
+    );
+    stops[2]();
+    s.set(1);
+    expect(runs.get(2)).toBe(1);
+    expect(runs.get(3)).toBe(2);
+  });
+});

package/src/internal.ts

@@ -16,6 +16,7 @@ export {
   effect,
   untrack,
   type PersistedSignalOptions,
+  type PersistedSignal,
   type SyncedSignal,
 } from "./signal";
 export { RootComponent } from "./component";

package/src/reactive/history.ts

@@ -12,6 +12,8 @@ export interface HistoryElement<T> {
   undo(): void;
   redo(): void;
   clear(): void;
+  /** Stops tracking the source. Existing entries stay readable; no new ones are recorded. */
+  destroy(): void;
 }
 
 export function history<T>(
@@ -25,7 +27,7 @@ export function history<T>(
   let _ignoreNext = false;
   let _initialized = false;
 
-  effect(() => {
+  const stop = effect(() => {
     const value = source();
 
     if (!_initialized) {
@@ -83,5 +85,6 @@ export function history<T>(
       _past.set([]);
       _future.set([]);
     },
+    destroy: stop,
   };
 }

package/src/signal/batch.ts

@@ -1,6 +1,6 @@
 import type { Effect } from "./effect";
 
-const batchEffects: Effect[] = [];
+const batchEffects = new Set<Effect>();
 let batchDepth = 0;
 
 export function isBatching(): boolean {
@@ -8,7 +8,7 @@ export function isBatching(): boolean {
 }
 
 export function enqueueEffect(effect: Effect): void {
-  if (!batchEffects.includes(effect)) batchEffects.push(effect);
+  batchEffects.add(effect);
 }
 
 export function batch(fn: () => void) {
@@ -16,10 +16,24 @@ export function batch(fn: () => void) {
   try {
     fn();
   } finally {
-    if (--batchDepth === 0) {
-      const n = batchEffects.length;
-      for (let i = 0; i < n; i++) batchEffects[i]();
-      batchEffects.length = 0;
+    if (--batchDepth === 0) flush();
+  }
+}
+
+// The queue is detached before running so a throwing effect can't leave stale entries behind,
+// and every queued effect still runs — matching how notifySubs treats errors outside a batch.
+function flush(): void {
+  const queued = [...batchEffects];
+  batchEffects.clear();
+  let lastError: unknown;
+  let hasError = false;
+  for (const effect of queued) {
+    try {
+      effect();
+    } catch (e) {
+      lastError = e;
+      hasError = true;
     }
   }
+  if (hasError) throw lastError;
 }

package/src/signal/computed.ts

@@ -60,7 +60,17 @@ export function computed<T>(getter: () => T): Computed<T> {
     return cachedValue as T;
   }
 
-  const c = read as Computed<T>;
+  const c = read as Computed<T> & { dispose(): void };
+
+  // Drops this computed's subscriptions to its sources so an unreachable one (e.g. an evicted
+  // @Memo entry) isn't kept alive by the signals it read. Does nothing while anything still
+  // depends on it: detaching then would leave those dependents silently stale.
+  c.dispose = () => {
+    if (leafHolder.subs !== null || computedHolder.subs !== null) return;
+    if (recompute !== null) cleanupEffectDeps(recompute);
+    dirty = true;
+    cachedValue = undefined;
+  };
 
   c.subscribe = (fn: (value: T) => void) => {
     const wrapped: Effect = () => { fn(read()); };

package/src/signal/effect.ts

@@ -1,21 +1,30 @@
 export type Effect = () => void;
-export type SubList = Effect | Effect[] | null;
+export type SubList = Effect | Effect[] | Set<Effect> | null;
 export interface SubscriberHolder {
   subs: SubList;
 }
 
+// Past this many subscribers an array makes unsubscribing O(n) per effect re-run, which turns one
+// signal with thousands of bindings into a quadratic update; a Set keeps removal O(1).
+export const SUBS_SET_THRESHOLD = 16;
+
 type TrackedEffect = Effect & { __deps?: Set<SubscriberHolder> };
 
 export let activeEffect: Effect | null = null;
 const effectStack: Effect[] = [];
 
-function removeTrackedSub(holder: SubscriberHolder, eff: Effect): void {
+export function removeSub(holder: SubscriberHolder, eff: Effect): void {
   const subs = holder.subs;
   if (subs === null) return;
   if (typeof subs === "function") {
     if (subs === eff) holder.subs = null;
     return;
   }
+  if (subs instanceof Set) {
+    subs.delete(eff);
+    if (subs.size === 0) holder.subs = null;
+    return;
+  }
   const idx = subs.indexOf(eff);
   if (idx >= 0) subs.splice(idx, 1);
   if (subs.length === 0) holder.subs = null;
@@ -31,7 +40,7 @@ export function cleanupEffectDeps(eff: Effect): void {
   const tracked = eff as TrackedEffect;
   const deps = tracked.__deps;
   if (!deps) return;
-  for (const holder of deps) removeTrackedSub(holder, eff);
+  for (const holder of deps) removeSub(holder, eff);
   deps.clear();
 }
 

package/src/signal/index.ts

@@ -2,6 +2,6 @@ export { batch } from "./batch";
 export { peek } from "./peek";
 export { signal } from "./signal";
 export { computed, writableComputed } from "./computed";
-export { type PersistedSignalOptions, persistedSignal } from "./persisted";
+export { type PersistedSignalOptions, type PersistedSignal, persistedSignal } from "./persisted";
 export { type SyncedSignal, syncedSignal } from "./synced";
 export { effect, untrack } from "./effect";

package/src/signal/persisted.ts

@@ -6,6 +6,17 @@ export interface PersistedSignalOptions<T> {
   serialize?: (value: T) => string;
   deserialize?: (value: string) => T;
   syncTabs?: boolean;
+  /**
+   * Milliseconds to hold back writes to `localStorage`. Writes within the window are coalesced
+   * into one, using the latest value; pending data is flushed on `pagehide` and `close()`.
+   * `0` (default) writes on every `set`.
+   */
+  writeDelay?: number;
+}
+
+export interface PersistedSignal<T> extends Signal<T> {
+  /** Stops listening for `storage` events from other tabs. The signal keeps working locally. */
+  close(): void;
 }
 
 export function persistedSignal<T>(
@@ -17,6 +28,7 @@ export function persistedSignal<T>(
     serialize = JSON.stringify,
     deserialize = JSON.parse as (value: string) => T,
     syncTabs = true,
+    writeDelay = 0,
   } = options;
 
   function getStoredValue(): T {
@@ -41,6 +53,29 @@ export function persistedSignal<T>(
     }
   }
 
+  let pendingWrite: { value: T } | undefined;
+  let writeTimer: ReturnType<typeof setTimeout> | undefined;
+
+  function flushWrite(): void {
+    clearTimeout(writeTimer);
+    writeTimer = undefined;
+    if (!pendingWrite) return;
+    const { value } = pendingWrite;
+    pendingWrite = undefined;
+    setStoredValue(value);
+  }
+
+  // The timer starts at the first write of a burst (throttle, not debounce) so a value that keeps
+  // changing still reaches storage within `writeDelay`.
+  function scheduleWrite(value: T): void {
+    if (writeDelay <= 0) {
+      setStoredValue(value);
+      return;
+    }
+    pendingWrite = { value };
+    writeTimer ??= setTimeout(flushWrite, writeDelay);
+  }
+
   const inner = signal(getStoredValue());
 
   function read() {
@@ -48,19 +83,23 @@ export function persistedSignal<T>(
   }
 
   function set(value: T) {
-    setStoredValue(value);
+    scheduleWrite(value);
     inner.set(value);
   }
 
   function update(fh: (prev: T) => T) {
     const newValue = fh(inner());
-    setStoredValue(newValue);
+    scheduleWrite(newValue);
     inner.set(newValue);
   }
 
+  let removeStorageListener: (() => void) | undefined;
+
   if (syncTabs) {
-    window.addEventListener("storage", (event) => {
+    const onStorage = (event: StorageEvent): void => {
       if (event.key !== key || event.storageArea !== localStorage) return;
+      // Another tab's value wins; a still-pending local write would overwrite it later.
+      pendingWrite = undefined;
       try {
         const newValue = event.newValue
           ? deserialize(event.newValue)
@@ -73,14 +112,24 @@ export function persistedSignal<T>(
         );
         inner.set(initialValue);
       }
-    });
+    };
+    window.addEventListener("storage", onStorage);
+    removeStorageListener = () => { window.removeEventListener("storage", onStorage); };
   }
 
-  const source = read as Signal<T>;
+  if (writeDelay > 0) window.addEventListener("pagehide", flushWrite);
+
+  const source = read as PersistedSignal<T>;
   source.set = set;
   source.update = update;
   source.subscribe = inner.subscribe.bind(inner);
   source.__isSignal = true;
+  source.close = () => {
+    removeStorageListener?.();
+    removeStorageListener = undefined;
+    window.removeEventListener("pagehide", flushWrite);
+    flushWrite();
+  };
 
   return source;
 }

package/src/signal/signal.ts

@@ -4,6 +4,8 @@ import { isBatching, enqueueEffect } from "./batch";
 import {
   activeEffect,
   recordDependency,
+  removeSub,
+  SUBS_SET_THRESHOLD,
   type Effect,
   type SubList,
   type SubscriberHolder,
@@ -17,23 +19,16 @@ export function addSub(holder: SubscriberHolder, eff: Effect): void {
     holder.subs = eff;
   } else if (typeof subs === "function") {
     if (subs !== eff) holder.subs = [subs, eff];
-  } else {
-    if (!subs.includes(eff)) subs.push(eff);
+  } else if (subs instanceof Set) {
+    subs.add(eff);
+  } else if (!subs.includes(eff)) {
+    subs.push(eff);
+    if (subs.length > SUBS_SET_THRESHOLD) holder.subs = new Set(subs);
   }
   recordDependency(eff, holder);
 }
 
-export function removeSub(holder: SubscriberHolder, eff: Effect): void {
-  const subs = holder.subs;
-  if (subs === null) return;
-  if (typeof subs === "function") {
-    if (subs === eff) holder.subs = null;
-  } else {
-    const idx = subs.indexOf(eff);
-    if (idx >= 0) subs.splice(idx, 1);
-    if (subs.length === 0) holder.subs = null;
-  }
-}
+export { removeSub };
 
 export function notifySubs(subs: Exclude<SubList, null>, batching: boolean): void {
   if (typeof subs === "function") {