@7nohe/openapi-react-query-codegen 3.0.0-beta.1 → 3.0.0-beta.3

package/README.md

@@ -1,12 +1,62 @@
 # OpenAPI React Query Codegen
 
-> Code generator for creating [React Query (also known as TanStack Query)](https://tanstack.com/query) hooks based on your OpenAPI schema.
+> Code generator for [TanStack Query (React Query)](https://tanstack.com/query) based on your OpenAPI schema — `queryOptions` factories following the official TanStack Query v5 pattern, plus ready-to-use hooks, prefetch, ensure, suspense, and infinite query helpers.
 
 [![npm version](https://badge.fury.io/js/%407nohe%2Fopenapi-react-query-codegen.svg)](https://badge.fury.io/js/%407nohe%2Fopenapi-react-query-codegen)
 
+📖 **[Documentation](https://openapi-react-query-codegen.vercel.app)** · [Migrating to v3](https://openapi-react-query-codegen.vercel.app/guides/migrating-to-v3/)
+
 ## Features
 
-- Generates custom react hooks that use React Query's `useQuery`, `useSuspenseQuery`, `useMutation` and `useInfiniteQuery` hooks
-- Generates custom functions that use React Query's `ensureQueryData` and `prefetchQuery` functions
-- Generates query keys and functions for query caching
-- Generates pure TypeScript clients generated by [@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts)
+- **`queryOptions` / `infiniteQueryOptions` factories** for every GET operation — the [TanStack Query v5 recommended pattern](https://tanstack.com/query/latest/docs/framework/react/guides/query-options), composable with `useQuery`, `useQueries`, `useSuspenseQuery`, `prefetchQuery`, `ensureQueryData`, and `setQueryData` with full type safety
+- **Custom hooks**: `useQuery`, `useSuspenseQuery`, `useMutation`, `useInfiniteQuery`, and `useSuspenseInfiniteQuery` variants per operation
+- **SSR helpers**: `prefetchQuery`, `prefetchInfiniteQuery`, and `ensureQueryData` functions per operation — ready for Next.js App Router hydration
+- **Hierarchical query keys** with exported key constants and functions: invalidate one exact query, all infinite pages of an operation, or every cache entry of an operation with a single prefix
+- **Pure TypeScript clients** generated by [@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts) (fetch and axios)
+
+## Quick start
+
+```bash
+npm install -D @7nohe/openapi-react-query-codegen
+npx openapi-rq -i ./petstore.yaml
+```
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { findPetsOptions } from "./openapi/queries";
+
+function Pets() {
+  const { data } = useQuery(findPetsOptions({ query: { limit: 10 } }));
+  // ...or use the generated hook directly: useFindPets({ query: { limit: 10 } })
+}
+```
+
+See the [documentation](https://openapi-react-query-codegen.vercel.app) for CLI options, SSR recipes, and infinite query usage.
+
+## How it compares
+
+|  | This library | @hey-api tanstack-query plugin | Orval |
+|---|---|---|---|
+| `queryOptions` / `infiniteQueryOptions` factories (TanStack v5 pattern) | ✅ | ✅ | ❌ |
+| Ready-to-use hooks (`useQuery` / suspense / infinite variants) | ✅ | ❌ (options only) | ✅ |
+| SSR helpers (`prefetchQuery` / `prefetchInfiniteQuery` / `ensureQueryData`) | ✅ | ❌ | Partial (`usePrefetch`) |
+| Hierarchical query keys for granular invalidation | ✅ | ✅ (tags) | Partial |
+| Stable release line | ✅ SemVer | pre-1.0, frequent breaking changes | ✅ |
+| MSW mock generation | ❌ (out of scope) | ❌ | ✅ |
+| Vue / Solid / Svelte / Angular | ❌ React-focused | ✅ | ✅ |
+
+**Scope**: this library is deliberately React-focused and does not generate API mocks — use Orval if MSW mocks are your priority, or hey-api's own plugin if you need non-React frameworks.
+
+## Stability policy
+
+This library builds on [@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts), which is pre-1.0 and moves fast. We **pin the exact hey-api version** and absorb its breaking changes for you: hey-api upgrades land here only after our full snapshot-test suite passes, and are released as minor versions. Your generated API surface follows SemVer — breaking output changes only happen in major versions, with a migration guide.
+
+## Requirements
+
+- Node.js 22.18+
+- `@tanstack/react-query` 5.x (peer dependency)
+- `typescript` 5.x or 6.x, `ts-morph` 28.x, `commander` 12–15 (peer dependencies)
+
+## License
+
+MIT

package/dist/constants.mjs

@@ -5,6 +5,7 @@ export const serviceFileName = "sdk.gen";
 export const modelsFileName = "types.gen";
 export const OpenApiRqFiles = {
     queries: "queries",
+    queryOptions: "queryOptions",
     infiniteQueries: "infiniteQueries",
     common: "common",
     suspense: "suspense",

package/dist/tsmorph/buildCommon.mjs

@@ -117,3 +117,72 @@ export function buildMutationKeyFn(op) {
         ],
     };
 }
+/**
+ * Build the client options type for infinite queries.
+ * The page parameter is excluded because TanStack Query supplies it via the
+ * pageParam mechanism (#140).
+ * Example:
+ * export type FindPaginatedPetsInfiniteClientOptions = Omit<Options<FindPaginatedPetsData, true>, "query"> &
+ *   { query?: Omit<NonNullable<FindPaginatedPetsData["query"]>, "page"> };
+ */
+export function buildInfiniteClientOptionsType(op, ctx) {
+    const dataTypeName = ctx.modelNames.includes(`${op.capitalizedMethodName}Data`)
+        ? `${op.capitalizedMethodName}Data`
+        : "unknown";
+    const type = dataTypeName === "unknown"
+        ? "Options<unknown, true>"
+        : `Omit<Options<${dataTypeName}, true>, "query"> & { query?: Omit<NonNullable<${dataTypeName}["query"]>, "${ctx.pageParam}"> }`;
+    return {
+        kind: StructureKind.TypeAlias,
+        isExported: true,
+        name: `${op.capitalizedMethodName}InfiniteClientOptions`,
+        type,
+    };
+}
+/**
+ * Build the infinite query key constant.
+ * Shares the plain query key as its first segment so a single
+ * `invalidateQueries({ queryKey: [useXKey] })` matches both the plain and the
+ * infinite cache entries of an operation (#174), while the extra "infinite"
+ * segment keeps cached InfiniteData from colliding with plain query data (#140).
+ * Example: export const useFindPaginatedPetsInfiniteKey = [useFindPaginatedPetsKey, "infinite"] as const;
+ */
+export function buildInfiniteQueryKeyConst(op) {
+    return {
+        kind: StructureKind.VariableStatement,
+        isExported: true,
+        declarationKind: VariableDeclarationKind.Const,
+        declarations: [
+            {
+                name: `use${op.capitalizedMethodName}InfiniteKey`,
+                initializer: `[use${op.capitalizedMethodName}Key, "infinite"] as const`,
+            },
+        ],
+    };
+}
+/**
+ * Build the infinite query key function.
+ * The custom queryKey argument only replaces the params segment — the
+ * hierarchical [opKey, "infinite"] prefix is always preserved so
+ * prefix-based invalidation keeps working.
+ * Example: export const UseFindPaginatedPetsInfiniteKeyFn = (clientOptions: FindPaginatedPetsInfiniteClientOptions = {}, queryKey?: Array<unknown>) =>
+ *   [...useFindPaginatedPetsInfiniteKey, ...(queryKey ?? [clientOptions])];
+ */
+export function buildInfiniteQueryKeyFn(op) {
+    const defaultValue = op.allParamsOptional ? " = {}" : "";
+    const params = [
+        `clientOptions: ${op.capitalizedMethodName}InfiniteClientOptions${defaultValue}`,
+        "queryKey?: Array<unknown>",
+    ];
+    return {
+        kind: StructureKind.VariableStatement,
+        isExported: true,
+        declarationKind: VariableDeclarationKind.Const,
+        declarations: [
+            {
+                name: `Use${op.capitalizedMethodName}InfiniteKeyFn`,
+                initializer: `(${params.join(", ")}) => [...use${op.capitalizedMethodName}InfiniteKey, ...(queryKey ?? [clientOptions])]`,
+            },
+        ],
+    };
+}

package/dist/tsmorph/buildMutationHooks.mjs

@@ -1,4 +1,5 @@
 import { StructureKind, VariableDeclarationKind, } from "ts-morph";
+import { SDK_CALL_ARGS } from "./buildQueryHooks.mjs";
 /**
  * Get the error type string based on client type.
  */
@@ -33,7 +34,7 @@ export function buildUseMutationHook(op, ctx) {
         ? `${op.capitalizedMethodName}Data`
         : "unknown";
     const optionsType = `Options<${dataTypeName}, true>`;
-    const mutationFn = `clientOptions => ${op.methodName}(clientOptions) as unknown as Promise<TData>`;
+    const mutationFn = `clientOptions => ${op.methodName}(${SDK_CALL_ARGS}) as unknown as Promise<TData>`;
     const body = `useMutation<TData, TError, ${optionsType}, TContext>({ mutationKey: Common.Use${op.capitalizedMethodName}KeyFn(mutationKey), mutationFn: ${mutationFn}, ...options })`;
     return {
         kind: StructureKind.VariableStatement,

package/dist/tsmorph/buildQueryHooks.mjs

@@ -14,38 +14,26 @@ function getErrorType(op, ctx) {
     return errorType;
 }
 /**
- * Get the data type based on hook type.
+ * Resolve the generated Data type name for an operation, falling back to
+ * unknown when the operation has no generated Data type.
  */
-function getDataTypeDefault(op, hookType) {
-    const baseType = `Common.${op.capitalizedMethodName}DefaultResponse`;
-    if (hookType === "useSuspenseQuery") {
-        return `NonNullable<${baseType}>`;
-    }
-    if (hookType === "useInfiniteQuery") {
-        return `InfiniteData<${baseType}>`;
-    }
-    return baseType;
+export function getDataTypeName(op, ctx) {
+    return ctx.modelNames.includes(`${op.capitalizedMethodName}Data`)
+        ? `${op.capitalizedMethodName}Data`
+        : "unknown";
 }
 /**
- * Get the options type name.
+ * SDK call arguments shared by every generated queryFn/mutationFn.
+ * throwOnError: true forces the SDK call to reject on error responses; the
+ * hey-api runtime default is false, which would resolve undefined data and
+ * swallow the error instead of surfacing it to TanStack Query (#172).
  */
-function getOptionsTypeName(hookType) {
-    switch (hookType) {
-        case "useSuspenseQuery":
-            return "UseSuspenseQueryOptions";
-        case "useInfiniteQuery":
-            return "UseInfiniteQueryOptions";
-        default:
-            return "UseQueryOptions";
-    }
-}
+export const SDK_CALL_ARGS = "{ ...clientOptions, throwOnError: true }";
 /**
  * Build the client options parameter string.
  */
-function buildClientOptionsParam(op, ctx) {
-    const dataTypeName = ctx.modelNames.includes(`${op.capitalizedMethodName}Data`)
-        ? `${op.capitalizedMethodName}Data`
-        : "unknown";
+export function buildClientOptionsParam(op, ctx) {
+    const dataTypeName = getDataTypeName(op, ctx);
     const hasParams = op.parameters.length > 0;
     if (!hasParams) {
         return `clientOptions: Options<${dataTypeName}, true> = {}`;
@@ -53,6 +41,62 @@ function buildClientOptionsParam(op, ctx) {
     const defaultValue = op.allParamsOptional ? " = {}" : "";
     return `clientOptions: Options<${dataTypeName}, true>${defaultValue}`;
 }
+/**
+ * Build the clientOptions parameter typed with the page-less infinite
+ * options type — the page parameter is supplied by TanStack Query's
+ * pageParam mechanism.
+ */
+export function buildInfiniteClientOptionsParam(op) {
+    const defaultValue = op.allParamsOptional ? " = {}" : "";
+    return `clientOptions: Common.${op.capitalizedMethodName}InfiniteClientOptions${defaultValue}`;
+}
+/**
+ * Build the paginated SDK call shared by every infinite query builder.
+ */
+export function buildPagedQueryFn(op, ctx, castTData) {
+    const dataTypeName = getDataTypeName(op, ctx);
+    const thenClause = castTData
+        ? ".then(response => response.data as TData) as TData"
+        : ".then(response => response.data)";
+    return `({ pageParam }) => ${op.methodName}({ ...clientOptions, query: { ...clientOptions.query, ${ctx.pageParam}: pageParam as number }, throwOnError: true } as Options<${dataTypeName}, true>)${thenClause}`;
+}
+/**
+ * Format the initialPageParam literal. Emits a numeric literal when possible
+ * so the inferred pageParam type matches what getNextPageParam returns.
+ */
+export function formatInitialPageParam(ctx) {
+    return /^-?\d+$/.test(ctx.initialPageParam)
+        ? ctx.initialPageParam
+        : JSON.stringify(ctx.initialPageParam);
+}
+/**
+ * Build the nested type for getNextPageParam.
+ * E.g., "meta.next" becomes "{ meta: { next: number } }"
+ */
+export function buildNestedNextPageType(nextPageParam) {
+    const segments = nextPageParam.split(".");
+    return segments.reduceRight((acc, segment) => {
+        return `{ ${segment}: ${acc} }`;
+    }, "number");
+}
+/**
+ * Build the getNextPageParam expression. The parameter is annotated because
+ * not every TanStack entry point contextually types it (prefetchInfiniteQuery
+ * does not, which would fail noImplicitAny).
+ */
+export function buildGetNextPageParamExpr(ctx) {
+    const nestedType = buildNestedNextPageType(ctx.nextPageParam);
+    return `(response: unknown) => (response as ${nestedType}).${ctx.nextPageParam}`;
+}
+/**
+ * Build an options type where the pagination fields TanStack Query marks as
+ * required become optional overrides: the generator supplies them, and
+ * callers may replace them for custom pagination schemes (#156, #146).
+ */
+export function buildOverridableInfiniteOptionsType(optionsTypeName) {
+    const instantiated = `${optionsTypeName}<TData, TError>`;
+    return `Omit<${instantiated}, "queryKey" | "queryFn" | "initialPageParam" | "getNextPageParam"> & Partial<Pick<${instantiated}, "initialPageParam" | "getNextPageParam">>`;
+}
 /**
  * Build useQuery hook.
  * Example:
@@ -62,19 +106,16 @@ function buildClientOptionsParam(op, ctx) {
  *   options?: Omit<UseQueryOptions<TData, TError>, "queryKey" | "queryFn">
  * ) => useQuery<TData, TError>({
  *   queryKey: Common.UseFindPetsKeyFn(clientOptions, queryKey),
- *   queryFn: () => findPets({ ...clientOptions }).then(response => response.data as TData) as TData,
+ *   queryFn: () => findPets({ ...clientOptions, throwOnError: true }).then(response => response.data as TData) as TData,
  *   ...options
  * });
  */
 export function buildUseQueryHook(op, ctx) {
     const hookName = `use${op.capitalizedMethodName}`;
     const errorType = getErrorType(op, ctx);
-    const dataTypeDefault = getDataTypeDefault(op, "useQuery");
+    const dataTypeDefault = `Common.${op.capitalizedMethodName}DefaultResponse`;
     const clientOptionsParam = buildClientOptionsParam(op, ctx);
-    const hasParams = op.parameters.length > 0;
-    // Build the queryFn body
-    const callArgs = hasParams ? "{ ...clientOptions }" : "{ ...clientOptions }";
-    const queryFn = `() => ${op.methodName}(${callArgs}).then(response => response.data as TData) as TData`;
+    const queryFn = `() => ${op.methodName}(${SDK_CALL_ARGS}).then(response => response.data as TData) as TData`;
     const body = `useQuery<TData, TError>({ queryKey: Common.Use${op.capitalizedMethodName}KeyFn(clientOptions, queryKey), queryFn: ${queryFn}, ...options })`;
     return {
         kind: StructureKind.VariableStatement,
@@ -96,11 +137,9 @@ export function buildUseQueryHook(op, ctx) {
 export function buildUseSuspenseQueryHook(op, ctx) {
     const hookName = `use${op.capitalizedMethodName}Suspense`;
     const errorType = getErrorType(op, ctx);
-    const dataTypeDefault = getDataTypeDefault(op, "useSuspenseQuery");
+    const dataTypeDefault = `NonNullable<Common.${op.capitalizedMethodName}DefaultResponse>`;
     const clientOptionsParam = buildClientOptionsParam(op, ctx);
-    const hasParams = op.parameters.length > 0;
-    const callArgs = hasParams ? "{ ...clientOptions }" : "{ ...clientOptions }";
-    const queryFn = `() => ${op.methodName}(${callArgs}).then(response => response.data as TData) as TData`;
+    const queryFn = `() => ${op.methodName}(${SDK_CALL_ARGS}).then(response => response.data as TData) as TData`;
     const body = `useSuspenseQuery<TData, TError>({ queryKey: Common.Use${op.capitalizedMethodName}KeyFn(clientOptions, queryKey), queryFn: ${queryFn}, ...options })`;
     return {
         kind: StructureKind.VariableStatement,
@@ -117,38 +156,30 @@ export function buildUseSuspenseQueryHook(op, ctx) {
     };
 }
 /**
- * Build the nested type for getNextPageParam.
- * E.g., "meta.next" becomes "{ meta: { next: number } }"
+ * Build a useInfiniteQuery / useSuspenseInfiniteQuery hook. Both variants
+ * share the infinite query key (and therefore the cache); they differ only
+ * in the TanStack hook called, the options type, and the NonNullable TData
+ * default of the suspense variant.
  */
-function buildNestedNextPageType(nextPageParam) {
-    const segments = nextPageParam.split(".");
-    return segments.reduceRight((acc, segment) => {
-        return `{ ${segment}: ${acc} }`;
-    }, "number");
-}
-/**
- * Build useInfiniteQuery hook.
- */
-export function buildUseInfiniteQueryHook(op, ctx) {
+function buildInfiniteHook(op, ctx, suspense) {
     if (!op.isPaginatable) {
         return null;
     }
-    const hookName = `use${op.capitalizedMethodName}Infinite`;
+    const hookCall = suspense ? "useSuspenseInfiniteQuery" : "useInfiniteQuery";
+    const optionsTypeName = suspense
+        ? "UseSuspenseInfiniteQueryOptions"
+        : "UseInfiniteQueryOptions";
+    const hookName = suspense
+        ? `use${op.capitalizedMethodName}SuspenseInfinite`
+        : `use${op.capitalizedMethodName}Infinite`;
     const errorType = getErrorType(op, ctx);
     const baseDataType = `Common.${op.capitalizedMethodName}DefaultResponse`;
-    const dataTypeName = ctx.modelNames.includes(`${op.capitalizedMethodName}Data`)
-        ? `${op.capitalizedMethodName}Data`
-        : "unknown";
-    const defaultValue = op.allParamsOptional ? " = {}" : "";
-    const clientOptionsParam = `clientOptions: Options<${dataTypeName}, true>${defaultValue}`;
-    // Build the queryFn with pageParam handling
-    const queryFn = `({ pageParam }) => ${op.methodName}({ ...clientOptions, query: { ...clientOptions.query, ${ctx.pageParam}: pageParam as number } }).then(response => response.data as TData) as TData`;
-    // Build getNextPageParam with nested type
-    const nestedType = buildNestedNextPageType(ctx.nextPageParam);
-    const getNextPageParam = `getNextPageParam: (response) => (response as ${nestedType}).${ctx.nextPageParam}`;
-    // initialPageParam is a string literal
-    const infiniteOptions = `initialPageParam: "${ctx.initialPageParam}", ${getNextPageParam}`;
-    const body = `useInfiniteQuery({ queryKey: Common.Use${op.capitalizedMethodName}KeyFn(clientOptions, queryKey), queryFn: ${queryFn}, ${infiniteOptions}, ...options })`;
+    const dataTypeDefault = suspense
+        ? `InfiniteData<NonNullable<${baseDataType}>>`
+        : `InfiniteData<${baseDataType}>`;
+    const queryFn = buildPagedQueryFn(op, ctx, true);
+    const infiniteOptions = `initialPageParam: ${formatInitialPageParam(ctx)}, getNextPageParam: ${buildGetNextPageParamExpr(ctx)}`;
+    const body = `${hookCall}({ queryKey: Common.Use${op.capitalizedMethodName}InfiniteKeyFn(clientOptions, queryKey), queryFn: ${queryFn}, ${infiniteOptions}, ...options })`;
     return {
         kind: StructureKind.VariableStatement,
         // Copy the operation's JSDoc (description and @deprecated) from the SDK function
@@ -158,33 +189,38 @@ export function buildUseInfiniteQueryHook(op, ctx) {
         declarations: [
             {
                 name: hookName,
-                initializer: `<TData = InfiniteData<${baseDataType}>, TError = ${errorType}, TQueryKey extends Array<unknown> = unknown[]>(${clientOptionsParam}, queryKey?: TQueryKey, options?: Omit<UseInfiniteQueryOptions<TData, TError>, "queryKey" | "queryFn">) => ${body}`,
+                initializer: `<TData = ${dataTypeDefault}, TError = ${errorType}, TQueryKey extends Array<unknown> = unknown[]>(${buildInfiniteClientOptionsParam(op)}, queryKey?: TQueryKey, options?: ${buildOverridableInfiniteOptionsType(optionsTypeName)}) => ${body}`,
             },
         ],
     };
 }
+/**
+ * Build useInfiniteQuery hook.
+ */
+export function buildUseInfiniteQueryHook(op, ctx) {
+    return buildInfiniteHook(op, ctx, false);
+}
+/**
+ * Build useSuspenseInfiniteQuery hook.
+ */
+export function buildUseSuspenseInfiniteQueryHook(op, ctx) {
+    return buildInfiniteHook(op, ctx, true);
+}
 /**
  * Build prefetch function.
  * Example:
- * export const prefetchUseFindPets = (queryClient: QueryClient, clientOptions: Options<FindPetsData, true> = {}) =>
+ * export const prefetchUseFindPets = (queryClient: QueryClient, clientOptions: Options<FindPetsData, true> = {}, options?: Omit<FetchQueryOptions<Common.FindPetsDefaultResponse>, "queryKey" | "queryFn">) =>
  *   queryClient.prefetchQuery({
  *     queryKey: Common.UseFindPetsKeyFn(clientOptions),
- *     queryFn: () => findPets({ ...clientOptions }).then(response => response.data)
+ *     queryFn: () => findPets({ ...clientOptions, throwOnError: true }).then(response => response.data),
+ *     ...options
  *   });
  */
 export function buildPrefetchFn(op, ctx) {
     const fnName = `prefetchUse${op.capitalizedMethodName}`;
-    const dataTypeName = ctx.modelNames.includes(`${op.capitalizedMethodName}Data`)
-        ? `${op.capitalizedMethodName}Data`
-        : "unknown";
-    const hasParams = op.parameters.length > 0;
-    const defaultValue = op.allParamsOptional ? " = {}" : "";
-    const clientOptionsParam = hasParams
-        ? `clientOptions: Options<${dataTypeName}, true>${defaultValue}`
-        : `clientOptions: Options<${dataTypeName}, true> = {}`;
-    const callArgs = "{ ...clientOptions }";
-    const queryFn = `() => ${op.methodName}(${callArgs}).then(response => response.data)`;
-    const body = `queryClient.prefetchQuery({ queryKey: Common.Use${op.capitalizedMethodName}KeyFn(clientOptions), queryFn: ${queryFn} })`;
+    const queryFn = `() => ${op.methodName}(${SDK_CALL_ARGS}).then(response => response.data)`;
+    const optionsParam = `options?: Omit<FetchQueryOptions<Common.${op.capitalizedMethodName}DefaultResponse>, "queryKey" | "queryFn">`;
+    const body = `queryClient.prefetchQuery({ queryKey: Common.Use${op.capitalizedMethodName}KeyFn(clientOptions), queryFn: ${queryFn}, ...options })`;
     return {
         kind: StructureKind.VariableStatement,
         // Copy the operation's JSDoc (description and @deprecated) from the SDK function
@@ -194,7 +230,42 @@ export function buildPrefetchFn(op, ctx) {
         declarations: [
             {
                 name: fnName,
-                initializer: `(queryClient: QueryClient, ${clientOptionsParam}) => ${body}`,
+                initializer: `(queryClient: QueryClient, ${buildClientOptionsParam(op, ctx)}, ${optionsParam}) => ${body}`,
+            },
+        ],
+    };
+}
+/**
+ * Build prefetchInfiniteQuery function for a paginatable operation.
+ * Example:
+ * export const prefetchUseFindPaginatedPetsInfinite = (queryClient: QueryClient, clientOptions: Common.FindPaginatedPetsInfiniteClientOptions = {}, options?: Omit<FetchInfiniteQueryOptions<Common.FindPaginatedPetsDefaultResponse>, "queryKey" | "queryFn" | "initialPageParam" | "getNextPageParam">) =>
+ *   queryClient.prefetchInfiniteQuery({
+ *     queryKey: Common.UseFindPaginatedPetsInfiniteKeyFn(clientOptions),
+ *     queryFn: ({ pageParam }) => findPaginatedPets({ ...clientOptions, query: { ...clientOptions.query, page: pageParam as number }, throwOnError: true } as Options<FindPaginatedPetsData, true>).then(response => response.data),
+ *     initialPageParam: 1,
+ *     getNextPageParam: (response: unknown) => (response as { nextPage: number }).nextPage,
+ *     ...options
+ *   });
+ */
+export function buildPrefetchInfiniteQueryFn(op, ctx) {
+    if (!op.isPaginatable) {
+        return null;
+    }
+    const fnName = `prefetchUse${op.capitalizedMethodName}Infinite`;
+    const queryFn = buildPagedQueryFn(op, ctx, false);
+    const infiniteOptions = `initialPageParam: ${formatInitialPageParam(ctx)}, getNextPageParam: ${buildGetNextPageParamExpr(ctx)}`;
+    const optionsParam = `options?: Omit<FetchInfiniteQueryOptions<Common.${op.capitalizedMethodName}DefaultResponse>, "queryKey" | "queryFn" | "initialPageParam" | "getNextPageParam">`;
+    const body = `queryClient.prefetchInfiniteQuery({ queryKey: Common.Use${op.capitalizedMethodName}InfiniteKeyFn(clientOptions), queryFn: ${queryFn}, ${infiniteOptions}, ...options })`;
+    return {
+        kind: StructureKind.VariableStatement,
+        // Copy the operation's JSDoc (description and @deprecated) from the SDK function
+        leadingTrivia: op.jsDoc ? `${op.jsDoc}\n` : undefined,
+        isExported: true,
+        declarationKind: VariableDeclarationKind.Const,
+        declarations: [
+            {
+                name: fnName,
+                initializer: `(queryClient: QueryClient, ${buildInfiniteClientOptionsParam(op)}, ${optionsParam}) => ${body}`,
             },
         ],
     };
@@ -202,25 +273,18 @@ export function buildPrefetchFn(op, ctx) {
 /**
  * Build ensureQueryData function.
  * Example:
- * export const ensureUseFindPetsData = (queryClient: QueryClient, clientOptions: Options<FindPetsData, true> = {}) =>
+ * export const ensureUseFindPetsData = (queryClient: QueryClient, clientOptions: Options<FindPetsData, true> = {}, options?: Omit<EnsureQueryDataOptions<Common.FindPetsDefaultResponse>, "queryKey" | "queryFn">) =>
  *   queryClient.ensureQueryData({
  *     queryKey: Common.UseFindPetsKeyFn(clientOptions),
- *     queryFn: () => findPets({ ...clientOptions }).then(response => response.data)
+ *     queryFn: () => findPets({ ...clientOptions, throwOnError: true }).then(response => response.data),
+ *     ...options
  *   });
  */
 export function buildEnsureQueryDataFn(op, ctx) {
     const fnName = `ensureUse${op.capitalizedMethodName}Data`;
-    const dataTypeName = ctx.modelNames.includes(`${op.capitalizedMethodName}Data`)
-        ? `${op.capitalizedMethodName}Data`
-        : "unknown";
-    const hasParams = op.parameters.length > 0;
-    const defaultValue = op.allParamsOptional ? " = {}" : "";
-    const clientOptionsParam = hasParams
-        ? `clientOptions: Options<${dataTypeName}, true>${defaultValue}`
-        : `clientOptions: Options<${dataTypeName}, true> = {}`;
-    const callArgs = "{ ...clientOptions }";
-    const queryFn = `() => ${op.methodName}(${callArgs}).then(response => response.data)`;
-    const body = `queryClient.ensureQueryData({ queryKey: Common.Use${op.capitalizedMethodName}KeyFn(clientOptions), queryFn: ${queryFn} })`;
+    const queryFn = `() => ${op.methodName}(${SDK_CALL_ARGS}).then(response => response.data)`;
+    const optionsParam = `options?: Omit<EnsureQueryDataOptions<Common.${op.capitalizedMethodName}DefaultResponse>, "queryKey" | "queryFn">`;
+    const body = `queryClient.ensureQueryData({ queryKey: Common.Use${op.capitalizedMethodName}KeyFn(clientOptions), queryFn: ${queryFn}, ...options })`;
     return {
         kind: StructureKind.VariableStatement,
         // Copy the operation's JSDoc (description and @deprecated) from the SDK function
@@ -230,7 +294,7 @@ export function buildEnsureQueryDataFn(op, ctx) {
         declarations: [
             {
                 name: fnName,
-                initializer: `(queryClient: QueryClient, ${clientOptionsParam}) => ${body}`,
+                initializer: `(queryClient: QueryClient, ${buildClientOptionsParam(op, ctx)}, ${optionsParam}) => ${body}`,
             },
         ],
     };

package/dist/tsmorph/buildQueryOptions.mjs

@@ -0,0 +1,67 @@
+import { StructureKind, VariableDeclarationKind, } from "ts-morph";
+import { buildClientOptionsParam, buildGetNextPageParamExpr, buildInfiniteClientOptionsParam, buildPagedQueryFn, formatInitialPageParam, SDK_CALL_ARGS, } from "./buildQueryHooks.mjs";
+/**
+ * Build a queryOptions factory for a GET operation.
+ * The factory centralizes queryKey and queryFn so they can be reused with
+ * every TanStack Query utility (useQuery, useQueries, prefetchQuery,
+ * ensureQueryData, setQueryData, ...) with full type safety.
+ * Example:
+ * export const findPetsOptions = (clientOptions: Options<FindPetsData, true> = {}, queryKey?: Array<unknown>) =>
+ *   queryOptions({
+ *     queryKey: Common.UseFindPetsKeyFn(clientOptions, queryKey),
+ *     queryFn: () => findPets({ ...clientOptions, throwOnError: true }).then(response => response.data),
+ *   });
+ */
+export function buildQueryOptionsFn(op, ctx) {
+    const fnName = `${op.methodName}Options`;
+    const clientOptionsParam = buildClientOptionsParam(op, ctx);
+    const queryFn = `() => ${op.methodName}(${SDK_CALL_ARGS}).then(response => response.data)`;
+    const body = `queryOptions({ queryKey: Common.Use${op.capitalizedMethodName}KeyFn(clientOptions, queryKey), queryFn: ${queryFn} })`;
+    return {
+        kind: StructureKind.VariableStatement,
+        // Copy the operation's JSDoc (description and @deprecated) from the SDK function
+        leadingTrivia: op.jsDoc ? `${op.jsDoc}\n` : undefined,
+        isExported: true,
+        declarationKind: VariableDeclarationKind.Const,
+        declarations: [
+            {
+                name: fnName,
+                initializer: `(${clientOptionsParam}, queryKey?: Array<unknown>) => ${body}`,
+            },
+        ],
+    };
+}
+/**
+ * Build an infiniteQueryOptions factory for a paginatable GET operation.
+ * Uses the dedicated infinite query key and page-less options type.
+ * Example:
+ * export const findPaginatedPetsInfiniteOptions = (clientOptions: Common.FindPaginatedPetsInfiniteClientOptions = {}, queryKey?: Array<unknown>) =>
+ *   infiniteQueryOptions({
+ *     queryKey: Common.UseFindPaginatedPetsInfiniteKeyFn(clientOptions, queryKey),
+ *     queryFn: ({ pageParam }) => findPaginatedPets({ ...clientOptions, query: { ...clientOptions.query, page: pageParam as number }, throwOnError: true } as Options<FindPaginatedPetsData, true>).then(response => response.data),
+ *     initialPageParam: 1,
+ *     getNextPageParam: (response: unknown) => (response as { nextPage: number }).nextPage,
+ *   });
+ */
+export function buildInfiniteQueryOptionsFn(op, ctx) {
+    if (!op.isPaginatable) {
+        return null;
+    }
+    const fnName = `${op.methodName}InfiniteOptions`;
+    const queryFn = buildPagedQueryFn(op, ctx, false);
+    const infiniteOptions = `initialPageParam: ${formatInitialPageParam(ctx)}, getNextPageParam: ${buildGetNextPageParamExpr(ctx)}`;
+    const body = `infiniteQueryOptions({ queryKey: Common.Use${op.capitalizedMethodName}InfiniteKeyFn(clientOptions, queryKey), queryFn: ${queryFn}, ${infiniteOptions} })`;
+    return {
+        kind: StructureKind.VariableStatement,
+        // Copy the operation's JSDoc (description and @deprecated) from the SDK function
+        leadingTrivia: op.jsDoc ? `${op.jsDoc}\n` : undefined,
+        isExported: true,
+        declarationKind: VariableDeclarationKind.Const,
+        declarations: [
+            {
+                name: fnName,
+                initializer: `(${buildInfiniteClientOptionsParam(op)}, queryKey?: Array<unknown>) => ${body}`,
+            },
+        ],
+    };
+}

package/dist/tsmorph/generateFiles.mjs

@@ -1,9 +1,9 @@
-import { StructureKind, } from "ts-morph";
 import { OpenApiRqFiles } from "../constants.mjs";
-import { buildDefaultResponseType, buildMutationKeyConst, buildMutationKeyFn, buildMutationResultType, buildQueryKeyConst, buildQueryKeyFn, buildQueryResultType, } from "./buildCommon.mjs";
+import { buildDefaultResponseType, buildInfiniteClientOptionsType, buildInfiniteQueryKeyConst, buildInfiniteQueryKeyFn, buildMutationKeyConst, buildMutationKeyFn, buildMutationResultType, buildQueryKeyConst, buildQueryKeyFn, buildQueryResultType, } from "./buildCommon.mjs";
 import { buildUseMutationHook } from "./buildMutationHooks.mjs";
-import { buildEnsureQueryDataFn, buildPrefetchFn, buildUseInfiniteQueryHook, buildUseQueryHook, buildUseSuspenseQueryHook, } from "./buildQueryHooks.mjs";
-import { buildAxiosErrorImport, buildClientImport, buildCommonImport, buildModelImport, buildQueryImport, buildServiceImport, createGenerationProject, } from "./projectFactory.mjs";
+import { buildEnsureQueryDataFn, buildPrefetchFn, buildPrefetchInfiniteQueryFn, buildUseInfiniteQueryHook, buildUseQueryHook, buildUseSuspenseInfiniteQueryHook, buildUseSuspenseQueryHook, } from "./buildQueryHooks.mjs";
+import { buildInfiniteQueryOptionsFn, buildQueryOptionsFn, } from "./buildQueryOptions.mjs";
+import { buildAxiosErrorImport, buildClientImport, buildCommonImport, buildModelImport, buildQueryImport, buildQueryOptionsImport, buildServiceImport, createGenerationProject, } from "./projectFactory.mjs";
 /**
  * Build imports for common.ts file.
  */
@@ -30,22 +30,10 @@ function buildHookFileImports(ctx) {
 }
 /**
  * Generate the index.ts file content.
+ * The content is constant, so no ts-morph project is needed.
  */
-function generateIndexFile(ctx) {
-    const project = createGenerationProject();
-    const sourceFile = project.createSourceFile(`${OpenApiRqFiles.index}.ts`, undefined, { overwrite: true });
-    const exports = [
-        {
-            kind: StructureKind.ExportDeclaration,
-            moduleSpecifier: "./common",
-        },
-        {
-            kind: StructureKind.ExportDeclaration,
-            moduleSpecifier: "./queries",
-        },
-    ];
-    sourceFile.addExportDeclarations(exports);
-    return sourceFile.getFullText();
+function generateIndexFile() {
+    return `export * from "./common";\nexport * from "./queries";\nexport * from "./queryOptions";\n`;
 }
 /**
  * Generate the common.ts file content.
@@ -65,6 +53,12 @@ function generateCommonFile(operations, ctx) {
         sourceFile.addVariableStatement(buildQueryKeyConst(op));
         sourceFile.addVariableStatement(buildQueryKeyFn(op, ctx));
     }
+    // Add dedicated infinite query types and keys for paginatable operations
+    for (const op of getOperations.filter((o) => o.isPaginatable)) {
+        sourceFile.addTypeAlias(buildInfiniteClientOptionsType(op, ctx));
+        sourceFile.addVariableStatement(buildInfiniteQueryKeyConst(op));
+        sourceFile.addVariableStatement(buildInfiniteQueryKeyFn(op));
+    }
     // Add mutation types and keys
     for (const op of mutationOperations) {
         sourceFile.addTypeAlias(buildMutationResultType(op));
@@ -94,6 +88,37 @@ function generateQueriesFile(operations, ctx) {
     }
     return sourceFile.getFullText();
 }
+/**
+ * Generate the queryOptions.ts file content.
+ */
+function generateQueryOptionsFile(operations, ctx) {
+    const project = createGenerationProject();
+    const sourceFile = project.createSourceFile(`${OpenApiRqFiles.queryOptions}.ts`, undefined, { overwrite: true });
+    // Add imports
+    const imports = [
+        buildCommonImport(),
+        buildQueryOptionsImport(),
+        buildClientImport(ctx),
+        buildServiceImport(ctx),
+    ];
+    const modelImport = buildModelImport(ctx);
+    if (modelImport) {
+        imports.push(modelImport);
+    }
+    sourceFile.addImportDeclarations(imports);
+    // Only GET operations have query options
+    const getOperations = operations.filter((op) => op.httpMethod === "GET");
+    for (const op of getOperations) {
+        sourceFile.addVariableStatement(buildQueryOptionsFn(op, ctx));
+    }
+    for (const op of getOperations) {
+        const infiniteOptions = buildInfiniteQueryOptionsFn(op, ctx);
+        if (infiniteOptions) {
+            sourceFile.addVariableStatement(infiniteOptions);
+        }
+    }
+    return sourceFile.getFullText();
+}
 /**
  * Generate the suspense.ts file content.
  */
@@ -108,6 +133,13 @@ function generateSuspenseFile(operations, ctx) {
     for (const op of getOperations) {
         sourceFile.addVariableStatement(buildUseSuspenseQueryHook(op, ctx));
     }
+    // Add useSuspenseInfiniteQuery hooks for paginatable operations
+    for (const op of getOperations.filter((o) => o.isPaginatable)) {
+        const hook = buildUseSuspenseInfiniteQueryHook(op, ctx);
+        if (hook) {
+            sourceFile.addVariableStatement(hook);
+        }
+    }
     return sourceFile.getFullText();
 }
 /**
@@ -143,6 +175,13 @@ function generatePrefetchFile(operations, ctx) {
     for (const op of getOperations) {
         sourceFile.addVariableStatement(buildPrefetchFn(op, ctx));
     }
+    // Add prefetchInfiniteQuery functions for paginatable operations
+    for (const op of getOperations.filter((o) => o.isPaginatable)) {
+        const fn = buildPrefetchInfiniteQueryFn(op, ctx);
+        if (fn) {
+            sourceFile.addVariableStatement(fn);
+        }
+    }
     return sourceFile.getFullText();
 }
 /**
@@ -175,7 +214,7 @@ export function generateAllFiles(operations, ctx) {
     return [
         {
             name: `${OpenApiRqFiles.index}.ts`,
-            content: addHeaderComment(generateIndexFile(ctx), ctx.version),
+            content: addHeaderComment(generateIndexFile(), ctx.version),
         },
         {
             name: `${OpenApiRqFiles.common}.ts`,
@@ -185,6 +224,10 @@ export function generateAllFiles(operations, ctx) {
             name: `${OpenApiRqFiles.queries}.ts`,
             content: addHeaderComment(generateQueriesFile(operations, ctx), ctx.version),
         },
+        {
+            name: `${OpenApiRqFiles.queryOptions}.ts`,
+            content: addHeaderComment(generateQueryOptionsFile(operations, ctx), ctx.version),
+        },
         {
             name: `${OpenApiRqFiles.suspense}.ts`,
             content: addHeaderComment(generateSuspenseFile(operations, ctx), ctx.version),

package/dist/tsmorph/index.mjs

@@ -1,5 +1,5 @@
-export { generateAllFiles } from "./generateFiles.mjs";
-export { createGenerationProject } from "./projectFactory.mjs";
 export * from "./buildCommon.mjs";
-export * from "./buildQueryHooks.mjs";
 export * from "./buildMutationHooks.mjs";
+export * from "./buildQueryHooks.mjs";
+export { generateAllFiles } from "./generateFiles.mjs";
+export { createGenerationProject } from "./projectFactory.mjs";

package/dist/tsmorph/projectFactory.mjs

@@ -41,17 +41,32 @@ export function buildQueryImport() {
             { name: "useQuery" },
             { name: "useSuspenseQuery" },
             { name: "useInfiniteQuery" },
+            { name: "useSuspenseInfiniteQuery" },
             { name: "useMutation" },
             { name: "UseQueryResult" },
             { name: "UseQueryOptions" },
             { name: "UseInfiniteQueryOptions" },
+            { name: "UseSuspenseInfiniteQueryOptions" },
             { name: "UseMutationOptions" },
             { name: "UseMutationResult" },
             { name: "UseSuspenseQueryOptions" },
             { name: "InfiniteData" },
+            { name: "FetchQueryOptions", isTypeOnly: true },
+            { name: "FetchInfiniteQueryOptions", isTypeOnly: true },
+            { name: "EnsureQueryDataOptions", isTypeOnly: true },
         ],
     };
 }
+/**
+ * Build import structure for the queryOptions/infiniteQueryOptions helpers.
+ */
+export function buildQueryOptionsImport() {
+    return {
+        kind: StructureKind.ImportDeclaration,
+        moduleSpecifier: "@tanstack/react-query",
+        namedImports: [{ name: "queryOptions" }, { name: "infiniteQueryOptions" }],
+    };
+}
 /**
  * Build import structure for services.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7nohe/openapi-react-query-codegen",
-  "version": "3.0.0-beta.1",
+  "version": "3.0.0-beta.3",
   "description": "OpenAPI React Query Codegen",
   "bin": {
     "openapi-rq": "dist/cli.mjs"
@@ -43,20 +43,22 @@
     "cross-spawn": "^7.0.3"
   },
   "devDependencies": {
-    "@biomejs/biome": "^1.9.3",
+    "@biomejs/biome": "^2.5.4",
     "@types/cross-spawn": "^6.0.6",
-    "@types/node": "^22.7.4",
+    "@types/node": "^22.20.1",
     "@types/semver": "^7.7.1",
-    "@vitest/coverage-v8": "^1.5.0",
-    "commander": "^12.0.0",
-    "lefthook": "^1.6.10",
-    "rimraf": "^5.0.5",
+    "@vitest/coverage-v8": "^4.1.10",
+    "commander": "^15.0.0",
+    "lefthook": "^2.1.10",
+    "rimraf": "^6.1.3",
     "ts-morph": "^28.0.0",
     "typescript": "^6.0.3",
-    "vitest": "^1.5.0"
+    "vite": "^7",
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
-    "commander": "12.x",
+    "@tanstack/react-query": "^5.0.0",
+    "commander": "12.x || 13.x || 14.x || 15.x",
     "ts-morph": "28.x",
     "typescript": "5.x || 6.x"
   },