@multiplatform.one/frappe 6.1.0 → 6.3.0

package/src/frappeReact.spec.ts

@@ -1,5 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { act, renderHook, waitFor } from "@testing-library/react";
+import { useState } from "react";
 
 const {
   mockSubscribe,
@@ -28,7 +29,14 @@ vi.mock("./sync", () => ({
   },
 }));
 
-vi.mock("./realtime", () => ({ RealtimeModule: class {} }));
+const { mockRealtimeCtor } = vi.hoisted(() => ({ mockRealtimeCtor: vi.fn() }));
+vi.mock("./realtime", () => ({
+  RealtimeModule: class {
+    constructor(config: unknown) {
+      mockRealtimeCtor(config);
+    }
+  },
+}));
 vi.mock("./core/http", () => ({ HttpClient: class {} }));
 vi.mock("./db", () => ({ DbModule: class {} }));
 const { mockCreateFrappeCollection, mockIsBrowser } = vi.hoisted(() => ({
@@ -41,6 +49,7 @@ vi.mock("./util", () => ({ isBrowser: mockIsBrowser }));
 vi.mock("./fixtureDb", () => ({ FixtureDbModule: class {} }));
 
 import { isBrowser } from "./util";
+import { Order } from "./sync/types";
 import type { UseFrappeCollectionConfig, UseFrappeInfiniteListConfig } from "./frappeReact";
 import {
   __getActiveSyncModule,
@@ -325,6 +334,561 @@ describe("useFrappeCollection", () => {
     const active = __getActiveSyncModule();
     expect(active).toBeDefined();
   });
+
+  it("passes socketOptions through to the RealtimeModule", () => {
+    const socketOptions = { transports: ["polling", "websocket"] };
+    const config: UseFrappeCollectionConfig = {
+      baseURL: `https://socketopts-${testNum}.example.com`,
+      socketOptions,
+    };
+    renderHook(() => useFrappeCollection(config, "Task"));
+    expect(mockRealtimeCtor).toHaveBeenCalledWith(expect.objectContaining({ socketOptions }));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// useFrappeCollection — shared collection cache (dedupe by configKey)
+// ---------------------------------------------------------------------------
+
+describe("useFrappeCollection shared cache", () => {
+  let testNum = 100;
+  /** > SHARED_COLLECTION_GC_MS in frappeReact.ts */
+  const GC_WAIT_MS = 1_500;
+
+  const makeCollection = () =>
+    ({ id: `collection-${Math.random().toString(36).slice(2)}`, cleanup: vi.fn() }) as any;
+
+  beforeEach(() => {
+    testNum++;
+    vi.clearAllMocks();
+    vi.useFakeTimers();
+    mockIsBrowser.mockReturnValue(true);
+    mockCreateFrappeCollection.mockImplementation(() => makeCollection());
+  });
+
+  afterEach(() => {
+    vi.runOnlyPendingTimers();
+    vi.useRealTimers();
+    mockIsBrowser.mockReturnValue(true);
+  });
+
+  const configFor = (label: string): UseFrappeCollectionConfig => ({
+    baseURL: `https://shared-${label}-${testNum}.example.com`,
+  });
+
+  it("shares one collection across consumers with the same config/doctype/options", () => {
+    const config = configFor("same");
+    const options = { filters: { name: "TODO-001" } };
+    const a = renderHook(() => useFrappeCollection(config, "Todo", options));
+    const b = renderHook(() => useFrappeCollection(config, "Todo", options));
+
+    expect(a.result.current).toBeDefined();
+    expect(b.result.current).toBe(a.result.current);
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not share across different filters", () => {
+    const config = configFor("difffilters");
+    const a = renderHook(() => useFrappeCollection(config, "Todo", { filters: { name: "A" } }));
+    const b = renderHook(() => useFrappeCollection(config, "Todo", { filters: { name: "B" } }));
+
+    expect(a.result.current).not.toBe(b.result.current);
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not share across different orderBy/limit (part of the identity key)", () => {
+    const config = configFor("difforder");
+    const a = renderHook(() =>
+      useFrappeCollection(config, "Todo", { orderBy: { field: "modified", order: Order.Desc } }),
+    );
+    const b = renderHook(() => useFrappeCollection(config, "Todo", { limit: 5 }));
+
+    expect(a.result.current).not.toBe(b.result.current);
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(2);
+  });
+
+  it("keeps the shared collection alive while any consumer remains mounted", () => {
+    const config = configFor("partial");
+    const options = { filters: { name: "TODO-001" } };
+    const a = renderHook(() => useFrappeCollection(config, "Todo", options));
+    const b = renderHook(() => useFrappeCollection(config, "Todo", options));
+    const shared = a.result.current as any;
+
+    a.unmount();
+    act(() => {
+      vi.advanceTimersByTime(GC_WAIT_MS);
+    });
+
+    expect(shared.cleanup).not.toHaveBeenCalled();
+    // Remaining consumer still gets the same live instance
+    b.rerender();
+    expect(b.result.current).toBe(shared);
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(1);
+  });
+
+  it("cleans up the shared collection after the last consumer unmounts", () => {
+    const config = configFor("lastout");
+    const options = { filters: { name: "TODO-001" } };
+    const a = renderHook(() => useFrappeCollection(config, "Todo", options));
+    const b = renderHook(() => useFrappeCollection(config, "Todo", options));
+    const shared = a.result.current as any;
+
+    a.unmount();
+    b.unmount();
+    expect(shared.cleanup).not.toHaveBeenCalled(); // grace period
+    act(() => {
+      vi.advanceTimersByTime(GC_WAIT_MS);
+    });
+    expect(shared.cleanup).toHaveBeenCalledTimes(1);
+
+    // A later consumer gets a fresh collection (no stale entry)
+    const c = renderHook(() => useFrappeCollection(config, "Todo", options));
+    expect(c.result.current).not.toBe(shared);
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(2);
+  });
+
+  it("reuses the same collection when remounting within the grace period", () => {
+    const config = configFor("remount");
+    const options = { filters: { name: "TODO-001" } };
+    const a = renderHook(() => useFrappeCollection(config, "Todo", options));
+    const shared = a.result.current as any;
+
+    a.unmount();
+    // Remount before the grace period elapses (e.g. StrictMode / quick nav)
+    const b = renderHook(() => useFrappeCollection(config, "Todo", options));
+    act(() => {
+      vi.advanceTimersByTime(GC_WAIT_MS);
+    });
+
+    expect(b.result.current).toBe(shared);
+    expect(shared.cleanup).not.toHaveBeenCalled();
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(1);
+  });
+
+  it("swaps cleanly when options change: new shared entry, old entry released", () => {
+    const config = configFor("swap");
+    const { result, rerender } = renderHook(
+      ({ name }: { name: string }) => useFrappeCollection(config, "Todo", { filters: { name } }),
+      { initialProps: { name: "TODO-001" } },
+    );
+    const first = result.current as any;
+
+    rerender({ name: "TODO-002" });
+    const second = result.current as any;
+    expect(second).not.toBe(first);
+
+    act(() => {
+      vi.advanceTimersByTime(GC_WAIT_MS);
+    });
+    expect(first.cleanup).toHaveBeenCalledTimes(1);
+    expect(second.cleanup).not.toHaveBeenCalled();
+  });
+
+  it("fans out onSyncError to every mounted consumer of the shared collection", () => {
+    const config = configFor("errfan");
+    const options = { filters: { name: "TODO-001" } };
+    const errorA = vi.fn();
+    const errorB = vi.fn();
+    renderHook(() => useFrappeCollection(config, "Todo", { ...options, onSyncError: errorA }));
+    renderHook(() => useFrappeCollection(config, "Todo", { ...options, onSyncError: errorB }));
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(1);
+
+    const passedOptions = mockCreateFrappeCollection.mock.calls[0][1];
+    const syncError = new Error("initial sync failed");
+    act(() => {
+      passedOptions.onSyncError(syncError);
+    });
+
+    expect(errorA).toHaveBeenCalledWith(syncError);
+    expect(errorB).toHaveBeenCalledWith(syncError);
+  });
+
+  it("HOLDS an errored entry while consumers are mounted: re-renders and late mounts share it (no refetch loop)", () => {
+    const config = configFor("errhold");
+    const options = { filters: { name: "TODO-001" } };
+    const a = renderHook(() => useFrappeCollection(config, "Todo", options));
+    const errored = a.result.current;
+
+    const passedOptions = mockCreateFrappeCollection.mock.calls[0][1];
+    act(() => {
+      passedOptions.onSyncError(new Error("initial sync failed"));
+    });
+
+    // The mounted consumer's next render (e.g. after storing the error in
+    // state) re-acquires the SAME errored entry — no fresh failing sync.
+    a.rerender();
+    expect(a.result.current).toBe(errored);
+    // A late consumer mounting while the error is held shares the errored
+    // entry and gets the error replayed on retain.
+    const lateError = vi.fn();
+    const late = renderHook(() =>
+      useFrappeCollection(config, "Todo", { ...options, onSyncError: lateError }),
+    );
+    expect(late.result.current).toBe(errored);
+    expect(lateError).toHaveBeenCalledTimes(1);
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(1);
+  });
+
+  it("REGRESSION: an error-state consumer does not loop failing fetches (bounded attempt count)", () => {
+    // Reproduces the retry storm: a consumer that stores the sync error in
+    // state re-renders on every failure. With eviction-on-error, each
+    // re-render acquired a fresh entry with a fresh failing sync — an
+    // unbounded fetch loop (froze storybook renderers, OOM'd vitest
+    // workers). The errored entry must be a stable fixpoint instead.
+    const config = configFor("errloop");
+    const options = { filters: { name: "TODO-001" } };
+
+    let failuresSeen = 0;
+    const consumer = renderHook(() => {
+      // Mimic the consumer pattern: setState-on-error → re-render.
+      const [, setError] = useState<unknown>(null);
+      return useFrappeCollection(config, "Todo", {
+        ...options,
+        onSyncError: (error) => {
+          failuresSeen++;
+          setError(error);
+        },
+      });
+    });
+
+    // Fail every FRESH sync attempt the cache starts, like a down bench:
+    // each newly created collection errors exactly once. Under the old
+    // eviction-on-error semantics every round created a new collection, so
+    // this drove 25 attempts; the fix must hold it at one.
+    let failedAttempts = 0;
+    for (let round = 0; round < 25; round++) {
+      const calls = mockCreateFrappeCollection.mock.calls;
+      if (calls.length > failedAttempts) {
+        failedAttempts = calls.length;
+        const passedOptions = calls[calls.length - 1][1];
+        act(() => {
+          passedOptions.onSyncError(new Error(`sync failure ${round}`));
+        });
+      }
+      consumer.rerender();
+    }
+
+    // ONE collection, ONE real failure surfaced — not 25 fresh attempts.
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(1);
+    expect(failuresSeen).toBe(1);
+    expect(consumer.result.current).toBeDefined();
+  });
+
+  it("REGRESSION: unmounting during an error state neither throws nor starts new syncs", () => {
+    const config = configFor("errunmount");
+    const options = { filters: { name: "TODO-001" } };
+    const a = renderHook(() => useFrappeCollection(config, "Todo", options));
+
+    const passedOptions = mockCreateFrappeCollection.mock.calls[0][1];
+    act(() => {
+      passedOptions.onSyncError(new Error("initial sync failed"));
+    });
+
+    expect(() => {
+      a.unmount();
+      act(() => {
+        vi.advanceTimersByTime(GC_WAIT_MS);
+      });
+    }).not.toThrow();
+    // Unmount must not have spawned another attempt.
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(1);
+  });
+
+  it("evicts the errored entry when the LAST consumer releases: the next mount is a fresh attempt (Retry contract)", () => {
+    const config = configFor("errretry");
+    const options = { filters: { name: "TODO-001" } };
+    const a = renderHook(() => useFrappeCollection(config, "Todo", options));
+    const errored = a.result.current;
+
+    const passedOptions = mockCreateFrappeCollection.mock.calls[0][1];
+    act(() => {
+      passedOptions.onSyncError(new Error("initial sync failed"));
+    });
+
+    // Retry-by-remount: the failing consumer unmounts…
+    a.unmount();
+    // …and the remount acquires a FRESH entry with a fresh sync attempt —
+    // immediately, not after a GC grace (a grace would replay the stale
+    // error back into the retry).
+    const retry = renderHook(() => useFrappeCollection(config, "Todo", options));
+    expect(retry.result.current).not.toBe(errored);
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(2);
+  });
+
+  it("an errored entry shared by two consumers survives one unmount and retries after both release", () => {
+    const config = configFor("errshared");
+    const options = { filters: { name: "TODO-001" } };
+    const a = renderHook(() => useFrappeCollection(config, "Todo", options));
+    const b = renderHook(() => useFrappeCollection(config, "Todo", options));
+    const errored = a.result.current;
+
+    const passedOptions = mockCreateFrappeCollection.mock.calls[0][1];
+    act(() => {
+      passedOptions.onSyncError(new Error("initial sync failed"));
+    });
+
+    // One consumer leaves: the other still holds the errored entry stably.
+    a.unmount();
+    b.rerender();
+    expect(b.result.current).toBe(errored);
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(1);
+
+    // Both released → next mount starts the one fresh attempt.
+    b.unmount();
+    const retry = renderHook(() => useFrappeCollection(config, "Todo", options));
+    expect(retry.result.current).not.toBe(errored);
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(2);
+  });
+
+  it("a released consumer's onSyncError no longer fires", () => {
+    const config = configFor("errrelease");
+    const options = { filters: { name: "TODO-001" } };
+    const errorA = vi.fn();
+    const errorB = vi.fn();
+    const a = renderHook(() =>
+      useFrappeCollection(config, "Todo", { ...options, onSyncError: errorA }),
+    );
+    renderHook(() => useFrappeCollection(config, "Todo", { ...options, onSyncError: errorB }));
+
+    a.unmount();
+    const passedOptions = mockCreateFrappeCollection.mock.calls[0][1];
+    act(() => {
+      passedOptions.onSyncError(new Error("late failure"));
+    });
+
+    expect(errorA).not.toHaveBeenCalled();
+    expect(errorB).toHaveBeenCalledTimes(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// useFrappeCollection — GC vs live-query subscribers
+// ---------------------------------------------------------------------------
+//
+// Live queries subscribe to a collection outside the hook refcount
+// (synchronously during render; detaching asynchronously through TanStack
+// DB's own GC). Cleaning up a collection while a query is attached
+// permanently errors the query ("Source collection … was manually cleaned up
+// while live query … depends on it"), so the registry GC must defer while
+// `collection.subscriberCount > 0` — bounded by a force window that reclaims
+// collections pinned by leaked queries from never-committed renders.
+
+describe("useFrappeCollection shared cache — GC vs live queries", () => {
+  let testNum = 200;
+  /** > SHARED_COLLECTION_GC_MS in frappeReact.ts */
+  const GC_WAIT_MS = 1_500;
+  /** > SHARED_COLLECTION_GC_FORCE_MS in frappeReact.ts (plus defer ticks) */
+  const FORCE_WAIT_MS = 40_000;
+
+  /** Mock collection mirroring the TanStack DB surface the registry relies
+   * on: `subscriberCount`, `status`, `on("status:change")`, and a cleanup()
+   * that transitions status and emits the event (as the real one does). */
+  const makeLiveCollection = () => {
+    const listeners = new Set<(event: { status?: string }) => void>();
+    const collection: any = {
+      id: `collection-${Math.random().toString(36).slice(2)}`,
+      status: "ready",
+      subscriberCount: 0,
+      on: vi.fn((event: string, cb: (event: { status?: string }) => void) => {
+        if (event === "status:change") listeners.add(cb);
+        return () => listeners.delete(cb);
+      }),
+      cleanup: vi.fn(() => {
+        collection.status = "cleaned-up";
+        for (const cb of [...listeners]) cb({ status: "cleaned-up" });
+      }),
+    };
+    return collection;
+  };
+
+  beforeEach(() => {
+    testNum++;
+    vi.clearAllMocks();
+    vi.useFakeTimers();
+    mockIsBrowser.mockReturnValue(true);
+    mockCreateFrappeCollection.mockImplementation(() => makeLiveCollection());
+  });
+
+  afterEach(() => {
+    vi.runOnlyPendingTimers();
+    vi.useRealTimers();
+    mockIsBrowser.mockReturnValue(true);
+  });
+
+  const configFor = (label: string): UseFrappeCollectionConfig => ({
+    baseURL: `https://gcrace-${label}-${testNum}.example.com`,
+  });
+
+  it("defers cleanup while a live query is still attached, then cleans up once it detaches", () => {
+    const config = configFor("defer");
+    const a = renderHook(() => useFrappeCollection(config, "Workspace"));
+    const shared = a.result.current as any;
+
+    // A live query attached to the collection (e.g. created during render or
+    // still detaching through TanStack's idle GC after unmount).
+    shared.subscriberCount = 1;
+    a.unmount();
+
+    act(() => {
+      vi.advanceTimersByTime(GC_WAIT_MS);
+    });
+    expect(shared.cleanup).not.toHaveBeenCalled();
+    act(() => {
+      vi.advanceTimersByTime(3 * GC_WAIT_MS);
+    });
+    expect(shared.cleanup).not.toHaveBeenCalled();
+
+    // Query detaches → the next deferred GC tick cleans up.
+    shared.subscriberCount = 0;
+    act(() => {
+      vi.advanceTimersByTime(GC_WAIT_MS);
+    });
+    expect(shared.cleanup).toHaveBeenCalledTimes(1);
+  });
+
+  it("a remount during a deferred GC window reuses the same still-live collection", () => {
+    const config = configFor("remountdefer");
+    const a = renderHook(() => useFrappeCollection(config, "Workspace"));
+    const shared = a.result.current as any;
+    shared.subscriberCount = 1;
+    a.unmount();
+
+    // Past the plain grace period — the entry survives on the deferral path.
+    act(() => {
+      vi.advanceTimersByTime(2 * GC_WAIT_MS);
+    });
+    const b = renderHook(() => useFrappeCollection(config, "Workspace"));
+    expect(b.result.current).toBe(shared);
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(1);
+
+    // Retained again: even the force window passing must not clean it up.
+    act(() => {
+      vi.advanceTimersByTime(FORCE_WAIT_MS);
+    });
+    expect(shared.cleanup).not.toHaveBeenCalled();
+  });
+
+  it("force-cleans after the max defer window when a leaked query pins the collection", () => {
+    const config = configFor("force");
+    const a = renderHook(() => useFrappeCollection(config, "Workspace"));
+    const shared = a.result.current as any;
+    // A query that never detaches (created by a render that never committed —
+    // TanStack DB never arms its GC because it never had a subscriber).
+    shared.subscriberCount = 1;
+    a.unmount();
+
+    act(() => {
+      vi.advanceTimersByTime(FORCE_WAIT_MS);
+    });
+    expect(shared.cleanup).toHaveBeenCalledTimes(1);
+
+    // A later consumer gets a fresh collection, not the force-cleaned husk.
+    const b = renderHook(() => useFrappeCollection(config, "Workspace"));
+    expect(b.result.current).not.toBe(shared);
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(2);
+  });
+
+  it("each idle period gets a fresh force window (deadline resets on retain)", () => {
+    const config = configFor("deadlinereset");
+    const a = renderHook(() => useFrappeCollection(config, "Workspace"));
+    const shared = a.result.current as any;
+    shared.subscriberCount = 1;
+    a.unmount();
+
+    // Burn most of the force window, then retain (remount) — resetting it.
+    act(() => {
+      vi.advanceTimersByTime(25_000);
+    });
+    const b = renderHook(() => useFrappeCollection(config, "Workspace"));
+    expect(b.result.current).toBe(shared);
+    b.unmount();
+
+    // A fresh full window applies after the release; 25s in, still deferred.
+    act(() => {
+      vi.advanceTimersByTime(25_000);
+    });
+    expect(shared.cleanup).not.toHaveBeenCalled();
+    act(() => {
+      vi.advanceTimersByTime(FORCE_WAIT_MS);
+    });
+    expect(shared.cleanup).toHaveBeenCalledTimes(1);
+  });
+
+  it("hands out a fresh collection when a cached entry's collection was cleaned up out-of-band", () => {
+    const config = configFor("stalerender");
+    const a = renderHook(() => useFrappeCollection(config, "Workspace"));
+    const stale = a.result.current as any;
+
+    // Out-of-band teardown the registry didn't drive (e.g. TanStack DB's own
+    // idle GC after every query detached, or a manual cleanup() call) — the
+    // status listener bumps the mounted consumer onto a fresh entry.
+    act(() => {
+      stale.cleanup();
+    });
+
+    expect(a.result.current).not.toBe(stale);
+    expect((a.result.current as any).status).not.toBe("cleaned-up");
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(2);
+
+    // New consumers share the fresh entry, not the husk.
+    const b = renderHook(() => useFrappeCollection(config, "Workspace"));
+    expect(b.result.current).toBe(a.result.current);
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(2);
+  });
+
+  it("REGRESSION: releasing an errored entry defers collection cleanup until live queries detach", () => {
+    // Unmount-during-error: the release evicts the entry immediately (Retry
+    // contract) but must NOT cleanup() while a live query is still attached
+    // — that would hard-error the query mid-detach ("Source collection …
+    // was manually cleaned up while live query … depends on it").
+    const config = configFor("erridle");
+    const a = renderHook(() => useFrappeCollection(config, "Workspace"));
+    const shared = a.result.current as any;
+    shared.subscriberCount = 1; // live query attached by the consumer's render
+
+    const passedOptions = mockCreateFrappeCollection.mock.calls[0][1];
+    act(() => {
+      passedOptions.onSyncError(new Error("initial sync failed"));
+    });
+    a.unmount();
+
+    // Evicted at once: a remount gets a fresh entry (fresh attempt) …
+    const retry = renderHook(() => useFrappeCollection(config, "Workspace"));
+    expect(retry.result.current).not.toBe(shared);
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(2);
+
+    // … while the old collection's cleanup waits for the query to detach.
+    act(() => {
+      vi.advanceTimersByTime(GC_WAIT_MS);
+    });
+    expect(shared.cleanup).not.toHaveBeenCalled();
+    shared.subscriberCount = 0;
+    act(() => {
+      vi.advanceTimersByTime(GC_WAIT_MS);
+    });
+    expect(shared.cleanup).toHaveBeenCalledTimes(1);
+  });
+
+  it("mount→unmount→mount within the grace window (StrictMode/HMR pattern) keeps one live instance", () => {
+    const config = configFor("strictish");
+    const a = renderHook(() => useFrappeCollection(config, "Workspace"));
+    const shared = a.result.current as any;
+    shared.subscriberCount = 1; // live query attached by the first mount
+    a.unmount();
+
+    // Remount well inside the grace window.
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+    const b = renderHook(() => useFrappeCollection(config, "Workspace"));
+    expect(b.result.current).toBe(shared);
+
+    act(() => {
+      vi.advanceTimersByTime(FORCE_WAIT_MS);
+    });
+    expect(shared.cleanup).not.toHaveBeenCalled();
+    expect(mockCreateFrappeCollection).toHaveBeenCalledTimes(1);
+  });
 });
 
 // ---------------------------------------------------------------------------