ruact 0.0.3 → 0.0.5

data/vendor/javascript/ruact-server-functions-runtime/usequery.test.mjs

@@ -0,0 +1,368 @@
+// @vitest-environment jsdom
+//
+// Story 9.5 — vitest coverage for the read-side runtime: the `useQuery` React
+// hook (loading/data/error transitions, param passing, value-stable refetch)
+// and the `_makeQuery` GET wire format (query-string encoding, FR88 primitive
+// allowlist, CSRF-free init). Runs under jsdom so `@testing-library/react`'s
+// `renderHook` can drive the hook through React's effect lifecycle.
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+
+import { useQuery, _makeQuery, RuactActionError, __internals } from "./index.js";
+
+let originalFetch;
+
+beforeEach(() => {
+  originalFetch = globalThis.fetch;
+  // Story 9.6 — start every case from a clean in-flight registry so a test that
+  // deliberately leaves a request pending cannot leak a shared promise into the
+  // next one.
+  __internals.__resetQueryDedup();
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  vi.restoreAllMocks();
+});
+
+function mockFetchOk(jsonBody, { status = 200, contentType = "application/json" } = {}) {
+  const response = {
+    ok: true,
+    status,
+    headers: { get: (n) => (n.toLowerCase() === "content-type" ? contentType : null) },
+    text: vi.fn().mockResolvedValue(typeof jsonBody === "string" ? jsonBody : JSON.stringify(jsonBody)),
+  };
+  globalThis.fetch = vi.fn().mockResolvedValue(response);
+  return response;
+}
+
+function mockFetchError(status, bodyText) {
+  const response = {
+    ok: false,
+    status,
+    headers: { get: () => "text/plain" },
+    text: vi.fn().mockResolvedValue(bodyText),
+  };
+  globalThis.fetch = vi.fn().mockResolvedValue(response);
+  return response;
+}
+
+// Story 9.6 — a fetch stub that returns a PENDING promise so two hooks can both
+// be in-flight at once (the precondition for exercising dedup). The test
+// resolves it manually AFTER both hooks have mounted.
+function deferredFetch() {
+  let settle;
+  const fetchMock = vi.fn(
+    () =>
+      new Promise((resolve) => {
+        settle = resolve;
+      }),
+  );
+  globalThis.fetch = fetchMock;
+  return {
+    fetchMock,
+    resolveOk(jsonBody, { status = 200, contentType = "application/json" } = {}) {
+      settle({
+        ok: true,
+        status,
+        headers: { get: (n) => (n.toLowerCase() === "content-type" ? contentType : null) },
+        text: () => Promise.resolve(typeof jsonBody === "string" ? jsonBody : JSON.stringify(jsonBody)),
+      });
+    },
+    resolveError(status, bodyText) {
+      settle({
+        ok: false,
+        status,
+        headers: { get: () => "text/plain" },
+        text: () => Promise.resolve(bodyText),
+      });
+    },
+  };
+}
+
+describe("Story 9.5 — useQuery hook contract", () => {
+  it("starts loading, then resolves to { data, loading: false, error: null }", async () => {
+    const ref = vi.fn().mockResolvedValue({ items: [1, 2] });
+    const { result } = renderHook(() => useQuery(ref));
+
+    expect(result.current.loading).toBe(true);
+    expect(result.current.data).toBeUndefined();
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.data).toEqual({ items: [1, 2] });
+    expect(result.current.error).toBe(null);
+  });
+
+  it("transitions loading → error on a rejected reference", async () => {
+    const err = new RuactActionError({ name: "/q/categories", status: 500, body: "boom", response: {} });
+    const ref = vi.fn().mockRejectedValue(err);
+    const { result } = renderHook(() => useQuery(ref));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.error).toBe(err);
+    expect(result.current.data).toBeUndefined();
+  });
+
+  it("passes params to the query reference", async () => {
+    const ref = vi.fn().mockResolvedValue("ok");
+    const params = { q: "ruby", limit: 5 };
+    renderHook(() => useQuery(ref, params));
+
+    await waitFor(() => expect(ref).toHaveBeenCalledTimes(1));
+    expect(ref).toHaveBeenCalledWith(params);
+  });
+
+  it("does not refetch when params are value-equal across renders", async () => {
+    const ref = vi.fn().mockResolvedValue("ok");
+    const { rerender } = renderHook(({ p }) => useQuery(ref, p), {
+      initialProps: { p: { q: "a" } },
+    });
+    await waitFor(() => expect(ref).toHaveBeenCalledTimes(1));
+
+    rerender({ p: { q: "a" } }); // fresh object literal, identical value
+    await Promise.resolve();
+    expect(ref).toHaveBeenCalledTimes(1);
+  });
+
+  it("refetches when params change by value", async () => {
+    const ref = vi.fn().mockResolvedValue("ok");
+    const { rerender } = renderHook(({ p }) => useQuery(ref, p), {
+      initialProps: { p: { q: "a" } },
+    });
+    await waitFor(() => expect(ref).toHaveBeenCalledTimes(1));
+
+    rerender({ p: { q: "b" } });
+    await waitFor(() => expect(ref).toHaveBeenCalledTimes(2));
+    expect(ref).toHaveBeenLastCalledWith({ q: "b" });
+  });
+
+  it("surfaces a synchronous throw from the reference as an error (not an unhandled rejection)", async () => {
+    const ref = () => {
+      throw new TypeError("params must be a plain object");
+    };
+    const { result } = renderHook(() => useQuery(ref, [1, 2]));
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.error).toBeInstanceOf(TypeError);
+  });
+});
+
+describe("Story 9.5 — useQuery against _makeQuery end-to-end (GET wire)", () => {
+  it("issues GET /q/<id>?<params> and resolves the JSON body through the hook", async () => {
+    mockFetchOk([{ value: 1, label: "Books" }]);
+    const categories = _makeQuery({ path: "/q/categories", kind: "query" });
+
+    const { result } = renderHook(() => useQuery(categories, { q: "bo" }));
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+    const [url, init] = globalThis.fetch.mock.calls[0];
+    expect(url).toBe("/q/categories?q=bo");
+    expect(init.method).toBe("GET");
+    expect(result.current.data).toEqual([{ value: 1, label: "Books" }]);
+  });
+
+  it("carries the structured RuactActionError into the hook's error on a 4xx", async () => {
+    mockFetchError(400, "bad");
+    const search = _makeQuery({ path: "/q/search", kind: "query" });
+
+    const { result } = renderHook(() => useQuery(search));
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.error).toBeInstanceOf(RuactActionError);
+    expect(result.current.error.status).toBe(400);
+  });
+});
+
+describe("Story 9.5 — _makeQuery / buildQueryUrl wire format (FR88)", () => {
+  const { buildQueryUrl, buildQueryFetchInit } = __internals;
+
+  it("omits the query string entirely when no params are given", () => {
+    expect(buildQueryUrl("/q/categories", undefined)).toBe("/q/categories");
+    expect(buildQueryUrl("/q/categories", null)).toBe("/q/categories");
+    expect(buildQueryUrl("/q/categories", {})).toBe("/q/categories");
+  });
+
+  it("encodes string / number / boolean primitives", () => {
+    expect(buildQueryUrl("/q/search", { q: "a b", limit: 5, active: true })).toBe(
+      "/q/search?q=a+b&limit=5&active=true",
+    );
+  });
+
+  it("encodes null as a BARE key (Rack parses `?q` as nil, distinct from `?q=` empty string)", () => {
+    expect(buildQueryUrl("/q/search", { q: null })).toBe("/q/search?q");
+    // value-bearing params keep `key=value`; a null alongside is a bare key
+    expect(buildQueryUrl("/q/search", { limit: 5, q: null })).toBe("/q/search?limit=5&q");
+  });
+
+  it("rejects an array value (FR88 — arrays are not primitives)", () => {
+    expect(() => buildQueryUrl("/q/search", { q: [1, 2] })).toThrow(/arrays and objects are rejected/);
+  });
+
+  it("rejects an object value", () => {
+    expect(() => buildQueryUrl("/q/search", { q: { deep: 1 } })).toThrow(/arrays and objects are rejected/);
+  });
+
+  it("rejects a top-level array of params", () => {
+    expect(() => buildQueryUrl("/q/search", [1, 2])).toThrow(/plain object/);
+  });
+
+  it("builds a GET init with Accept JSON, no body, no CSRF, redirect: error", () => {
+    const init = buildQueryFetchInit();
+    expect(init.method).toBe("GET");
+    expect(init.body).toBeUndefined();
+    expect(init.headers.Accept).toBe("application/json");
+    expect(init.headers["X-CSRF-Token"]).toBeUndefined();
+    expect(init.redirect).toBe("error");
+  });
+});
+
+describe("Story 9.6 — useQuery in-flight request de-duplication", () => {
+  it("shares ONE network request across concurrent callers (same ref + same params) — AC1", async () => {
+    const deferred = deferredFetch();
+    const categories = _makeQuery({ path: "/q/categories", kind: "query" });
+
+    const a = renderHook(() => useQuery(categories, { q: "bo" }));
+    const b = renderHook(() => useQuery(categories, { q: "bo" }));
+
+    // Both hooks are in-flight: the second joined the first's request.
+    await waitFor(() => expect(deferred.fetchMock).toHaveBeenCalledTimes(1));
+
+    deferred.resolveOk([{ value: 1, label: "Books" }]);
+    await waitFor(() => expect(a.result.current.loading).toBe(false));
+    await waitFor(() => expect(b.result.current.loading).toBe(false));
+
+    // Still exactly one network call, and both callers got the same data.
+    expect(deferred.fetchMock).toHaveBeenCalledTimes(1);
+    expect(a.result.current.data).toEqual([{ value: 1, label: "Books" }]);
+    expect(b.result.current.data).toEqual([{ value: 1, label: "Books" }]);
+  });
+
+  it("propagates the SAME error instance to ALL sharers of an in-flight request — AC1", async () => {
+    const deferred = deferredFetch();
+    const search = _makeQuery({ path: "/q/search", kind: "query" });
+
+    const a = renderHook(() => useQuery(search, { q: "x" }));
+    const b = renderHook(() => useQuery(search, { q: "x" }));
+    await waitFor(() => expect(deferred.fetchMock).toHaveBeenCalledTimes(1));
+
+    deferred.resolveError(500, "boom");
+    await waitFor(() => expect(a.result.current.loading).toBe(false));
+    await waitFor(() => expect(b.result.current.loading).toBe(false));
+
+    expect(a.result.current.error).toBeInstanceOf(RuactActionError);
+    expect(a.result.current.error).toBe(b.result.current.error); // identical instance
+    expect(deferred.fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("collapses params that differ only in key ORDER onto one request — AC2", async () => {
+    const deferred = deferredFetch();
+    const search = _makeQuery({ path: "/q/search", kind: "query" });
+
+    renderHook(() => useQuery(search, { a: 1, b: 2 }));
+    renderHook(() => useQuery(search, { b: 2, a: 1 }));
+
+    await waitFor(() => expect(deferred.fetchMock).toHaveBeenCalledTimes(1));
+    // Give any stray second request a chance to fire before asserting once.
+    await Promise.resolve();
+    expect(deferred.fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("issues SEPARATE requests for different params — AC2", async () => {
+    const deferred = deferredFetch();
+    const search = _makeQuery({ path: "/q/search", kind: "query" });
+
+    renderHook(() => useQuery(search, { q: "a" }));
+    renderHook(() => useQuery(search, { q: "b" }));
+
+    await waitFor(() => expect(deferred.fetchMock).toHaveBeenCalledTimes(2));
+  });
+
+  it("does NOT dedup across distinct references with the same params — AC2 (keys off the reference)", async () => {
+    const deferred = deferredFetch();
+    const categories = _makeQuery({ path: "/q/categories", kind: "query" });
+    const search = _makeQuery({ path: "/q/search", kind: "query" });
+
+    renderHook(() => useQuery(categories, { q: "x" }));
+    renderHook(() => useQuery(search, { q: "x" }));
+
+    await waitFor(() => expect(deferred.fetchMock).toHaveBeenCalledTimes(2));
+  });
+
+  it("does NOT share an invalid-shape params call onto an in-flight no-param request (surfaces the error) — AC2", async () => {
+    const deferred = deferredFetch();
+    const categories = _makeQuery({ path: "/q/categories", kind: "query" });
+
+    // A no-param request is in flight (key "").
+    const noParams = renderHook(() => useQuery(categories));
+    await waitFor(() => expect(deferred.fetchMock).toHaveBeenCalledTimes(1));
+
+    // An invalid array-shaped params call must NOT join the "" request — it must
+    // invoke the reference, whose buildQueryUrl throws a TypeError.
+    const invalid = renderHook(() => useQuery(categories, [1, 2]));
+    await waitFor(() => expect(invalid.result.current.loading).toBe(false));
+
+    expect(invalid.result.current.error).toBeInstanceOf(TypeError);
+    expect(invalid.result.current.data).toBeUndefined();
+    // No new network call: buildQueryUrl threw before fetch, and it never shared.
+    expect(deferred.fetchMock).toHaveBeenCalledTimes(1);
+    expect(noParams.result.current.loading).toBe(true); // still in flight
+  });
+
+  it("issues a FRESH request on a mount AFTER the previous settled (in-flight only, no cache) — AC3", async () => {
+    mockFetchOk([{ value: 1 }]);
+    const categories = _makeQuery({ path: "/q/categories", kind: "query" });
+
+    const first = renderHook(() => useQuery(categories, { q: "bo" }));
+    await waitFor(() => expect(first.result.current.loading).toBe(false));
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+    first.unmount();
+
+    // The previous request settled, so its registry entry is gone — a new mount
+    // with identical reference + params must refetch (no TTL / no SWR).
+    const second = renderHook(() => useQuery(categories, { q: "bo" }));
+    await waitFor(() => expect(second.result.current.loading).toBe(false));
+    expect(globalThis.fetch).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("Story 9.6 — canonicalParamsKey (dedup key derivation)", () => {
+  const { canonicalParamsKey } = __internals;
+
+  it("is order-independent ({a,b} === {b,a})", () => {
+    expect(canonicalParamsKey({ a: 1, b: 2 })).toBe(canonicalParamsKey({ b: 2, a: 1 }));
+  });
+
+  it("distinguishes different values", () => {
+    expect(canonicalParamsKey({ q: "a" })).not.toBe(canonicalParamsKey({ q: "b" }));
+  });
+
+  it("treats null / undefined / empty object as the same empty key", () => {
+    expect(canonicalParamsKey(null)).toBe("");
+    expect(canonicalParamsKey(undefined)).toBe("");
+    expect(canonicalParamsKey({})).toBe("");
+  });
+
+  it("skips undefined-valued keys (mirrors buildQueryUrl's wire omission)", () => {
+    expect(canonicalParamsKey({ q: "a", extra: undefined })).toBe(canonicalParamsKey({ q: "a" }));
+  });
+
+  it("distinguishes null from non-finite numbers (NaN / Infinity), which the wire sends differently", () => {
+    const asNull = canonicalParamsKey({ q: null });
+    const asNaN = canonicalParamsKey({ q: NaN });
+    const asInfinity = canonicalParamsKey({ q: Infinity });
+    expect(asNull).not.toBe(asNaN);
+    expect(asNaN).not.toBe(asInfinity);
+    expect(asNull).not.toBe(asInfinity);
+  });
+
+  it("distinguishes a null value (bare key) from the empty string (key=)", () => {
+    expect(canonicalParamsKey({ q: null })).not.toBe(canonicalParamsKey({ q: "" }));
+  });
+
+  it("returns null (non-shareable) for shapes buildQueryUrl rejects — array top level or array/object value", () => {
+    expect(canonicalParamsKey([1, 2])).toBe(null);
+    expect(canonicalParamsKey({ q: [1, 2] })).toBe(null);
+    expect(canonicalParamsKey({ q: { deep: 1 } })).toBe(null);
+  });
+});

data/vendor/javascript/vite-plugin-ruact/server-functions-codegen.mjs

@@ -49,12 +49,18 @@ const RESERVED_JS_IDENTIFIERS = new Set([
 ]);
 
 // Story 8.2 R12 (2026-05-17) — names ALREADY bound at module top by the
-// codegen itself: `_makeRef` (imported from the runtime) and `revalidate`
-// (re-exported unconditionally from the runtime). A snapshot that
-// declared either as an action `js_identifier` would emit a duplicate
-// binding and crash at module-load time. Mirrors Ruby
-// `NameBridge::RESERVED_BY_RUACT`.
-const RESERVED_BY_RUACT = new Set(["_makeRef", "_makeServerFunction", "revalidate"]);
+// codegen itself: the runtime imports (`_makeRef`, `_makeServerFunction`,
+// `_makeQuery`) and the re-exports (`revalidate`, `useQuery`). A snapshot that
+// declared any as a `js_identifier` would emit a duplicate binding and crash
+// at module-load time. Mirrors Ruby `NameBridge::RESERVED_BY_RUACT`.
+// Story 9.5 added `_makeQuery` + `useQuery`.
+const RESERVED_BY_RUACT = new Set([
+  "_makeQuery",
+  "_makeRef",
+  "_makeServerFunction",
+  "revalidate",
+  "useQuery",
+]);
 
 // Story 9.3 — the route-driven snapshot schema version + its verb allowlist.
 // A version-2 snapshot renders `_makeServerFunction({...})` calls; `render`
@@ -62,6 +68,10 @@ const RESERVED_BY_RUACT = new Set(["_makeRef", "_makeServerFunction", "revalidat
 // Mirrors Ruby `Codegen::VERSION_V2` / `V2_HTTP_METHODS`.
 export const VERSION_V2 = 2;
 const V2_HTTP_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+// Story 9.5 — queries are GET-only (the `POST /__ruact/fn/:id` query mechanism
+// is voided by the 2026-06-02 ADR addendum). Mirrors Ruby
+// `Codegen::V2::QUERY_HTTP_METHODS`.
+const V2_QUERY_HTTP_METHODS = new Set(["GET"]);
 
 /**
  * Absolute path to the placeholder runtime bundled inside the gem. Used as the
@@ -305,16 +315,18 @@ function validateSnapshotV2(snapshot) {
     }
     seen.add(fn.js_identifier);
 
-    if (fn.kind !== "action") {
+    if (fn.kind !== "action" && fn.kind !== "query") {
       throw new Error(
         `ruact server-function codegen: v2 snapshot entry "${fn.js_identifier}" has invalid ` +
-          `kind ${JSON.stringify(fn.kind)} (v2 entries are always "action").`,
+          `kind ${JSON.stringify(fn.kind)} (v2 entries are "action" or "query").`,
       );
     }
-    if (!V2_HTTP_METHODS.has(fn.http_method)) {
+    // Story 9.5 — actions carry a mutation verb; queries are GET-only.
+    const allowedMethods = fn.kind === "query" ? V2_QUERY_HTTP_METHODS : V2_HTTP_METHODS;
+    if (!allowedMethods.has(fn.http_method)) {
       throw new Error(
         `ruact server-function codegen: v2 snapshot entry "${fn.js_identifier}" has invalid ` +
-          `http_method ${JSON.stringify(fn.http_method)} (must be POST/PUT/PATCH/DELETE).`,
+          `http_method ${JSON.stringify(fn.http_method)} (must be one of ${JSON.stringify([...allowedMethods])}).`,
       );
     }
     if (typeof fn.path !== "string" || !fn.path.startsWith("/")) {
@@ -369,11 +381,21 @@ function validateSnapshotV2(snapshot) {
 function renderV2(snapshot) {
   validateSnapshotV2(snapshot);
   const { version, generated_at, functions } = snapshot;
+
+  const hasQuery = functions.some((fn) => fn.kind === "query");
+  const hasAction = functions.some((fn) => fn.kind === "action");
+
+  // Story 9.5 — import only what is used. Keep `_makeServerFunction` in the
+  // empty case so the no-functions module stays byte-identical to Story 9.3.
+  const imports = [];
+  if (hasAction || functions.length === 0) imports.push("_makeServerFunction");
+  if (hasQuery) imports.push("_makeQuery");
+
   let out = "";
   out += "// AUTO-GENERATED by vite-plugin-ruact (Story 9.3). DO NOT EDIT.\n";
   out += `// Source: Rails route table (version ${version})\n`;
   out += `// Generated at: ${generated_at}\n`;
-  out += `import { _makeServerFunction } from "${RUNTIME_IMPORT_SPECIFIER}";\n`;
+  out += `import { ${imports.join(", ")} } from "${RUNTIME_IMPORT_SPECIFIER}";\n`;
 
   if (functions.length === 0) {
     out += "\n// (no server functions exposed yet — add a non-GET route on a Ruact::Server controller)\n";
@@ -386,12 +408,17 @@ function renderV2(snapshot) {
   }
   out += "\n";
   out += `export { revalidate } from "${RUNTIME_IMPORT_SPECIFIER}";\n`;
+  // Story 9.5 — `useQuery` re-export ONLY when queries are present (keeps the
+  // action-only / empty modules byte-identical to Story 9.3).
+  if (hasQuery) out += `export { useQuery } from "${RUNTIME_IMPORT_SPECIFIER}";\n`;
   return out;
 }
 
 function renderExportV2(fn) {
-  // Same intersection signature as v1 actions (Story 8.2) — every v2 entry is
-  // an action. Mirrors `Ruact::ServerFunctions::Codegen::ACTION_SIGNATURE`.
+  if (fn.kind === "query") return renderQueryExportV2(fn);
+
+  // The same intersection signature as v1 actions (Story 8.2). Mirrors
+  // `Ruact::ServerFunctions::Codegen::ACTION_SIGNATURE`.
   const signature =
     "((args?: FormData | Record<string, unknown>) => Promise<unknown>) & ((formData: FormData) => Promise<void>)";
   const method = JSON.stringify(String(fn.http_method));
@@ -404,6 +431,22 @@ function renderExportV2(fn) {
   );
 }
 
+// Story 9.5 — a query export binds a `_makeQuery` accessor carrying its GET
+// descriptor `{ path, kind: "query" }`; `useQuery(<id>, …)` consumes it. The
+// signature accepts params only when the query method declares kwargs (FR88).
+// Mirrors `Ruact::ServerFunctions::Codegen::V2.render_query_export`.
+function renderQueryExportV2(fn) {
+  const signature = fn.accepts_params
+    ? "(params: Record<string, unknown>) => Promise<unknown>"
+    : "() => Promise<unknown>";
+  const pathLit = JSON.stringify(String(fn.path));
+  const descriptor = `{ path: ${pathLit}, kind: "query" }`;
+  return (
+    `export const ${fn.js_identifier}: ${signature} =\n` +
+    `  _makeQuery(${descriptor});\n`
+  );
+}
+
 function renderExport(fn) {
   // Story 8.2 (refined 2026-05-17 per review patch R1) — action signature
   // is an intersection of two call signatures so `<form action={fn}>`

data/vendor/javascript/vite-plugin-ruact/server-functions-codegen.test.mjs

@@ -864,3 +864,98 @@ describe("Story 9.3 — route-driven (v2) render + parity", () => {
     expect(jsOutput).toBe(rubyOutput);
   });
 });
+
+describe("Story 9.5 — v2 query entries render + parity", () => {
+  const queryFixture = {
+    version: 2,
+    generated_at: "2026-06-10T00:00:00Z",
+    functions: [
+      {
+        js_identifier: "createPost",
+        kind: "action",
+        http_method: "POST",
+        path: "/posts",
+        segments: [],
+        controller: "posts",
+        action: "create",
+      },
+      {
+        js_identifier: "categories",
+        kind: "query",
+        http_method: "GET",
+        path: "/q/categories",
+        segments: [],
+        accepts_params: false,
+        controller: "CatalogQuery",
+        action: "categories",
+      },
+      {
+        js_identifier: "searchUsers",
+        kind: "query",
+        http_method: "GET",
+        path: "/q/searchUsers",
+        segments: [],
+        accepts_params: true,
+        controller: "CatalogQuery",
+        action: "search_users",
+      },
+    ],
+  };
+
+  it("emits _makeQuery refs with GET descriptors + the useQuery re-export", () => {
+    const out = render(queryFixture);
+    expect(out).toContain('import { _makeServerFunction, _makeQuery } from "ruact/server-functions-runtime";');
+    expect(out).toContain(
+      'export const categories: () => Promise<unknown> =\n  _makeQuery({ path: "/q/categories", kind: "query" });',
+    );
+    expect(out).toContain(
+      'export const searchUsers: (params: Record<string, unknown>) => Promise<unknown> =\n' +
+        '  _makeQuery({ path: "/q/searchUsers", kind: "query" });',
+    );
+    expect(out).toContain('export { useQuery } from "ruact/server-functions-runtime";');
+  });
+
+  it("accepts GET for a query entry but rejects a non-GET verb", () => {
+    expect(() =>
+      render({
+        version: 2,
+        generated_at: "x",
+        functions: [
+          { js_identifier: "categories", kind: "query", http_method: "POST", path: "/q/categories", segments: [] },
+        ],
+      }),
+    ).toThrow(/invalid.*http_method/i);
+  });
+
+  it("rejects an unknown kind (action/query only)", () => {
+    expect(() =>
+      render({
+        version: 2,
+        generated_at: "x",
+        functions: [
+          { js_identifier: "x", kind: "mutation", http_method: "GET", path: "/q/x", segments: [] },
+        ],
+      }),
+    ).toThrow(/"action" or "query"/);
+  });
+
+  it("Ruby's render and JS's render produce byte-identical query output", () => {
+    const jsOutput = render(queryFixture);
+    const gemLibPath = path.resolve(
+      path.dirname(new URL(import.meta.url).pathname),
+      "..",
+      "..",
+      "..",
+      "lib",
+    );
+    const fixtureJson = JSON.stringify(queryFixture);
+    const script =
+      'require "ruact/server_functions/codegen"; ' +
+      'require "json"; ' +
+      `print Ruact::ServerFunctions::Codegen.render(JSON.parse('${fixtureJson}'))`;
+    const rubyOutput = execFileSync("ruby", ["-I", gemLibPath, "-e", script], {
+      encoding: "utf8",
+    });
+    expect(jsOutput).toBe(rubyOutput);
+  });
+});

data/vendor/javascript/vite-plugin-ruact/vitest.config.mjs

@@ -9,7 +9,13 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   test: {
     environment: "node",
-    include: ["**/*.test.mjs", "../ruact-server-functions-runtime/*.test.mjs"],
+    // The runtime's `index.test.mjs` is node-environment + dependency-free, so
+    // it rides along here for a single parity-plus-runtime run. Its jsdom +
+    // React hook tests (`usequery.test.mjs`, Story 9.5) need
+    // `@testing-library/react` from the runtime package's own node_modules and
+    // run via that package's `npm test` — they are intentionally NOT globbed
+    // in here (a `*.test.mjs` glob would pull them in and fail to resolve).
+    include: ["**/*.test.mjs", "../ruact-server-functions-runtime/index.test.mjs"],
     globals: false,
   },
 });

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruact
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.5
 platform: ruby
 authors:
 - Luiz Garcia
@@ -84,6 +84,7 @@ files:
 - lib/ruact/server_functions/name_bridge.rb
 - lib/ruact/server_functions/query_context.rb
 - lib/ruact/server_functions/query_dispatch.rb
+- lib/ruact/server_functions/query_source.rb
 - lib/ruact/server_functions/registry.rb
 - lib/ruact/server_functions/registry_entry.rb
 - lib/ruact/server_functions/route_source.rb
@@ -154,6 +155,7 @@ files:
 - spec/ruact/server_functions/error_suggestion_spec.rb
 - spec/ruact/server_functions/name_bridge_spec.rb
 - spec/ruact/server_functions/query_context_spec.rb
+- spec/ruact/server_functions/query_source_spec.rb
 - spec/ruact/server_functions/railtie_integration_spec.rb
 - spec/ruact/server_functions/rake_spec.rb
 - spec/ruact/server_functions/registry_spec.rb
@@ -178,6 +180,7 @@ files:
 - vendor/javascript/ruact-server-functions-runtime/index.js
 - vendor/javascript/ruact-server-functions-runtime/index.test.mjs
 - vendor/javascript/ruact-server-functions-runtime/package.json
+- vendor/javascript/ruact-server-functions-runtime/usequery.test.mjs
 - vendor/javascript/vite-plugin-ruact/index.js
 - vendor/javascript/vite-plugin-ruact/package-lock.json
 - vendor/javascript/vite-plugin-ruact/package.json