ruact 0.0.3 → 0.0.5

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

@@ -16,6 +16,13 @@
 // 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.
+import { useState, useEffect } from "react";
+
 const RUNTIME_VERSION = 1;
 
 // Re-run-5 (2026-05-15) — module-level runtime configuration. Hosts
@@ -149,6 +156,182 @@ export function _makeServerFunction(descriptor) {
   };
 }
 
+/**
+ * Story 9.5 — the read-side (query) accessor. The codegen emits
+ * `_makeQuery({ path, kind: "query" })` for every method on a mounted
+ * `Ruact::Query` subclass. The returned callable issues a **GET** to the
+ * 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` /
+ * `RuactActionError` / `redirect: "error"` with the mutation path so the
+ * success + failure shapes are identical.
+ *
+ * Usually consumed through {useQuery}, but the returned function is a plain
+ * `(params?) => Promise<unknown>` so it also works in imperative code.
+ *
+ * FR88 wire format: only primitives (string / number / boolean / null) are
+ * encoded into the query string; arrays and objects throw a `TypeError`
+ * client-side too — though the server-side sanitization is authoritative.
+ *
+ * @param {{ path: string, kind?: string }} descriptor
+ * @returns {(params?: Record<string, unknown>) => Promise<unknown>}
+ */
+export function _makeQuery(descriptor) {
+  const { path } = descriptor || {};
+  return function ruactQueryCall(params) {
+    const url = buildQueryUrl(path, params);
+    return ruactQueryGet(url, path);
+  };
+}
+
+// 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
+ * issues `GET /q/<jsId>` on mount (and whenever the serialized params change)
+ * and returns `{ data, loading, error }`:
+ *
+ *   - `loading` is true until the first resolution;
+ *   - `data` carries the JSON-decoded response on success (and the last
+ *     successful value while a subsequent refetch is in flight);
+ *   - `error` carries the structured `RuactActionError` (or a transport
+ *     `Error`) on failure, and is reset to `null` on a successful refetch.
+ *
+ * A superseded in-flight response (params changed, or the component
+ * unmounted) is dropped — the hook never sets state for a stale request.
+ *
+ * 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]
+ * @returns {{ data: unknown, loading: boolean, error: unknown }}
+ */
+export function useQuery(reference, params) {
+  const [state, setState] = useState({ data: undefined, loading: true, error: null });
+
+  // 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. 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 }));
+    dedupedQuery(reference, params)
+      .then((data) => {
+        if (active) setState({ data, loading: false, error: null });
+      })
+      .catch((error) => {
+        if (active) setState((prev) => ({ data: prev.data, loading: false, error }));
+      });
+    return () => {
+      active = false;
+    };
+    // `params` is intentionally tracked via the serialized `paramsKey`.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [reference, paramsKey]);
+
+  return state;
+}
+
 // 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
