@praxisjs/core 2.0.0 → 2.2.0

package/src/__tests__/resource-server-pass.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+
+import { flushPendingResources, resource } from "../async/resource";
+import { _clearCache, getPendingResources } from "../async/resource-cache";
+import { setServerRenderPass, isServerRenderPass } from "../async/server-mode";
+
+describe("server render pass — flushPendingResources", () => {
+  beforeEach(() => { _clearCache(); });
+  afterEach(() => { setServerRenderPass(false); });
+
+  it("is a no-op when no server pass is active", async () => {
+    setServerRenderPass(false);
+    const r = resource(() => new Promise<string>(() => {}));
+    expect(getPendingResources().size).toBe(0);
+    await flushPendingResources();
+    // Untouched — resource() never settled and flush didn't wait for it.
+    expect(r.status()).toBe("pending");
+  });
+
+  it("resolves immediately when nothing is pending", async () => {
+    setServerRenderPass(true);
+    await expect(flushPendingResources()).resolves.toBeUndefined();
+  });
+
+  it("tracks isServerRenderPass() state via the setter", () => {
+    expect(isServerRenderPass()).toBe(false);
+    setServerRenderPass(true);
+    expect(isServerRenderPass()).toBe(true);
+  });
+
+  it("awaits an unkeyed resource() (e.g. @Collection) before returning", async () => {
+    setServerRenderPass(true);
+    const r = resource(() => new Promise<string>((res) => { setTimeout(() => { res("content"); }, 5); }));
+    await flushPendingResources();
+    expect(r.status()).toBe("success");
+    expect(r.data()).toBe("content");
+  });
+
+  it("awaits a keyed resource() too", async () => {
+    setServerRenderPass(true);
+    const r = resource(() => Promise.resolve("keyed-value"), { key: "ssg-key" });
+    await flushPendingResources();
+    expect(r.status()).toBe("success");
+    expect(r.data()).toBe("keyed-value");
+  });
+
+  it("awaits multiple concurrently pending resources", async () => {
+    setServerRenderPass(true);
+    const r1 = resource(() => new Promise<number>((res) => { setTimeout(() => { res(1); }, 5); }));
+    const r2 = resource(() => new Promise<number>((res) => { setTimeout(() => { res(2); }, 10); }));
+    await flushPendingResources();
+    expect(r1.data()).toBe(1);
+    expect(r2.data()).toBe(2);
+  });
+
+  it("fixed-point loop: awaits a resource created while an earlier one settles", async () => {
+    setServerRenderPass(true);
+    let second: ReturnType<typeof resource> | undefined;
+
+    // Simulates a component that, upon its first resource resolving, creates a
+    // second resource (e.g. a detail page fetching related content) — the new
+    // promise must still be picked up even though it didn't exist yet when
+    // flushPendingResources() started its first pass.
+    const first = resource(() => new Promise<string>((res) => {
+      setTimeout(() => {
+        res("first");
+        second = resource(() => new Promise<string>((res2) => { setTimeout(() => { res2("second"); }, 5); }));
+      }, 5);
+    }));
+
+    await flushPendingResources();
+    expect(first.status()).toBe("success");
+    expect(second?.status()).toBe("success");
+    expect(second?.data()).toBe("second");
+  });
+
+  it("does not leave stale entries after resources settle", async () => {
+    setServerRenderPass(true);
+    resource(() => Promise.resolve("done"));
+    await flushPendingResources();
+    expect(getPendingResources().size).toBe(0);
+  });
+
+  it("a rejected resource does not hang the flush", async () => {
+    setServerRenderPass(true);
+    const r = resource(() => Promise.reject(new Error("boom")));
+    await expect(flushPendingResources()).resolves.toBeUndefined();
+    expect(r.status()).toBe("error");
+  });
+});

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/async/resource-cache.ts

