@praxisjs/core 1.6.0 → 1.8.0

package/src/__tests__/resource.test.ts

@@ -1,6 +1,7 @@
-import { describe, it, expect, vi } from "vitest";
+import { describe, it, expect, vi, beforeEach } from "vitest";
 
 import { resource, createResource } from "../async/resource";
+import { invalidateResource, _clearCache } from "../async/resource-cache";
 import { signal } from "../signal/signal";
 
 describe("resource", () => {
@@ -151,6 +152,182 @@ describe("resource — execute() sync throw via refetch()", () => {
   });
 });
 
+describe("resource — destroy()", () => {
+  it("destroy() stops the reactive effect — signal changes no longer trigger refetch", async () => {
+    const id = signal(1);
+    const fetcher = vi.fn((n: number) => Promise.resolve(n * 10));
+    const r = resource(() => fetcher(id()), { immediate: true });
+    await vi.waitFor(() => r.status() === "success");
+    expect(fetcher).toHaveBeenCalledTimes(1);
+
+    r.destroy();
+    id.set(2);
+    await new Promise((res) => setTimeout(res, 10));
+    expect(fetcher).toHaveBeenCalledTimes(1); // no re-fetch after destroy
+  });
+
+  it("destroy() is idempotent", async () => {
+    const r = resource(() => Promise.resolve(1));
+    await vi.waitFor(() => r.status() === "success");
+    expect(() => { r.destroy(); r.destroy(); }).not.toThrow();
+  });
+});
+
+describe("resource — cache + SWR (key, staleTime)", () => {
+  beforeEach(() => { _clearCache(); });
+
+  it("key: populates data from cache on creation (SWR)", async () => {
+    // First resource fills the cache
+    const r1 = resource(() => Promise.resolve("cached-value"), { key: "swr-test" });
+    await vi.waitFor(() => r1.status() === "success");
+
+    // Second resource with same key starts with cached data immediately
+    const r2 = resource(() => Promise.resolve("new-value"), { key: "swr-test" });
+    expect(r2.data()).toBe("cached-value"); // stale data shown immediately
+    expect(r2.status()).toBe("pending"); // fetching fresh data in background
+    await vi.waitFor(() => r2.data() === "new-value");
+    r1.destroy();
+    r2.destroy();
+  });
+
+  it("staleTime: skips fetch when cache is fresh", async () => {
+    const fetcher = vi.fn(() => Promise.resolve("fresh"));
+    const r1 = resource(fetcher, { key: "fresh-test", staleTime: 60_000 });
+    await vi.waitFor(() => r1.status() === "success");
+    expect(fetcher).toHaveBeenCalledTimes(1);
+
+    // Second resource within staleTime — no fetch
+    const r2 = resource(fetcher, { key: "fresh-test", staleTime: 60_000 });
+    expect(r2.data()).toBe("fresh");
+    expect(r2.status()).toBe("success");
+    await new Promise((res) => setTimeout(res, 10));
+    expect(fetcher).toHaveBeenCalledTimes(1); // no second fetch
+    r1.destroy();
+    r2.destroy();
+  });
+
+  it("staleTime: 0 (default) always refetches even with cached data", async () => {
+    const fetcher = vi.fn(() => Promise.resolve("v1"));
+    const r1 = resource(fetcher, { key: "always-stale" });
+    await vi.waitFor(() => r1.status() === "success");
+
+    const r2 = resource(fetcher, { key: "always-stale", staleTime: 0 });
+    expect(r2.data()).toBe("v1"); // shows stale immediately
+    await vi.waitFor(() => r2.status() === "success");
+    expect(fetcher).toHaveBeenCalledTimes(2); // did refetch
+    r1.destroy();
+    r2.destroy();
+  });
+});
+
+describe("resource — deduplication", () => {
+  beforeEach(() => { _clearCache(); });
+
+  it("two resources with the same key share a single in-flight request", async () => {
+    let resolveShared!: (v: string) => void;
+    const fetcher = vi.fn(
+      () => new Promise<string>((res) => { resolveShared = res; }),
+    );
+
+    const r1 = resource(fetcher, { key: "dedup-test" });
+    const r2 = resource(fetcher, { key: "dedup-test" });
+
+    expect(fetcher).toHaveBeenCalledTimes(1); // only one fetch started
+
+    resolveShared("shared-result");
+    await vi.waitFor(() => r1.status() === "success");
+    await vi.waitFor(() => r2.status() === "success");
+
+    expect(r1.data()).toBe("shared-result");
+    expect(r2.data()).toBe("shared-result");
+    r1.destroy();
+    r2.destroy();
+  });
+});
+
+describe("resource — key + non-Error sync throw in effect", () => {
+  beforeEach(() => { _clearCache(); });
+
+  it("key: wraps non-Error sync throw from fetcher inside effect in Error", async () => {
+    const r = resource(
+      () => {
+        // eslint-disable-next-line @typescript-eslint/only-throw-error
+        throw "raw string error in keyed effect";
+      },
+      { key: "non-error-keyed" },
+    );
+    await vi.waitFor(() => r.status() === "error");
+    expect(r.error()).toBeInstanceOf(Error);
+    expect((r.error() as Error).message).toBe("raw string error in keyed effect");
+    r.destroy();
+  });
+});
+
+describe("resource — key + rejection / sync-throw", () => {
+  beforeEach(() => { _clearCache(); });
+
+  it("key: clears in-flight entry on rejection (catch path)", async () => {
+    const r = resource(
+      () => Promise.reject(new Error("keyed failure")),
+      { key: "reject-test" },
+    );
+    await new Promise((res) => setTimeout(res, 0));
+    expect(r.status()).toBe("error");
+    expect((r.error() as Error).message).toBe("keyed failure");
+    r.destroy();
+  });
+
+  it("key: sync throw inside effect is captured as error", async () => {
+    const r = resource(
+      () => { throw new Error("sync in keyed effect"); },
+      { key: "sync-throw-keyed" },
+    );
+    await vi.waitFor(() => r.status() === "error");
+    expect((r.error() as Error).message).toBe("sync in keyed effect");
+    r.destroy();
+  });
+});
+
+describe("resource — invalidateResource()", () => {
+  beforeEach(() => { _clearCache(); });
+
+  it("clears cache and triggers refetch on all registered resources", async () => {
+    let call = 0;
+    const fetcher = vi.fn(() => Promise.resolve(++call));
+
+    const r1 = resource(fetcher, { key: "inv-test" });
+    const r2 = resource(fetcher, { key: "inv-test" });
+    await vi.waitFor(() => r1.status() === "success");
+    await vi.waitFor(() => r2.status() === "success");
+
+    const callsBefore = fetcher.mock.calls.length;
+    invalidateResource("inv-test");
+
+    await vi.waitFor(() => r1.status() === "success" && r1.data() !== callsBefore);
+    expect(fetcher.mock.calls.length).toBeGreaterThan(callsBefore);
+    r1.destroy();
+    r2.destroy();
+  });
+
+  it("no-op when key has no registered resources", () => {
+    expect(() => { invalidateResource("nonexistent-key"); }).not.toThrow();
+  });
+
+  it("unregisters resource on destroy — invalidate no longer triggers it", async () => {
+    let call = 0;
+    const fetcher = vi.fn(() => Promise.resolve(++call));
+    const r = resource(fetcher, { key: "unreg-test" });
+    await vi.waitFor(() => r.status() === "success");
+
+    r.destroy();
+    const callsBefore = fetcher.mock.calls.length;
+
+    invalidateResource("unreg-test");
+    await new Promise((res) => setTimeout(res, 10));
+    expect(fetcher.mock.calls.length).toBe(callsBefore); // no refetch after destroy
+  });
+});
+
 describe("resource — additional cases", () => {
   it("two concurrent refetch() calls — last result wins, stale result is discarded", async () => {
     let resolveFirst!: (v: string) => void;

package/src/__tests__/signal.test.ts

@@ -1,6 +1,8 @@
 import { describe, it, expect } from "vitest";
 
-import { signal } from "../signal/signal";
+import { batch } from "../signal/batch";
+import { signal, addSub, removeSub, type SubList } from "../signal/signal";
+import type { Effect } from "../signal/effect";
 
 describe("signal", () => {
   it("returns initial value", () => {
@@ -125,6 +127,58 @@ describe("signal", () => {
     expect(() => s.set(1)).not.toThrow();
   });
 
+  it("unsubscribing one of multiple subscribers removes only that subscriber", () => {
+    const s = signal(0);
+    const a: number[] = [];
+    const b: number[] = [];
+    const unsubA = s.subscribe((v) => a.push(v));
+    s.subscribe((v) => b.push(v));
+    // subs is now an array — hits removeSub else branch
+    unsubA();
+    s.set(1);
+    expect(a).toEqual([0]); // A stopped after initial fire
+    expect(b).toEqual([0, 1]); // B still receives
+  });
+
+  it("unsubscribing a non-existent subscriber from array subs is a no-op", () => {
+    const s = signal(0);
+    const a: number[] = [];
+    const b: number[] = [];
+    s.subscribe((v) => a.push(v));
+    const unsubB = s.subscribe((v) => b.push(v));
+    unsubB(); // remove B, subs becomes array without B
+    unsubB(); // call again — idx will be -1, splice not called
+    expect(() => s.set(1)).not.toThrow();
+    expect(a).toContain(1);
+  });
+
+  it("batch defers notifications for multiple array subscribers", () => {
+    const s = signal(0);
+    const a: number[] = [];
+    const b: number[] = [];
+    s.subscribe((v) => a.push(v));
+    s.subscribe((v) => b.push(v));
+    // subs is an array; inside batch, notifySubs hits the batching=true array path
+    batch(() => {
+      s.set(1);
+      expect(a).toEqual([0]); // not yet fired
+      expect(b).toEqual([0]);
+    });
+    expect(a).toContain(1);
+    expect(b).toContain(1);
+  });
+
+  it("removeSub with non-matching single-function subscriber is a no-op", () => {
+    // When subs is a single function and we try to remove a different function,
+    // the holder must remain unchanged (subs !== eff → false branch).
+    const holder: { subs: SubList } = { subs: null };
+    const fn1: Effect = () => {};
+    const fn2: Effect = () => {};
+    addSub(holder, fn1); // subs = fn1 (single function)
+    removeSub(holder, fn2); // fn2 !== fn1 → no-op
+    expect(holder.subs).toBe(fn1);
+  });
+
   it("set() with mutated object reference (same ref) does NOT notify — Object.is semantics", () => {
     const obj = { count: 0 };
     const s = signal(obj);

package/src/async/resource-cache.ts

@@ -0,0 +1,62 @@
+interface CacheEntry {
+  data: unknown;
+  timestamp: number;
+}
+
+const _cache = new Map<string, CacheEntry>();
+const _inflight = new Map<string, Promise<unknown>>();
+const _registry = new Map<string, Set<() => void>>();
+
+export function getCacheEntry(key: string): CacheEntry | undefined {
+  return _cache.get(key);
+}
+
+export function setCacheEntry(key: string, data: unknown): void {
+  _cache.set(key, { data, timestamp: Date.now() });
+}
+
+export function deleteCacheEntry(key: string): void {
+  _cache.delete(key);
+}
+
+export function getInflight(key: string): Promise<unknown> | undefined {
+  return _inflight.get(key);
+}
+
+export function setInflight(key: string, promise: Promise<unknown>): void {
+  _inflight.set(key, promise);
+}
+
+export function deleteInflight(key: string): void {
+  _inflight.delete(key);
+}
+
+export function registerResource(key: string, refetch: () => void): void {
+  let set = _registry.get(key);
+  if (!set) {
+    set = new Set();
+    _registry.set(key, set);
+  }
+  set.add(refetch);
+}
+
+export function unregisterResource(key: string, refetch: () => void): void {
+  _registry.get(key)?.delete(refetch);
+}
+
+/**
+ * Clears the cache entry and in-flight request for `key`, then triggers
+ * every active resource registered under that key to refetch.
+ */
+export function invalidateResource(key: string): void {
+  deleteCacheEntry(key);
+  deleteInflight(key);
+  _registry.get(key)?.forEach((fn) => { fn(); });
+}
+
+/** Resets all cache state. Intended for use in tests only. */
+export function _clearCache(): void {
+  _cache.clear();
+  _inflight.clear();
+  _registry.clear();
+}

package/src/async/resource.ts

@@ -1,7 +1,16 @@
 import type { Computed, Signal } from "@praxisjs/shared";
 
 import { computed, signal } from "../signal";
-import { effect } from "../signal/effect";
+import {
+  getCacheEntry,
+  setCacheEntry,
+  deleteInflight,
+  getInflight,
+  setInflight,
+  registerResource,
+  unregisterResource,
+} from "./resource-cache";
+import { effect, untrack } from "../signal/effect";
 
 export type ResourceStatus = "idle" | "pending" | "success" | "error";
 
@@ -13,12 +22,16 @@ export interface Resource<T> {
   refetch(): void;
   cancel(): void;
   mutate(data: T): void;
+  destroy(): void;
 }
 
 export interface ResourceOptions<T> {
   initialData?: T;
   immediate?: boolean;
   keepPreviousData?: boolean;
+  key?: string;
+  staleTime?: number;
+  refetchOnFocus?: boolean;
 }
 
 export function resource<T>(
@@ -29,18 +42,27 @@ export function resource<T>(
     initialData = null,
     immediate = true,
     keepPreviousData = false,
+    key,
+    staleTime = 0,
+    refetchOnFocus = false,
   } = options;
 
-  const _data = signal(initialData);
+  const cached = key ? getCacheEntry(key) : undefined;
+  const isCacheFresh =
+    cached !== undefined && Date.now() - cached.timestamp < staleTime;
+
+  const _data = signal(cached ? (cached.data as T) : initialData);
   const _error = signal<Error | null>(null);
-  const _status = signal<ResourceStatus>("idle");
+  const _status = signal<ResourceStatus>(cached ? "success" : "idle");
 
   let _runId = 0;
 
-  function _execute(fn: Promise<T>) {
+  function _execute(fn: Promise<T>): void {
     const currentRunId = ++_runId;
 
-    if (!keepPreviousData) {
+    // untrack: _data.set(result) in the resolve handler must not re-trigger the enclosing effect.
+    const hasCachedData = key !== undefined && untrack(() => _data()) !== null;
+    if (!keepPreviousData && !hasCachedData) {
       _data.set(null);
     }
     _error.set(null);
@@ -51,16 +73,36 @@ export function resource<T>(
       _data.set(result);
       _error.set(null);
       _status.set("success");
+      if (key) {
+        setCacheEntry(key, result);
+        deleteInflight(key);
+      }
     }).catch((err: unknown) => {
       if (currentRunId !== _runId) return;
       _error.set(err instanceof Error ? err : new Error(String(err)));
       _status.set("error");
+      if (key) deleteInflight(key);
     });
   }
 
-  function execute() {
-    try {
+  function _startFetch(): void {
+    if (key) {
+      const existing = getInflight(key);
+      if (existing) {
+        _execute(existing as Promise<T>);
+        return;
+      }
+      const promise = fetcher();
+      setInflight(key, promise as Promise<unknown>);
+      _execute(promise);
+    } else {
       _execute(fetcher());
+    }
+  }
+
+  function execute(): void {
+    try {
+      _startFetch();
     } catch (err: unknown) {
       _runId++;
       _error.set(err instanceof Error ? err : new Error(String(err)));
@@ -68,17 +110,56 @@ export function resource<T>(
     }
   }
 
-  if (immediate) {
-    effect(() => {
+  if (key) {
+    registerResource(key, execute);
+  }
+
+  let stopEffect: (() => void) | undefined;
+
+  if (immediate && !isCacheFresh) {
+    stopEffect = effect(() => {
       try {
-        _execute(fetcher());
+        if (key) {
+          const existing = getInflight(key);
+          if (existing) {
+            _execute(existing as Promise<T>);
+          } else {
+            const promise = fetcher();
+            setInflight(key, promise as Promise<unknown>);
+            _execute(promise);
+          }
+        } else {
+          _execute(fetcher());
+        }
       } catch (err: unknown) {
+        _runId++;
         _error.set(err instanceof Error ? err : new Error(String(err)));
         _status.set("error");
       }
     });
   }
 
+  let _removeFocusListener: (() => void) | undefined;
+  if (refetchOnFocus && typeof document !== "undefined") {
+    const onVisibility = (): void => {
+      if (document.visibilityState === "visible") {
+        execute();
+      }
+    };
+    document.addEventListener("visibilitychange", onVisibility);
+    _removeFocusListener = (): void => {
+      document.removeEventListener("visibilitychange", onVisibility);
+    };
+  }
+
+  function destroy(): void {
+    stopEffect?.();
+    stopEffect = undefined;
+    _removeFocusListener?.();
+    _removeFocusListener = undefined;
+    if (key) unregisterResource(key, execute);
+  }
+
   return {
     data: computed(() => _data()),
     pending: computed(() => _status() === "pending"),
@@ -97,6 +178,7 @@ export function resource<T>(
       _error.set(null);
       _status.set("success");
     },
+    destroy,
   };
 }
 

package/src/component/base.ts

@@ -19,7 +19,8 @@ export abstract class RootComponent<T extends object = Record<string, never>> {
   onBeforeMount?(): void;
   onMount?(): void;
   onUnmount?(): void;
-  onError?(error: Error): void;
+  // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
+  onError?(error: Error): Node | Node[] | null | undefined | void;
 
   abstract render(): Node | Node[] | null;
 }

package/src/internal.ts

@@ -11,6 +11,7 @@ export {
   syncedSignal,
   peek,
   computed,
+  writableComputed,
   batch,
   effect,
   untrack,
@@ -25,3 +26,4 @@ export {
   type Resource,
   type ResourceOptions,
 } from "./async/resource";
+export { invalidateResource, _clearCache } from "./async/resource-cache";

package/src/reactive/reactive.ts

@@ -45,7 +45,6 @@ export function debounced<T>(source: Signal<T> | Computed<T>, ms: number) {
 
   const stop = effect(() => {
     const value = source();
-    if (timeout) clearTimeout(timeout);
     timeout = setTimeout(() => {
       current.set(value);
       timeout = undefined;

package/src/signal/computed.ts

@@ -1,4 +1,4 @@
-import type { Computed } from "@praxisjs/shared";
+import type { Computed, WritableComputed } from "@praxisjs/shared";
 
 import { activeEffect, runEffect, type Effect } from "./effect";
 import { addSub, removeSub, notifySubs, type SubList } from "./signal";
@@ -70,3 +70,11 @@ export function computed<T>(getter: () => T): Computed<T> {
   c.__isComputed = true;
   return c;
 }
+
+export function writableComputed<T>(getter: () => T, setter: (value: T) => void): WritableComputed<T> {
+  const c = computed(getter) as WritableComputed<T>;
+  c.set = setter;
+  c.update = (updater) => { setter(updater(c())); };
+  c.__isWritableComputed = true;
+  return c;
+}

package/src/signal/index.ts

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