@@ -218,6 +401,17 @@ export const __internals = {
   pickWirePayload,
   interpolatePath,
   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
@@ -265,6 +459,88 @@ async function ruactInvoke({ method, url, args, label }) {
   return parseResponse(response);
 }
 
+// Story 9.5 — the GET fetch core for queries. Mirrors `ruactInvoke`'s
+// structure (loud transport error, structured `RuactActionError` on !ok,
+// shared `parseResponse`) but for a read: GET, no body, no CSRF.
+async function ruactQueryGet(url, label) {
+  let response;
+  try {
+    response = await fetch(url, buildQueryFetchInit());
+  } catch (err) {
+    throw new Error(
+      `ruact query ${label} request failed: ${err?.message ?? err}`,
+    );
+  }
+  if (!response.ok) {
+    const body = await safeParseBody(response);
+    throw new RuactActionError({ name: label, status: response.status, body, response });
+  }
+  return parseResponse(response);
+}
+
+// Story 9.5 — serialize the params object into the GET query string. FR88
+// wire format: only primitives (string / number / boolean / null) are
+// encoded. Arrays and objects throw a `TypeError` client-side for immediate
+// local feedback; the server-side sanitization in `query_dispatch.rb` is the
+// authoritative gate. `null` is encoded as an empty value (`key=`).
+function buildQueryUrl(path, params) {
+  if (params == null) return path;
+  if (typeof params !== "object" || Array.isArray(params)) {
+    throw new TypeError(
+      `ruact useQuery for ${path}: params must be a plain object of ` +
+        "string / number / boolean / null values",
+    );
+  }
+  const search = new URLSearchParams();
+  // `null` is sent as a BARE key (`?q`, no `=`) — Rack parses that as `nil`,
+  // whereas `?q=` parses as `""`. This keeps `null` distinguishable from the
+  // empty string at the Ruby query-method boundary (the server allowlist
+  // accepts both `nil` and `String`). Bare keys are collected separately
+  // because `URLSearchParams` always emits `key=`; their order relative to
+  // the `=`-valued params is irrelevant server-side.
+  const bareKeys = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined) continue;
+    if (value === null) {
+      bareKeys.push(encodeURIComponent(key));
+    } else if (
+      typeof value === "string" ||
+      typeof value === "number" ||
+      typeof value === "boolean"
+    ) {
+      search.append(key, String(value));
+    } else {
+      throw new TypeError(
+        `ruact useQuery for ${path}: param "${key}" must be a string, number, ` +
+          "boolean, or null — arrays and objects are rejected",
+      );
+    }
+  }
+  const qs = [search.toString(), ...bareKeys].filter((s) => s.length > 0).join("&");
+  return qs.length === 0 ? path : `${path}?${qs}`;
+}
+
+// Story 9.5 — fetch init for a query GET. No body, no `X-CSRF-Token` (reads
+// are CSRF-free). `defaultHeaders` still apply (e.g. an API-mode
+// `Authorization: Bearer …`), with the gem's own `Accept` winning. Keeps
+// `redirect: "error"` so an auth `redirect_to "/login"` surfaces as a loud
+// failure rather than resolving with the login page HTML.
+function buildQueryFetchInit() {
+  const RESERVED = new Set(["accept"]);
+  const extra =
+    typeof runtimeOptions.defaultHeaders === "function"
+      ? runtimeOptions.defaultHeaders()
+      : runtimeOptions.defaultHeaders;
+  const headers = {};
+  if (extra && typeof extra === "object") {
+    for (const [key, value] of Object.entries(extra)) {
+      if (!RESERVED.has(key.toLowerCase())) headers[key] = value;
+    }
+  }
+  headers.Accept = "application/json";
+  return { method: "GET", credentials: "same-origin", redirect: "error", headers };
+}
+
 // Story 9.3 (D7) — substitute dynamic path segments (`:id`, …) from the single
 // call argument. Values are read BY NAME (FormData.get / object property); the
 // argument is still sent as the body. A missing required segment fails loudly

data/vendor/javascript/ruact-server-functions-runtime/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ruact-server-functions-runtime",
-  "version": "0.2.0",
-  "description": "Server-functions runtime for ruact gem (Stories 8.1 + 8.2). Provides `_makeRef(name)` (POSTs to `/__ruact/fn/:name` with CSRF + JSON / FormData support, including the useActionState two-arg shape) and `revalidate(path?)` (Flight refetch via the installed ruact-router).",
+  "version": "0.4.0",
+  "description": "Server-functions runtime for ruact gem (Stories 8.1 + 8.2 + 9.5 + 9.6). Provides `_makeRef(name)` / `_makeServerFunction(descriptor)` (mutations: POST/PUT/PATCH/DELETE with CSRF + JSON / FormData), `revalidate(path?)` (Flight refetch), and `_makeQuery(descriptor)` + `useQuery(ref, params?)` (reads: GET /q/<jsId>, CSRF-free, FR88 primitive params → { data, loading, error }; identical concurrent calls share one in-flight request).",
   "type": "module",
   "main": "index.js",
   "types": "./index.d.ts",
@@ -16,7 +16,14 @@
   "scripts": {
     "test": "vitest run"
   },
+  "peerDependencies": {
+    "react": ">=18"
+  },
   "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "jsdom": "^25.0.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "vitest": "^2.1.9"
   }
 }