@kubb/plugin-react-query 5.0.0-beta.99 → 5.0.1

package/dist/index.js

@@ -1,250 +1,10 @@
 import "./rolldown-runtime-C0LytTxp.js";
+import { Resolver, Url, ast, createResolver, defineGenerator, definePlugin } from "kubb/kit";
 import path from "node:path";
-import { Resolver, ast, createResolver, defineGenerator, definePlugin } from "kubb/kit";
 import { createFunctionParameter, createFunctionParameters, createObjectBindingPattern, createTypeLiteral, functionPrinter, pluginTsName } from "@kubb/plugin-ts";
 import { File, Function, Type, jsxRenderer } from "kubb/jsx";
 import { Fragment, jsx, jsxs } from "kubb/jsx/jsx-runtime";
 import fs from "node:fs";
-//#region ../../internals/utils/src/casing.ts
-/**
-* Shared implementation for camelCase and PascalCase conversion.
-* Splits on common word boundaries (spaces, hyphens, underscores, dots, slashes, colons)
-* and capitalizes each word according to `pascal`.
-*
-* When `pascal` is `true` the first word is also capitalized (PascalCase), otherwise only subsequent words are.
-*/
-function toCamelOrPascal(text, pascal) {
-	return text.trim().replace(/([a-z\d])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").replace(/(\d)([a-z])/g, "$1 $2").split(/[\s\-_./\\:]+/).filter(Boolean).map((word, i) => {
-		if (word.length > 1 && word === word.toUpperCase()) return word;
-		return (i === 0 && !pascal ? word.charAt(0).toLowerCase() : word.charAt(0).toUpperCase()) + word.slice(1);
-	}).join("").replace(/[^a-zA-Z0-9]/g, "");
-}
-/**
-* Converts `text` to camelCase.
-*
-* @example Word boundaries
-* `camelCase('hello-world') // 'helloWorld'`
-*
-* @example With a prefix
-* `camelCase('tag', { prefix: 'create' }) // 'createTag'`
-*/
-function camelCase(text, { prefix = "", suffix = "" } = {}) {
-	return toCamelOrPascal(`${prefix} ${text} ${suffix}`, false);
-}
-/**
-* Uppercases only the first character of `text`, leaving the rest untouched.
-* Unlike {@link pascalCase} it never re-splits word boundaries or strips characters.
-*
-* @example
-* `capitalize('getPetById') // 'GetPetById'`
-*/
-function capitalize(text) {
-	return `${text.charAt(0).toUpperCase()}${text.slice(1)}`;
-}
-//#endregion
-//#region ../../internals/utils/src/reserved.ts
-/**
-* JavaScript and Java reserved words.
-* @link https://github.com/jonschlinkert/reserved/blob/master/index.js
-*/
-const reservedWords = /* @__PURE__ */ new Set([
-	"abstract",
-	"arguments",
-	"boolean",
-	"break",
-	"byte",
-	"case",
-	"catch",
-	"char",
-	"class",
-	"const",
-	"continue",
-	"debugger",
-	"default",
-	"delete",
-	"do",
-	"double",
-	"else",
-	"enum",
-	"eval",
-	"export",
-	"extends",
-	"false",
-	"final",
-	"finally",
-	"float",
-	"for",
-	"function",
-	"goto",
-	"if",
-	"implements",
-	"import",
-	"in",
-	"instanceof",
-	"int",
-	"interface",
-	"let",
-	"long",
-	"native",
-	"new",
-	"null",
-	"package",
-	"private",
-	"protected",
-	"public",
-	"return",
-	"short",
-	"static",
-	"super",
-	"switch",
-	"synchronized",
-	"this",
-	"throw",
-	"throws",
-	"transient",
-	"true",
-	"try",
-	"typeof",
-	"var",
-	"void",
-	"volatile",
-	"while",
-	"with",
-	"yield",
-	"Array",
-	"Date",
-	"hasOwnProperty",
-	"Infinity",
-	"isFinite",
-	"isNaN",
-	"isPrototypeOf",
-	"length",
-	"Math",
-	"name",
-	"NaN",
-	"Number",
-	"Object",
-	"prototype",
-	"String",
-	"toString",
-	"undefined",
-	"valueOf"
-]);
-/**
-* Returns `true` when `name` is a syntactically valid JavaScript variable name.
-*
-* @example
-* ```ts
-* isValidVarName('status')  // true
-* isValidVarName('class')   // false (reserved word)
-* isValidVarName('42foo')   // false (starts with digit)
-* ```
-*/
-function isValidVarName(name) {
-	if (!name || reservedWords.has(name)) return false;
-	return isIdentifier(name);
-}
-/**
-* Returns `true` when `name` is syntactically a valid identifier, ignoring reserved words.
-*
-* Reserved words and globals (`class`, `name`, `Date`, …) are valid as bare object-literal keys
-* even though they are not valid variable names, so use this (not {@link isValidVarName}) when
-* deciding whether an object key needs quoting.
-*
-* @example
-* ```ts
-* isIdentifier('name')   // true
-* isIdentifier('x-total')// false
-* ```
-*/
-function isIdentifier(name) {
-	return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name);
-}
-//#endregion
-//#region ../../internals/utils/src/strings.ts
-/**
-* Renders a dotted path or string array as an optional-chaining accessor expression rooted at
-* `accessor`. Returns `null` for an empty path.
-*
-* @example
-* ```ts
-* getNestedAccessor('pagination.next.id', 'lastPage')
-* // "lastPage?.['pagination']?.['next']?.['id']"
-* ```
-*/
-function getNestedAccessor(param, accessor) {
-	const parts = Array.isArray(param) ? param : param.split(".");
-	if (parts.length === 0 || parts.length === 1 && parts[0] === "") return null;
-	return `${accessor}?.['${`${parts.join("']?.['")}']`}`;
-}
-//#endregion
-//#region ../../internals/utils/src/url.ts
-/**
-* Keeps the OpenAPI parameter name as-is when it is already a valid JS identifier, and
-* camelCases it only enough to become one otherwise (for example a hyphenated path segment).
-*/
-function transformParam(raw) {
-	return isValidVarName(raw) ? raw : camelCase(raw);
-}
-/**
-* Helpers for OpenAPI/Swagger paths.
-*/
-var Url = class Url {
-	/**
-	* Converts an OpenAPI/Swagger path to Express-style colon syntax.
-	*
-	* @example
-	* Url.toPath('/pet/{petId}') // '/pet/:petId'
-	*/
-	static toPath(path) {
-		return path.replace(/\{([^}]+)\}/g, ":$1");
-	}
-	/**
-	* Rewrites OpenAPI placeholder names while keeping the `{...}` braces, so the generated `url`
-	* literal aligns with the grouped `path` request option that the runtime client interpolates by
-	* key.
-	*
-	* @example
-	* Url.toSafeTemplate('/user/{monetary-account-id}') // '/user/{monetaryAccountId}'
-	*/
-	static toSafeTemplate(path) {
-		return path.replace(/\{([^}]+)\}/g, (_, name) => `{${transformParam(name)}}`);
-	}
-	/**
-	* Converts an OpenAPI/Swagger path to a TypeScript template literal string.
-	* `prefix` is prepended inside the literal, and `replacer` transforms each parameter name.
-	*
-	* @example
-	* Url.toTemplateString('/pet/{petId}') // '`/pet/${petId}`'
-	*
-	* @example
-	* Url.toTemplateString('/pet/{petId}', { prefix: 'https://api' }) // '`https://api/pet/${petId}`'
-	*/
-	static toTemplateString(path, { prefix, replacer } = {}) {
-		const result = path.split(/\{([^}]+)\}/).map((part, i) => {
-			if (i % 2 === 0) return part;
-			const param = transformParam(part);
-			return `\${${replacer ? replacer(param) : param}}`;
-		}).join("");
-		return `\`${prefix ?? ""}${result}\``;
-	}
-	/**
-	* Converts an OpenAPI/Swagger path to a template literal that reads each parameter off the
-	* grouped `path` request option, e.g. `/pet/{petId}` becomes `` `/pet/${path.petId}` ``. Parameter
-	* names match the generated `path` type, and `prefix` is prepended inside the literal. Shared by
-	* the client and cypress generators that pass a grouped `path` object.
-	*
-	* @example
-	* Url.toGroupedTemplateString('/pet/{petId}') // '`/pet/${path.petId}`'
-	*/
-	static toGroupedTemplateString(path, { prefix } = {}) {
-		return Url.toTemplateString(path, {
-			prefix,
-			replacer: (name) => `path.${name}`
-		});
-	}
-};
-//#endregion
 //#region ../../internals/shared/src/params.ts
 /**
 * Drops parameters that share the same name, keeping the first.
@@ -283,11 +43,30 @@ function operationFileEntry(node, name, extname = ".ts") {
 		path: node.path
 	};
 }
+/**
+* Resolves a dependency plugin's generated file for `node.operationId`, cached in `cache` (the
+* current node's `ctx.cache`) under the resolver's own plugin name. Several dependents reading the
+* same dependency for the same operation in one pass (a query plugin's several hook generators, the
+* MCP handler, ...) share one computed name and path instead of each calling `resolver.file` again.
+*
+* @example Cache `plugin-ts`'s file for the current operation
+* ```ts
+* const fileTs = resolveDependencyOperationFile({ cache: ctx.cache, node, resolver: tsResolver, root, output })
+* ```
+*/
+function resolveDependencyOperationFile(options) {
+	const { cache, node, resolver, root, output, group } = options;
+	return cache.ensureItem(`${resolver.pluginName}:operationFile`, () => resolver.file({
+		...operationFileEntry(node, node.operationId),
+		root,
+		output,
+		group: group ?? void 0
+	}));
+}
 function getOperationLink(node, link) {
 	if (!link) return null;
 	if (typeof link === "function") return link(node) ?? null;
-	if (link === "urlPath") return node.path ? `{@link ${Url.toPath(node.path)}}` : null;
-	return node.path ? `{@link ${node.path.replaceAll("{", ":").replaceAll("}", "")}}` : null;
+	return node.path ? `{@link ${Url.toPath(node.path)}}` : null;
 }
 /**
 * Derives the shared `ContentTypeInfo` shape from a list of content types, tracking whether several
@@ -377,16 +156,24 @@ function buildOperationComments(node, options = {}) {
 	if (!splitLines) return filteredComments;
 	return filteredComments.flatMap((text) => text.split(/\r?\n/).map((line) => line.trim())).filter((comment) => Boolean(comment));
 }
+const operationParameterGroupsByNode = /* @__PURE__ */ new WeakMap();
+/**
+* Groups an operation's parameters by location (`path`/`query`/`header`/`cookie`), deduping each
+* group by name. Every plugin generator visiting the same `OperationNode` shares one AST instance
+* (see `KubbDriver`), so the result is cached per node to avoid re-filtering and re-deduping the
+* same parameters once per plugin.
+*/
 function getOperationParameters(node) {
-	return {
-		path: dedupeParams(node.parameters.filter((param) => param.in === "path").map((param) => isValidVarName(param.name) ? param : {
-			...param,
-			name: camelCase(param.name)
-		})),
+	const cached = operationParameterGroupsByNode.get(node);
+	if (cached) return cached;
+	const groups = {
+		path: dedupeParams(node.parameters.filter((param) => param.in === "path")),
 		query: dedupeParams(node.parameters.filter((param) => param.in === "query")),
 		header: dedupeParams(node.parameters.filter((param) => param.in === "header")),
 		cookie: dedupeParams(node.parameters.filter((param) => param.in === "cookie"))
 	};
+	operationParameterGroupsByNode.set(node, groups);
+	return groups;
 }
 function getStatusCodeNumber(statusCode) {
 	const code = Number(statusCode);
@@ -451,6 +238,60 @@ function resolveOperationTypeNames(node, resolver, options = {}) {
 	return result;
 }
 //#endregion
+//#region ../../internals/utils/src/casing.ts
+/**
+* Shared implementation for camelCase and PascalCase conversion.
+* Splits on common word boundaries (spaces, hyphens, underscores, dots, slashes, colons)
+* and capitalizes each word according to `pascal`.
+*
+* When `pascal` is `true` the first word is also capitalized (PascalCase), otherwise only subsequent words are.
+*/
+function toCamelOrPascal(text, pascal) {
+	return text.trim().replace(/([a-z\d])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").replace(/(\d)([a-z])/g, "$1 $2").split(/[\s\-_./\\:]+/).filter(Boolean).map((word, i) => {
+		if (word.length > 1 && word === word.toUpperCase()) return word;
+		return (i === 0 && !pascal ? word.charAt(0).toLowerCase() : word.charAt(0).toUpperCase()) + word.slice(1);
+	}).join("").replace(/[^a-zA-Z0-9]/g, "");
+}
+/**
+* Converts `text` to camelCase.
+*
+* @example Word boundaries
+* `camelCase('hello-world') // 'helloWorld'`
+*
+* @example With a prefix
+* `camelCase('tag', { prefix: 'create' }) // 'createTag'`
+*/
+function camelCase(text, { prefix = "", suffix = "" } = {}) {
+	return toCamelOrPascal(`${prefix} ${text} ${suffix}`, false);
+}
+/**
+* Uppercases only the first character of `text`, leaving the rest untouched.
+* Unlike {@link pascalCase} it never re-splits word boundaries or strips characters.
+*
+* @example
+* `capitalize('getPetById') // 'GetPetById'`
+*/
+function capitalize(text) {
+	return `${text.charAt(0).toUpperCase()}${text.slice(1)}`;
+}
+//#endregion
+//#region ../../internals/utils/src/strings.ts
+/**
+* Renders a dotted path or string array as an optional-chaining accessor expression rooted at
+* `accessor`. Returns `null` for an empty path.
+*
+* @example
+* ```ts
+* getNestedAccessor('pagination.next.id', 'lastPage')
+* // "lastPage?.['pagination']?.['next']?.['id']"
+* ```
+*/
+function getNestedAccessor(param, accessor) {
+	const parts = Array.isArray(param) ? param : param.split(".");
+	if (parts.length === 0 || parts.length === 1 && parts[0] === "") return null;
+	return `${accessor}?.['${`${parts.join("']?.['")}']`}`;
+}
+//#endregion
 //#region ../../internals/shared/src/group.ts
 /**
 * Builds the `group` config a Kubb plugin passes to `ctx.setOptions`, applying the
@@ -570,23 +411,30 @@ function resolveContractClient(options) {
 * (plugin-fetch or plugin-axios). Returns `null` when no contract plugin is in play (the inline
 * path). The plugin injects `.kubb/client.ts` at the global output root, the same path consumers
 * read `RequestConfig` / `ResponseErrorConfig` from.
+*
+* The result is cached in the current node's `cache` (`ctx.cache`) under the client plugin's name,
+* so several dependents reading the same client plugin for one operation in a single pass
+* (react-query's query/mutation/infinite generators, vue-query, swr, the MCP handler, ...) share
+* one computed result instead of each re-deriving the name and path.
 */
 function resolveClientOperation(options) {
-	const { clientPlugin, driver, node, root, output } = options;
+	const { clientPlugin, driver, node, root, output, cache } = options;
 	if (!clientPlugin) return null;
-	const resolver = driver.getResolver(clientPlugin.pluginName);
-	const plugin = driver.getPlugin(clientPlugin.pluginName);
-	const file = resolver.file({
-		...operationFileEntry(node, node.operationId),
-		root,
-		output: plugin?.options?.output ?? output,
-		group: plugin?.options?.group ?? void 0
+	return cache.ensureItem(`${clientPlugin.pluginName}:clientOperation`, () => {
+		const resolver = driver.getResolver(clientPlugin.pluginName);
+		const plugin = driver.getPlugin(clientPlugin.pluginName);
+		const file = resolver.file({
+			...operationFileEntry(node, node.operationId),
+			root,
+			output: plugin?.options?.output ?? output,
+			group: plugin?.options?.group ?? void 0
+		});
+		return {
+			name: resolver.name(node.operationId),
+			path: file.path,
+			clientPath: path.resolve(root, ".kubb/client.ts")
+		};
 	});
-	return {
-		name: resolver.name(node.operationId),
-		path: file.path,
-		clientPath: path.resolve(root, ".kubb/client.ts")
-	};
 }
 //#endregion
 //#region ../../internals/tanstack-query/src/utils.ts
@@ -657,14 +505,16 @@ function buildGroupedRequestParam(node, options) {
 */
 function buildQueryOptionsParams(node, options) {
 	const { resolver, memberTypeWrapper } = options;
-	return createFunctionParameters({ params: [buildGroupedRequestParam(node, {
+	const groupedParam = buildGroupedRequestParam(node, {
 		resolver,
 		memberTypeWrapper
-	}), createFunctionParameter({
+	});
+	const configParam = createFunctionParameter({
 		name: "config",
 		type: `Partial<Omit<RequestConfig, 'path' | 'query' | 'body' | 'headers' | 'url'>>`,
 		default: "{}"
-	})].filter((param) => param !== null) });
+	});
+	return createFunctionParameters({ params: [groupedParam, configParam].filter((param) => param !== null) });
 }
 /**
 * Builds the call to a client `<op>` function inside a query/mutation hook body. The function takes
@@ -762,6 +612,19 @@ function resolveMutationConfig(mutation, options) {
 	};
 }
 /**
+* Classifies an operation as a query or a mutation from the resolved `query` / `mutation` method lists.
+* `query: false` still marks the operation as a query so the query-family generators keep matching it,
+* and a method already claimed by `query` never counts as a mutation.
+*/
+function classifyOperation(node, { query, mutation }) {
+	const isQuery = query === false || !!query && query.methods.some((method) => node.method.toLowerCase() === method.toLowerCase());
+	const queryMethods = new Set(query ? query.methods : []);
+	return {
+		isQuery,
+		isMutation: mutation !== false && !isQuery && (mutation ? mutation.methods : []).some((method) => !queryMethods.has(method) && node.method.toLowerCase() === method.toLowerCase())
+	};
+}
+/**
 * Applies the shared infinite-query defaults during plugin setup: a falsy value disables infinite
 * queries, and an object merges over `queryParam: 'id'` and `initialPageParam: 0` with the cursor
 * paths cleared.
@@ -800,6 +663,24 @@ function resolveOperationOverrides(node, override) {
 	return override.find((ov) => matchesPattern(node, ov))?.options ?? {};
 }
 /**
+* The request groups a query key is built from, matching `buildQueryKeyParams`. Headers are
+* deliberately absent: they do not identify a cache entry, so the key factory takes no parameter
+* for an operation that only carries headers.
+*/
+const queryKeyGroupOrder = [
+	"path",
+	"query",
+	"body"
+];
+/**
+* Whether the generated query key factory declares a parameter, so a call site passes an argument
+* only when one is accepted.
+*/
+function hasQueryKeyParams(node) {
+	const groups = getRequestGroups(node);
+	return queryKeyGroupOrder.some((key) => groups[key]);
+}
+/**
 * Build QueryKey params as the grouped `{ path, query, body }` object (NO headers, NO config),
 * typed from the operation's `Options` minus `url`. The query key transformer reads the
 * grouped `path`/`query`/`body` bindings.
@@ -808,11 +689,7 @@ function buildQueryKeyParams(node, options) {
 	const { resolver } = options;
 	const groupedParam = buildGroupedRequestParam(node, {
 		resolver,
-		keys: [
-			"path",
-			"query",
-			"body"
-		]
+		keys: queryKeyGroupOrder
 	});
 	return createFunctionParameters({ params: groupedParam ? [groupedParam] : [] });
 }
@@ -829,11 +706,7 @@ function InfiniteQueryOptions({ name, clientName, initialPageParam, cursorParam,
 	});
 	const groupedKeyParam = buildGroupedRequestParam(node, {
 		resolver: tsResolver,
-		keys: [
-			"path",
-			"query",
-			"body"
-		],
+		keys: queryKeyGroupOrder,
 		memberTypeWrapper
 	});
 	const queryKeyParamsNode = createFunctionParameters({ params: groupedKeyParam ? [groupedKeyParam] : [] });
@@ -1131,19 +1004,6 @@ function buildResolvedRequestParams(node) {
 	if (names.length === 0) return null;
 	return `{ ${names.map((name) => `${name}: typeof ${name} === 'function' ? ${name}() : ${name}`).join(", ")} }`;
 }
-/**
-* Classifies an operation as a query or a mutation from the resolved `query` / `mutation` method lists.
-* `query: false` still marks the operation as a query so the query-family generators keep matching it,
-* and a method already claimed by `query` never counts as a mutation.
-*/
-function classifyOperation(node, { query, mutation }) {
-	const isQuery = query === false || !!query && query.methods.some((method) => node.method.toLowerCase() === method.toLowerCase());
-	const queryMethods = new Set(query ? query.methods : []);
-	return {
-		isQuery,
-		isMutation: mutation !== false && !isQuery && (mutation ? mutation.methods : []).some((method) => !queryMethods.has(method) && node.method.toLowerCase() === method.toLowerCase())
-	};
-}
 //#endregion
 //#region src/generators/hookOptionsGenerator.tsx
 /**
@@ -1318,10 +1178,11 @@ function buildInfiniteQueryParamsNode(node, options) {
 }`,
 		default: "{}"
 	});
-	return createFunctionParameters({ params: [buildGroupedRequestParam(node, {
+	const groupedParam = buildGroupedRequestParam(node, {
 		resolver,
 		memberTypeWrapper: maybeValueOrGetter
-	}), optionsParam].filter((param) => param !== null) });
+	});
+	return createFunctionParameters({ params: [groupedParam, optionsParam].filter((param) => param !== null) });
 }
 function InfiniteQuery({ name, queryKeyTypeName, queryOptionsName, queryKeyName, node, tsResolver, initialPageParam, queryParam, customOptions, suspense }) {
 	const { TData: responseType, TError: errorType } = buildResponseTypes(node, tsResolver);
@@ -1341,7 +1202,7 @@ function InfiniteQuery({ name, queryKeyTypeName, queryOptionsName, queryKeyName,
 		`TPageParam = ${pageParamType}`
 	];
 	const resolvedParams = buildResolvedRequestParams(node);
-	const queryKeyArgs = resolvedParams ? "resolvedParams" : "";
+	const queryKeyArgs = resolvedParams && hasQueryKeyParams(node) ? "resolvedParams" : "";
 	const queryOptionsArgs = resolvedParams ? "resolvedParams, config" : "config";
 	const paramsNode = buildInfiniteQueryParamsNode(node, {
 		resolver: tsResolver,
@@ -1434,15 +1295,16 @@ function resolveMutationRequestType(node, resolver) {
 function buildMutationParamsNode(node, options) {
 	const { resolver } = options;
 	const { TData, TError } = buildResponseTypes(node, resolver);
+	const generics = [
+		TData,
+		TError,
+		resolveMutationRequestType(node, resolver),
+		"TContext"
+	].join(", ");
 	return createFunctionParameters({ params: [createFunctionParameter({
 		name: "options",
 		type: `{
-  mutation?: UseMutationOptions<${[
-			TData,
-			TError,
-			resolveMutationRequestType(node, resolver),
-			"TContext"
-		].join(", ")}> & { client?: QueryClient },
+  mutation?: UseMutationOptions<${generics}> & { client?: QueryClient },
   client?: ${buildRequestConfigType(node)},
 }`,
 		default: "{}"
@@ -1500,10 +1362,11 @@ function buildQueryParamsNode(node, options) {
 }`,
 		default: "{}"
 	});
-	return createFunctionParameters({ params: [buildGroupedRequestParam(node, {
+	const groupedParam = buildGroupedRequestParam(node, {
 		resolver,
 		memberTypeWrapper: maybeValueOrGetter
-	}), optionsParam].filter((param) => param !== null) });
+	});
+	return createFunctionParameters({ params: [groupedParam, optionsParam].filter((param) => param !== null) });
 }
 function Query({ name, queryKeyTypeName, queryOptionsName, queryKeyName, node, tsResolver, customOptions, suspense }) {
 	const { TData, TError } = buildResponseTypes(node, tsResolver);
@@ -1528,7 +1391,7 @@ function Query({ name, queryKeyTypeName, queryOptionsName, queryKeyName, node, t
 		`TQueryKey extends QueryKey = ${queryKeyTypeName}`
 	];
 	const resolvedParams = buildResolvedRequestParams(node);
-	const queryKeyArgs = resolvedParams ? "resolvedParams" : "";
+	const queryKeyArgs = resolvedParams && hasQueryKeyParams(node) ? "resolvedParams" : "";
 	const queryOptionsArgs = resolvedParams ? "resolvedParams, config" : "config";
 	const paramsNode = buildQueryParamsNode(node, {
 		resolver: tsResolver,
@@ -1568,14 +1431,11 @@ function Query({ name, queryKeyTypeName, queryOptionsName, queryKeyName, node, t
 //#region src/components/QueryOptions.tsx
 const declarationPrinter = functionPrinter({ mode: "declaration" });
 const callPrinter = functionPrinter({ mode: "call" });
-function getQueryOptionsParams(node, options) {
-	return buildQueryOptionsParams(node, options);
-}
 function QueryOptions({ name, clientName, node, tsResolver, queryKeyName }) {
 	const { TData, TError } = buildResponseTypes(node, tsResolver);
 	const queryKeyParamsNode = buildQueryKeyParams(node, { resolver: tsResolver });
 	const queryKeyParamsCall = callPrinter.print(queryKeyParamsNode) ?? "";
-	const paramsNode = getQueryOptionsParams(node, { resolver: tsResolver });
+	const paramsNode = buildQueryOptionsParams(node, { resolver: tsResolver });
 	const paramsSignature = declarationPrinter.print(paramsNode) ?? "";
 	const queryFnBody = `const { data } = await ${buildClientCall(node, {
 		clientName,
@@ -1606,36 +1466,44 @@ function QueryOptions({ name, clientName, node, tsResolver, queryKeyName }) {
 //#region src/generators/infiniteQueryGenerator.tsx
 /**
 * Built-in generator for `useInfiniteQuery` hooks. Enabled when
-* `pluginReactQuery({ infinite: { ... } })`. Emits one `useFooInfiniteQuery`
-* hook per query operation, wiring the configured `nextParam` /
-* `previousParam` paths into TanStack Query's cursor-based pagination.
+* `pluginReactQuery({ infinite: { ... }, hooks: true })`. Emits one
+* `useFooInfiniteQuery` hook per query operation, wiring the configured
+* `nextParam` / `previousParam` paths into TanStack Query's cursor-based
+* pagination.
 */
 const infiniteQueryGenerator = defineGenerator({
 	name: "react-infinite-query",
 	renderer: jsxRenderer,
+	match(node, ctx) {
+		const operationNode = node;
+		if (!ast.isHttpOperationNode(operationNode)) return false;
+		const { query, mutation, infinite, hooks } = ctx.options;
+		const { isQuery, isMutation } = classifyOperation(operationNode, {
+			query,
+			mutation
+		});
+		const infiniteOptions = infinite && typeof infinite === "object" ? infinite : null;
+		if (!isQuery || isMutation || !infiniteOptions || !hooks) return false;
+		const queryParamKeys = getOperationParameters(operationNode).query.map((p) => p.name);
+		return infiniteOptions.queryParam ? queryParamKeys.includes(infiniteOptions.queryParam) || queryParamKeys.includes(`${infiniteOptions.queryParam}?`) : false;
+	},
 	operation(node, ctx) {
 		if (!ast.isHttpOperationNode(node)) return null;
 		const { config, driver, resolver, root } = ctx;
-		const { output, query, mutation, infinite, client, group, customOptions, hooks } = ctx.options;
+		const { output, query, infinite, client, group, customOptions } = ctx.options;
 		const pluginTs = driver.getPlugin(pluginTsName);
 		if (!pluginTs) return null;
 		const tsResolver = driver.getResolver(pluginTsName);
-		const { isQuery, isMutation } = classifyOperation(node, {
-			query,
-			mutation
-		});
 		const infiniteOptions = infinite && typeof infinite === "object" ? infinite : null;
-		if (!isQuery || isMutation || !infiniteOptions) return null;
-		const normalizeKey = (key) => key.replace(/\?$/, "");
-		const queryParamKeys = getOperationParameters(node).query.map((p) => p.name);
-		if (!(infiniteOptions.queryParam ? queryParamKeys.some((k) => normalizeKey(k) === infiniteOptions.queryParam) : false)) return null;
+		if (!infiniteOptions) return null;
 		const importPath = query ? query.importPath : "@tanstack/react-query";
 		const contractOp = resolveClientOperation({
 			clientPlugin: { pluginName: client.pluginName },
 			driver,
 			node,
 			root,
-			output
+			output,
+			cache: ctx.cache
 		});
 		if (!contractOp) return null;
 		const queryName = resolver.infiniteQuery.name(node);
@@ -1649,15 +1517,20 @@ const infiniteQueryGenerator = defineGenerator({
 				output,
 				group: group ?? void 0
 			}),
-			fileTs: tsResolver.file({
-				...operationFileEntry(node, node.operationId),
+			fileTs: resolveDependencyOperationFile({
+				cache: ctx.cache,
+				node,
+				resolver: tsResolver,
 				root,
 				output: pluginTs.options?.output ?? output,
-				group: pluginTs.options?.group ?? void 0
+				group: pluginTs.options?.group
 			})
 		};
-		const rawQueryParams = getOperationParameters(node).query;
-		const queryParamsTypeName = rawQueryParams.length > 0 && tsResolver.param.query(node, rawQueryParams[0]) !== tsResolver.param.name(node, rawQueryParams[0]) ? tsResolver.param.query(node, rawQueryParams[0]) : null;
+		const { queryParamsTypeName } = resolvePageParamType(node, {
+			resolver: tsResolver,
+			initialPageParam: infiniteOptions.initialPageParam,
+			queryParam: infiniteOptions.queryParam
+		});
 		const importedTypeNames = [
 			tsResolver.response.options(node),
 			queryParamsTypeName,
@@ -1738,33 +1611,31 @@ const infiniteQueryGenerator = defineGenerator({
 					initialPageParam: infiniteOptions.initialPageParam,
 					queryParam: infiniteOptions.queryParam
 				}),
-				hooks && /* @__PURE__ */ jsxs(Fragment, { children: [
-					/* @__PURE__ */ jsx(File.Import, {
-						name: ["useInfiniteQuery"],
-						path: importPath
-					}),
-					/* @__PURE__ */ jsx(File.Import, {
-						name: [
-							"QueryKey",
-							"QueryClient",
-							"InfiniteQueryObserverOptions",
-							"UseInfiniteQueryResult"
-						],
-						path: importPath,
-						isTypeOnly: true
-					}),
-					/* @__PURE__ */ jsx(InfiniteQuery, {
-						name: queryName,
-						queryOptionsName,
-						queryKeyName,
-						queryKeyTypeName,
-						node,
-						tsResolver,
-						initialPageParam: infiniteOptions.initialPageParam,
-						queryParam: infiniteOptions.queryParam,
-						customOptions
-					})
-				] })
+				/* @__PURE__ */ jsx(File.Import, {
+					name: ["useInfiniteQuery"],
+					path: importPath
+				}),
+				/* @__PURE__ */ jsx(File.Import, {
+					name: [
+						"QueryKey",
+						"QueryClient",
+						"InfiniteQueryObserverOptions",
+						"UseInfiniteQueryResult"
+					],
+					path: importPath,
+					isTypeOnly: true
+				}),
+				/* @__PURE__ */ jsx(InfiniteQuery, {
+					name: queryName,
+					queryOptionsName,
+					queryKeyName,
+					queryKeyTypeName,
+					node,
+					tsResolver,
+					initialPageParam: infiniteOptions.initialPageParam,
+					queryParam: infiniteOptions.queryParam,
+					customOptions
+				})
 			]
 		});
 	}
@@ -1779,25 +1650,30 @@ const infiniteQueryGenerator = defineGenerator({
 const mutationGenerator = defineGenerator({
 	name: "react-query-mutation",
 	renderer: jsxRenderer,
+	match(node, ctx) {
+		const operationNode = node;
+		if (!ast.isHttpOperationNode(operationNode)) return false;
+		const { query, mutation } = ctx.options;
+		return classifyOperation(operationNode, {
+			query,
+			mutation
+		}).isMutation;
+	},
 	operation(node, ctx) {
 		if (!ast.isHttpOperationNode(node)) return null;
 		const { config, driver, resolver, root } = ctx;
-		const { output, query, mutation, client, group, customOptions, hooks } = ctx.options;
+		const { output, mutation, client, group, customOptions, hooks } = ctx.options;
 		const pluginTs = driver.getPlugin(pluginTsName);
 		if (!pluginTs) return null;
 		const tsResolver = driver.getResolver(pluginTsName);
-		const { isMutation } = classifyOperation(node, {
-			query,
-			mutation
-		});
-		if (!isMutation) return null;
 		const importPath = mutation ? mutation.importPath : "@tanstack/react-query";
 		const contractOp = resolveClientOperation({
 			clientPlugin: { pluginName: client.pluginName },
 			driver,
 			node,
 			root,
-			output
+			output,
+			cache: ctx.cache
 		});
 		if (!contractOp) return null;
 		const mutationHookName = resolver.mutation.name(node);
@@ -1811,11 +1687,13 @@ const mutationGenerator = defineGenerator({
 				output,
 				group: group ?? void 0
 			}),
-			fileTs: tsResolver.file({
-				...operationFileEntry(node, node.operationId),
+			fileTs: resolveDependencyOperationFile({
+				cache: ctx.cache,
+				node,
+				resolver: tsResolver,
 				root,
 				output: pluginTs.options?.output ?? output,
-				group: pluginTs.options?.group ?? void 0
+				group: pluginTs.options?.group
 			})
 		};
 		const importedTypeNames = [tsResolver.response.options(node), ...resolveOperationTypeNames(node, tsResolver, {
@@ -1919,25 +1797,31 @@ const mutationGenerator = defineGenerator({
 const queryGenerator = defineGenerator({
 	name: "react-query",
 	renderer: jsxRenderer,
+	match(node, ctx) {
+		const operationNode = node;
+		if (!ast.isHttpOperationNode(operationNode)) return false;
+		const { query, mutation } = ctx.options;
+		const { isQuery, isMutation } = classifyOperation(operationNode, {
+			query,
+			mutation
+		});
+		return isQuery && !isMutation;
+	},
 	operation(node, ctx) {
 		if (!ast.isHttpOperationNode(node)) return null;
 		const { config, driver, resolver, root } = ctx;
-		const { output, query, mutation, client, group, customOptions, hooks } = ctx.options;
+		const { output, query, client, group, customOptions, hooks } = ctx.options;
 		const pluginTs = driver.getPlugin(pluginTsName);
 		if (!pluginTs) return null;
 		const tsResolver = driver.getResolver(pluginTsName);
-		const { isQuery, isMutation } = classifyOperation(node, {
-			query,
-			mutation
-		});
-		if (!isQuery || isMutation) return null;
 		const importPath = query ? query.importPath : "@tanstack/react-query";
 		const contractOp = resolveClientOperation({
 			clientPlugin: { pluginName: client.pluginName },
 			driver,
 			node,
 			root,
-			output
+			output,
+			cache: ctx.cache
 		});
 		if (!contractOp) return null;
 		const queryName = resolver.query.name(node);
@@ -1951,11 +1835,13 @@ const queryGenerator = defineGenerator({
 				output,
 				group: group ?? void 0
 			}),
-			fileTs: tsResolver.file({
-				...operationFileEntry(node, node.operationId),
+			fileTs: resolveDependencyOperationFile({
+				cache: ctx.cache,
+				node,
+				resolver: tsResolver,
 				root,
 				output: pluginTs.options?.output ?? output,
-				group: pluginTs.options?.group ?? void 0
+				group: pluginTs.options?.group
 			})
 		};
 		const importedTypeNames = [tsResolver.response.options(node), ...resolveOperationTypeNames(node, tsResolver, {
@@ -2056,38 +1942,44 @@ const queryGenerator = defineGenerator({
 //#endregion
 //#region src/generators/suspenseInfiniteQueryGenerator.tsx
 /**
-* Built-in generator for `useSuspenseInfiniteQuery` hooks. Enabled when both
-* `suspense` and `infinite` are configured. Combines suspense semantics with
-* cursor-based pagination. Handlers throw promises while loading and pull
-* additional pages on demand.
+* Built-in generator for `useSuspenseInfiniteQuery` hooks. Enabled when
+* `suspense`, `infinite`, and `hooks` are all configured. Combines suspense
+* semantics with cursor-based pagination. Handlers throw promises while
+* loading and pull additional pages on demand.
 */
 const suspenseInfiniteQueryGenerator = defineGenerator({
 	name: "react-suspense-infinite-query",
 	renderer: jsxRenderer,
+	match(node, ctx) {
+		const operationNode = node;
+		if (!ast.isHttpOperationNode(operationNode)) return false;
+		const { query, mutation, infinite, suspense, hooks } = ctx.options;
+		const { isQuery, isMutation } = classifyOperation(operationNode, {
+			query,
+			mutation
+		});
+		const infiniteOptions = infinite && typeof infinite === "object" ? infinite : null;
+		if (!isQuery || isMutation || !suspense || !infiniteOptions || !hooks) return false;
+		const queryParamKeys = getOperationParameters(operationNode).query.map((p) => p.name);
+		return infiniteOptions.queryParam ? queryParamKeys.includes(infiniteOptions.queryParam) || queryParamKeys.includes(`${infiniteOptions.queryParam}?`) : false;
+	},
 	operation(node, ctx) {
 		if (!ast.isHttpOperationNode(node)) return null;
 		const { config, driver, resolver, root } = ctx;
-		const { output, query, mutation, infinite, suspense, client, group, customOptions, hooks } = ctx.options;
+		const { output, query, infinite, client, group, customOptions } = ctx.options;
 		const pluginTs = driver.getPlugin(pluginTsName);
 		if (!pluginTs) return null;
 		const tsResolver = driver.getResolver(pluginTsName);
-		const { isQuery, isMutation } = classifyOperation(node, {
-			query,
-			mutation
-		});
-		const isSuspense = !!suspense;
 		const infiniteOptions = infinite && typeof infinite === "object" ? infinite : null;
-		if (!isQuery || isMutation || !isSuspense || !infiniteOptions) return null;
-		const normalizeKey = (key) => key.replace(/\?$/, "");
-		const queryParamKeys = getOperationParameters(node).query.map((p) => p.name);
-		if (!(infiniteOptions.queryParam ? queryParamKeys.some((k) => normalizeKey(k) === infiniteOptions.queryParam) : false)) return null;
+		if (!infiniteOptions) return null;
 		const importPath = query ? query.importPath : "@tanstack/react-query";
 		const contractOp = resolveClientOperation({
 			clientPlugin: { pluginName: client.pluginName },
 			driver,
 			node,
 			root,
-			output
+			output,
+			cache: ctx.cache
 		});
 		if (!contractOp) return null;
 		const queryName = resolver.suspenseInfiniteQuery.name(node);
@@ -2101,11 +1993,13 @@ const suspenseInfiniteQueryGenerator = defineGenerator({
 				output,
 				group: group ?? void 0
 			}),
-			fileTs: tsResolver.file({
-				...operationFileEntry(node, node.operationId),
+			fileTs: resolveDependencyOperationFile({
+				cache: ctx.cache,
+				node,
+				resolver: tsResolver,
 				root,
 				output: pluginTs.options?.output ?? output,
-				group: pluginTs.options?.group ?? void 0
+				group: pluginTs.options?.group
 			})
 		};
 		const rawQueryParams = getOperationParameters(node).query;
@@ -2189,34 +2083,32 @@ const suspenseInfiniteQueryGenerator = defineGenerator({
 					initialPageParam: infiniteOptions.initialPageParam,
 					queryParam: infiniteOptions.queryParam
 				}),
-				hooks && /* @__PURE__ */ jsxs(Fragment, { children: [
-					/* @__PURE__ */ jsx(File.Import, {
-						name: ["useSuspenseInfiniteQuery"],
-						path: importPath
-					}),
-					/* @__PURE__ */ jsx(File.Import, {
-						name: [
-							"QueryKey",
-							"QueryClient",
-							"UseSuspenseInfiniteQueryOptions",
-							"UseSuspenseInfiniteQueryResult"
-						],
-						path: importPath,
-						isTypeOnly: true
-					}),
-					/* @__PURE__ */ jsx(InfiniteQuery, {
-						name: queryName,
-						queryOptionsName,
-						queryKeyName,
-						queryKeyTypeName,
-						node,
-						tsResolver,
-						initialPageParam: infiniteOptions.initialPageParam,
-						queryParam: infiniteOptions.queryParam,
-						customOptions,
-						suspense: true
-					})
-				] })
+				/* @__PURE__ */ jsx(File.Import, {
+					name: ["useSuspenseInfiniteQuery"],
+					path: importPath
+				}),
+				/* @__PURE__ */ jsx(File.Import, {
+					name: [
+						"QueryKey",
+						"QueryClient",
+						"UseSuspenseInfiniteQueryOptions",
+						"UseSuspenseInfiniteQueryResult"
+					],
+					path: importPath,
+					isTypeOnly: true
+				}),
+				/* @__PURE__ */ jsx(InfiniteQuery, {
+					name: queryName,
+					queryOptionsName,
+					queryKeyName,
+					queryKeyTypeName,
+					node,
+					tsResolver,
+					initialPageParam: infiniteOptions.initialPageParam,
+					queryParam: infiniteOptions.queryParam,
+					customOptions,
+					suspense: true
+				})
 			]
 		});
 	}
@@ -2225,32 +2117,39 @@ const suspenseInfiniteQueryGenerator = defineGenerator({
 //#region src/generators/suspenseQueryGenerator.tsx
 /**
 * Built-in generator for `useSuspenseQuery` hooks. Enabled when
-* `pluginReactQuery({ suspense: {} })`. Emits one `useFooSuspenseQuery` hook
-* per query operation. Suspense queries throw promises while loading and
-* require a `<Suspense>` boundary in the React tree. TanStack Query v5+ only.
+* `pluginReactQuery({ suspense: {}, hooks: true })`. Emits one
+* `useFooSuspenseQuery` hook per query operation. Suspense queries throw
+* promises while loading and require a `<Suspense>` boundary in the React
+* tree. TanStack Query v5+ only.
 */
 const suspenseQueryGenerator = defineGenerator({
 	name: "react-suspense-query",
 	renderer: jsxRenderer,
+	match(node, ctx) {
+		const operationNode = node;
+		if (!ast.isHttpOperationNode(operationNode)) return false;
+		const { query, mutation, suspense, hooks } = ctx.options;
+		const { isQuery, isMutation } = classifyOperation(operationNode, {
+			query,
+			mutation
+		});
+		return isQuery && !isMutation && !!suspense && hooks;
+	},
 	operation(node, ctx) {
 		if (!ast.isHttpOperationNode(node)) return null;
 		const { config, driver, resolver, root } = ctx;
-		const { output, query, mutation, suspense, client, group, customOptions, hooks } = ctx.options;
+		const { output, query, client, group, customOptions } = ctx.options;
 		const pluginTs = driver.getPlugin(pluginTsName);
 		if (!pluginTs) return null;
 		const tsResolver = driver.getResolver(pluginTsName);
-		const { isQuery, isMutation } = classifyOperation(node, {
-			query,
-			mutation
-		});
-		if (!isQuery || isMutation || !!!suspense) return null;
 		const importPath = query ? query.importPath : "@tanstack/react-query";
 		const contractOp = resolveClientOperation({
 			clientPlugin: { pluginName: client.pluginName },
 			driver,
 			node,
 			root,
-			output
+			output,
+			cache: ctx.cache
 		});
 		if (!contractOp) return null;
 		const queryName = resolver.suspenseQuery.name(node);
@@ -2264,11 +2163,13 @@ const suspenseQueryGenerator = defineGenerator({
 				output,
 				group: group ?? void 0
 			}),
-			fileTs: tsResolver.file({
-				...operationFileEntry(node, node.operationId),
+			fileTs: resolveDependencyOperationFile({
+				cache: ctx.cache,
+				node,
+				resolver: tsResolver,
 				root,
 				output: pluginTs.options?.output ?? output,
-				group: pluginTs.options?.group ?? void 0
+				group: pluginTs.options?.group
 			})
 		};
 		const importedTypeNames = [tsResolver.response.options(node), ...resolveOperationTypeNames(node, tsResolver, {
@@ -2337,32 +2238,30 @@ const suspenseQueryGenerator = defineGenerator({
 					node,
 					tsResolver
 				}),
-				suspense && hooks && /* @__PURE__ */ jsxs(Fragment, { children: [
-					/* @__PURE__ */ jsx(File.Import, {
-						name: ["useSuspenseQuery"],
-						path: importPath
-					}),
-					/* @__PURE__ */ jsx(File.Import, {
-						name: [
-							"QueryKey",
-							"QueryClient",
-							"UseSuspenseQueryOptions",
-							"UseSuspenseQueryResult"
-						],
-						path: importPath,
-						isTypeOnly: true
-					}),
-					/* @__PURE__ */ jsx(Query, {
-						name: queryName,
-						queryOptionsName,
-						queryKeyName,
-						queryKeyTypeName,
-						node,
-						tsResolver,
-						customOptions,
-						suspense: true
-					})
-				] })
+				/* @__PURE__ */ jsx(File.Import, {
+					name: ["useSuspenseQuery"],
+					path: importPath
+				}),
+				/* @__PURE__ */ jsx(File.Import, {
+					name: [
+						"QueryKey",
+						"QueryClient",
+						"UseSuspenseQueryOptions",
+						"UseSuspenseQueryResult"
+					],
+					path: importPath,
+					isTypeOnly: true
+				}),
+				/* @__PURE__ */ jsx(Query, {
+					name: queryName,
+					queryOptionsName,
+					queryKeyName,
+					queryKeyTypeName,
+					node,
+					tsResolver,
+					customOptions,
+					suspense: true
+				})
 			]
 		});
 	}
@@ -2448,7 +2347,7 @@ const pluginReactQuery = definePlugin((options) => {
 	const { output = {
 		path: "hooks",
 		barrel: { type: "named" }
-	}, group, exclude = [], include, override = [], suspense = {}, infinite = false, mutation = {}, query = {}, mutationKey = mutationKeyTransformer, queryKey = queryKeyTransformer, customOptions, hooks = false, client, resolver: userResolver, macros: userMacros } = options;
+	}, group, exclude = [], include, override = [], suspense = false, infinite = false, mutation = {}, query = {}, mutationKey = mutationKeyTransformer, queryKey = queryKeyTransformer, customOptions, hooks = false, client, resolver: userResolver, macros: userMacros } = options;
 	const selectedGenerators = [
 		queryGenerator,
 		suspenseQueryGenerator,