@reliantlabs/forge-web-runtime 0.9.1 → 0.10.0

package/dist/service-hooks.d.ts

@@ -1,5 +1,5 @@
 import { type DescMessage, type MessageInitShape } from "@bufbuild/protobuf";
-import { type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseQueryResult } from "@tanstack/react-query";
+import { type InfiniteData, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseQueryResult } from "@tanstack/react-query";
 import type { ConnectClientError } from "./errors.js";
 /**
  * A generated query key. The tuple is [service, entity?, method,
@@ -32,6 +32,37 @@ export interface ServiceKeyBuilders {
      * call-site prefetch/setQueryData use.
      */
     query<Schema extends DescMessage>(method: string, schema: Schema, entityScope?: string): (req: MessageInitShape<Schema>) => ServiceQueryKey;
+    /**
+     * One paged read: [service, entity?, method, protojson(req), "infinite"],
+     * where req is the request WITHOUT its page token — the hook owns the
+     * token, so every page of one listing shares one cache entry.
+     *
+     * It nests under the same scopes as `query`, so an entity or service-wide
+     * invalidation refetches it. The "infinite" suffix keeps it OFF the plain
+     * query's entry for the same request: an infinite query caches
+     * `{ pages, pageParams }`, not one response, and a plain hook reading that
+     * entry would get the wrong shape.
+     */
+    infinite<Schema extends DescMessage>(method: string, schema: Schema, entityScope?: string): (req: PageRequest<Schema>) => ServiceQueryKey;
+}
+/**
+ * Omit distributed over a union. MessageInitShape is `Message | init
+ * object`, and a plain Omit over a union keeps only the keys both members
+ * share — which would silently drop every field from the init side.
+ */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/**
+ * The request a generated infinite hook takes: the rpc's request without
+ * `pageToken`, which the hook supplies page by page.
+ */
+export type PageRequest<Schema extends DescMessage> = DistributiveOmit<MessageInitShape<Schema>, "pageToken">;
+/**
+ * The response shape forge's list-pagination convention (AIP-158) gives a
+ * paged read: `string next_page_token`, empty on the last page. Optional so
+ * an `optional string next_page_token` response satisfies it too.
+ */
+export interface PagedResponse {
+    nextPageToken?: string;
 }
 /**
  * serviceKeys returns the builders for one service's query-key factory.
@@ -44,10 +75,57 @@ export interface ServiceKeyBuilders {
  * what forge previously inlined into every generated hook file.
  */
 export declare function serviceKeys(service: string): ServiceKeyBuilders;
-/** A generated query hook: `useGetOrder(req, options?)`. */
-export type ServiceQueryHook<Schema extends DescMessage, Response> = (req: MessageInitShape<Schema>, options?: Partial<UseQueryOptions<Response, ConnectClientError>>) => UseQueryResult<Response, ConnectClientError>;
-/** A generated mutation hook: `useCreateOrder(options?)`. */
-export type ServiceMutationHook<Schema extends DescMessage, Response> = (options?: Partial<UseMutationOptions<Response, ConnectClientError, MessageInitShape<Schema>>>) => UseMutationResult<Response, ConnectClientError, MessageInitShape<Schema>>;
+/**
+ * How a generated file calls one rpc. `signal` is React Query's: a query
+ * that is unmounted or superseded (a new key while typing) aborts its
+ * request instead of letting it land on a cache entry nobody reads.
+ */
+export type ServiceCall<Schema extends DescMessage, Response> = (req: MessageInitShape<Schema>, signal?: AbortSignal) => Promise<Response>;
+/**
+ * A generated query hook: `useGetOrder(req, options?)`.
+ *
+ * TData is what the hook's `data` is, exactly as in React Query's own
+ * useQuery: the response by default, or whatever `select` returns. A call
+ * site mapping the proto response to a view model passes
+ * `select: (r) => toView(r)` and gets `data: View` — no useMemo over `data`,
+ * and React Query re-runs the mapping only when the response changes (or
+ * when `select` itself does, so hoist it or wrap it in useCallback when it
+ * is expensive). TData is inferred from `select` and is a parameter of the
+ * HOOK, not of the factory, so every call site picks its own.
+ */
+export type ServiceQueryHook<Schema extends DescMessage, Response> = <TData = Response>(req: MessageInitShape<Schema>, options?: Partial<UseQueryOptions<Response, ConnectClientError, TData>>) => UseQueryResult<TData, ConnectClientError>;
+/**
+ * The options a generated infinite hook takes: React Query's own, minus the
+ * four the hook owns — the key, the fetch, and the page-token plumbing.
+ * `getNextPageParam` defaults to the response's `nextPageToken` (empty means
+ * last page) and may be overridden; everything else (`select`,
+ * `placeholderData`, `staleTime`, `enabled`, `maxPages`, …) passes through.
+ */
+export type ServiceInfiniteQueryOptions<Response, TData> = Partial<Omit<UseInfiniteQueryOptions<Response, ConnectClientError, TData, ServiceQueryKey, string>, "queryKey" | "queryFn" | "initialPageParam">>;
+/**
+ * A generated infinite-query hook: `useListOrdersInfinite(req, options?)`,
+ * for a read that follows forge's list-pagination shape (`string page_token`
+ * on the request, `string next_page_token` on the response).
+ *
+ * `req` is the first page's request without its token. `data` is React
+ * Query's `{ pages, pageParams }` by default; `select` reshapes it, so
+ * flattening the pages into one list is
+ * `select: (d) => d.pages.flatMap((p) => p.orders)`.
+ */
+export type ServiceInfiniteQueryHook<Schema extends DescMessage, Response extends PagedResponse> = <TData = InfiniteData<Response, string>>(req: PageRequest<Schema>, options?: ServiceInfiniteQueryOptions<Response, TData>) => UseInfiniteQueryResult<TData, ConnectClientError>;
+/**
+ * A generated mutation hook: `useCreateOrder(options?)`.
+ *
+ * TContext is React Query's fourth type parameter — what `onMutate` returns
+ * and `onError` / `onSettled` receive back. It is a parameter of the HOOK,
+ * not of the factory, so each call site gets its own: TypeScript infers it
+ * from the `onMutate` the caller passes, and an optimistic update reads its
+ * rollback off `context` with no cast. Fixing it at the factory (or leaving
+ * it out, which pinned it to `unknown`) forced every such call site to
+ * narrow `unknown` by hand. It defaults to `unknown`, so a call without
+ * `onMutate` types exactly as before.
+ */
+export type ServiceMutationHook<Schema extends DescMessage, Response> = <TContext = unknown>(options?: Partial<UseMutationOptions<Response, ConnectClientError, MessageInitShape<Schema>, TContext>>) => UseMutationResult<Response, ConnectClientError, MessageInitShape<Schema>, TContext>;
 /**
  * createQueryHook builds one useQuery wrapper.
  *
@@ -60,7 +138,23 @@ export type ServiceMutationHook<Schema extends DescMessage, Response> = (options
  * and `.retryable`, and left `err.message.includes(...)` as the only
  * expression that compiled — the one thing the error contract forbids.
  */
