@pylonsync/react 0.4.5 → 0.4.7

package/dist/engine-registry.d.ts

@@ -0,0 +1,8 @@
+import type { SyncEngine } from "@pylonsync/sync";
+/** Publish the engine `init()` built. Called only from `db.ts`. */
+export declare function setActiveEngine(engine: SyncEngine | null): void;
+/**
+ * The engine, if one exists. Never constructs one — a `null` return
+ * means "this app isn't running sync", not "not yet initialized".
+ */
+export declare function peekActiveEngine(): SyncEngine | null;

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.4.5",
+  "version": "0.4.7",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",
@@ -14,8 +14,8 @@
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@pylonsync/sdk": "0.4.5",
-    "@pylonsync/sync": "0.4.5"
+    "@pylonsync/sdk": "0.4.7",
+    "@pylonsync/sync": "0.4.7"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/callFn.test.ts

@@ -0,0 +1,82 @@
+// `callFn` routing. The bug this locks down: the exported helper did a bare
+// fetch and dropped the `X-Pylon-Change-Seq` response header, so a caller's
+// own mutation didn't land in their own replica — add a row, and it isn't
+// there until something else refreshes. `db.fn` and `useMutation` both went
+// through `SyncEngine.fn`, which observes the header, so the same operation
+// behaved differently depending on which import you reached for.
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { callFn } from "./index";
+import { peekActiveEngine, setActiveEngine } from "./engine-registry";
+
+describe("callFn", () => {
+  const realFetch = globalThis.fetch;
+  let requests: Array<{ url: string; headers: Record<string, string> }>;
+
+  beforeEach(() => {
+    requests = [];
+    setActiveEngine(null);
+    globalThis.fetch = (async (input: any, init: any = {}) => {
+      requests.push({
+        url: String(input?.url ?? input),
+        headers: (init.headers ?? {}) as Record<string, string>,
+      });
+      return new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    }) as typeof fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = realFetch;
+    setActiveEngine(null);
+  });
+
+  /** Minimal engine stand-in that records `fn` calls. */
+  function fakeEngine() {
+    const calls: Array<{ name: string; args: unknown }> = [];
+    const engine = {
+      async fn<T>(name: string, args: unknown): Promise<T> {
+        calls.push({ name, args });
+        return { viaEngine: true } as unknown as T;
+      },
+    };
+    setActiveEngine(engine as any);
+    return calls;
+  }
+
+  test("routes through the engine when the app has one", async () => {
+    const calls = fakeEngine();
+    const result = await callFn("addRoom", { name: "Main" });
+    expect(calls).toEqual([{ name: "addRoom", args: { name: "Main" } }]);
+    expect(result).toEqual({ viaEngine: true } as any);
+    // The engine owns the request, so nothing should have gone out
+    // through the bare transport.
+    expect(requests).toHaveLength(0);
+  });
+
+  test("falls back to a plain fetch when no engine exists", async () => {
+    // Apps that never call init() must keep working — and must NOT have
+    // an engine constructed (and a WebSocket opened) by a single POST.
+    await callFn("addRoom", { name: "Main" });
+    expect(requests).toHaveLength(1);
+    expect(requests[0]!.url).toContain("/api/fn/addRoom");
+    expect(peekActiveEngine()).toBeNull();
+  });
+
+  test("an explicit token bypasses the engine", async () => {
+    // That's a call as some other identity. Pulling its results into
+    // this replica would mix two users' data.
+    const calls = fakeEngine();
+    await callFn("addRoom", { name: "Main" }, { token: "someone-elses" });
+    expect(calls).toHaveLength(0);
+    expect(requests).toHaveLength(1);
+  });
+
+  test("peekActiveEngine never constructs an engine", async () => {
+    // The distinction from db.ts's getSync(), which deliberately does.
+    expect(peekActiveEngine()).toBeNull();
+    expect(peekActiveEngine()).toBeNull();
+  });
+});

package/src/db.ts

