ruact 0.0.4 → 0.0.6

data/vendor/javascript/ruact-server-functions-runtime/index.js

@@ -1,26 +1,27 @@
-// Story 8.1 — real server-functions runtime.
+// Server-functions runtime (route-driven, v2).
 //
-// Replaces the Story 8.0a placeholder. Each export of the generated module
-// `app/javascript/.ruact/server-functions.ts` calls `_makeRef("<symbol>")`
-// and gets back a function that, when invoked, POSTs to
-// `/__ruact/fn/<symbol>` with the args serialized as JSON or FormData.
+// Each export of the generated module `app/javascript/.ruact/server-functions.ts`
+// is built by `_makeServerFunction({ method, path, segments })` (mutations) or
+// `_makeQuery({ path, kind: "query" })` (reads), targeting the REAL Rails route
+// + verb. Story 9.9 demolished the v1 `_makeRef` accessor + the synthetic
+// endpoint it POSTed to.
 //
-// Wire contract (locked by Story 8.0 ADR Decision-log clarification of
-// 2026-05-13, items 2–3): POST for everything (actions AND queries),
-// request body carries the args, response is JSON. CSRF symmetric — the
-// runtime forwards the `<meta name="csrf-token">` value as `X-CSRF-Token`
-// if the meta tag is present in the document (the gem does not impose its
-// own CSRF; the host's `protect_from_forgery` is what enforces).
+// Wire contract: mutations send the args as JSON or FormData over the route's
+// real verb; reads issue a GET with params serialized into the query string;
+// responses are JSON. CSRF (mutations only) — the runtime forwards the
+// `<meta name="csrf-token">` value as `X-CSRF-Token` if the meta tag is present
+// (the gem does not impose its own CSRF; the host's `protect_from_forgery`
+// enforces). Reads are CSRF-free (GET semantics).
 //
-// The `_makeRef` export surface and the `"ruact/server-functions-runtime"`
-// import path are part of the locked API — do NOT change without coordinated
-// codegen + Vite-plugin updates.
+// The export surface (`_makeServerFunction`, `_makeQuery`, `useQuery`,
+// `revalidate`, `configureRuactRuntime`, `RuactActionError`) and the
+// `"ruact/server-functions-runtime"` import path are part of the locked API —
+// do NOT change without coordinated codegen + Vite-plugin updates.
 
 // Story 9.5 — `useQuery` is a React hook, so the runtime now depends on React.
 // React is declared as a `peerDependency` (every host already has it; the
-// runtime never bundles its own copy). This is the runtime's first React
-// import — the mutation path (`_makeRef` / `_makeServerFunction`) stays
-// React-free.
+// runtime never bundles its own copy). The mutation path
+// (`_makeServerFunction`) stays React-free.
 import { useState, useEffect } from "react";
 
 const RUNTIME_VERSION = 1;
@@ -28,8 +29,8 @@ const RUNTIME_VERSION = 1;
 // Re-run-5 (2026-05-15) — module-level runtime configuration. Hosts
 // in API mode (no session cookie / no CSRF meta tag) need a way to
 // inject auth headers (`Authorization: Bearer …`) on every call.
