ruact 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ae4dcaf2cb6bc327dabdfcfb4d29b809e4c76e272b3e25238c972c644f37129
-  data.tar.gz: 7b438642cfd87f31404cfd056bb80f97265f0524f3b2b3d6bdf00a1717983e0d
+  metadata.gz: 2f8e264e2e404e5257d0fe7457cef545f4104288dc16db01e1c8e5762d361f99
+  data.tar.gz: 4a2ed748edb281b7d8bb0c20ce5e404db6ce7872f82c8db1545349ab709677d3
 SHA512:
-  metadata.gz: 100c14dc7e8976ef488f62888fcbce9f2d560038fb75616c26952df54688f8c5fc77968456d81443c19f640505257d1f244288e2b84f8c0fdaac218d4abcd038
-  data.tar.gz: '028ce642e81327af34b50a5d7cc8ba67599ad419f67517df3965eae0d61f284053bfdc0ec742e5dafb7236cb59637d7fdbb745c90f6dfa7e1a90ad9b14604e0d'
+  metadata.gz: 36eb5942d50d3761874bd912a9cfae5ad3538500b8e08a79b196310db8db66bc86fa8a6fc78262c8a2e73ba659feaa1dd821c344fe89ecbddf247c2e05924153
+  data.tar.gz: f8902075c57bb47e42f404d43a864829719bddc4f497371097f0c1576ef1565312b45e628f1d7a3e9a3811db497e1aa8325f8e935da4e7b4941ae2bdc468d72e