@@ -1,3 +1,5 @@
+import { isServerRenderPass } from "./server-mode";
+
 interface CacheEntry {
   data: unknown;
   timestamp: number;
@@ -6,6 +8,7 @@ interface CacheEntry {
 const _cache = new Map<string, CacheEntry>();
 const _inflight = new Map<string, Promise<unknown>>();
 const _registry = new Map<string, Set<() => void>>();
+const _pendingResources = new Set<Promise<unknown>>();
 
 export function getCacheEntry(key: string): CacheEntry | undefined {
   return _cache.get(key);
@@ -54,9 +57,26 @@ export function invalidateResource(key: string): void {
   _registry.get(key)?.forEach((fn) => { fn(); });
 }
 
+/**
+ * Registers `promise` as pending while a server render pass is active (no-op otherwise,
+ * so client-side resource() calls never pay this cost). Self-removes on settle.
+ */
+export function trackPendingResource(promise: Promise<unknown>): void {
+  if (!isServerRenderPass()) return;
+  _pendingResources.add(promise);
+  const cleanup = (): void => { _pendingResources.delete(promise); };
+  promise.then(cleanup, cleanup);
+}
+
+/** Snapshot of currently in-flight resource promises tracked during a server render pass. */
+export function getPendingResources(): ReadonlySet<Promise<unknown>> {
+  return _pendingResources;
+}
+
 /** Resets all cache state. Intended for use in tests only. */
 export function _clearCache(): void {
   _cache.clear();
   _inflight.clear();
   _registry.clear();
+  _pendingResources.clear();
 }

package/src/async/resource.ts

@@ -9,6 +9,8 @@ import {
   setInflight,
   registerResource,
   unregisterResource,
+  trackPendingResource,
+  getPendingResources,
 } from "./resource-cache";
 import { effect, untrack } from "../signal/effect";
 
@@ -58,6 +60,7 @@ export function resource<T>(
   let _runId = 0;
 
   function _execute(fn: Promise<T>): void {
+    trackPendingResource(fn);
     const currentRunId = ++_runId;
 
     function clearInflight(): void {
@@ -194,3 +197,17 @@ export function createResource<P, T>(
 ): Resource<T> {
   return resource(() => fetcher(param()), options);
 }
+
+/**
+ * Awaits every resource fetch tracked during a server render pass (see
+ * `setServerRenderPass`), including ones triggered by resources that themselves
+ * settle while waiting (fixed-point loop). No-op — resolves immediately — when
+ * nothing is pending or tracking isn't active.
+ */
+export async function flushPendingResources(): Promise<void> {
+  for (;;) {
+    const pending = Array.from(getPendingResources());
+    if (pending.length === 0) return;
+    await Promise.allSettled(pending);
+  }
+}

package/src/async/server-mode.ts

@@ -0,0 +1,16 @@
+let _serverRenderPass = false;
+
+/**
+ * Marks whether the current process is doing a build-time server/SSG render pass
+ * (as opposed to a normal browser render). Consumed by `resource-cache` (gates
+ * pending-promise tracking for `flushPendingResources`) and by `@praxisjs/runtime`'s
+ * `Portal`, which skips mounting entirely during a server pass so its content
+ * never gets baked into static HTML (it mounts normally once on the client).
+ */
+export function setServerRenderPass(active: boolean): void {
+  _serverRenderPass = active;
+}
+
+export function isServerRenderPass(): boolean {
+  return _serverRenderPass;
+}

package/src/internal.ts

@@ -16,6 +16,7 @@ export {
   effect,
   untrack,
   type PersistedSignalOptions,
+  type PersistedSignal,
   type SyncedSignal,
 } from "./signal";
 export { RootComponent } from "./component";
@@ -38,8 +39,10 @@ export {
 export {
   resource,
   createResource,
+  flushPendingResources,
   type ResourceStatus,
   type Resource,
   type ResourceOptions,
 } from "./async/resource";
-export { invalidateResource, _clearCache } from "./async/resource-cache";
+export { invalidateResource, trackPendingResource, _clearCache } from "./async/resource-cache";
+export { setServerRenderPass, isServerRenderPass } from "./async/server-mode";

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") {