@multiplatform.one/frappe 6.6.0 → 7.0.0

package/src/optimistic.ts

@@ -37,3 +37,98 @@ export { tanstackCreateOptimisticAction as createOptimisticAction };
  * await tx.isPersisted.promise;
  * ```
  */
+
+// ---------------------------------------------------------------------------
+// Optimistic RPC lifecycle — the ONE pattern for mutations that ride
+// whitelisted desk RPCs instead of the document CRUD path.
+// ---------------------------------------------------------------------------
+//
+// Document CRUD (collection insert/update/delete) is already optimistic via
+// the MutationEngine: local cache apply → journal Pending → server ack →
+// temp-id → real-name remap, snapshot rollback on failure. Desk RPC
+// mutations (add_comment, assign_to, tags, likes, shares…) bypass that
+// engine, and every callsite used to hand-roll "await, then refetch" — the
+// user saw nothing until the server round-trip completed.
+//
+// `runOptimisticRpc` gives those callsites the same lifecycle the engine
+// gives documents, without per-callsite hacks:
+//
+//   1. APPLY     — synchronous local apply BEFORE the request leaves;
+//                  returns the undo used for rollback. The applied state
+//                  should carry a pending marker so surfaces can render it
+//                  visible-but-distinct (Axiom 6 HONEST STATE).
+//   2. SEND      — the RPC itself.
+//   3. RECONCILE — on ack, converge the optimistic identity (the issued
+//                  `tmp_*` id) to the server identity so the optimistic
+//                  record and the server record become ONE record, never
+//                  duplicates.
+//   4. ROLLBACK  — on failure, the apply-phase undo runs, then `onError`
+//                  surfaces a visible error (house `notify()`), and the
+//                  error rethrows for the caller.
+
+/** Prefix shared with the MutationEngine's synthesized create identities. */
+export const OPTIMISTIC_TEMP_PREFIX = "tmp_";
+
+/** Issues a client-only identity for an optimistic record (`tmp_<uuid>`). */
+export function newOptimisticTempId(): string {
+  const id =
+    typeof crypto !== "undefined" && "randomUUID" in crypto
+      ? crypto.randomUUID()
+      : Math.random().toString(36).slice(2);
+  return `${OPTIMISTIC_TEMP_PREFIX}${id}`;
+}
+
+/** True when a document name is a client-issued optimistic identity. */
+export function isOptimisticTempId(name: unknown): name is string {
+  return typeof name === "string" && name.startsWith(OPTIMISTIC_TEMP_PREFIX);
+}
+
+export interface OptimisticRpcContext {
+  /** Client-only identity for the optimistic record (`tmp_<uuid>`). */
+  tempId: string;
+}
+
+export interface OptimisticRpcOptions<TAck> {
+  /**
+   * Apply the mutation locally, synchronously, before the request is sent.
+   * Returns the undo that restores the exact pre-apply state (rollback).
+   * The applied record should use `ctx.tempId` as its identity and carry a
+   * pending marker for the UI.
+   */
+  apply: (ctx: OptimisticRpcContext) => (() => void) | undefined | void;
+  /** The server RPC. */
+  send: (ctx: OptimisticRpcContext) => Promise<TAck>;
+  /**
+   * Converge on ack: replace the `ctx.tempId` record with the server's
+   * authoritative record (dedupe by server identity — a racing refetch may
+   * already have delivered it).
+   */
+  reconcile?: (ack: TAck, ctx: OptimisticRpcContext) => void;
+  /**
+   * Visible-error surface for the rollback path (house `notify()` or an
+   * inline error slot). Runs after the apply-phase undo.
+   */
+  onError?: (error: unknown, ctx: OptimisticRpcContext) => void;
+}
+
+/**
+ * Runs one mutation through the optimistic lifecycle:
+ * apply (local, immediate) → send → reconcile on ack, or undo + onError on
+ * failure (the error rethrows).
+ */
+export async function runOptimisticRpc<TAck>(options: OptimisticRpcOptions<TAck>): Promise<TAck> {
+  const ctx: OptimisticRpcContext = { tempId: newOptimisticTempId() };
+  const undo = options.apply(ctx) ?? undefined;
+  try {
+    const ack = await options.send(ctx);
+    options.reconcile?.(ack, ctx);
+    return ack;
+  } catch (error) {
+    try {
+      undo?.();
+    } finally {
+      options.onError?.(error, ctx);
+    }
+    throw error;
+  }
+}

package/src/pacer.ts

@@ -6,6 +6,7 @@ import { useCallback, useMemo, useRef, useState } from "react";
 import type { FrappeDoc, FrappeDocData } from "./common/types";
 import type { AuthConfig } from "./core/types";
 import { DbModule } from "./db";
+import type { FixtureProvider } from "./fixtures";
 import { HttpClient } from "./core/http";
 import type { SyncModule } from "./sync";
 import { Operation } from "./sync/types";
@@ -62,6 +63,13 @@ export interface FrappeConnectionConfig {
     token?: string | (() => string | Promise<string>);
     type?: string;
   };
+  /**
+   * Fixture provider for story / test hosts. Consumers already forward it
+   * (frappe-ui's FrappeProvider builds this config from its own context), and
+   * `useDocTypeMeta` reads doctype metadata from it before reaching for the
+   * network.
+   */
+  fixtures?: FixtureProvider;
 }
 
 function createDbModule(config: FrappeConnectionConfig): DbModule {

package/src/realtime.spec.ts

@@ -783,6 +783,68 @@ describe("RealtimeModule", () => {
       rt.disconnect();
     });
 
+    it("uses an explicit siteName as the Socket.IO namespace (127.0.0.1 → localhost)", async () => {
+      // Frappe socketio maps Host localhost/127.0.0.1 to conf.default_site
+      // and rejects any other namespace. Connecting via the IPv4 literal
+      // (the serve_dev.py workaround for shcd on [::1]:8000) must still
+      // join /localhost, not /127.0.0.1.
+      const rt = new RealtimeModule({
+        baseURL: "http://127.0.0.1:8000",
+        socketPort: 9000,
+        siteName: "localhost",
+      });
+      await (rt as any).connect();
+
+      const calls = (io as unknown as ReturnType<typeof vi.fn>).mock.calls;
+      expect(calls[calls.length - 1]?.[0]).toBe("http://127.0.0.1:9000/localhost");
+      rt.disconnect();
+    });
+
+    it("dials socketBaseURL when set, joining the siteName namespace (same-origin dev)", async () => {
+      // Web dev: the dev server proxies /socket.io on the PAGE origin (e.g.
+      // :3998) to the bench socketio — the client must dial that origin, not
+      // baseURL+socketPort, so the polling handshake is same-origin.
+      const rt = new RealtimeModule({
+        baseURL: "http://127.0.0.1:8000",
+        socketBaseURL: "http://127.0.0.1:3998",
+        siteName: "localhost",
+      });
+      await (rt as any).connect();
+
+      const calls = (io as unknown as ReturnType<typeof vi.fn>).mock.calls;
+      expect(calls[calls.length - 1]?.[0]).toBe("http://127.0.0.1:3998/localhost");
+      rt.disconnect();
+    });
+
+    it("socketBaseURL wins over socketPort and trims a trailing slash", async () => {
+      const rt = new RealtimeModule({
+        baseURL: "http://127.0.0.1:8000",
+        socketPort: 9000,
+        socketBaseURL: "http://localhost:3998/",
+        siteName: "localhost",
+      });
+      await (rt as any).connect();
+
+      const calls = (io as unknown as ReturnType<typeof vi.fn>).mock.calls;
+      expect(calls[calls.length - 1]?.[0]).toBe("http://localhost:3998/localhost");
+      rt.disconnect();
+    });
+
+    it("falls back to the baseURL hostname namespace under socketBaseURL without siteName", async () => {
+      // Same fallback as the derived path: the namespace comes from the
+      // BENCH URL's hostname — never from socketBaseURL, whose hostname is
+      // the dev server, not a Frappe site.
+      const rt = new RealtimeModule({
+        baseURL: "http://bench.example.com:8000",
+        socketBaseURL: "http://localhost:3998",
+      });
+      await (rt as any).connect();
+
+      const calls = (io as unknown as ReturnType<typeof vi.fn>).mock.calls;
+      expect(calls[calls.length - 1]?.[0]).toBe("http://localhost:3998/bench.example.com");
+      rt.disconnect();
+    });
+
     it("uses the token scheme when auth type is token", async () => {
       const rt = new RealtimeModule({
         baseURL: "http://localhost:3000",