-export declare function createQueryHook<Schema extends DescMessage, Response>(keyFor: (req: MessageInitShape<Schema>) => ServiceQueryKey, call: (req: MessageInitShape<Schema>) => Promise<Response>): ServiceQueryHook<Schema, Response>;
+export declare function createQueryHook<Schema extends DescMessage, Response>(keyFor: (req: MessageInitShape<Schema>) => ServiceQueryKey, call: ServiceCall<Schema, Response>): ServiceQueryHook<Schema, Response>;
+/**
+ * createInfiniteQueryHook builds one useInfiniteQuery wrapper over a paged
+ * read.
+ *
+ * The page token is the hook's: the first page is fetched with the caller's
+ * request as given (no token, so an `optional string page_token` stays
+ * unset), each later one with the previous response's `nextPageToken`, and
+ * an empty token ends the listing. The key is `keys.infinite(...)`, which
+ * strips the token and sits under the service and entity scopes, so the
+ * mutations that invalidate a plain list refetch this one too.
+ *
+ * The caller's options are spread BETWEEN the default getNextPageParam and
+ * the four fields the hook owns: a caller may replace the default, never the
+ * key or the fetch.
+ */
+export declare function createInfiniteQueryHook<Schema extends DescMessage, Response extends PagedResponse>(keyFor: (req: PageRequest<Schema>) => ServiceQueryKey, call: ServiceCall<Schema, Response>): ServiceInfiniteQueryHook<Schema, Response>;
 /**
  * createMutationHook builds one useMutation wrapper with scoped invalidation.
  *
@@ -76,3 +170,4 @@ export declare function createQueryHook<Schema extends DescMessage, Response>(ke
  * spread over a default onSuccess would do.
  */
 export declare function createMutationHook<Schema extends DescMessage, Response>(invalidateKey: ServiceQueryKey, call: (req: MessageInitShape<Schema>) => Promise<Response>): ServiceMutationHook<Schema, Response>;
+export {};

package/dist/service-hooks.js

@@ -36,7 +36,7 @@
 // either: "CreateOrder succeeded" leaks RPC names into the UI, so the toast /
 // redirect / inline confirmation stays the call site's via options.onSuccess.
 import { create, toJson, } from "@bufbuild/protobuf";
