@pylonsync/functions 0.3.237 → 0.3.238

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.237",
+  "version": "0.3.238",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/runtime.ts

@@ -329,7 +329,11 @@ function rpc(callId: string, msg: Record<string, unknown>): Promise<unknown> {
 // Context builders
 // ---------------------------------------------------------------------------
 
-function buildDbReader(callId: string, unsafeOp = false): DbReader {
+// Exported so the SSR runtime (ssr-runtime.ts) can build a page-facing
+// `serverData` read handle that reuses this module's `send` + `pendingRpcs`
+// + reader loop. The render call_id ("r_<n>") correlates DB replies back
+// through the shared pendingRpcs map.
+export function buildDbReader(callId: string, unsafeOp = false): DbReader {
   // All DB ops use rpcDb so Promise.all over ctx.db reads can run in
   // parallel without colliding on the outer call_id key.
   //

package/src/ssr-client-bundler.ts

@@ -192,6 +192,92 @@ function buildTree(Page, Layouts, props) {
   return tree;
 }
 
+// Deterministic stringify — MUST match stableStringify in ssr-runtime.ts so
+// a serverData call's cache key is identical on server and client.
+function stableStringify(v) {
+  if (v === null || v === undefined || typeof v !== "object") {
+    return JSON.stringify(v === undefined ? null : v);
+  }
+  if (Array.isArray(v)) return "[" + v.map(stableStringify).join(",") + "]";
+  const keys = Object.keys(v).sort();
+  return (
+    "{" +
+    keys.map((k) => JSON.stringify(k) + ":" + stableStringify(v[k])).join(",") +
+    "}"
+  );
+}
+
+const SERVER_DATA_METHODS = [
+  "get",
+  "list",
+  "lookup",
+  "query",
+  "queryGraph",
+  "paginate",
+  "search",
+];
+
+// A React-recognized fulfilled thenable: use() reads .value synchronously
+// (status === "fulfilled") instead of suspending. Critical for hydration —
+// the server streamed the post-Suspense content, so the client must render
+// that content on the FIRST pass without re-suspending (no fallback flash,
+// no mismatch).
+function fulfilledThenable(value) {
+  return {
+    status: "fulfilled",
+    value,
+    then(onFulfilled) {
+      return onFulfilled ? onFulfilled(value) : value;
+    },
+  };
+}
+
+// Client stand-in for the server's serverData handle. Each method returns a
+// pre-fulfilled thenable (cached per key) sourced from the SSR'd ssrData map,
+// keyed identically to the server. Misses yield undefined — the page
+// rendered with whatever the server fetched, so a hit is expected.
+function makeClientServerData(ssrData) {
+  const cache = ssrData || {};
+  const pc = new Map();
+  const wrap = (prefix) => {
+    const out = {};
+    for (const m of SERVER_DATA_METHODS) {
+      out[m] = (...args) => {
+        const key = prefix + m + ":" + stableStringify(args);
+        if (!pc.has(key)) pc.set(key, fulfilledThenable(cache[key]));
+        return pc.get(key);
+      };
+    }
+    return out;
+  };
+  const sd = wrap("");
+  sd.unsafe = wrap("u:");
+  return sd;
+}
+
+// Server-only response controller has no meaning on the client (the status/
+// redirect/cookies already shipped). Give pages a no-op so a body that
+// touches props.response during hydration doesn't crash.
+function makeNoopResponse() {
+  const noop = () => {};
+  return {
+    setStatus: noop,
+    setHeader: noop,
+    setCookie: noop,
+    redirect: noop,
+    notFound: noop,
+  };
+}
+
+// Rehydrate the live, server-only props (serverData + response) that were
+// stripped before serialization, so the client tree matches the server's.
+function withClientProps(data) {
+  const props = { ...(data.props || {}) };
+  props.serverData = makeClientServerData(data.ssrData);
+  props.response = makeNoopResponse();
+  return props;
+}
+
 function readPylonData() {
   const dataEl = document.getElementById("__PYLON_DATA__");
   if (!dataEl) return null;
@@ -286,7 +372,7 @@ export function hydrate(component, Page, Layouts) {
       );
       return;
     }
-    const tree = buildTree(Page, Layouts, data.props);
+    const tree = buildTree(Page, Layouts, withClientProps(data));
     activeRoot = hydrateRoot(document, tree);
     installNavHandlers();
     return;
@@ -340,7 +426,7 @@ async function navigate(href, opts) {
     return;
   }
   document.title = doc.title || document.title;
-  const tree = buildTree(route.Page, route.Layouts, data.props);
+  const tree = buildTree(route.Page, route.Layouts, withClientProps(data));
   activeRoot.render(tree);
   if (push) {
     history.pushState({ component: data.component }, "", url.pathname + url.search);

package/src/ssr-runtime.ts

@@ -560,6 +560,72 @@ async function tryRenderBoundary(
   }
 }
 
+/**
+ * Deterministic stringify (keys sorted recursively) so a `serverData` call's
+ * cache key is identical on the server (here) and on the client (the
+ * hydration shim in ssr-client-bundler's client-runtime). MUST stay in sync
+ * with `stableStringify` in that template.
+ */
+function stableStringify(v: any): string {
+  if (v === null || v === undefined || typeof v !== "object") {
+    return JSON.stringify(v ?? null);
+  }
+  if (Array.isArray(v)) return "[" + v.map(stableStringify).join(",") + "]";
+  const keys = Object.keys(v).sort();
+  return (
+    "{" +
+    keys.map((k) => JSON.stringify(k) + ":" + stableStringify(v[k])).join(",") +
+    "}"
+  );
+}
+
+// The read methods a page reaches through `serverData`. Mirrors the
+// DbReader read surface (writes are blocked server-side). Kept in sync with
+// the client-runtime shim's method list.
+const SERVER_DATA_METHODS = [
+  "get",
+  "list",
+  "lookup",
+  "query",
+  "queryGraph",
+  "paginate",
+  "search",
+] as const;
+
+/**
+ * Wrap a DbReader so each `serverData.x(...)` call returns a PROMISE CACHED
+ * by (method, args) — required for React 19 `use()`, which re-invokes the
+ * call on the post-suspense re-render and must get the same (now-resolved)
+ * promise instead of a fresh pending one (else it suspends forever). Each
+ * resolved value is also recorded into `valueCache` keyed identically, so it
+ * can be serialized into `__PYLON_DATA__.ssrData` and replayed on the client
+ * — keeping hydration free of mismatches.
+ */
+function makeServerData(reader: any, valueCache: Record<string, any>): any {
+  const promiseCache = new Map<string, Promise<any>>();
+  const wrap = (r: any, prefix: string): any => {
+    const out: any = {};
+    for (const m of SERVER_DATA_METHODS) {
+      out[m] = (...args: any[]) => {
+        const key = prefix + m + ":" + stableStringify(args);
+        let p = promiseCache.get(key);
+        if (!p) {
+          p = Promise.resolve(r[m](...args)).then((value: any) => {
+            valueCache[key] = value;
+            return value;
+          });
+          promiseCache.set(key, p);
+        }
+        return p;
+      };
+    }
+    return out;
+  };
+  const sd = wrap(reader, "");
+  if (reader.unsafe) sd.unsafe = wrap(reader.unsafe, "u:");
+  return sd;
+}
+
 export async function handleRenderRoute(
   msg: RenderRouteMessage,
   send: Send,
@@ -578,6 +644,11 @@ export async function handleRenderRoute(
   let React: any = null;
   let renderToReadableStream: any = null;
   let props: any = null;
+  // Accumulates the resolved results of every `serverData.*` read the page
+  // made during render, keyed identically to the client shim. Serialized
+  // into `__PYLON_DATA__.ssrData` so hydration replays the same values
+  // without a second round trip — and without a server/client mismatch.
+  const ssrValueCache: Record<string, any> = {};
   try {
     // react + react-dom are USER deps. ssr-runtime.ts lives in
     // packages/functions/src/, but the user's react install is under
@@ -636,6 +707,19 @@ export async function handleRenderRoute(
       );
     }
 
+    // `serverData` — a read-only DB handle the page reaches during render
+    // via React 19 `use()` + <Suspense>. Reuses runtime.ts's RPC pipe
+    // (shared `send` + pendingRpcs) keyed by this render's call_id; the
+    // Rust render loop answers the frames against the same store + policy
+    // gate as a query function's ctx.db, and rejects any write. Promise-
+    // cached so `use()` doesn't re-suspend forever; resolved values land in
+    // `ssrValueCache` for hydration replay.
+    const { buildDbReader } = await import("./runtime");
+    const serverData = makeServerData(
+      buildDbReader(msg.call_id),
+      ssrValueCache,
+    );
+
     props = {
       url: msg.url,
       params: msg.params,
@@ -646,6 +730,8 @@ export async function handleRenderRoute(
       // Response controller — a page/layout calls response.setStatus /
       // setHeader / setCookie / redirect / notFound to shape the reply.
       response,
+      // Read-only server data handle (see above).
+      serverData,
     };
 
     // SEO metadata: static `export const metadata` or dynamic
@@ -689,6 +775,19 @@ export async function handleRenderRoute(
       },
     );
 
+    // Wait for ALL Suspense boundaries to resolve before emitting the body,
+    // so the HTML is fully formed — no `<!--$?-->` pending markers, no
+    // hidden fallback segments, no `$RC` reveal scripts. This is what makes
+    // `serverData` + `use()` + <Suspense> hydrate cleanly: the client
+    // hydrates a RESOLVED boundary against the SSR'd content (resolved from
+    // `ssrData`), instead of fighting React's streaming-reveal scripts +
+    // whole-document hydration (which leaves the boundary stuck on its
+    // fallback). Pages with no async data have no boundaries, so `allReady`
+    // resolves immediately — zero cost for the common case.
+    if ((stream as any).allReady) {
+      await (stream as any).allReady;
+    }
+
     // Headers go out before the first chunk so the host can write the
     // response head.
     // The shell rendered without a redirect()/notFound() throw, so the
@@ -783,10 +882,16 @@ export async function handleRenderRoute(
     // to a no-hydration warning if the manifest can't be loaded
     // (rare — usually means the bundler crashed).
     if (!isBoundaryComponent) {
+      // Strip live, non-serializable handles from the props that seed
+      // hydration: `serverData` (an RPC handle — the client rebuilds its
+      // own from `ssrData`) and `response` (a server-only controller — the
+      // client gets a no-op). Their resolved data rides along in `ssrData`.
+      const { serverData: _sd, response: _resp, ...serializableProps } = props;
       const hydrationPayload = {
         component: msg.component,
         layouts: msg.layouts ?? [],
-        props,
+        props: serializableProps,
+        ssrData: ssrValueCache,
       };
       const json = JSON.stringify(hydrationPayload).replaceAll("<", "\\u003c");