@7nohe/openapi-react-query-codegen 3.0.0-beta.2 → 3.0.0-beta.4

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/cli.mjs

@@ -32,6 +32,7 @@ async function setupProgram() {
         .option("--pageParam <value>", "Name of the query parameter used for pagination", "page")
         .option("--nextPageParam <value>", "Name of the response parameter used for next page", "nextPage")
         .option("--initialPageParam <value>", "Initial page value to query", "1")
+        .option("--omitInitialPageParam", "Send no initial page parameter at all (overrides --initialPageParam)")
         .parse();
     const options = program.opts();
     await generate(options, version);

package/dist/common.mjs

@@ -52,6 +52,12 @@ export function BuildCommonTypeName(name) {
  * @returns The parsed number or NaN if the value is not a valid number.
  */
 export function safeParseNumber(value) {
+    // `Number("")` is 0, which would silently turn a blank option such as
+    // `--initialPageParam ""` into a numeric 0. Treat blank strings as NaN so
+    // callers keep the original value.
+    if (typeof value === "string" && value.trim() === "") {
+        return Number.NaN;
+    }
     const parsed = Number(value);
     if (!Number.isNaN(parsed) && Number.isFinite(parsed)) {
         return parsed;

package/dist/createSource.mjs

@@ -5,7 +5,7 @@ import { generateAllFiles } from "./tsmorph/index.mjs";
 /**
  * Create source files using ts-morph based generation.
  */
-export const createSource = async ({ outputPath, client, version, pageParam, nextPageParam, initialPageParam, }) => {
+export const createSource = async ({ outputPath, client, version, pageParam, nextPageParam, initialPageParam, omitInitialPageParam, }) => {
     // Initialize ts-morph project to read the generated OpenAPI client
     const project = new Project({
         skipAddingFilesFromTsConfig: true,
@@ -15,7 +15,7 @@ export const createSource = async ({ outputPath, client, version, pageParam, nex
     // Parse operations from the service file
     const operations = await parseOperations(project, pageParam);
     // Build generation context
-    const ctx = buildGenerationContext(project, client, pageParam, nextPageParam, initialPageParam, version);
+    const ctx = buildGenerationContext(project, client, pageParam, nextPageParam, initialPageParam, omitInitialPageParam, version);
     // Generate all files using ts-morph
     return generateAllFiles(operations, ctx);
 };

package/dist/generate.mjs

@@ -59,6 +59,7 @@ export async function generate(options, version) {
         pageParam: formattedOptions.pageParam,
         nextPageParam: formattedOptions.nextPageParam,
         initialPageParam: formattedOptions.initialPageParam.toString(),
+        omitInitialPageParam: formattedOptions.omitInitialPageParam ?? false,
     });
     await print(source, formattedOptions);
     const queriesOutputPath = buildQueriesOutputPath(options.output);

package/dist/parseOperations.mjs

@@ -96,7 +96,7 @@ export async function parseOperations(project, pageParam) {
 /**
  * Build generation context from project configuration.
  */
-export function buildGenerationContext(project, client, pageParam, nextPageParam, initialPageParam, version) {
+export function buildGenerationContext(project, client, pageParam, nextPageParam, initialPageParam, omitInitialPageParam, version) {
     const modelsFile = project
         .getSourceFiles()
         .find((sf) => sf.getFilePath().includes(modelsFileName));
@@ -117,6 +117,7 @@ export function buildGenerationContext(project, client, pageParam, nextPageParam
         pageParam,
         nextPageParam,
         initialPageParam,
+        omitInitialPageParam,
         version,
     };
 }

package/dist/tsmorph/buildCommon.mjs

@@ -141,9 +141,11 @@ export function buildInfiniteClientOptionsType(op, ctx) {
 }
 /**
  * Build the infinite query key constant.
- * Kept distinct from the plain query key so cached InfiniteData never
- * collides with plain query data for the same operation (#140).
- * Example: export const useFindPaginatedPetsInfiniteKey = "FindPaginatedPetsInfinite";
+ * 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 {
@@ -153,15 +155,18 @@ export function buildInfiniteQueryKeyConst(op) {
         declarations: [
             {
                 name: `use${op.capitalizedMethodName}InfiniteKey`,
-                initializer: `"${op.capitalizedMethodName}Infinite"`,
+                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])];
+ *   [...useFindPaginatedPetsInfiniteKey, ...(queryKey ?? [clientOptions])];
  */
 export function buildInfiniteQueryKeyFn(op) {
     const defaultValue = op.allParamsOptional ? " = {}" : "";
@@ -176,7 +181,7 @@ export function buildInfiniteQueryKeyFn(op) {
         declarations: [
             {
                 name: `Use${op.capitalizedMethodName}InfiniteKeyFn`,
-                initializer: `(${params.join(", ")}) => [use${op.capitalizedMethodName}InfiniteKey, ...(queryKey ?? [clientOptions])]`,
+                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

@@ -13,32 +13,6 @@ function getErrorType(op, ctx) {
     }
     return errorType;
 }
-/**
- * Get the data type based on hook 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;
-}
-/**
- * Get the options type name.
- */
-function getOptionsTypeName(hookType) {
-    switch (hookType) {
-        case "useSuspenseQuery":
-            return "UseSuspenseQueryOptions";
-        case "useInfiniteQuery":
-            return "UseInfiniteQueryOptions";
-        default:
-            return "UseQueryOptions";
-    }
-}
 /**
  * Resolve the generated Data type name for an operation, falling back to
  * unknown when the operation has no generated Data type.
@@ -48,13 +22,18 @@ export function getDataTypeName(op, ctx) {
         ? `${op.capitalizedMethodName}Data`
         : "unknown";
 }
+/**
+ * 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).
+ */
+export const SDK_CALL_ARGS = "{ ...clientOptions, throwOnError: true }";
 /**
  * Build the client options parameter string.
  */
 export function buildClientOptionsParam(op, ctx) {
-    const dataTypeName = ctx.modelNames.includes(`${op.capitalizedMethodName}Data`)
-        ? `${op.capitalizedMethodName}Data`
-        : "unknown";
+    const dataTypeName = getDataTypeName(op, ctx);
     const hasParams = op.parameters.length > 0;
     if (!hasParams) {
         return `clientOptions: Options<${dataTypeName}, true> = {}`;
@@ -62,6 +41,71 @@ export 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)";
+    // When the initial page param is omitted, the first request must send no
+    // page param at all, so spread it in only once TanStack Query provides one.
+    const pageQuery = ctx.omitInitialPageParam
+        ? `...(pageParam === undefined ? {} : { ${ctx.pageParam}: pageParam as number })`
+        : `${ctx.pageParam}: pageParam as number`;
+    return `({ pageParam }) => ${op.methodName}({ ...clientOptions, query: { ...clientOptions.query, ${pageQuery} }, throwOnError: true } as Options<${dataTypeName}, true>)${thenClause}`;
+}
+/**
+ * Format the initialPageParam literal. Emits `undefined` when the caller opted
+ * to omit it (#177); otherwise a numeric literal when possible so the inferred
+ * pageParam type matches what getNextPageParam returns.
+ */
+export function formatInitialPageParam(ctx) {
+    if (ctx.omitInitialPageParam) {
+        return "undefined";
+    }
+    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:
@@ -71,19 +115,16 @@ export 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,
@@ -105,11 +146,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,
@@ -126,38 +165,30 @@ export function buildUseSuspenseQueryHook(op, ctx) {
     };
 }
 /**
- * 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 useInfiniteQuery hook.
+ * 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.
  */
-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 = getDataTypeName(op, ctx);
-    // Infinite queries take a dedicated options type that excludes the page
-    // parameter — it is supplied by TanStack Query's pageParam mechanism
-    const defaultValue = op.allParamsOptional ? " = {}" : "";
-    const clientOptionsParam = `clientOptions: Common.${op.capitalizedMethodName}InfiniteClientOptions${defaultValue}`;
-    // Build the queryFn with pageParam handling
-    const queryFn = `({ pageParam }) => ${op.methodName}({ ...clientOptions, query: { ...clientOptions.query, ${ctx.pageParam}: pageParam as number } } as Options<${dataTypeName}, true>).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}InfiniteKeyFn(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
@@ -167,33 +198,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
@@ -203,7 +239,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}`,
             },
         ],
     };
@@ -211,25 +282,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
@@ -239,7 +303,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

@@ -1,5 +1,5 @@
 import { StructureKind, VariableDeclarationKind, } from "ts-morph";
-import { buildClientOptionsParam, buildNestedNextPageType, getDataTypeName, } from "./buildQueryHooks.mjs";
+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
@@ -9,13 +9,13 @@ import { buildClientOptionsParam, buildNestedNextPageType, getDataTypeName, } fr
  * export const findPetsOptions = (clientOptions: Options<FindPetsData, true> = {}, queryKey?: Array<unknown>) =>
  *   queryOptions({
  *     queryKey: Common.UseFindPetsKeyFn(clientOptions, queryKey),
- *     queryFn: () => findPets({ ...clientOptions }).then(response => response.data),
+ *     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}({ ...clientOptions }).then(response => response.data)`;
+    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,
@@ -38,9 +38,9 @@ export function buildQueryOptionsFn(op, ctx) {
  * 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 Options<FindPaginatedPetsData, true>).then(response => response.data),
+ *     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) => (response as { nextPage: number }).nextPage,
+ *     getNextPageParam: (response: unknown) => (response as { nextPage: number }).nextPage,
  *   });
  */
 export function buildInfiniteQueryOptionsFn(op, ctx) {
@@ -48,18 +48,9 @@ export function buildInfiniteQueryOptionsFn(op, ctx) {
         return null;
     }
     const fnName = `${op.methodName}InfiniteOptions`;
-    const dataTypeName = getDataTypeName(op, ctx);
-    const defaultValue = op.allParamsOptional ? " = {}" : "";
-    const clientOptionsParam = `clientOptions: Common.${op.capitalizedMethodName}InfiniteClientOptions${defaultValue}`;
-    const queryFn = `({ pageParam }) => ${op.methodName}({ ...clientOptions, query: { ...clientOptions.query, ${ctx.pageParam}: pageParam } } as Options<${dataTypeName}, true>).then(response => response.data)`;
-    // Emit a numeric literal when possible so the inferred pageParam type
-    // matches what getNextPageParam returns
-    const initialPageParam = /^-?\d+$/.test(ctx.initialPageParam)
-        ? ctx.initialPageParam
-        : JSON.stringify(ctx.initialPageParam);
-    const nestedType = buildNestedNextPageType(ctx.nextPageParam);
-    const getNextPageParam = `(response) => (response as ${nestedType}).${ctx.nextPageParam}`;
-    const body = `infiniteQueryOptions({ queryKey: Common.Use${op.capitalizedMethodName}InfiniteKeyFn(clientOptions, queryKey), queryFn: ${queryFn}, initialPageParam: ${initialPageParam}, getNextPageParam: ${getNextPageParam} })`;
+    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
@@ -69,7 +60,7 @@ export function buildInfiniteQueryOptionsFn(op, ctx) {
         declarations: [
             {
                 name: fnName,
-                initializer: `(${clientOptionsParam}, queryKey?: Array<unknown>) => ${body}`,
+                initializer: `(${buildInfiniteClientOptionsParam(op)}, queryKey?: Array<unknown>) => ${body}`,
             },
         ],
     };

package/dist/tsmorph/generateFiles.mjs

@@ -1,8 +1,7 @@
-import { StructureKind, } from "ts-morph";
 import { OpenApiRqFiles } from "../constants.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 { 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";
 /**
@@ -31,26 +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",
-        },
-        {
-            kind: StructureKind.ExportDeclaration,
-            moduleSpecifier: "./queryOptions",
-        },
-    ];
-    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.
@@ -150,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();
 }
 /**
@@ -185,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();
 }
 /**
@@ -217,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`,

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,14 +41,19 @@ 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 },
         ],
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7nohe/openapi-react-query-codegen",
-  "version": "3.0.0-beta.2",
+  "version": "3.0.0-beta.4",
   "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"
   },