-import { useMutation, useQuery, useQueryClient, } from "@tanstack/react-query";
+import { useInfiniteQuery, useMutation, useQuery, useQueryClient, } from "@tanstack/react-query";
 /**
  * requestKey projects a request init into protojson for use inside a query
  * key. Two reasons this is not the raw request object:
@@ -52,6 +52,21 @@ import { useMutation, useQuery, useQueryClient, } from "@tanstack/react-query";
 export function requestKey(schema, req) {
     return toJson(schema, create(schema, req));
 }
+/**
+ * pageRequestKey is requestKey with the page token dropped, so every page of
+ * one listing hashes to one key even when a caller (JS, or a cast) passes a
+ * token anyway. It is dropped from the protojson rather than from the init
+ * object: a spread Message keeps its $typeName, and create() would hand that
+ * token-less copy back as if it were a complete message.
+ */
+function pageRequestKey(schema, req) {
+    const json = requestKey(schema, req);
+    if (json === null || typeof json !== "object" || Array.isArray(json)) {
+        return json;
+    }
+    const { pageToken: _pageToken, ...rest } = json;
+    return rest;
+}
 /**
  * serviceKeys returns the builders for one service's query-key factory.
  *
@@ -69,6 +84,20 @@ export function serviceKeys(service) {
         query: (method, schema, entityScope) => (req) => entityScope === undefined
             ? [service, method, requestKey(schema, req)]
             : [service, entityScope, method, requestKey(schema, req)],
+        infinite: (method, schema, entityScope) => (req) => entityScope === undefined
+            ? [
+                service,
+                method,
+                pageRequestKey(schema, req),
+                "infinite",
+            ]
+            : [
+                service,
+                entityScope,
+                method,
+                pageRequestKey(schema, req),
+                "infinite",
+            ],
     };
 }
 /**
@@ -86,10 +115,39 @@ export function serviceKeys(service) {
 export function createQueryHook(keyFor, call) {
     return (req, options) => useQuery({
         queryKey: keyFor(req),
-        queryFn: () => call(req),
+        queryFn: ({ signal }) => call(req, signal),
         ...options,
     });
 }
+/**
+ * createInfiniteQueryHook builds one useInfiniteQuery wrapper over a paged
+ * read.
+ *
+ * The page token is the hook's: the first page is fetched with the caller's
+ * request as given (no token, so an `optional string page_token` stays
+ * unset), each later one with the previous response's `nextPageToken`, and
+ * an empty token ends the listing. The key is `keys.infinite(...)`, which
+ * strips the token and sits under the service and entity scopes, so the
+ * mutations that invalidate a plain list refetch this one too.
+ *
+ * The caller's options are spread BETWEEN the default getNextPageParam and
+ * the four fields the hook owns: a caller may replace the default, never the
+ * key or the fetch.
+ */
+export function createInfiniteQueryHook(keyFor, call) {
+    return (req, options) => useInfiniteQuery({
+        getNextPageParam: (last) => last.nextPageToken || undefined,
+        ...options,
+        queryKey: keyFor(req),
+        queryFn: ({ pageParam, signal }) => call((pageParam === ""
+            ? req
+            : {
+                ...req,
+                pageToken: pageParam,
+            }), signal),
+        initialPageParam: "",
+    });
+}
 /**
  * createMutationHook builds one useMutation wrapper with scoped invalidation.
  *

package/dist/service-hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"service-hooks.js","sourceRoot":"","sources":["../src/service-hooks.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,sEAAsE;AACtE,EAAE;AACF,8EAA8E;AAC9E,6EAA6E;AAC7E,uEAAuE;AACvE,6EAA6E;AAC7E,+EAA+E;AAC/E,yEAAyE;AACzE,gEAAgE;AAChE,EAAE;AACF,8EAA8E;AAC9E,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,qEAAqE;AACrE,qEAAqE;AACrE,+EAA+E;AAC/E,4EAA4E;AAC5E,8EAA8E;AAC9E,sEAAsE;AACtE,EAAE;AACF,+EAA+E;AAC/E,2EAA2E;AAC3E,sEAAsE;AACtE,wEAAwE;AACxE,6EAA6E;AAC7E,4EAA4E;AAC5E,mCAAmC;AACnC,EAAE;AACF,wEAAwE;AACxE,8EAA8E;AAC9E,uDAAuD;AACvD,yEAAyE;AACzE,8EAA8E;AAC9E,8EAA8E;AAC9E,OAAO,EACL,MAAM,EACN,MAAM,GAGP,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,WAAW,EACX,QAAQ,EACR,cAAc,GAKf,MAAM,uBAAuB,CAAC;AAW/B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CACxB,MAAc,EACd,GAA6B;IAE7B,OAAO,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;AAC7C,CAAC;AAoBD;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO;QACL,GAAG,EAAE,CAAC,OAAO,CAAU;QACvB,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,CAAU;QAClD,KAAK,EACH,CACE,MAAc,EACd,MAAc,EACd,WAAoB,EACpB,EAAE,CACJ,CAAC,GAA6B,EAAmB,EAAE,CACjD,WAAW,KAAK,SAAS;YACvB,CAAC,CAAE,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAW;YACvD,CAAC,CAAE,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAW;KAC3E,CAAC;AACJ,CAAC;AAeD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAC7B,MAA0D,EAC1D,IAA0D;IAE1D,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,CACtB,QAAQ,CAAC;QACP,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC;QACrB,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC;QACxB,GAAG,OAAO;KACX,CAAC,CAAC;AACP,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAChC,aAA8B,EAC9B,IAA0D;IAE1D,OAAO,CAAC,OAAO,EAAE,EAAE;QACjB,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;QACrC,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;QAC7C,OAAO,WAAW,CAAC;YACjB,UAAU,EAAE,CAAC,GAA6B,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC;YACxD,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,EAAE;gBACrB,WAAW,CAAC,iBAAiB,CAAC,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC,CAAC;gBAC3D,SAAS,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;YACvB,CAAC;YACD,GAAG,IAAI;SACR,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC","sourcesContent":["\"use client\";\n\n// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// Every export below is a React hook or builds one, so this module belongs in\n// the CLIENT graph. Without the directive the Next.js App Router compiles it\n// into the SERVER graph, where it binds a SECOND @tanstack/react-query\n// instance and every generated hook throws \"No QueryClient set\" at runtime —\n// invisible to tsc, eslint AND `next build`. published-surface.test.ts asserts\n// the directive survives into dist/. It is NOT applied package-wide: the\n// ./interceptors subpath exists to be importable without React.\n//\n// The React Query wrapper machinery behind forge's generated per-service hook\n// files (`src/hooks/<svc>-service-hooks_gen.ts`).\n//\n// WHAT WAS HERE BEFORE. Each generated file re-emitted the same three things\n// per RPC: a query-key entry, a useQuery or useMutation wrapper, and — for\n// mutations — the entity-scoped invalidateQueries plus the onSuccess\n// composition, with the reasoning for each re-inlined as comments. A\n// five-service project rendered five copies of machinery that differed only in\n// RPC names and message types. This module IS that machinery, written once.\n// The generated file keeps exactly what varies per RPC: the name, the request\n// schema, the response type, query-vs-mutation, and the entity scope.\n//\n// WHY A SUBPATH AND NOT THE BARREL. This module imports @tanstack/react-query.\n// Every browser frontend forge scaffolds depends on it — but the barrel is\n// also what a consumer imports for interceptors and errors alone, and\n// anchoring React Query there would make a non-React consumer resolve a\n// package it never installed. Same reasoning as ./mock-transport and ./otel:\n// an engine with its own dependency footprint gets its own entry point, and\n// React Query is an OPTIONAL peer.\n//\n// WHAT IT DELIBERATELY DOES NOT DO. It does not emit error toasts — the\n// app-wide MutationCache in src/lib/query-client.ts is the single error-toast\n// chokepoint, and pages that render errors inline pass\n// `meta: { silenceErrorToast: true }`. It never defaults success-side UX\n// either: \"CreateOrder succeeded\" leaks RPC names into the UI, so the toast /\n// redirect / inline confirmation stays the call site's via options.onSuccess.\nimport {\n  create,\n  toJson,\n  type DescMessage,\n  type MessageInitShape,\n} from \"@bufbuild/protobuf\";\nimport {\n  useMutation,\n  useQuery,\n  useQueryClient,\n  type UseMutationOptions,\n  type UseMutationResult,\n  type UseQueryOptions,\n  type UseQueryResult,\n} from \"@tanstack/react-query\";\n\nimport type { ConnectClientError } from \"./errors.js\";\n\n/**\n * A generated query key. The tuple is [service, entity?, method,\n * protojson(req)] for a method key and [service] / [service, entity] for the\n * broader scopes.\n */\nexport type ServiceQueryKey = readonly unknown[];\n\n/**\n * requestKey projects a request init into protojson for use inside a query\n * key. Two reasons this is not the raw request object:\n *\n *   - React Query's default hasher is JSON.stringify, which THROWS on bigint\n *     fields (any proto int64) — the raw message crashes the cache.\n *   - protojson normalizes representations, so { id: 1 } and { id: \"1\" } land\n *     in ONE cache entry instead of silently splitting the cache.\n *\n * Exported because a hand-written hook that wants to share a generated hook's\n * cache entry has to hash its request the identical way.\n */\nexport function requestKey<Schema extends DescMessage>(\n  schema: Schema,\n  req: MessageInitShape<Schema>,\n): unknown {\n  return toJson(schema, create(schema, req));\n}\n\n/** The three key-scope builders a generated key factory is assembled from. */\nexport interface ServiceKeyBuilders {\n  /** Every query on this service: [service]. */\n  readonly all: readonly [string];\n  /** Every query for one CRUD entity: [service, entity]. Mutations invalidate this. */\n  entity(name: string): readonly [string, string];\n  /**\n   * One query: [service, entity?, method, protojson(req)]. Returns the\n   * per-request key FUNCTION, which is what both the query hook and any\n   * call-site prefetch/setQueryData use.\n   */\n  query<Schema extends DescMessage>(\n    method: string,\n    schema: Schema,\n    entityScope?: string,\n  ): (req: MessageInitShape<Schema>) => ServiceQueryKey;\n}\n\n/**\n * serviceKeys returns the builders for one service's query-key factory.\n *\n * Cache-key semantics are a compatibility contract, not an implementation\n * detail: an existing app's\n * `invalidateQueries({ queryKey: orderServiceKeys.order })` has to keep\n * matching the keys its queries were registered under across a version bump.\n * So the tuple order and contents produced here are fixed, and identical to\n * what forge previously inlined into every generated hook file.\n */\nexport function serviceKeys(service: string): ServiceKeyBuilders {\n  return {\n    all: [service] as const,\n    entity: (name: string) => [service, name] as const,\n    query:\n      <Schema extends DescMessage>(\n        method: string,\n        schema: Schema,\n        entityScope?: string,\n      ) =>\n      (req: MessageInitShape<Schema>): ServiceQueryKey =>\n        entityScope === undefined\n          ? ([service, method, requestKey(schema, req)] as const)\n          : ([service, entityScope, method, requestKey(schema, req)] as const),\n  };\n}\n\n/** A generated query hook: `useGetOrder(req, options?)`. */\nexport type ServiceQueryHook<Schema extends DescMessage, Response> = (\n  req: MessageInitShape<Schema>,\n  options?: Partial<UseQueryOptions<Response, ConnectClientError>>,\n) => UseQueryResult<Response, ConnectClientError>;\n\n/** A generated mutation hook: `useCreateOrder(options?)`. */\nexport type ServiceMutationHook<Schema extends DescMessage, Response> = (\n  options?: Partial<\n    UseMutationOptions<Response, ConnectClientError, MessageInitShape<Schema>>\n  >,\n) => UseMutationResult<Response, ConnectClientError, MessageInitShape<Schema>>;\n\n/**\n * createQueryHook builds one useQuery wrapper.\n *\n * The signature it returns is the one call sites already use — `(req,\n * options?)`, with the error typed as ConnectClientError rather than React\n * Query's default `Error`. That type is declared on the OPTIONS parameter\n * because React Query takes the result's error type from the same TError it\n * reads there, so `query.error` is a ConnectClientError at every call site\n * with nothing to pass. Typing it as `Error` hid `.reason`, `.codeName`, `.status`\n * and `.retryable`, and left `err.message.includes(...)` as the only\n * expression that compiled — the one thing the error contract forbids.\n */\nexport function createQueryHook<Schema extends DescMessage, Response>(\n  keyFor: (req: MessageInitShape<Schema>) => ServiceQueryKey,\n  call: (req: MessageInitShape<Schema>) => Promise<Response>,\n): ServiceQueryHook<Schema, Response> {\n  return (req, options) =>\n    useQuery({\n      queryKey: keyFor(req),\n      queryFn: () => call(req),\n      ...options,\n    });\n}\n\n/**\n * createMutationHook builds one useMutation wrapper with scoped invalidation.\n *\n * invalidateKey is the entity scope when the RPC maps to a CRUD entity, and\n * the whole-service scope otherwise — a bespoke mutation may touch anything,\n * so over-invalidating is the safe default there.\n *\n * The invalidation is composed BEFORE the caller's onSuccess and is never\n * replaced by it: onSuccess is destructured out and re-invoked after the\n * invalidate, while the rest of the options object is spread separately. A\n * caller passing onSuccess therefore ADDS behaviour, rather than silently\n * disabling the cache refresh — which is exactly what a plain `...options`\n * spread over a default onSuccess would do.\n */\nexport function createMutationHook<Schema extends DescMessage, Response>(\n  invalidateKey: ServiceQueryKey,\n  call: (req: MessageInitShape<Schema>) => Promise<Response>,\n): ServiceMutationHook<Schema, Response> {\n  return (options) => {\n    const queryClient = useQueryClient();\n    const { onSuccess, ...rest } = options ?? {};\n    return useMutation({\n      mutationFn: (req: MessageInitShape<Schema>) => call(req),\n      onSuccess: (...args) => {\n        queryClient.invalidateQueries({ queryKey: invalidateKey });\n        onSuccess?.(...args);\n      },\n      ...rest,\n    });\n  };\n}\n"]}
+{"version":3,"file":"service-hooks.js","sourceRoot":"","sources":["../src/service-hooks.ts"],"names":[],"mappings":"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","sourcesContent":["\"use client\";\n\n// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// Every export below is a React hook or builds one, so this module belongs in\n// the CLIENT graph. Without the directive the Next.js App Router compiles it\n// into the SERVER graph, where it binds a SECOND @tanstack/react-query\n// instance and every generated hook throws \"No QueryClient set\" at runtime —\n// invisible to tsc, eslint AND `next build`. published-surface.test.ts asserts\n// the directive survives into dist/. It is NOT applied package-wide: the\n// ./interceptors subpath exists to be importable without React.\n//\n// The React Query wrapper machinery behind forge's generated per-service hook\n// files (`src/hooks/<svc>-service-hooks_gen.ts`).\n//\n// WHAT WAS HERE BEFORE. Each generated file re-emitted the same three things\n// per RPC: a query-key entry, a useQuery or useMutation wrapper, and — for\n// mutations — the entity-scoped invalidateQueries plus the onSuccess\n// composition, with the reasoning for each re-inlined as comments. A\n// five-service project rendered five copies of machinery that differed only in\n// RPC names and message types. This module IS that machinery, written once.\n// The generated file keeps exactly what varies per RPC: the name, the request\n// schema, the response type, query-vs-mutation, and the entity scope.\n//\n// WHY A SUBPATH AND NOT THE BARREL. This module imports @tanstack/react-query.\n// Every browser frontend forge scaffolds depends on it — but the barrel is\n// also what a consumer imports for interceptors and errors alone, and\n// anchoring React Query there would make a non-React consumer resolve a\n// package it never installed. Same reasoning as ./mock-transport and ./otel:\n// an engine with its own dependency footprint gets its own entry point, and\n// React Query is an OPTIONAL peer.\n//\n// WHAT IT DELIBERATELY DOES NOT DO. It does not emit error toasts — the\n// app-wide MutationCache in src/lib/query-client.ts is the single error-toast\n// chokepoint, and pages that render errors inline pass\n// `meta: { silenceErrorToast: true }`. It never defaults success-side UX\n// either: \"CreateOrder succeeded\" leaks RPC names into the UI, so the toast /\n// redirect / inline confirmation stays the call site's via options.onSuccess.\nimport {\n  create,\n  toJson,\n  type DescMessage,\n  type MessageInitShape,\n} from \"@bufbuild/protobuf\";\nimport {\n  useInfiniteQuery,\n  useMutation,\n  useQuery,\n  useQueryClient,\n  type InfiniteData,\n  type UseInfiniteQueryOptions,\n  type UseInfiniteQueryResult,\n  type UseMutationOptions,\n  type UseMutationResult,\n  type UseQueryOptions,\n  type UseQueryResult,\n} from \"@tanstack/react-query\";\n\nimport type { ConnectClientError } from \"./errors.js\";\n\n/**\n * A generated query key. The tuple is [service, entity?, method,\n * protojson(req)] for a method key and [service] / [service, entity] for the\n * broader scopes.\n */\nexport type ServiceQueryKey = readonly unknown[];\n\n/**\n * requestKey projects a request init into protojson for use inside a query\n * key. Two reasons this is not the raw request object:\n *\n *   - React Query's default hasher is JSON.stringify, which THROWS on bigint\n *     fields (any proto int64) — the raw message crashes the cache.\n *   - protojson normalizes representations, so { id: 1 } and { id: \"1\" } land\n *     in ONE cache entry instead of silently splitting the cache.\n *\n * Exported because a hand-written hook that wants to share a generated hook's\n * cache entry has to hash its request the identical way.\n */\nexport function requestKey<Schema extends DescMessage>(\n  schema: Schema,\n  req: MessageInitShape<Schema>,\n): unknown {\n  return toJson(schema, create(schema, req));\n}\n\n/** The three key-scope builders a generated key factory is assembled from. */\nexport interface ServiceKeyBuilders {\n  /** Every query on this service: [service]. */\n  readonly all: readonly [string];\n  /** Every query for one CRUD entity: [service, entity]. Mutations invalidate this. */\n  entity(name: string): readonly [string, string];\n  /**\n   * One query: [service, entity?, method, protojson(req)]. Returns the\n   * per-request key FUNCTION, which is what both the query hook and any\n   * call-site prefetch/setQueryData use.\n   */\n  query<Schema extends DescMessage>(\n    method: string,\n    schema: Schema,\n    entityScope?: string,\n  ): (req: MessageInitShape<Schema>) => ServiceQueryKey;\n  /**\n   * One paged read: [service, entity?, method, protojson(req), \"infinite\"],\n   * where req is the request WITHOUT its page token — the hook owns the\n   * token, so every page of one listing shares one cache entry.\n   *\n   * It nests under the same scopes as `query`, so an entity or service-wide\n   * invalidation refetches it. The \"infinite\" suffix keeps it OFF the plain\n   * query's entry for the same request: an infinite query caches\n   * `{ pages, pageParams }`, not one response, and a plain hook reading that\n   * entry would get the wrong shape.\n   */\n  infinite<Schema extends DescMessage>(\n    method: string,\n    schema: Schema,\n    entityScope?: string,\n  ): (req: PageRequest<Schema>) => ServiceQueryKey;\n}\n\n/**\n * Omit distributed over a union. MessageInitShape is `Message | init\n * object`, and a plain Omit over a union keeps only the keys both members\n * share — which would silently drop every field from the init side.\n */\ntype DistributiveOmit<T, K extends PropertyKey> = T extends unknown\n  ? Omit<T, K>\n  : never;\n\n/**\n * The request a generated infinite hook takes: the rpc's request without\n * `pageToken`, which the hook supplies page by page.\n */\nexport type PageRequest<Schema extends DescMessage> = DistributiveOmit<\n  MessageInitShape<Schema>,\n  \"pageToken\"\n>;\n\n/**\n * The response shape forge's list-pagination convention (AIP-158) gives a\n * paged read: `string next_page_token`, empty on the last page. Optional so\n * an `optional string next_page_token` response satisfies it too.\n */\nexport interface PagedResponse {\n  nextPageToken?: string;\n}\n\n/**\n * pageRequestKey is requestKey with the page token dropped, so every page of\n * one listing hashes to one key even when a caller (JS, or a cast) passes a\n * token anyway. It is dropped from the protojson rather than from the init\n * object: a spread Message keeps its $typeName, and create() would hand that\n * token-less copy back as if it were a complete message.\n */\nfunction pageRequestKey<Schema extends DescMessage>(\n  schema: Schema,\n  req: PageRequest<Schema>,\n): unknown {\n  const json = requestKey(schema, req as unknown as MessageInitShape<Schema>);\n  if (json === null || typeof json !== \"object\" || Array.isArray(json)) {\n    return json;\n  }\n  const { pageToken: _pageToken, ...rest } = json as Record<string, unknown>;\n  return rest;\n}\n\n/**\n * serviceKeys returns the builders for one service's query-key factory.\n *\n * Cache-key semantics are a compatibility contract, not an implementation\n * detail: an existing app's\n * `invalidateQueries({ queryKey: orderServiceKeys.order })` has to keep\n * matching the keys its queries were registered under across a version bump.\n * So the tuple order and contents produced here are fixed, and identical to\n * what forge previously inlined into every generated hook file.\n */\nexport function serviceKeys(service: string): ServiceKeyBuilders {\n  return {\n    all: [service] as const,\n    entity: (name: string) => [service, name] as const,\n    query:\n      <Schema extends DescMessage>(\n        method: string,\n        schema: Schema,\n        entityScope?: string,\n      ) =>\n      (req: MessageInitShape<Schema>): ServiceQueryKey =>\n        entityScope === undefined\n          ? ([service, method, requestKey(schema, req)] as const)\n          : ([service, entityScope, method, requestKey(schema, req)] as const),\n    infinite:\n      <Schema extends DescMessage>(\n        method: string,\n        schema: Schema,\n        entityScope?: string,\n      ) =>\n      (req: PageRequest<Schema>): ServiceQueryKey =>\n        entityScope === undefined\n          ? ([\n              service,\n              method,\n              pageRequestKey(schema, req),\n              \"infinite\",\n            ] as const)\n          : ([\n              service,\n              entityScope,\n              method,\n              pageRequestKey(schema, req),\n              \"infinite\",\n            ] as const),\n  };\n}\n\n/**\n * How a generated file calls one rpc. `signal` is React Query's: a query\n * that is unmounted or superseded (a new key while typing) aborts its\n * request instead of letting it land on a cache entry nobody reads.\n */\nexport type ServiceCall<Schema extends DescMessage, Response> = (\n  req: MessageInitShape<Schema>,\n  signal?: AbortSignal,\n) => Promise<Response>;\n\n/**\n * A generated query hook: `useGetOrder(req, options?)`.\n *\n * TData is what the hook's `data` is, exactly as in React Query's own\n * useQuery: the response by default, or whatever `select` returns. A call\n * site mapping the proto response to a view model passes\n * `select: (r) => toView(r)` and gets `data: View` — no useMemo over `data`,\n * and React Query re-runs the mapping only when the response changes (or\n * when `select` itself does, so hoist it or wrap it in useCallback when it\n * is expensive). TData is inferred from `select` and is a parameter of the\n * HOOK, not of the factory, so every call site picks its own.\n */\nexport type ServiceQueryHook<Schema extends DescMessage, Response> = <\n  TData = Response,\n>(\n  req: MessageInitShape<Schema>,\n  options?: Partial<UseQueryOptions<Response, ConnectClientError, TData>>,\n) => UseQueryResult<TData, ConnectClientError>;\n\n/**\n * The options a generated infinite hook takes: React Query's own, minus the\n * four the hook owns — the key, the fetch, and the page-token plumbing.\n * `getNextPageParam` defaults to the response's `nextPageToken` (empty means\n * last page) and may be overridden; everything else (`select`,\n * `placeholderData`, `staleTime`, `enabled`, `maxPages`, …) passes through.\n */\nexport type ServiceInfiniteQueryOptions<Response, TData> = Partial<\n  Omit<\n    UseInfiniteQueryOptions<\n      Response,\n      ConnectClientError,\n      TData,\n      ServiceQueryKey,\n      string\n    >,\n    \"queryKey\" | \"queryFn\" | \"initialPageParam\"\n  >\n>;\n\n/**\n * A generated infinite-query hook: `useListOrdersInfinite(req, options?)`,\n * for a read that follows forge's list-pagination shape (`string page_token`\n * on the request, `string next_page_token` on the response).\n *\n * `req` is the first page's request without its token. `data` is React\n * Query's `{ pages, pageParams }` by default; `select` reshapes it, so\n * flattening the pages into one list is\n * `select: (d) => d.pages.flatMap((p) => p.orders)`.\n */\nexport type ServiceInfiniteQueryHook<\n  Schema extends DescMessage,\n  Response extends PagedResponse,\n> = <TData = InfiniteData<Response, string>>(\n  req: PageRequest<Schema>,\n  options?: ServiceInfiniteQueryOptions<Response, TData>,\n) => UseInfiniteQueryResult<TData, ConnectClientError>;\n\n/**\n * A generated mutation hook: `useCreateOrder(options?)`.\n *\n * TContext is React Query's fourth type parameter — what `onMutate` returns\n * and `onError` / `onSettled` receive back. It is a parameter of the HOOK,\n * not of the factory, so each call site gets its own: TypeScript infers it\n * from the `onMutate` the caller passes, and an optimistic update reads its\n * rollback off `context` with no cast. Fixing it at the factory (or leaving\n * it out, which pinned it to `unknown`) forced every such call site to\n * narrow `unknown` by hand. It defaults to `unknown`, so a call without\n * `onMutate` types exactly as before.\n */\nexport type ServiceMutationHook<Schema extends DescMessage, Response> = <\n  TContext = unknown,\n>(\n  options?: Partial<\n    UseMutationOptions<\n      Response,\n      ConnectClientError,\n      MessageInitShape<Schema>,\n      TContext\n    >\n  >,\n) => UseMutationResult<\n  Response,\n  ConnectClientError,\n  MessageInitShape<Schema>,\n  TContext\n>;\n\n/**\n * createQueryHook builds one useQuery wrapper.\n *\n * The signature it returns is the one call sites already use — `(req,\n * options?)`, with the error typed as ConnectClientError rather than React\n * Query's default `Error`. That type is declared on the OPTIONS parameter\n * because React Query takes the result's error type from the same TError it\n * reads there, so `query.error` is a ConnectClientError at every call site\n * with nothing to pass. Typing it as `Error` hid `.reason`, `.codeName`, `.status`\n * and `.retryable`, and left `err.message.includes(...)` as the only\n * expression that compiled — the one thing the error contract forbids.\n */\nexport function createQueryHook<Schema extends DescMessage, Response>(\n  keyFor: (req: MessageInitShape<Schema>) => ServiceQueryKey,\n  call: ServiceCall<Schema, Response>,\n): ServiceQueryHook<Schema, Response> {\n  return <TData = Response>(\n    req: MessageInitShape<Schema>,\n    options?: Partial<UseQueryOptions<Response, ConnectClientError, TData>>,\n  ) =>\n    useQuery<Response, ConnectClientError, TData>({\n      queryKey: keyFor(req),\n      queryFn: ({ signal }) => call(req, signal),\n      ...options,\n    });\n}\n\n/**\n * createInfiniteQueryHook builds one useInfiniteQuery wrapper over a paged\n * read.\n *\n * The page token is the hook's: the first page is fetched with the caller's\n * request as given (no token, so an `optional string page_token` stays\n * unset), each later one with the previous response's `nextPageToken`, and\n * an empty token ends the listing. The key is `keys.infinite(...)`, which\n * strips the token and sits under the service and entity scopes, so the\n * mutations that invalidate a plain list refetch this one too.\n *\n * The caller's options are spread BETWEEN the default getNextPageParam and\n * the four fields the hook owns: a caller may replace the default, never the\n * key or the fetch.\n */\nexport function createInfiniteQueryHook<\n  Schema extends DescMessage,\n  Response extends PagedResponse,\n>(\n  keyFor: (req: PageRequest<Schema>) => ServiceQueryKey,\n  call: ServiceCall<Schema, Response>,\n): ServiceInfiniteQueryHook<Schema, Response> {\n  return <TData = InfiniteData<Response, string>>(\n    req: PageRequest<Schema>,\n    options?: ServiceInfiniteQueryOptions<Response, TData>,\n  ) =>\n    useInfiniteQuery<\n      Response,\n      ConnectClientError,\n      TData,\n      ServiceQueryKey,\n      string\n    >({\n      getNextPageParam: (last) => last.nextPageToken || undefined,\n      ...options,\n      queryKey: keyFor(req),\n      queryFn: ({ pageParam, signal }) =>\n        call(\n          (pageParam === \"\"\n            ? req\n            : {\n                ...req,\n                pageToken: pageParam,\n              }) as unknown as MessageInitShape<Schema>,\n          signal,\n        ),\n      initialPageParam: \"\",\n    });\n}\n\n/**\n * createMutationHook builds one useMutation wrapper with scoped invalidation.\n *\n * invalidateKey is the entity scope when the RPC maps to a CRUD entity, and\n * the whole-service scope otherwise — a bespoke mutation may touch anything,\n * so over-invalidating is the safe default there.\n *\n * The invalidation is composed BEFORE the caller's onSuccess and is never\n * replaced by it: onSuccess is destructured out and re-invoked after the\n * invalidate, while the rest of the options object is spread separately. A\n * caller passing onSuccess therefore ADDS behaviour, rather than silently\n * disabling the cache refresh — which is exactly what a plain `...options`\n * spread over a default onSuccess would do.\n */\nexport function createMutationHook<Schema extends DescMessage, Response>(\n  invalidateKey: ServiceQueryKey,\n  call: (req: MessageInitShape<Schema>) => Promise<Response>,\n): ServiceMutationHook<Schema, Response> {\n  return <TContext = unknown>(\n    options?: Partial<\n      UseMutationOptions<\n        Response,\n        ConnectClientError,\n        MessageInitShape<Schema>,\n        TContext\n      >\n    >,\n  ) => {\n    const queryClient = useQueryClient();\n    const { onSuccess, ...rest } = options ?? {};\n    return useMutation<\n      Response,\n      ConnectClientError,\n      MessageInitShape<Schema>,\n      TContext\n    >({\n      mutationFn: (req: MessageInitShape<Schema>) => call(req),\n      onSuccess: (...args) => {\n        queryClient.invalidateQueries({ queryKey: invalidateKey });\n        onSuccess?.(...args);\n      },\n      ...rest,\n    });\n  };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reliantlabs/forge-web-runtime",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "The forge frontend runtime: Connect interceptor stack, session, error boundary, toast queue, <Resource> container, W3C trace propagation and the HyperDX browser SDK wiring (errors, console, network, traces; replay off by default). The web twin of forge/pkg.",
   "license": "Apache-2.0",
   "//repository note": "REQUIRED for `npm publish --provenance`, not decoration. npm cross-checks this against the repository in the signed provenance statement and rejects the publish with a 422 if they disagree — an absent field reads as \"\" and fails that comparison. `directory` names the subdirectory this package lives in, so the provenance points at the real source. Omitting this is what made the first 0.3.1 publish fail AFTER the tarball had been signed and written to the sigstore transparency log.",