data/CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **`useQuery` request de-duplication** ([Story 9.6](../_bmad-output/implementation-artifacts/9-6-automatic-request-deduplication-for-usequery.md)). Identical concurrent `useQuery` calls now share ONE network request: when three components mount `useQuery(categories)` with the same params while a request is in flight, exactly one `GET /q/categories` is issued — all of them receive the same resolved `data`, and an error propagates to every sharer. The dedup key derives from the **query reference identity + the serialized params**, with order-independent param serialization (`{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` share a request; different params do not). Scope is **in-flight only** — there is no TTL cache and no stale-while-revalidate: once a request settles its shared entry is dropped, so a fresh mount refetches. Runtime-only change (`useQuery` hook); the `_makeQuery` GET accessor, codegen, and the Ruby query dispatch are unchanged. Runtime package version `0.3.0` → `0.4.0`; coverage in `usequery.test.mjs`.
+
 - **Queries in codegen + `useQuery` hook + FR88 kwargs sanitization** ([Story 9.5](../_bmad-output/implementation-artifacts/9-5-queries-in-codegen-usequery-re-pointed-kwargs-params.md)). The read-side of the route-driven redesign is complete: `import { categories, useQuery } from "@/.ruact/server-functions"` and `useQuery(categories)` / `useQuery(searchUsers, { q: input })` now work against `Ruact::Query` classes — same mental model as mutations, zero new concepts. **Codegen.** A new `Ruact::ServerFunctions::QuerySource` derives v2 query entries from the **drawn route table** (the GET routes the `ruact_queries` macro mounted under the generated query-dispatch namespace) — route-truth-consistent with dispatch, so only classes actually mounted in `routes.rb` are exposed (no over-exposure, and no `app/queries` force-load needed). Query entries join the **same merged JS namespace** as mutations; collisions fail loudly at boot naming both origins (route×query is caught at the codegen combine point; `query×query` by the source; the `ruact_function_name` rename macro on the mutation controller — or renaming the query method — is the escape hatch). The emitted module binds each query to `_makeQuery({ path, kind: "query" })` with a per-query TS signature (`() => Promise<unknown>` when the method declares no kwargs, `(params: Record<string, unknown>) => Promise<unknown>` when it does) and re-exports `useQuery` from the runtime (only when ≥1 query exists, so action-only/empty v2 modules stay byte-identical to Story 9.3). The Ruby↔JS byte-equality parity test covers query entries. **Runtime.** New `useQuery(reference, params?)` React hook → `{ data, loading, error }` (loading until first resolution; structured `RuactActionError` into `error`; superseded in-flight responses dropped; refetch on value-changed params); new `_makeQuery` GET helper issues `GET /q/<jsId>` with params in the query string — **no body, no CSRF** (reads are CSRF-free; the stale `POST /__ruact/fn/:id` query mechanism is voided). The runtime gains `react` as a **peerDependency** (its first React import; the mutation path stays React-free); package version `0.2.0` → `0.3.0`. **FR88 sanitization.** `query_dispatch.rb#__ruact_query_kwargs` now enforces the authoritative kwargs allowlist on `request.query_parameters`: only `string | number | boolean | null` are accepted — arrays (`?q[]=`) and objects (`?q[k]=`) are **rejected with a descriptive error naming the key and the allowlist**; a **missing required kwarg → 400** naming it; an **unknown param → 400** (rejected, not silently dropped). All raise the new `Ruact::BadRequestError` → HTTP 400 via the Story 8.4 structured payload. 9.5 writes ONLY the parallel `.next` codegen target (ownership flip is 9.8); `useQuery` request de-duplication is 9.6; the v1 substrate is untouched (demolition is 9.9). New files `lib/ruact/server_functions/query_source.rb`; new specs `query_source_spec.rb`, `:story_9_5` cases in `codegen_spec.rb` / `railtie_integration_spec.rb` / `query_request_spec.rb`; new runtime vitest `usequery.test.mjs` + query parity cases. ADR addendum (2026-06-10).
 
 - **`Ruact::Query` base class + `ruact_queries` route macro** ([Story 9.4](../_bmad-output/implementation-artifacts/9-4-ruact-query-base-class-and-ruact-queries-route-macro.md)). Server QUERIES are now plain classes under `app/queries/` (`class CatalogQuery < ApplicationQuery`, `ApplicationQuery < Ruact::Query`) — each public method defined directly on the subclass is one query — mounted with one line in `routes.rb`: `ruact_queries CatalogQuery` draws one **named GET route per public method** (`def search_users` → `GET /q/searchUsers`, named `ruact_query_searchUsers`), all visible in `rails routes` (no hidden endpoint; the route table stays the single source of truth). The prefix is configurable via the new `Ruact.config.query_route_prefix` (default `"/q"`). Dispatch goes through an internal gem controller — one generated subclass per query class — inheriting the new `Ruact.config.query_parent_controller` (default `"ApplicationController"`, constantized lazily at route-draw), so the host's REAL callback chain (`authenticate_user!`, tenant scoping, Pundit) runs **before** the query class is instantiated. The query instance is fresh per request and receives its context via the constructor: `current_user` / `params` / `request` / `session` delegate to the dispatching controller (so `current_user` IS the host's own method), and `CatalogQuery.new(fake_context).categories` is unit-testable with no Rails boot. Per-query callback opt-out via the new `ruact_skip_before_action` class macro (mirrors Rails' `skip_before_action` signature incl. `only:`/`except:`/`raise: false`; scoped to the declaring query class by construction). Queries are GET — no CSRF; the method's return value is serialized through the same `ruact_props` / `Ruact::Serializable` / `strict_serialization` policy as Bucket 2 (new `BucketTwoPayload.serialize_value` extraction; `nil` → JSON `null` with 200), and a query raise renders the salvaged structured-error payload with the same 422/403/413/500 mapping (the GET gate is overridden for query dispatch — `Ruact::ConfigurationError` still re-raises loudly). Keyword arguments are passed best-effort from GET query params by name (the strict FR88 sanitization wire contract ships with `useQuery` in Story 9.5; codegen of query entries is also 9.5). New files `lib/ruact/query.rb`, `lib/ruact/routing.rb`, `lib/ruact/server_functions/query_dispatch.rb`, `lib/ruact/server_functions/query_context.rb`. New specs `query_spec.rb`, `query_context_spec.rb`, `query_request_spec.rb` + extensions to `configuration_spec.rb` / `bucket_two_payload_spec.rb`, all tagged `:story_9_4`.

data/lib/ruact/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ruact
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

data/vendor/javascript/ruact-server-functions-runtime/index.d.ts

@@ -113,8 +113,10 @@ export function _makeQuery(descriptor: {
  * resolution; `error` carries the structured {@link RuactActionError} on
  * failure. A superseded in-flight response is dropped.
  *
- * 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 a request settles the shared entry is dropped, so a fresh mount
+ * refetches (no TTL cache, no stale-while-revalidate).
  */
 export function useQuery<T = unknown>(
   reference: (params?: Record<string, unknown>) => Promise<unknown>,

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

@@ -187,6 +187,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 +292,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 +306,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 });
       })
@@ -312,6 +403,15 @@ 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

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

@@ -1,7 +1,7 @@
 {
   "name": "ruact-server-functions-runtime",
-  "version": "0.3.0",
-  "description": "Server-functions runtime for ruact gem (Stories 8.1 + 8.2 + 9.5). 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 }).",
+  "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",

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

@@ -15,6 +15,10 @@ 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(() => {
@@ -44,6 +48,39 @@ function mockFetchError(status, bodyText) {
   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] });
@@ -179,3 +216,153 @@ describe("Story 9.5 — _makeQuery / buildQueryUrl wire format (FR88)", () => {
     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);
+  });
+});

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruact
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Luiz Garcia