@multiplatform.one/frappe 7.11.0 → 7.15.0

package/src/frappeReact.spec.ts

@@ -56,6 +56,7 @@ vi.mock("./fixtureDb", () => ({ FixtureDbModule: class {} }));
 
 import { isBrowser } from "./util";
 import { Order } from "./sync/types";
+import type { FixtureProvider } from "./fixtures";
 import type { UseFrappeCollectionConfig, UseFrappeInfiniteListConfig } from "./frappeReact";
 import {
   __getActiveSyncModule,
@@ -341,6 +342,61 @@ describe("useFrappeCollection", () => {
     expect(active).toBeDefined();
   });
 
+  it("__getActiveSyncModule returns the SyncModule when the only one was created in fixture mode", async () => {
+    vi.resetModules();
+    const fresh = await import("./frappeReact");
+    expect(fresh.__getActiveSyncModule()).toBeUndefined();
+    const fixtures = {} as FixtureProvider;
+    renderHook(() => fresh.useFrappeCollection({ fixtures }, "Task"));
+    const active = fresh.__getActiveSyncModule();
+    expect(active).toBeDefined();
+    expect(active).toBe(mockCreateFrappeCollection.mock.calls.at(-1)?.[1].sync);
+  });
+
+  it("__getActiveSyncModule prefers a fixture-mode SyncModule created after live ones", () => {
+    renderHook(() =>
+      useFrappeCollection({ baseURL: `https://before-fixture-${testNum}.example.com` }, "Task"),
+    );
+    const fixtures = {} as FixtureProvider;
+    renderHook(() => useFrappeCollection({ fixtures }, "Task"));
+    const fixtureSync = mockCreateFrappeCollection.mock.calls.at(-1)?.[1].sync;
+    expect(fixtureSync).toBeDefined();
+    expect(__getActiveSyncModule()).toBe(fixtureSync);
+  });
+
+  it("__getActiveSyncModule falls back to the live cache once the latest SyncModule is collected", async () => {
+    vi.resetModules();
+    const fresh = await import("./frappeReact");
+    const live = fresh.getFrappeSyncModule({ baseURL: `https://collected-${testNum}.example.com` });
+    vi.stubGlobal(
+      "WeakRef",
+      class {
+        deref() {
+          return undefined;
+        }
+      },
+    );
+    try {
+      expect(fresh.getFrappeSyncModule({ fixtures: {} as FixtureProvider })).toBeDefined();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+    expect(live).toBeDefined();
+    expect(fresh.__getActiveSyncModule()).toBe(live);
+  });
+
+  it("builds fixture-mode SyncModules on runtimes without WeakRef", async () => {
+    vi.resetModules();
+    const fresh = await import("./frappeReact");
+    vi.stubGlobal("WeakRef", undefined);
+    try {
+      expect(fresh.getFrappeSyncModule({ fixtures: {} as FixtureProvider })).toBeDefined();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+    expect(fresh.__getActiveSyncModule()).toBeUndefined();
+  });
+
   it("passes socketOptions through to the RealtimeModule", () => {
     const socketOptions = { transports: ["polling", "websocket"] };
     const config: UseFrappeCollectionConfig = {

package/src/frappeReact.ts

@@ -77,12 +77,25 @@ const fixtureSyncModuleCache = new WeakMap<
   import("./fixtures").FixtureProvider,
   Map<string, SyncModule>
 >();
+// A WeakMap can't be enumerated, so this slot is how the accessor below sees
+// a fixture-mode module. WeakRef rather than an explicit clear: nothing
+// refcounts SyncModules, and a strong slot would pin a discarded fixture
+// set's module (and its FixtureProvider) and hand devtools a dead one.
+// Runtimes without WeakRef never fill the slot and keep the live-cache scan.
+let latestSyncModule: WeakRef<SyncModule> | undefined;
+
+function rememberLatestSyncModule(sync: SyncModule): void {
+  if (typeof WeakRef === "function") latestSyncModule = new WeakRef(sync);
+}
 
 /**
- * Returns the first active SyncModule, or undefined if none exist.
+ * Returns the most recently constructed SyncModule (live or fixture mode),
+ * falling back to the first live one, or undefined if none exist.
  * Intended for devtools integration — not part of the public API.
  */
 export function __getActiveSyncModule(): SyncModule | undefined {
+  const latest = latestSyncModule?.deref();
+  if (latest) return latest;
   for (const sync of syncModuleCache.values()) return sync;
   return undefined;
 }
@@ -132,6 +145,7 @@ function getSyncModule(config: UseFrappeCollectionConfig): SyncModule | undefine
       const db = new FixtureDbModule(config.fixtures) as unknown as DbModule;
       sync = new SyncModule(db, undefined, config.syncOptions);
       cache.set(optionsKey, sync);
+      rememberLatestSyncModule(sync);
     }
     return sync;
   }
@@ -185,6 +199,7 @@ function getSyncModule(config: UseFrappeCollectionConfig): SyncModule | undefine
       config.syncOptions,
     );
     syncModuleCache.set(key, sync);
+    rememberLatestSyncModule(sync);
   }
   return sync;
 }
@@ -465,6 +480,10 @@ function cleanupEntryCollectionWhenIdle(entry: SharedCollectionEntry): void {
   entry.gcTimer = setTimeout(tick, SHARED_COLLECTION_GC_MS);
 }
 
+const subscribeHydration = () => () => {};
+const clientCollectionAvailable = () => true;
+const serverCollectionAvailable = () => false;
+
 /**
  * React hook that returns a TanStack DB Collection backed by a Frappe doctype.
  *
@@ -488,7 +507,7 @@ function cleanupEntryCollectionWhenIdle(entry: SharedCollectionEntry): void {
  * @param config - Connection configuration (baseURL, auth)
  * @param doctype - The Frappe doctype name
  * @param options - Optional collection configuration (fields, filters, etc.)
- * @returns A stable TanStack DB Collection instance, or undefined if config is not provided
+ * @returns A stable collection, or undefined during SSR/hydration or without config
  *
  * @example
  * ```tsx
@@ -515,6 +534,13 @@ export function useFrappeCollection<TDoc extends object & { name: string; doctyp
   doctype: string,
   options?: Omit<FrappeCollectionOptionsConfig<TDoc>, "sync">,
 ): Collection<TDoc, string> | undefined {
+  // Each hydrating boundary must match SSR even if an earlier reader has
+  // already filled the shared cache. Client-only and native mounts read true.
+  const collectionAvailable = useSyncExternalStore(
+    subscribeHydration,
+    clientCollectionAvailable,
+    serverCollectionAvailable,
+  );
   // Consumers pass inline onSyncError closures; keep one stable wrapper per
   // hook instance so the entry's handler registry doesn't churn every render.
   const errorHandlerRef = useRef(options?.onSyncError);
@@ -526,16 +552,16 @@ export function useFrappeCollection<TDoc extends object & { name: string; doctyp
   const [, setStaleEntryBump] = useState(0);
 
   // Resolve the shared entry during render so the collection is available on
-  // the FIRST render (same contract as before the cache). An empty doctype is
+  // the first client-only/native render and after hydration. An empty doctype is
   // treated like an undefined config: consumers such as DynamicLink pass ""
   // before a doctype is chosen, and syncing doctype "" fires a bogus
   // `/api/v2/document/` 404. During SSR, getSyncModule returns undefined —
   // the component renders a loading state and the client hydration pass
-  // creates the real collection.
+  // exposes the real collection after this boundary hydrates.
   let cache: Map<string, SharedCollectionEntry> | undefined;
   let key = "";
   let entry: SharedCollectionEntry | undefined;
-  if (config && doctype) {
+  if (collectionAvailable && config && doctype) {
     const syncModule = getSyncModule(config);
     if (syncModule) {
       key = collectionOptionsKey(doctype, options);

package/src/index.ts

@@ -8,6 +8,13 @@
 // Core Frappe functionality
 export { FrappeApp } from "./frappeApp";
 export type { FrappeConfig } from "./frappeApp";
+export {
+  loadDoc,
+  loadDocList,
+  type FrappeLoaderRequest,
+  type LoadDocListOptions,
+  type LoadDocOptions,
+} from "./serverLoaders";
 export { AuthModule } from "./auth";
 export { CallModule } from "./call";
 export { DbModule } from "./db";
@@ -174,11 +181,15 @@ export {
   useDocTypeSearch,
   parseDependsOn,
   parseFormLayout,
+  stockFieldTypes,
+  customFieldTypes,
+  frappeFieldTypes,
 } from "./doctype";
 export type {
   DocTypeMeta,
   DocTypeField,
   DocTypePermission,
+  DocTypeLink,
   FormSection,
   FormColumn,
   FrappeFieldType,

package/src/serverLoaders.ts

@@ -0,0 +1,77 @@
+import type { ListOptions } from "./core/types";
+import { FrappeApp } from "./frappeApp";
+
+/** The slice of a route loader's `Request` the server reads: its cookie header. */
+export interface FrappeLoaderRequest {
+  headers?: { get(name: string): string | null } | null;
+}
+
+interface LoaderTarget {
+  /** Bench address the server dials (not the browser's). */
+  baseURL: string;
+  doctype: string;
+  /**
+   * The incoming request. Its cookie rides along so the server reads with
+   * the visitor's session. Absent (a loader run in the browser), nothing is
+   * fetched: the live collection reads instead.
+   */
+  request?: FrappeLoaderRequest | null;
+}
+
+export type LoadDocListOptions = LoaderTarget &
+  Pick<ListOptions, "fields" | "filters" | "orderBy" | "limit">;
+
+export interface LoadDocOptions extends LoaderTarget {
+  name: string;
+}
+
+function serverApp(baseURL: string, request: FrappeLoaderRequest): FrappeApp {
+  const cookie = request.headers?.get("cookie") ?? undefined;
+  return new FrappeApp(baseURL, cookie ? { cookie } : {});
+}
+
+function isNotFound(error: unknown): boolean {
+  return (
+    typeof error === "object" && error !== null && (error as { status?: number }).status === 404
+  );
+}
+
+/**
+ * Rows for a server-rendered list, read with the query the page's live
+ * collection will use: hand both the same fields, filters, order and limit,
+ * or the collection's first sync replaces the rendered page with a
+ * different one (a 20-row default page shrank a 21-row list, MPO-322).
+ * A failed read renders an empty page rather than failing the route.
+ */
+export async function loadDocList<TDoc extends { name: string; doctype: string }>({
+  baseURL,
+  doctype,
+  request,
+  ...query
+}: LoadDocListOptions): Promise<TDoc[]> {
+  if (!request) return [];
+  try {
+    const rows = await serverApp(baseURL, request).db().getDocList<TDoc>(doctype, query);
+    return rows.map((row) => ({ ...row, doctype }) as TDoc);
+  } catch (error) {
+    console.error(`[loadDocList] ${doctype}:`, error);
+    return [];
+  }
+}
+
+/** One document, child tables included, for a server-rendered detail page; null when missing. */
+export async function loadDoc<TDoc extends { name: string; doctype: string }>({
+  baseURL,
+  doctype,
+  name,
+  request,
+}: LoadDocOptions): Promise<TDoc | null> {
+  if (!request || !name) return null;
+  try {
+    const doc = await serverApp(baseURL, request).db().getDoc<TDoc>(doctype, name);
+    return doc ? ({ ...doc, doctype } as TDoc) : null;
+  } catch (error) {
+    if (!isNotFound(error)) console.error(`[loadDoc] ${doctype}/${name}:`, error);
+    return null;
+  }
+}

package/src/sync/index.ts

@@ -286,6 +286,15 @@ export class SyncModule {
     this.emit();
   }
 
+  /**
+   * The name the server assigned a document this module created under
+   * `temporaryName`, once the create is acknowledged. Undefined while it is
+   * pending, or when the server kept the name it was given.
+   */
+  createdName(temporaryName: string): string | undefined {
+    return this.rehydrationManager.resolveTempId(temporaryName);
+  }
+
   /** Refresh active query snapshots in place. Failures retain the last committed data. */
   async refreshSubscriptions(
     options?: SubscriptionRefreshOptions,

package/src/sync/rehydration.ts

@@ -370,6 +370,11 @@ export class RehydrationManager {
     this.temporaryIdMap.set(tempId, realName);
   }
 
+  /** The name the server gave a document created under a temp id. */
+  resolveTempId(tempId: string): string | undefined {
+    return this.temporaryIdMap.get(tempId);
+  }
+
   /**
    * Clears the rehydration queue.
    */

package/src/sync/syncModule.spec.ts

@@ -65,6 +65,26 @@ describe("SyncModule", () => {
     return new SyncModule(mockDb, mockRealtime, options);
   }
 
+  describe("createdName (MPO-333)", () => {
+    it("names the document the server created under a temporary name", async () => {
+      mockDb.createDoc.mockResolvedValue({
+        name: "a1b2c3",
+        doctype: "TestDoc",
+        modified: "2024-01-01T11:00:00",
+        title: "hash named",
+      });
+      sync = createSync();
+      expect(sync.createdName("new-1")).toBeUndefined();
+      await sync.mutate({
+        mutationId: "create-hash",
+        operation: Operation.Create,
+        doc: { name: "new-1", doctype: "TestDoc", title: "hash named" },
+      });
+      expect(sync.createdName("new-1")).toBe("a1b2c3");
+      expect(sync.createdName("new-2")).toBeUndefined();
+    });
+  });
+
   describe("automatic journal storage", () => {
     it("reads HTTP rows during SSR with Node's incomplete localStorage object", async () => {
       vi.stubGlobal("window", undefined);

package/src/useLiveQuery.hydration.spec.tsx

@@ -0,0 +1,129 @@
+import { act } from "react";
+import { hydrateRoot } from "react-dom/client";
+import { renderToString } from "react-dom/server";
+import { expect, it, vi } from "vitest";
+
+const platform = vi.hoisted(() => ({ server: true }));
+vi.mock("@multiplatform.one/platform", () => ({
+  get isServer() {
+    return platform.server;
+  },
+}));
+
+it.each([
+  { warm: false, enabled: true },
+  { warm: true, enabled: true },
+  { warm: true, enabled: false },
+])("hydrates real queries and preserves updates/cleanup (%j)", async ({ warm, enabled }) => {
+  platform.server = true;
+  vi.resetModules();
+  const serverDb = await import("@tanstack/db");
+  const serverCollection = serverDb.createCollection(
+    serverDb.localOnlyCollectionOptions({
+      getKey: (row: { id: string; label: string }) => row.id,
+      initialData: [{ id: "alpha", label: "Alpha" }],
+    }),
+  );
+  const { useLiveQuery: serverQuery } = await import("./useLiveQuery");
+  function ServerView() {
+    const result = serverQuery((q) => (enabled ? q.from({ item: serverCollection }) : undefined));
+    return (
+      <div data-testid="result">
+        {!result.isEnabled
+          ? "Disabled"
+          : result.data?.map((row) => row.label).join(",") || "Loading"}
+      </div>
+    );
+  }
+  const container = document.createElement("div");
+  container.innerHTML = renderToString(<ServerView />);
+  document.body.append(container);
+  const serverNode = container.firstChild;
+  platform.server = false;
+  vi.resetModules();
+  const clientDb = await import("@tanstack/db");
+  const collection = clientDb.createCollection(
+    clientDb.localOnlyCollectionOptions({
+      getKey: (row: { id: string; label: string }) => row.id,
+      initialData: [{ id: "alpha", label: "Alpha" }],
+    }),
+  );
+  if (warm) await collection.preload();
+  const { useLiveQuery: clientQuery } = await import("./useLiveQuery");
+  let observedQuery: { subscriberCount: number; status: string } | undefined;
+  function ClientView({ active = enabled, selected }: { active?: boolean; selected?: string }) {
+    const result = clientQuery(
+      (q) => {
+        if (!active) return undefined;
+        const query = q.from({ item: collection });
+        return selected ? query.where(({ item }) => clientDb.eq(item.id, selected)) : query;
+      },
+      [active, selected],
+    );
+    observedQuery = result.collection;
+    return (
+      <div data-testid="result">
+        {!result.isEnabled
+          ? "Disabled"
+          : result.data?.map((row) => row.label).join(",") || "Loading"}
+      </div>
+    );
+  }
+  const onRecoverableError = vi.fn();
+  let root: ReturnType<typeof hydrateRoot> | undefined;
+  try {
+    await act(async () => {
+      root = hydrateRoot(container, <ClientView />, { onRecoverableError });
+    });
+    expect(
+      onRecoverableError.mock.calls.map(([error]) => error.cause?.message || error.message),
+    ).toEqual([]);
+    expect(container.firstChild).toBe(serverNode);
+    await vi.waitFor(() => expect(container.textContent).toBe(enabled ? "Alpha" : "Disabled"));
+    if (!enabled) {
+      expect(collection.subscriberCount).toBe(0);
+      await act(async () => root!.render(<ClientView active />));
+    }
+    await act(async () => {
+      const transaction = collection.insert({ id: "beta", label: "Beta" });
+      await transaction.isPersisted.promise;
+    });
+    await vi.waitFor(() => expect(container.textContent).toBe("Alpha,Beta"));
+    await act(async () => root!.render(<ClientView active selected="beta" />));
+    await vi.waitFor(() => expect(container.textContent).toBe("Beta"));
+    const { createOptimisticAction } = await import("./optimistic");
+    let rejectWrite: (reason: Error) => void = () => {};
+    const write = new Promise<void>((_resolve, reject) => {
+      rejectWrite = reject;
+    });
+    const rename = createOptimisticAction({
+      onMutate: () =>
+        collection.update("beta", (row) => {
+          row.label = "Pending";
+        }),
+      mutationFn: () => write,
+    });
+    let transaction: ReturnType<typeof rename>;
+    await act(async () => {
+      transaction = rename(undefined);
+    });
+    await vi.waitFor(() => expect(container.textContent).toBe("Pending"));
+    await act(async () => {
+      const refused = expect(transaction!.isPersisted.promise).rejects.toThrow("Write refused");
+      rejectWrite(new Error("Write refused"));
+      await refused;
+    });
+    await vi.waitFor(() => expect(container.textContent).toBe("Beta"));
+    const lastQuery = observedQuery;
+    expect(lastQuery?.subscriberCount).toBeGreaterThan(0);
+    await act(async () => root!.unmount());
+    root = undefined;
+    await vi.waitFor(() => expect(lastQuery?.subscriberCount).toBe(0));
+    await vi.waitFor(() => expect(lastQuery?.status).toBe("cleaned-up"));
+  } finally {
+    await act(async () => root?.unmount());
+    container.remove();
+    await collection.cleanup();
+    await serverCollection.cleanup();
+  }
+});

package/src/useLiveQuery.spec.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { isServer } from "@multiplatform.one/platform";
+import { useLiveQuery as upstreamUseLiveQuery } from "@tanstack/react-db";
 import { describe, expect, it } from "vitest";
 import { useLiveQuery } from "./useLiveQuery";
 
@@ -22,9 +22,8 @@ describe("useLiveQuery carries no import.meta (MPO-204)", () => {
     expect(source).not.toMatch(/import\.meta/);
   });
 
-  it("takes its SSR answer from the platform package, which is split by FILE and not by a bundler define", () => {
-    expect(source).toMatch(/import \{ isServer \} from "@multiplatform\.one\/platform";/);
-    expect(source).toMatch(/const IS_SSR: boolean = isServer;/);
+  it("preserves the upstream hook and its server snapshot lifecycle", () => {
+    expect(useLiveQuery).toBe(upstreamUseLiveQuery);
   });
 
   it("has no platform twin — a .web twin replaced the bake once already (MPO-192)", () => {
@@ -34,10 +33,3 @@ describe("useLiveQuery carries no import.meta (MPO-204)", () => {
     }
   });
 });
-
-describe("useLiveQuery answers client in a browser-like environment", () => {
-  it("resolves isServer false, so the hook delegates to @tanstack/react-db", () => {
-    expect(isServer).toBe(false);
-    expect(typeof useLiveQuery).toBe("function");
-  });
-});

package/src/useLiveQuery.ts

@@ -1,59 +1,5 @@
-import { isServer } from "@multiplatform.one/platform";
-import { useLiveQuery as useLiveQueryBase } from "@tanstack/react-db";
-
 /**
- * Result returned while server rendering: mirrors the shape
- * `@tanstack/react-db` produces during its initial client-side "loading"
- * state so SSR markup matches the client's first paint.
+ * React DB supplies the server snapshot for both SSR and browser hydration.
+ * Keep the upstream hook lifecycle intact on every platform.
  */
-const SSR_LIVE_QUERY_RESULT = Object.freeze({
-  state: undefined,
-  data: undefined,
-  collection: undefined,
-  status: "loading",
-  isLoading: true,
-  isReady: false,
-  isIdle: false,
-  isError: false,
-  isCleanedUp: false,
-  isEnabled: true,
-});
-
-/**
- * True when this module is evaluated during web server rendering.
- *
- * This used to read `import.meta.env.SSR` behind a try/catch. MPO-192 ruled
- * that shape out: two bundles execute mpo as a CLASSIC script — the
- * vxrn/rolldown native bundle for Hermes, and any Metro bundle for
- * platform=web, which is what an Expo DOM component (`'use dom'`) is — and in
- * a classic script `import.meta` is a PARSE-time SyntaxError, so the catch
- * never gets to run. The whole module fails to parse and takes its consumers
- * with it.
- *
- * `isServer` is the repo's own answer and carries no `import.meta`: it comes
- * from @tamagui/constants through @multiplatform.one/platform, and it is
- * split at the FILE level (`constants.native.ts` hardcodes `isServer = false`)
- * rather than by a bundler define. Web server render is the only case that
- * answers true — a browser has navigator + location, native takes the
- * `.native` flavour, and a DOM component's WebView is a browser.
- */
-const IS_SSR: boolean = isServer;
-
-/**
- * SSR-safe wrapper around `useLiveQuery` from `@tanstack/react-db`.
- *
- * The upstream hook calls `useSyncExternalStore(subscribe, getSnapshot)`
- * without a `getServerSnapshot`, so react-dom/server throws "Missing
- * getServerSnapshot, which is required for server-rendered content" the
- * moment any component using it is server rendered (e.g. deep-linking a
- * web route). On the server we skip the subscription entirely and return
- * a static "loading" result; the live query takes over on the client.
- *
- * `IS_SSR` is constant for the lifetime of the process, so hook order
- * never varies within a renderer.
- */
-export const useLiveQuery: typeof useLiveQueryBase = ((...args: unknown[]) => {
-  if (IS_SSR) return SSR_LIVE_QUERY_RESULT;
-  // oxlint-disable-next-line rules-of-hooks -- branch is process-constant
-  return (useLiveQueryBase as (...args: unknown[]) => unknown)(...args);
-}) as typeof useLiveQueryBase;
+export { useLiveQuery } from "@tanstack/react-db";