@@ -1,6 +1,7 @@
 "use client";
 
 import { SyncEngine, createSyncEngine, type Row, type SyncEngineConfig } from "@pylonsync/sync";
+import { setActiveEngine } from "./engine-registry";
 import {
   useQuery as useQueryHook,
   useQueryOne as useQueryOneHook,
@@ -57,6 +58,9 @@ let _started = false;
 export function init(config?: Partial<SyncEngineConfig> & { baseUrl?: string }) {
   _sync = createSyncEngine(config?.baseUrl, config);
   _started = false;
+  // Publish it so the free helpers in index.ts (callFn) can route
+  // through the engine and observe X-Pylon-Change-Seq.
+  setActiveEngine(_sync);
   // Keep the React-side helpers in sync — a single init() should fully
   // namespace this app's storage without a separate configureClient call.
   // Match createSyncEngine's resolution: when init({ appName }) omits
@@ -124,6 +128,7 @@ export function getSync(): SyncEngine {
     // app's SyncProvider effect lands would leak `localhost:4321`
     // requests in production.
     _sync = createSyncEngine();
+    setActiveEngine(_sync);
   }
   if (!_started) {
     _started = true;

package/src/engine-registry.ts

@@ -0,0 +1,30 @@
+// The active SyncEngine, readable without creating one.
+//
+// `db.ts` owns the engine's lifecycle, and `getSync()` there deliberately
+// creates and starts an engine on first access. That is right for `db.*`
+// — a call to `db.useQuery` means the app wants sync — but wrong for the
+// free helpers in `index.ts`, which must work in apps that never call
+// `init()`. `callFn` reaching for `getSync()` would open a WebSocket and
+// run an initial pull as a side effect of a single POST.
+//
+// Hence a separate module: `db.ts` publishes the engine here, `index.ts`
+// peeks at it, and neither imports the other. They already form a cycle
+// (`db.ts` imports `callFn` from `index.ts`), so the registry has to live
+// outside both.
+
+import type { SyncEngine } from "@pylonsync/sync";
+
+let _engine: SyncEngine | null = null;
+
+/** Publish the engine `init()` built. Called only from `db.ts`. */
+export function setActiveEngine(engine: SyncEngine | null): void {
+  _engine = engine;
+}
+
+/**
+ * The engine, if one exists. Never constructs one — a `null` return
+ * means "this app isn't running sync", not "not yet initialized".
+ */
+export function peekActiveEngine(): SyncEngine | null {
+  return _engine;
+}

package/src/index.ts

@@ -64,6 +64,7 @@ import {
   pylonFetchRaw,
   type Storage as PylonStorage,
 } from "@pylonsync/sync";
+import { peekActiveEngine } from "./engine-registry";
 
 // React hooks — high-level ergonomic shape
 export {
@@ -485,6 +486,25 @@ export async function callFn<T = unknown>(
   args: Record<string, unknown> = {},
   options: { token?: string } = {}
 ): Promise<T> {
+  // Route through the engine when the app has one. `SyncEngine.fn`
+  // observes the `X-Pylon-Change-Seq` response header and fires a
+  // one-shot pull when the call produced events the replica hasn't
+  // seen — without it the caller's own write doesn't appear until
+  // something else refreshes, which reads as "I added it and nothing
+  // happened". `db.fn` and `useMutation` have always done this; the
+  // free helper silently didn't, so the same operation behaved
+  // differently depending on which import you reached for.
+  //
+  // Two cases deliberately keep the bare fetch:
+  //   - no engine: apps that never call `init()` must not have one
+  //     constructed (and a WebSocket opened) by a plain POST.
+  //   - an explicit `options.token`: that's a call as some other
+  //     identity, and pulling its results into this replica would mix
+  //     two users' data.
+  const engine = options.token ? null : peekActiveEngine();
+  if (engine) {
+    return engine.fn<T>(name, args);
+  }
   return pylonFetch<T>(
     {
       baseUrl: getBaseUrl(),