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

package/dist/cli.d.mts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+export type LimitedUserConfig = {
+    input: string;
+    output: string;
+    client?: "@hey-api/client-fetch" | "@hey-api/client-axios";
+    format?: "biome" | "prettier";
+    lint?: "biome" | "eslint";
+    noOperationId?: boolean;
+    enums?: "javascript" | "typescript" | false;
+    useDateType?: boolean;
+    debug?: boolean;
+    noSchemas?: boolean;
+    schemaType?: "form" | "json";
+    pageParam: string;
+    nextPageParam: string;
+    initialPageParam: string | number;
+    omitInitialPageParam?: boolean;
+};

package/dist/cli.mjs

@@ -25,13 +25,14 @@ async function setupProgram() {
         .addOption(new Option("--lint <value>", "Process output folder with linter?").choices(["biome", "eslint"]))
         .option("--noOperationId", "Do not use operationId to generate operation names")
         .addOption(new Option("--enums <value>", "Generate JavaScript objects from enum definitions?").choices(["javascript", "typescript"]))
-        .option("--useDateType", "Use Date type instead of string for date types for models, this will not convert the data to a Date object")
+        .option("--useDateType", "Use Date for date/date-time model properties and convert response values to Date objects")
         .option("--debug", "Run in debug mode?")
         .option("--noSchemas", "Disable generating JSON schemas")
         .addOption(new Option("--schemaType <value>", "Type of JSON schema [Default: 'json']").choices(["form", "json"]))
         .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.d.mts

@@ -0,0 +1,51 @@
+import type { PathLike } from "node:fs";
+import { type ClassDeclaration, type ParameterDeclaration, type SourceFile, type VariableDeclaration } from "ts-morph";
+import ts from "typescript";
+import type { LimitedUserConfig } from "./cli.mjs";
+export declare const capitalizeFirstLetter: (str: string) => string;
+export declare const lowercaseFirstLetter: (str: string) => string;
+export declare const getVariableArrowFunctionParameters: (variable: VariableDeclaration) => ParameterDeclaration[];
+export declare const getNameFromVariable: (variable: VariableDeclaration) => string;
+export type FunctionDescription = {
+    node: SourceFile;
+    method: VariableDeclaration;
+    methodBlock?: ts.Block;
+    httpMethodName: string;
+    jsDoc: string;
+    isDeprecated: boolean;
+};
+export declare function exists(f: PathLike): Promise<boolean>;
+/**
+ * Build a common type name by prepending the Common namespace.
+ */
+export declare function BuildCommonTypeName(name: string | ts.Identifier): ts.Identifier;
+/**
+ * Safely parse a value into a number. Checks for NaN and Infinity.
+ * Returns NaN if the string is not a valid number.
+ * @param value The value to parse.
+ * @returns The parsed number or NaN if the value is not a valid number.
+ */
+export declare function safeParseNumber(value: unknown): number;
+export declare function extractPropertiesFromObjectParam(param: ParameterDeclaration): {
+    name: string;
+    optional: boolean;
+    type: import("ts-morph").Type<import("ts-morph").ts.Type> | undefined;
+}[];
+/**
+ * Replace the import("...") surrounding the type if there is one.
+ * This can happen when the type is imported from another file, but
+ * we are already importing all the types from that file.
+ *
+ * https://regex101.com/r/3DyHaQ/1
+ *
+ * TODO: Replace with a more robust solution.
+ */
+export declare function getShortType(type: string): string;
+export declare function getClassesFromService(node: SourceFile): {
+    className: string;
+    klass: ClassDeclaration;
+}[];
+export declare function getClassNameFromClassNode(klass: ClassDeclaration): string;
+export declare function formatOptions(options: LimitedUserConfig): LimitedUserConfig;
+export declare function buildRequestsOutputPath(outputPath: string): string;
+export declare function buildQueriesOutputPath(outputPath: string): string;

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/constants.d.mts

@@ -0,0 +1,15 @@
+export declare const defaultOutputPath = "openapi";
+export declare const queriesOutputPath = "queries";
+export declare const requestsOutputPath = "requests";
+export declare const serviceFileName = "sdk.gen";
+export declare const modelsFileName = "types.gen";
+export declare const OpenApiRqFiles: {
+    readonly queries: "queries";
+    readonly queryOptions: "queryOptions";
+    readonly infiniteQueries: "infiniteQueries";
+    readonly common: "common";
+    readonly suspense: "suspense";
+    readonly index: "index";
+    readonly prefetch: "prefetch";
+    readonly ensureQueryData: "ensureQueryData";
+};

package/dist/createSource.d.mts

@@ -0,0 +1,15 @@
+import type { GeneratedFile } from "./types.mjs";
+type ClientType = "@hey-api/client-fetch" | "@hey-api/client-axios";
+/**
+ * Create source files using ts-morph based generation.
+ */
+export declare const createSource: ({ outputPath, client, version, pageParam, nextPageParam, initialPageParam, omitInitialPageParam, }: {
+    outputPath: string;
+    client: ClientType;
+    version: string;
+    pageParam: string;
+    nextPageParam: string;
+    initialPageParam: string;
+    omitInitialPageParam: boolean;
+}) => Promise<GeneratedFile[]>;
+export {};

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/format.d.mts

@@ -0,0 +1,6 @@
+export declare const formatOutput: (outputPath: string) => Promise<void>;
+export declare const processOutput: ({ output, format, lint, }: {
+    output: string;
+    format?: "prettier" | "biome";
+    lint?: "biome" | "eslint";
+}) => Promise<void>;

package/dist/generate.d.mts

@@ -0,0 +1,2 @@
+import type { LimitedUserConfig } from "./cli.mjs";
+export declare function generate(options: LimitedUserConfig, version: string): Promise<void>;

package/dist/generate.mjs

@@ -18,20 +18,31 @@ export async function generate(options, version) {
             enums: formattedOptions.enums,
         }
         : "@hey-api/typescript";
-    const sdkPlugin = formattedOptions.noOperationId
-        ? {
-            name: "@hey-api/sdk",
-            // `operationId: false` was deprecated in favor of `operations.nesting`
-            operations: {
-                nesting: "id",
-            },
-        }
-        : "@hey-api/sdk";
+    const sdkPlugin = {
+        name: "@hey-api/sdk",
+        ...(formattedOptions.noOperationId
+            ? {
+                // `operationId: false` was deprecated in favor of `operations.nesting`
+                operations: {
+                    nesting: "id",
+                },
+            }
+            : {}),
+        ...(formattedOptions.useDateType
+            ? { transformer: "@hey-api/transformers" }
+            : {}),
+    };
     const plugins = [
         clientPlugin,
         typescriptPlugin,
         sdkPlugin,
     ];
+    if (formattedOptions.useDateType) {
+        plugins.push({
+            name: "@hey-api/transformers",
+            dates: "date",
+        });
+    }
     // Conditionally add schemas plugin
     if (!formattedOptions.noSchemas) {
         plugins.push(formattedOptions.schemaType
@@ -59,6 +70,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.d.mts

@@ -0,0 +1,10 @@
+import type { Project } from "ts-morph";
+import type { GenerationContext, OperationInfo } from "./types.mjs";
+/**
+ * Parse operations from the OpenAPI-generated service file and return normalized DTOs.
+ */
+export declare function parseOperations(project: Project, pageParam: string): Promise<OperationInfo[]>;
+/**
+ * Build generation context from project configuration.
+ */
+export declare function buildGenerationContext(project: Project, client: GenerationContext["client"], pageParam: string, nextPageParam: string, initialPageParam: string, omitInitialPageParam: boolean, version: string): GenerationContext;

package/dist/parseOperations.mjs

@@ -2,6 +2,20 @@ import ts from "typescript";
 import { capitalizeFirstLetter, extractPropertiesFromObjectParam, getNameFromVariable, getShortType, getVariableArrowFunctionParameters, } from "./common.mjs";
 import { modelsFileName, serviceFileName } from "./constants.mjs";
 import { getServices } from "./service.mjs";
+function getPageParamTypeKind(type) {
+    const types = type.isUnion()
+        ? type.types.filter((item) => !(item.flags & (ts.TypeFlags.Null | ts.TypeFlags.Undefined)))
+        : [type];
+    if (types.length > 0 &&
+        types.every((item) => item.flags & ts.TypeFlags.StringLike)) {
+        return "string";
+    }
+    if (types.length > 0 &&
+        types.every((item) => item.flags & ts.TypeFlags.NumberLike)) {
+        return "number";
+    }
+    return "other";
+}
 /**
  * Extract parameter information from a method's variable declaration.
  */
@@ -30,8 +44,9 @@ function getPaginatableMethods(project, pageParam) {
         .getSourceFiles()
         .find((sf) => sf.getFilePath().includes(modelsFileName));
     if (!modelsFile)
-        return [];
-    const paginatableMethods = [];
+        return new Map();
+    const paginatableMethods = new Map();
+    const typeChecker = project.getTypeChecker().compilerObject;
     const modelDeclarations = modelsFile.getExportedDeclarations();
     const entries = modelDeclarations.entries();
     for (const [key, value] of entries) {
@@ -53,13 +68,18 @@ function getPaginatableMethods(project, pageParam) {
         const queryType = query.type;
         if (!queryType || queryType.kind !== ts.SyntaxKind.TypeLiteral)
             continue;
-        const hasPageParam = queryType.members.some((m) => m.name?.getText() === pageParam);
-        if (hasPageParam) {
+        const pageParamNode = queryType.members.find((m) => ts.isPropertySignature(m) && m.name?.getText() === pageParam);
+        if (pageParamNode) {
             // Extract method name from Data type name (e.g., "FindPetsData" -> "findPets")
             const methodName = key.slice(0, -4); // Remove "Data" suffix
             // Convert first letter to lowercase
             const methodNameLower = methodName.charAt(0).toLowerCase() + methodName.slice(1);
-            paginatableMethods.push(methodNameLower);
+            const pageParamType = pageParamNode.type?.getText(modelsFile.compilerNode);
+            const resolvedType = typeChecker.getTypeAtLocation(pageParamNode.type ?? pageParamNode);
+            paginatableMethods.set(methodNameLower, {
+                type: pageParamType ?? "unknown",
+                typeKind: getPageParamTypeKind(resolvedType),
+            });
         }
     }
     return paginatableMethods;
@@ -80,7 +100,8 @@ export async function parseOperations(project, pageParam) {
         // via extractPropertiesFromObjectParam for type alias properties (path, url).
         const sdkParams = getVariableArrowFunctionParameters(desc.method);
         const allParamsOptional = sdkParams.length === 0 || sdkParams[0].isOptional();
-        const isPaginatable = httpMethod === "GET" && paginatableMethods.includes(methodName);
+        const pageParamInfo = paginatableMethods.get(methodName);
+        const isPaginatable = httpMethod === "GET" && pageParamInfo !== undefined;
         return {
             methodName,
             capitalizedMethodName: capitalizeFirstLetter(methodName),
@@ -90,13 +111,15 @@ export async function parseOperations(project, pageParam) {
             parameters,
             allParamsOptional,
             isPaginatable,
+            pageParamType: isPaginatable ? pageParamInfo.type : undefined,
+            pageParamTypeKind: isPaginatable ? pageParamInfo.typeKind : undefined,
         };
     });
 }
 /**
  * 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 +140,7 @@ export function buildGenerationContext(project, client, pageParam, nextPageParam
         pageParam,
         nextPageParam,
         initialPageParam,
+        omitInitialPageParam,
         version,
     };
 }

package/dist/print.d.mts

@@ -0,0 +1,5 @@
+import type { LimitedUserConfig } from "./cli.mjs";
+export declare function print(results: {
+    name: string;
+    content: string;
+}[], options: Pick<LimitedUserConfig, "output">): Promise<void>;

package/dist/service.d.mts

@@ -0,0 +1,8 @@
+import type { Project, SourceFile } from "ts-morph";
+import type { FunctionDescription } from "./common.mjs";
+export type Service = {
+    node: SourceFile;
+    methods: Array<FunctionDescription>;
+};
+export declare function getServices(project: Project): Promise<Service>;
+export declare function getMethodsFromService(node: SourceFile): FunctionDescription[];

package/dist/tsmorph/buildCommon.d.mts

@@ -0,0 +1,66 @@
+import { type TypeAliasDeclarationStructure, type VariableStatementStructure } from "ts-morph";
+import type { GenerationContext, OperationInfo } from "../types.mjs";
+/**
+ * Build the default response type alias.
+ * Example: export type FindPetsDefaultResponse = Awaited<ReturnType<typeof findPets>>["data"];
+ */
+export declare function buildDefaultResponseType(op: OperationInfo): TypeAliasDeclarationStructure;
+/**
+ * Build the query result type alias.
+ * Example: export type FindPetsQueryResult<TData = FindPetsDefaultResponse, TError = unknown> = UseQueryResult<TData, TError>;
+ */
+export declare function buildQueryResultType(op: OperationInfo): TypeAliasDeclarationStructure;
+/**
+ * Build the mutation result type alias.
+ * Example: export type AddPetMutationResult = Awaited<ReturnType<typeof addPet>>;
+ */
+export declare function buildMutationResultType(op: OperationInfo): TypeAliasDeclarationStructure;
+/**
+ * Build query key constant.
+ * Example: export const useFindPetsKey = "FindPets";
+ */
+export declare function buildQueryKeyConst(op: OperationInfo): VariableStatementStructure;
+/**
+ * Build mutation key constant.
+ * Example: export const useAddPetKey = "AddPet";
+ */
+export declare function buildMutationKeyConst(op: OperationInfo): VariableStatementStructure;
+/**
+ * Build query key function.
+ * Example: export const UseFindPetsKeyFn = (clientOptions: Options<FindPetsData, true> = {}, queryKey?: Array<unknown>) =>
+ *   [useFindPetsKey, ...(queryKey ?? [clientOptions])];
+ */
+export declare function buildQueryKeyFn(op: OperationInfo, ctx: GenerationContext): VariableStatementStructure;
+/**
+ * Build mutation key function.
+ * Example: export const UseAddPetKeyFn = (mutationKey?: Array<unknown>) =>
+ *   [useAddPetKey, ...(mutationKey ?? [])];
+ */
+export declare function buildMutationKeyFn(op: OperationInfo): VariableStatementStructure;
+/**
+ * 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 declare function buildInfiniteClientOptionsType(op: OperationInfo, ctx: GenerationContext): TypeAliasDeclarationStructure;
+/**
+ * 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 declare function buildInfiniteQueryKeyConst(op: OperationInfo): VariableStatementStructure;
+/**
+ * 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 declare function buildInfiniteQueryKeyFn(op: OperationInfo): VariableStatementStructure;

package/dist/tsmorph/buildKeys.d.mts

@@ -0,0 +1,42 @@
+import { type VariableStatementStructure } from "ts-morph";
+import type { GenerationContext, OperationInfo } from "../types.mjs";
+/**
+ * Build query key constant name (e.g., "findPetsQueryKey").
+ */
+export declare function getQueryKeyName(op: OperationInfo): string;
+/**
+ * Build mutation key constant name (e.g., "addPetMutationKey").
+ */
+export declare function getMutationKeyName(op: OperationInfo): string;
+/**
+ * Build query key fn name (e.g., "FindPetsQueryKeyFn").
+ */
+export declare function getQueryKeyFnName(op: OperationInfo): string;
+/**
+ * Build mutation key fn name (e.g., "AddPetMutationKeyFn").
+ */
+export declare function getMutationKeyFnName(op: OperationInfo): string;
+/**
+ * Build the query key constant export.
+ * Example: export const findPetsQueryKey = "FindPets";
+ */
+export declare function buildQueryKeyExport(op: OperationInfo): VariableStatementStructure;
+/**
+ * Build the mutation key constant export.
+ * Example: export const addPetMutationKey = "AddPet";
+ */
+export declare function buildMutationKeyExport(op: OperationInfo): VariableStatementStructure;
+/**
+ * Build the query key function export.
+ * Example:
+ * export const FindPetsQueryKeyFn = (clientOptions: Options<FindPetsData, true>, queryKey?: Array<unknown>) =>
+ *   [findPetsQueryKey, ...(queryKey ?? [clientOptions])] as const;
+ */
+export declare function buildQueryKeyFnExport(op: OperationInfo, ctx: GenerationContext): VariableStatementStructure;
+/**
+ * Build the mutation key function export.
+ * Example:
+ * export const AddPetMutationKeyFn = (mutationKey?: Array<unknown>) =>
+ *   [addPetMutationKey, ...(mutationKey ?? [])] as const;
+ */
+export declare function buildMutationKeyFnExport(op: OperationInfo): VariableStatementStructure;

package/dist/tsmorph/buildMutationHooks.d.mts

@@ -0,0 +1,15 @@
+import { type VariableStatementStructure } from "ts-morph";
+import type { GenerationContext, OperationInfo } from "../types.mjs";
+/**
+ * Build useMutation hook.
+ * Example:
+ * export const useAddPet = <TData = Common.AddPetMutationResult, TError = AddPetError, TQueryKey extends Array<unknown> = unknown[], TContext = unknown>(
+ *   mutationKey?: TQueryKey,
+ *   options?: Omit<UseMutationOptions<TData, TError, Options<AddPetData, true>, TContext>, "mutationKey" | "mutationFn">
+ * ) => useMutation<TData, TError, Options<AddPetData, true>, TContext>({
+ *   mutationKey: Common.UseAddPetKeyFn(mutationKey),
+ *   mutationFn: clientOptions => addPet(clientOptions) as unknown as Promise<TData>,
+ *   ...options
+ * });
+ */
+export declare function buildUseMutationHook(op: OperationInfo, ctx: GenerationContext): VariableStatementStructure;

package/dist/tsmorph/buildQueryHooks.d.mts

@@ -0,0 +1,116 @@
+import { type VariableStatementStructure } from "ts-morph";
+import type { GenerationContext, OperationInfo } from "../types.mjs";
+/**
+ * Resolve the generated Data type name for an operation, falling back to
+ * unknown when the operation has no generated Data type.
+ */
+export declare function getDataTypeName(op: OperationInfo, ctx: GenerationContext): string;
+/**
+ * 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 declare const SDK_CALL_ARGS = "{ ...clientOptions, throwOnError: true }";
+/** SDK call arguments for TanStack query functions with cancellation. */
+export declare const QUERY_SDK_CALL_ARGS = "{ ...clientOptions, signal, throwOnError: true }";
+/** Resolve the OpenAPI page parameter type, preserving older numeric output. */
+export declare function getPageParamType(op: OperationInfo): string;
+/**
+ * Build the client options parameter string.
+ */
+export declare function buildClientOptionsParam(op: OperationInfo, ctx: GenerationContext): string;
+/**
+ * Build the clientOptions parameter typed with the page-less infinite
+ * options type — the page parameter is supplied by TanStack Query's
+ * pageParam mechanism.
+ */
+export declare function buildInfiniteClientOptionsParam(op: OperationInfo): string;
+/**
+ * Build the paginated SDK call shared by every infinite query builder.
+ */
+export declare function buildPagedQueryFn(op: OperationInfo, ctx: GenerationContext, castTData: boolean): string;
+/**
+ * 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 declare function formatInitialPageParam(ctx: GenerationContext, op?: OperationInfo): string;
+/**
+ * Build the nested type for getNextPageParam.
+ * E.g., "meta.next" becomes "{ meta: { next: number } }"
+ */
+export declare function buildNestedNextPageType(nextPageParam: string, pageParamType?: string): string;
+/**
+ * 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 declare function buildGetNextPageParamExpr(ctx: GenerationContext, op?: OperationInfo): string;
+/**
+ * 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 declare function buildOverridableInfiniteOptionsType(optionsTypeName: string): string;
+/**
+ * Build useQuery hook.
+ * Example:
+ * export const useFindPets = <TData = Common.FindPetsDefaultResponse, TError = FindPetsError, TQueryKey extends Array<unknown> = unknown[]>(
+ *   clientOptions: Options<FindPetsData, true> = {},
+ *   queryKey?: TQueryKey,
+ *   options?: Omit<UseQueryOptions<TData, TError>, "queryKey" | "queryFn">
+ * ) => useQuery<TData, TError>({
+ *   queryKey: Common.UseFindPetsKeyFn(clientOptions, queryKey),
+ *   queryFn: () => findPets({ ...clientOptions, throwOnError: true }).then(response => response.data as TData) as TData,
+ *   ...options
+ * });
+ */
+export declare function buildUseQueryHook(op: OperationInfo, ctx: GenerationContext): VariableStatementStructure;
+/**
+ * Build useSuspenseQuery hook.
+ */
+export declare function buildUseSuspenseQueryHook(op: OperationInfo, ctx: GenerationContext): VariableStatementStructure;
+/**
+ * Build useInfiniteQuery hook.
+ */
+export declare function buildUseInfiniteQueryHook(op: OperationInfo, ctx: GenerationContext): VariableStatementStructure | null;
+/**
+ * Build useSuspenseInfiniteQuery hook.
+ */
+export declare function buildUseSuspenseInfiniteQueryHook(op: OperationInfo, ctx: GenerationContext): VariableStatementStructure | null;
+/**
+ * Build prefetch function.
+ * Example:
+ * 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, throwOnError: true }).then(response => response.data),
+ *     ...options
+ *   });
+ */
+export declare function buildPrefetchFn(op: OperationInfo, ctx: GenerationContext): VariableStatementStructure;
+/**
+ * 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 declare function buildPrefetchInfiniteQueryFn(op: OperationInfo, ctx: GenerationContext): VariableStatementStructure | null;
+/**
+ * Build ensureQueryData function.
+ * Example:
+ * 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, throwOnError: true }).then(response => response.data),
+ *     ...options
+ *   });
+ */
+export declare function buildEnsureQueryDataFn(op: OperationInfo, ctx: GenerationContext): VariableStatementStructure;

package/dist/tsmorph/buildQueryHooks.mjs

@@ -29,6 +29,12 @@ export function getDataTypeName(op, ctx) {
  * swallow the error instead of surfacing it to TanStack Query (#172).
  */
 export const SDK_CALL_ARGS = "{ ...clientOptions, throwOnError: true }";
+/** SDK call arguments for TanStack query functions with cancellation. */
+export const QUERY_SDK_CALL_ARGS = "{ ...clientOptions, signal, throwOnError: true }";
+/** Resolve the OpenAPI page parameter type, preserving older numeric output. */
+export function getPageParamType(op) {
+    return op.pageParamType ?? "number";
+}
 /**
  * Build the client options parameter string.
  */
@@ -58,13 +64,31 @@ export function buildPagedQueryFn(op, ctx, castTData) {
     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}`;
+    const pageParamType = getPageParamType(op);
+    // 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 ${pageParamType} })`
+        : `${ctx.pageParam}: pageParam as ${pageParamType}`;
+    return `({ pageParam, signal }) => ${op.methodName}({ ...clientOptions, query: { ...clientOptions.query, ${pageQuery} }, signal, 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.
+ * 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) {
+export function formatInitialPageParam(ctx, op) {
+    if (ctx.omitInitialPageParam) {
+        return "undefined";
+    }
+    const isStringPageParam = op
+        ? op.pageParamTypeKind === "string" ||
+            (op.pageParamTypeKind === undefined &&
+                /\bstring\b/.test(getPageParamType(op)))
+        : false;
+    if (isStringPageParam) {
+        return JSON.stringify(ctx.initialPageParam);
+    }
     return /^-?\d+$/.test(ctx.initialPageParam)
         ? ctx.initialPageParam
         : JSON.stringify(ctx.initialPageParam);
@@ -73,19 +97,19 @@ export function formatInitialPageParam(ctx) {
  * Build the nested type for getNextPageParam.
  * E.g., "meta.next" becomes "{ meta: { next: number } }"
  */
-export function buildNestedNextPageType(nextPageParam) {
+export function buildNestedNextPageType(nextPageParam, pageParamType = "number") {
     const segments = nextPageParam.split(".");
     return segments.reduceRight((acc, segment) => {
         return `{ ${segment}: ${acc} }`;
-    }, "number");
+    }, pageParamType);
 }
 /**
  * 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);
+export function buildGetNextPageParamExpr(ctx, op) {
+    const nestedType = buildNestedNextPageType(ctx.nextPageParam, op ? getPageParamType(op) : "number");
     return `(response: unknown) => (response as ${nestedType}).${ctx.nextPageParam}`;
 }
 /**
@@ -115,7 +139,7 @@ export function buildUseQueryHook(op, ctx) {
     const errorType = getErrorType(op, ctx);
     const dataTypeDefault = `Common.${op.capitalizedMethodName}DefaultResponse`;
     const clientOptionsParam = buildClientOptionsParam(op, ctx);
-    const queryFn = `() => ${op.methodName}(${SDK_CALL_ARGS}).then(response => response.data as TData) as TData`;
+    const queryFn = `({ signal }) => ${op.methodName}(${QUERY_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,
@@ -139,7 +163,7 @@ export function buildUseSuspenseQueryHook(op, ctx) {
     const errorType = getErrorType(op, ctx);
     const dataTypeDefault = `NonNullable<Common.${op.capitalizedMethodName}DefaultResponse>`;
     const clientOptionsParam = buildClientOptionsParam(op, ctx);
-    const queryFn = `() => ${op.methodName}(${SDK_CALL_ARGS}).then(response => response.data as TData) as TData`;
+    const queryFn = `({ signal }) => ${op.methodName}(${QUERY_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,
@@ -178,7 +202,7 @@ function buildInfiniteHook(op, ctx, suspense) {
         ? `InfiniteData<NonNullable<${baseDataType}>>`
         : `InfiniteData<${baseDataType}>`;
     const queryFn = buildPagedQueryFn(op, ctx, true);
-    const infiniteOptions = `initialPageParam: ${formatInitialPageParam(ctx)}, getNextPageParam: ${buildGetNextPageParamExpr(ctx)}`;
+    const infiniteOptions = `initialPageParam: ${formatInitialPageParam(ctx, op)}, getNextPageParam: ${buildGetNextPageParamExpr(ctx, op)}`;
     const body = `${hookCall}({ queryKey: Common.Use${op.capitalizedMethodName}InfiniteKeyFn(clientOptions, queryKey), queryFn: ${queryFn}, ${infiniteOptions}, ...options })`;
     return {
         kind: StructureKind.VariableStatement,
@@ -218,7 +242,7 @@ export function buildUseSuspenseInfiniteQueryHook(op, ctx) {
  */
 export function buildPrefetchFn(op, ctx) {
     const fnName = `prefetchUse${op.capitalizedMethodName}`;
-    const queryFn = `() => ${op.methodName}(${SDK_CALL_ARGS}).then(response => response.data)`;
+    const queryFn = `({ signal }) => ${op.methodName}(${QUERY_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 {
@@ -253,7 +277,7 @@ export function buildPrefetchInfiniteQueryFn(op, ctx) {
     }
     const fnName = `prefetchUse${op.capitalizedMethodName}Infinite`;
     const queryFn = buildPagedQueryFn(op, ctx, false);
-    const infiniteOptions = `initialPageParam: ${formatInitialPageParam(ctx)}, getNextPageParam: ${buildGetNextPageParamExpr(ctx)}`;
+    const infiniteOptions = `initialPageParam: ${formatInitialPageParam(ctx, op)}, getNextPageParam: ${buildGetNextPageParamExpr(ctx, op)}`;
     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 {
@@ -282,7 +306,7 @@ export function buildPrefetchInfiniteQueryFn(op, ctx) {
  */
 export function buildEnsureQueryDataFn(op, ctx) {
     const fnName = `ensureUse${op.capitalizedMethodName}Data`;
-    const queryFn = `() => ${op.methodName}(${SDK_CALL_ARGS}).then(response => response.data)`;
+    const queryFn = `({ signal }) => ${op.methodName}(${QUERY_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 {

package/dist/tsmorph/buildQueryOptions.d.mts

@@ -0,0 +1,28 @@
+import { type VariableStatementStructure } from "ts-morph";
+import type { GenerationContext, OperationInfo } from "../types.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 declare function buildQueryOptionsFn(op: OperationInfo, ctx: GenerationContext): VariableStatementStructure;
+/**
+ * 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 declare function buildInfiniteQueryOptionsFn(op: OperationInfo, ctx: GenerationContext): VariableStatementStructure | null;

package/dist/tsmorph/buildQueryOptions.mjs

@@ -1,5 +1,5 @@
 import { StructureKind, VariableDeclarationKind, } from "ts-morph";
-import { buildClientOptionsParam, buildGetNextPageParamExpr, buildInfiniteClientOptionsParam, buildPagedQueryFn, formatInitialPageParam, SDK_CALL_ARGS, } from "./buildQueryHooks.mjs";
+import { buildClientOptionsParam, buildGetNextPageParamExpr, buildInfiniteClientOptionsParam, buildPagedQueryFn, formatInitialPageParam, QUERY_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
@@ -15,7 +15,7 @@ import { buildClientOptionsParam, buildGetNextPageParamExpr, buildInfiniteClient
 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 queryFn = `({ signal }) => ${op.methodName}(${QUERY_SDK_CALL_ARGS}).then(response => response.data)`;
     const body = `queryOptions({ queryKey: Common.Use${op.capitalizedMethodName}KeyFn(clientOptions, queryKey), queryFn: ${queryFn} })`;
     return {
         kind: StructureKind.VariableStatement,
@@ -49,7 +49,7 @@ export function buildInfiniteQueryOptionsFn(op, ctx) {
     }
     const fnName = `${op.methodName}InfiniteOptions`;
     const queryFn = buildPagedQueryFn(op, ctx, false);
-    const infiniteOptions = `initialPageParam: ${formatInitialPageParam(ctx)}, getNextPageParam: ${buildGetNextPageParamExpr(ctx)}`;
+    const infiniteOptions = `initialPageParam: ${formatInitialPageParam(ctx, op)}, getNextPageParam: ${buildGetNextPageParamExpr(ctx, op)}`;
     const body = `infiniteQueryOptions({ queryKey: Common.Use${op.capitalizedMethodName}InfiniteKeyFn(clientOptions, queryKey), queryFn: ${queryFn}, ${infiniteOptions} })`;
     return {
         kind: StructureKind.VariableStatement,

package/dist/tsmorph/generateFiles.d.mts

@@ -0,0 +1,5 @@
+import type { GeneratedFile, GenerationContext, OperationInfo } from "../types.mjs";
+/**
+ * Generate all files using ts-morph.
+ */
+export declare function generateAllFiles(operations: OperationInfo[], ctx: GenerationContext): GeneratedFile[];

package/dist/tsmorph/index.d.mts

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

package/dist/tsmorph/projectFactory.d.mts

@@ -0,0 +1,45 @@
+import { type ImportDeclarationStructure, Project } from "ts-morph";
+import type { GenerationContext } from "../types.mjs";
+/**
+ * Create a shared ts-morph Project for code generation.
+ * Uses consistent formatting settings to match existing output.
+ */
+export declare function createGenerationProject(): Project;
+/**
+ * Build import structure for the Options type.
+ * sdk.gen re-exports Options extended with `client` and `meta`, which the
+ * base client Options lacks; hooks must accept those properties.
+ */
+export declare function buildClientImport(_ctx: GenerationContext): ImportDeclarationStructure;
+/**
+ * Build import structure for TanStack Query.
+ */
+export declare function buildQueryImport(): ImportDeclarationStructure;
+/**
+ * Build import structure for the queryOptions/infiniteQueryOptions helpers.
+ */
+export declare function buildQueryOptionsImport(): ImportDeclarationStructure;
+/**
+ * Build import structure for services.
+ */
+export declare function buildServiceImport(ctx: GenerationContext): ImportDeclarationStructure;
+/**
+ * Build import structure for models.
+ */
+export declare function buildModelImport(ctx: GenerationContext): ImportDeclarationStructure | null;
+/**
+ * Build import structure for axios error type.
+ */
+export declare function buildAxiosErrorImport(): ImportDeclarationStructure;
+/**
+ * Build import for Common namespace.
+ */
+export declare function buildCommonImport(): ImportDeclarationStructure;
+/**
+ * Build all imports needed for the common file.
+ */
+export declare function buildCommonFileImports(ctx: GenerationContext): ImportDeclarationStructure[];
+/**
+ * Build all imports needed for hook files (queries, suspense, infinite).
+ */
+export declare function buildHookFileImports(ctx: GenerationContext): ImportDeclarationStructure[];

package/dist/types.d.mts

@@ -0,0 +1,66 @@
+/**
+ * Normalized operation information extracted from the OpenAPI service.
+ * This is a pure JSON-serializable structure that can be consumed by generators.
+ */
+export interface OperationInfo {
+    /** Method/function name as defined in service (e.g., "findPets") */
+    methodName: string;
+    /** Capitalized method name (e.g., "FindPets") */
+    capitalizedMethodName: string;
+    /** HTTP method (e.g., "GET", "POST", "PUT", "PATCH", "DELETE") */
+    httpMethod: string;
+    /** JSDoc comment string (if present) */
+    jsDoc?: string;
+    /** Whether the operation is deprecated */
+    isDeprecated: boolean;
+    /** Parameter information for the operation */
+    parameters: OperationParameter[];
+    /** Whether all parameters are optional */
+    allParamsOptional: boolean;
+    /** Whether this operation supports pagination (for infinite queries) */
+    isPaginatable: boolean;
+    /** Type of the configured page query parameter */
+    pageParamType?: string;
+    /** Resolved primitive kind of the configured page query parameter */
+    pageParamTypeKind?: PageParamTypeKind;
+}
+export type PageParamTypeKind = "string" | "number" | "other";
+export interface OperationParameter {
+    /** Parameter name */
+    name: string;
+    /** TypeScript type as string */
+    typeName: string;
+    /** Whether this parameter is optional */
+    optional: boolean;
+}
+/**
+ * Context for generating hooks and utilities.
+ * Contains shared information needed across all generators.
+ */
+export interface GenerationContext {
+    /** Client type: "@hey-api/client-fetch" or "@hey-api/client-axios" */
+    client: "@hey-api/client-fetch" | "@hey-api/client-axios";
+    /** Model type names exported from the models file */
+    modelNames: string[];
+    /** Service function names exported from the service file */
+    serviceNames: string[];
+    /** Page param name for infinite queries (e.g., "page") */
+    pageParam: string;
+    /** Next page param name for infinite queries (e.g., "nextPage") */
+    nextPageParam: string;
+    /** Initial page param value for infinite queries */
+    initialPageParam: string;
+    /** Omit the initial page param entirely (sends no page param on the first request) */
+    omitInitialPageParam: boolean;
+    /** Package version for generated comment */
+    version: string;
+}
+/**
+ * Generated output for a single file.
+ */
+export interface GeneratedFile {
+    /** Filename without path (e.g., "queries.ts") */
+    name: string;
+    /** File content as string */
+    content: string;
+}

package/dist/util.d.mts

@@ -0,0 +1,2 @@
+import ts from "typescript";
+export declare function addJSDocToNode<T extends ts.Node>(node: T, jsDoc: string | undefined): T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7nohe/openapi-react-query-codegen",
-  "version": "3.0.0-beta.3",
+  "version": "3.0.0-beta.5",
   "description": "OpenAPI React Query Codegen",
   "bin": {
     "openapi-rq": "dist/cli.mjs"