-// `_makeRef`'s signature is locked by the codegen so we don't widen
-// it; instead, hosts call `configureRuactRuntime` once at app boot
+// the accessor signatures are locked by the codegen so we don't widen
+// them; instead, hosts call `configureRuactRuntime` once at app boot
 // to register a headers-producing function. The function runs on
 // every fetch so dynamic tokens (refreshed at runtime) are picked up.
 const runtimeOptions = {
@@ -73,59 +74,22 @@ export class RuactActionError extends Error {
 }
 
 /**
- * Returns a callable accessor for a server function registered with the
- * given Ruby symbol name. The accessor, when invoked, POSTs the args to
- * `/__ruact/fn/${name}` and resolves with the response (JSON-decoded for
- * application/json responses, text for everything else).
- *
- * Story 8.2 — the returned function accepts up to TWO positional
- * arguments to support React 19's `useActionState` shape:
- *
- *   useActionState(action, initialState)
+ * Story 9.3 — the route-driven (v2) accessor. The codegen emits
+ * `_makeServerFunction({ method, path, segments })` for every non-GET routed
+ * action on a `Ruact::Server` controller. The returned callable targets the
+ * REAL Rails route + verb (e.g. `POST /posts`, `PUT /posts/:id`).
  *
- * calls `action(prevState, formData)` on every submit. `_makeRef` picks
- * the FormData-typed candidate from the call and discards the prevState
- * argument silently — prev-state is a client-only concern, never
+ * Story 8.2 — the returned function accepts up to TWO positional arguments to
+ * support React 19's `useActionState` shape: `useActionState(action,
+ * initialState)` calls `action(prevState, formData)` on every submit. The
+ * accessor picks the FormData-typed candidate from the call and discards the
+ * prevState argument silently — prev-state is a client-only concern, never
  * transmitted to the server. The single-arg shape (`fn(args)` from event
  * handlers; `<form action={fn}>` passing FormData directly) is preserved.
  *
- * Argument shape selection rules (first match wins):
- *   - 0 args                                     → JSON body, `{}`
- *   - 1 arg, FormData                            → multipart
- *   - 1 arg, plain object / null / undefined     → JSON body
- *   - 2 args, FormData in either slot            → multipart (FormData wins;
- *                                                  the other arg is discarded)
- *   - 2 args, neither FormData                   → JSON body of the SECOND arg
- *                                                  (the `useActionState` payload
- *                                                  slot); first arg discarded
- *                                                  as prev-state
- *   - 3+ args                                    → TypeError
- *
- * @param {string} name
- * @returns {(arg1?: Record<string, unknown> | FormData, arg2?: FormData | Record<string, unknown>) => Promise<unknown>}
- */
-export function _makeRef(name) {
-  return function ruactServerFunctionCall(...callArgs) {
-    if (callArgs.length > 2) {
-      throw new TypeError(
-        `ruact action :${name} called with ${callArgs.length} arguments — ` +
-          "expected 0, 1, or 2 (the useActionState shape)",
-      );
-    }
-    return ruactPost(name, pickWirePayload(callArgs));
-  };
-}
-
-/**
- * Story 9.3 — the route-driven (v2) accessor. The codegen emits
- * `_makeServerFunction({ method, path, segments })` for every non-GET routed
- * action on a `Ruact::Server` controller (instead of v1's `_makeRef("<sym>")`).
- * The returned callable targets the REAL Rails route + verb (e.g. `POST /posts`,
- * `PUT /posts/:id`) rather than the v1 synthetic `POST /__ruact/fn/:name`.
- *
- * It shares the exact fetch core (`ruactInvoke`) with `_makeRef` — FormData
- * branching, CSRF meta injection, text-first parsing, `RuactActionError`,
- * `redirect: "error"` — so all the salvaged 8.1/8.2 behaviors are preserved.
+ * It uses the shared fetch core (`ruactInvoke`) — FormData branching, CSRF
+ * meta injection, text-first parsing, `RuactActionError`, `redirect: "error"`
+ * — so all the salvaged 8.1/8.2 behaviors are preserved.
  * Two additions over v1:
  *   - **Path-param interpolation (D7):** dynamic `:id`-style segments are read
  *     BY NAME from the single call argument (FormData.get / object property) and
@@ -163,9 +127,9 @@ export function _makeServerFunction(descriptor) {
  * named query route (`GET /q/<jsId>`), serializing `params` into the query
  * string.
  *
- * Reads are CSRF-free (NFR27 / the 2026-06-02 ADR addendum voids the old
- * `POST /__ruact/fn/:id` query mechanism and restores HTTP GET semantics):
- * no request body, no `X-CSRF-Token`. It shares `parseResponse` /
+ * Reads are CSRF-free (NFR27 / the 2026-06-02 ADR addendum restored HTTP GET
+ * semantics for queries): no request body, no `X-CSRF-Token`. It shares
+ * `parseResponse` /
  * `RuactActionError` / `redirect: "error"` with the mutation path so the
  * success + failure shapes are identical.
  *
@@ -187,6 +151,96 @@ export function _makeQuery(descriptor) {
   };
 }
 
+// Story 9.6 — in-flight request de-duplication for `useQuery`. Identical
+// concurrent calls (same query reference + same params) share ONE network
+// request instead of each firing its own GET. The registry maps a query
+// reference (the codegen-emitted `_makeQuery` accessor — stable module identity,
+// so the same import is the same key) to a `Map` of canonical-params-key →
+// in-flight Promise. Each promise is removed the instant it settles, so dedup is
+// strictly IN-FLIGHT-ONLY: no TTL, no stale-while-revalidate (Story 9.7 documents
+// that scope). A mount AFTER the previous request settled always refetches.
+//
+// Keyed by the reference FUNCTION via a WeakMap so dynamically-created references
+// can be GC'd; the inner `Map` self-empties as requests settle. `let` (not
+// `const`) so the test-only `__resetQueryDedup` can swap a fresh registry in
+// between cases — `dedupedQuery` closes over the binding, so the swap is seen.
+let inflightQueries = new WeakMap();
+
+// Order-independent dedup key, used BOTH as the registry key and as the
+// `useEffect` dependency. It mirrors the WIRE output of `buildQueryUrl` exactly
+// (the per-param tokens, sorted so order doesn't matter), so two param objects
+// share a request IFF they produce the SAME query string — the true "same
+// network request" equivalence. Building from the wire (not `JSON.stringify`)
+// is deliberate: `JSON.stringify` maps `NaN`/`Infinity`/`-Infinity` to `null`,
+// which would collide those distinct wire values (`?q=NaN` vs bare `?q`) onto
+// one key. Mirrors `buildQueryUrl`'s rules: `undefined` skipped, `null` → bare
+// key, string/number/boolean → `key=String(value)`.
+//
+// Returns `null` to signal a NON-SHAREABLE shape (a non-object/array top level,
+// or an array/object VALUE) — exactly the inputs `buildQueryUrl` rejects with a
+// `TypeError`. `dedupedQuery` bypasses the registry for those so the reference
+// is still invoked and the error surfaces (Story 9.5 behavior), instead of an
+// invalid call wrongly joining an in-flight no-param request. `null`/no params
+// both serialize to "".
+function canonicalParamsKey(params) {
+  if (params == null) return "";
+  if (typeof params !== "object" || Array.isArray(params)) return null;
+  const tokens = [];
+  for (const key of Object.keys(params)) {
+    const value = params[key];
+    if (value === undefined) continue;
+    if (value === null) {
+      tokens.push(encodeURIComponent(key)); // bare key — mirrors buildQueryUrl
+    } else if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      tokens.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+    } else {
+      return null; // array/object value — buildQueryUrl throws; non-shareable
+    }
+  }
+  tokens.sort();
+  return tokens.join("&");
+}
+
+// Share the in-flight request for (reference, canonical params). The first
+// caller creates the promise and registers it; concurrent callers with the same
+// key get the SAME promise back — one fetch, shared resolution, shared error.
+// The settle handler removes the entry, guarded by promise identity so a newer
+// in-flight request for the same key (started after this one settled but before
+// its handler ran) is never clobbered. A rejected promise is removed the same
+// way, so a failed shared request does not poison the key — the next mount
+// retries fresh.
+function dedupedQuery(reference, params) {
+  const key = canonicalParamsKey(params);
+  // A `null` key marks a non-shareable shape (the inputs `buildQueryUrl`
+  // rejects). Bypass the registry entirely so the reference is invoked and its
+  // `TypeError` surfaces on the error path — never share onto another request.
+  if (key === null) {
+    return Promise.resolve().then(() => reference(params));
+  }
+  let perRef = inflightQueries.get(reference);
+  if (perRef) {
+    const existing = perRef.get(key);
+    if (existing) return existing;
+  } else {
+    perRef = new Map();
+    inflightQueries.set(reference, perRef);
+  }
+  // Wrap in Promise.resolve so a SYNCHRONOUS throw inside `reference` (e.g. a
+  // non-primitive param rejected by `buildQueryUrl`) becomes a rejected promise
+  // on the error path, preserving the Story 9.5 "sync throw surfaces as error"
+  // behavior.
+  const promise = Promise.resolve().then(() => reference(params));
+  perRef.set(key, promise);
+  const forget = () => {
+    if (perRef.get(key) === promise) perRef.delete(key);
+  };
+  // `.then(forget, forget)` (not `.finally`) so the cleanup branch swallows a
+  // rejection rather than spawning a derived promise that could surface as an
+  // unhandled rejection. The original `promise` is what callers handle.
+  promise.then(forget, forget);
+  return promise;
+}
+
 /**
  * Story 9.5 — React hook for reading a server query. Pass a query reference
  * (the codegen-emitted `_makeQuery` accessor) and optional params; the hook
@@ -202,8 +256,10 @@ export function _makeQuery(descriptor) {
  * A superseded in-flight response (params changed, or the component
  * unmounted) is dropped — the hook never sets state for a stale request.
  *
- * Request de-duplication across components is Story 9.6; this hook fetches
- * once per mount.
+ * Story 9.6 — identical CONCURRENT calls (same reference + same params,
+ * order-independent) share ONE in-flight request. Dedup is in-flight only:
+ * once the request settles the shared entry is dropped, so a fresh mount
+ * refetches — there is no TTL cache and no stale-while-revalidate.
  *
  * @param {(params?: Record<string, unknown>) => Promise<unknown>} reference
  * @param {Record<string, unknown>} [params]
@@ -214,17 +270,16 @@ export function useQuery(reference, params) {
 
   // Re-run the effect by VALUE, not identity: an inline `{ q: input }` literal
   // is a fresh object every render, which would refetch on every render if used
-  // directly as a dependency. Serializing collapses equal params to one key.
-  const paramsKey = params == null ? "" : JSON.stringify(params);
+  // directly as a dependency. The canonical (sorted-key) serialization collapses
+  // equal params — including reordered keys — to one string, and is the SAME key
+  // the dedup registry uses, so the effect dependency and the shared-request
+  // identity stay in lockstep.
+  const paramsKey = canonicalParamsKey(params);
 
   useEffect(() => {
     let active = true;
     setState((prev) => ({ data: prev.data, loading: true, error: null }));
-    // Wrap in Promise.resolve so a synchronous throw inside `reference`
-    // (e.g. a non-primitive param rejected by `buildQueryUrl`) lands on the
-    // error branch instead of escaping the effect.
-    Promise.resolve()
-      .then(() => reference(params))
+    dedupedQuery(reference, params)
       .then((data) => {
         if (active) setState({ data, loading: false, error: null });
       })
@@ -242,8 +297,8 @@ export function useQuery(reference, params) {
 }
 
 // Story 8.2 — picks the argument the wire request should serialize from
-// `_makeRef`'s call-args, following the rules documented in the JSDoc
-// above. Exported through `__internals` for the vitest suite (AC10) — it
+// `_makeServerFunction`'s call-args, following the useActionState rules
+// documented above. Exported through `__internals` for the vitest suite (AC10) — it
 // is intentionally NOT part of the public runtime surface.
 function pickWirePayload(callArgs) {
   const isFD = (v) => typeof FormData !== "undefined" && v instanceof FormData;
@@ -312,31 +367,21 @@ export const __internals = {
   followRedirectIfPresent,
   buildQueryUrl,
   buildQueryFetchInit,
+  // Story 9.6 — exposed for the dedup vitest suite. `canonicalParamsKey` is the
+  // order-independent dedup/effect key; `__resetQueryDedup` swaps a fresh
+  // in-flight registry so a test asserting mid-flight state starts from a clean
+  // slate (the registry self-empties on settle, so this only matters for tests
+  // that deliberately leave a request pending).
+  canonicalParamsKey,
+  __resetQueryDedup: () => {
+    inflightQueries = new WeakMap();
+  },
 };
 
-// v1 (Story 8.1) — POST to the synthetic endpoint. A thin wrapper over the
-// shared `ruactInvoke` core; the URL, verb, and error label are exactly what
-// 8.1 used so the v1 path stays byte-behavior-identical (Story 9.3 AC6).
-//
-// Re-run-3 (2026-05-15) — `encodeURIComponent(name)` so a stray `/`, `?`, or
-// `#` in a name (only reachable through direct/buggy `_makeRef` calls — the
-// gem-side route constraint and the codegen validator both refuse
-// non-identifier characters) cannot rewrite the path or hijack the
-// query/fragment of the request URL.
-function ruactPost(name, args) {
-  return ruactInvoke({
-    method: "POST",
-    url: `/__ruact/fn/${encodeURIComponent(name)}`,
-    args,
-    label: name,
-  });
-}
-
-// Story 9.3 — the shared fetch core for BOTH v1 (`_makeRef`) and v2
-// (`_makeServerFunction`). Extracted verbatim from the original `ruactPost` so
-// neither path drifts: same FormData branching, CSRF injection, `redirect:
-// "error"`, text-first parsing, and structured `RuactActionError`. The only
-// parameters are the verb + URL + the wire payload + a human label for errors.
+// Story 9.3 — the shared fetch core for the route-driven (`_makeServerFunction`)
+// mutation path: FormData branching, CSRF injection, `redirect: "error"`,
+// text-first parsing, and structured `RuactActionError`. The only parameters
+// are the verb + URL + the wire payload + a human label for errors.
 async function ruactInvoke({ method, url, args, label }) {
   const init = buildFetchInit(args, method);
   let response;
@@ -472,8 +517,7 @@ function readSegment(args, seg) {
 // Story 9.3 (AC8 / D2) — the client half of the `$redirect` contract 9.2
 // deferred. A Bucket-2 mutation that `redirect_to`s returns
 // `{ "$redirect": "<path>" }`; follow it via the router handoff and resolve
-// `null` (consistent with the 204→null contract). Only applied on the v2 path
-// — the v1 endpoint never emits `$redirect`, so `_makeRef` is unaffected (AC6).
+// `null` (consistent with the 204→null contract).
 function followRedirectIfPresent(parsed) {
   if (
     parsed &&