@orval/query 8.9.1 → 8.11.0

package/dist/index.mjs

@@ -10,7 +10,10 @@ const normalizeQueryOptions = (queryOptions = {}, outputWorkspace) => {
 		...queryOptions.useInvalidate ? { useInvalidate: true } : {},
 		...queryOptions.useSetQueryData ? { useSetQueryData: true } : {},
 		...queryOptions.useGetQueryData ? { useGetQueryData: true } : {},
-		...queryOptions.useQuery ? { useQuery: true } : {},
+		...queryOptions.useQuery === void 0 ? {} : { useQuery: queryOptions.useQuery },
+		...queryOptions.useMutation === void 0 ? {} : { useMutation: queryOptions.useMutation },
+		...queryOptions.useSuspenseQuery ? { useSuspenseQuery: true } : {},
+		...queryOptions.useSuspenseInfiniteQuery ? { useSuspenseInfiniteQuery: true } : {},
 		...queryOptions.useInfinite ? { useInfinite: true } : {},
 		...queryOptions.useInfiniteQueryParam ? { useInfiniteQueryParam: queryOptions.useInfiniteQueryParam } : {},
 		...queryOptions.options ? { options: queryOptions.options } : {},
@@ -701,8 +704,11 @@ const VUE_QUERY_DEPENDENCIES = [{
 	],
 	dependency: "vue"
 }];
-const getSolidQueryImports = (prefix) => {
+const getSolidQueryImports = (prefix, hasRenamedOptionsTypes) => {
 	const capitalized = prefix === "use" ? "Use" : "Create";
+	const queryOptionsTypeName = hasRenamedOptionsTypes ? "QueryOptions" : "SolidQueryOptions";
+	const infiniteQueryOptionsTypeName = hasRenamedOptionsTypes ? "InfiniteQueryOptions" : "SolidInfiniteQueryOptions";
+	const mutationOptionsTypeName = hasRenamedOptionsTypes ? "MutationOptions" : "SolidMutationOptions";
 	return [{
 		exports: [
 			{
@@ -719,10 +725,9 @@ const getSolidQueryImports = (prefix) => {
 			},
 			{ name: `${capitalized}QueryOptions` },
 			{ name: `${capitalized}InfiniteQueryOptions` },
-			{ name: `${capitalized}MutationOptions` },
-			{ name: "SolidQueryOptions" },
-			{ name: "SolidInfiniteQueryOptions" },
-			{ name: "SolidMutationOptions" },
+			{ name: queryOptionsTypeName },
+			{ name: infiniteQueryOptionsTypeName },
+			{ name: mutationOptionsTypeName },
 			{ name: "QueryFunction" },
 			{ name: "MutationFunction" },
 			{ name: `${capitalized}QueryResult` },
@@ -803,7 +808,7 @@ const getSolidQueryDependencies = (hasGlobalMutator, hasParamsSerializerOptions,
 	return [
 		...!hasGlobalMutator && httpClient === OutputHttpClient.AXIOS ? AXIOS_DEPENDENCIES : [],
 		...hasParamsSerializerOptions ? PARAMS_SERIALIZER_DEPENDENCIES : [],
-		...getSolidQueryImports(isSolidQueryWithUsePrefix(packageJson) ? "use" : "create")
+		...getSolidQueryImports(isSolidQueryWithUsePrefix(packageJson) ? "use" : "create", isSolidQueryWithRenamedOptionsTypes(packageJson))
 	];
 };
 const getAngularQueryDependencies = (hasGlobalMutator, hasParamsSerializerOptions, packageJson, httpClient) => {
@@ -861,6 +866,25 @@ const isSolidQueryWithUsePrefix = (packageJson) => {
 	const withoutRc = version.split("-")[0];
 	return compareVersions(withoutRc, "5.71.5");
 };
+/**
+* Solid Query renamed its plain options interfaces in v5.100.6, dropping the
+* `Solid` prefix:
+*   - `SolidQueryOptions` → `QueryOptions`
+*   - `SolidInfiniteQueryOptions` → `InfiniteQueryOptions`
+*   - `SolidMutationOptions` → `MutationOptions`
+*
+* The Accessor wrappers `UseQueryOptions` / `UseInfiniteQueryOptions` /
+* `UseMutationOptions` keep the same names but reference the renamed
+* interfaces internally.
+*
+* https://github.com/TanStack/query/commit/<rename-commit>
+*/
+const isSolidQueryWithRenamedOptionsTypes = (packageJson) => {
+	const version = getPackageByQueryClient(packageJson, "solid-query");
+	if (!version) return false;
+	const withoutRc = version.split("-")[0];
+	return compareVersions(withoutRc, "5.100.6");
+};
 const getPackageByQueryClient = (packageJson, queryClient) => {
 	switch (queryClient) {
 		case "react-query": {
@@ -901,7 +925,7 @@ const generateQueryOptions = ({ params, options, type, adapter }) => {
 		if (options) return `${queryConfig} ...queryOptions`;
 		return "...queryOptions";
 	}
-	return `${adapter ? adapter.generateEnabledOption(params, options) : !isObject(options) || !Object.hasOwn(options, "enabled") ? `enabled: !!(${params.map(({ name }) => name).join(" && ")}),` : ""}${queryConfig} ...queryOptions`;
+	return `${adapter ? adapter.generateEnabledOption(params, options) : !isObject(options) || !Object.hasOwn(options, "enabled") ? `enabled: ${params.map(({ name }) => `${name} != null`).join(" && ")},` : ""}${queryConfig} ...queryOptions`;
 };
 const isSuspenseQuery = (type) => {
 	return [QueryType.SUSPENSE_INFINITE, QueryType.SUSPENSE_QUERY].includes(type);
@@ -922,7 +946,7 @@ const getQueryOptionsDefinition = ({ operationName, mutator, definitions, type,
 		const optionType = optionsTypeName ? `${optionsTypeName}<${funcReturnType}, TError, TData${hasQueryV5 && (type === QueryType.INFINITE || type === QueryType.SUSPENSE_INFINITE) && queryParam && queryParams ? `, QueryKey, ${queryParams.schema.name}['${queryParam}']` : ""}>` : `${prefix}${pascal(type)}Options<${funcReturnType}, TError, TData${hasQueryV5 && (type === QueryType.INFINITE || type === QueryType.SUSPENSE_INFINITE) && queryParam && queryParams ? hasQueryV5WithInfiniteQueryOptionsError ? `, QueryKey, ${queryParams.schema.name}['${queryParam}']` : `, ${funcReturnType}, QueryKey, ${queryParams.schema.name}['${queryParam}']` : ""}>`;
 		return `${partialOptions ? "Partial<" : ""}${optionType}${partialOptions ? ">" : ""}${optionTypeInitialDataPostfix}`;
 	}
-	const mutationOptionsTypeName = isReturnType && adapter?.getOptionsReturnTypeName ? adapter.getOptionsReturnTypeName("mutation") : void 0;
+	const mutationOptionsTypeName = adapter?.getOptionsReturnTypeName ? adapter.getOptionsReturnTypeName("mutation") : void 0;
 	return mutationOptionsTypeName ? `${mutationOptionsTypeName}<Awaited<ReturnType<${isMutatorHook ? `ReturnType<typeof use${pascal(operationName)}Hook>` : `typeof ${operationName}`}>>, TError,${definitions ? `{${definitions}}` : "void"}, TContext>` : `${prefix}MutationOptions<Awaited<ReturnType<${isMutatorHook ? `ReturnType<typeof use${pascal(operationName)}Hook>` : `typeof ${operationName}`}>>, TError,${definitions ? `{${definitions}}` : "void"}, TContext>`;
 };
 //#endregion
@@ -1107,7 +1131,7 @@ const createReactAdapter = ({ hasQueryV5, hasQueryV5WithDataTagError, hasQueryV5
 });
 //#endregion
 //#region src/frameworks/solid.ts
-const createSolidAdapter = ({ hasQueryV5, hasQueryV5WithDataTagError, hasQueryV5WithInfiniteQueryOptionsError, hasQueryV5WithMutationContextOnSuccess, hasQueryV5WithRequiredContextOnSuccess, hasSolidQueryUsePrefix }) => ({
+const createSolidAdapter = ({ hasQueryV5, hasQueryV5WithDataTagError, hasQueryV5WithInfiniteQueryOptionsError, hasQueryV5WithMutationContextOnSuccess, hasQueryV5WithRequiredContextOnSuccess, hasSolidQueryUsePrefix, hasSolidQueryRenamedOptionsTypes }) => ({
 	outputClient: OutputClient.SOLID_QUERY,
 	hookPrefix: hasSolidQueryUsePrefix ? "use" : "create",
 	hasQueryV5,
@@ -1119,9 +1143,9 @@ const createSolidAdapter = ({ hasQueryV5, hasQueryV5WithDataTagError, hasQueryV5
 		return hasSolidQueryUsePrefix ? "Use" : "Create";
 	},
 	getOptionsReturnTypeName(type) {
-		if (type === "mutation") return "SolidMutationOptions";
-		if (type === "infiniteQuery") return "SolidInfiniteQueryOptions";
-		return "SolidQueryOptions";
+		if (type === "mutation") return hasSolidQueryRenamedOptionsTypes ? "MutationOptions" : "SolidMutationOptions";
+		if (type === "infiniteQuery") return hasSolidQueryRenamedOptionsTypes ? "InfiniteQueryOptions" : "SolidInfiniteQueryOptions";
+		return hasSolidQueryRenamedOptionsTypes ? "QueryOptions" : "SolidQueryOptions";
 	},
 	getQueryKeyPrefix() {
 		return "";
@@ -1328,7 +1352,8 @@ const createVueAdapter = ({ hasVueQueryV4, hasQueryV5, hasQueryV5WithDataTagErro
 		return vueUnRefParams(props.filter((prop) => prop.type === GetterPropType.NAMED_PATH_PARAMS));
 	},
 	generateEnabledOption(params, options) {
-		if (!isObject(options) || !Object.hasOwn(options, "enabled")) return `enabled: computed(() => !!(${params.map(({ name }) => `unref(${name})`).join(" && ")})),`;
+		if (params.length === 0) return "";
+		if (!isObject(options) || !Object.hasOwn(options, "enabled")) return `enabled: computed(() => ${params.map(({ name }) => `unref(${name}) !== null && unref(${name}) !== undefined`).join(" && ")}),`;
 		return "";
 	},
 	getQueryKeyPrefix() {
@@ -1378,7 +1403,8 @@ const withDefaults = (adapter) => ({
 		return `\`${route}\``;
 	},
 	generateEnabledOption(params, options) {
-		if (!isObject(options) || !Object.hasOwn(options, "enabled")) return `enabled: !!(${params.map(({ name }) => name).join(" && ")}),`;
+		if (params.length === 0) return "";
+		if (!isObject(options) || !Object.hasOwn(options, "enabled")) return `enabled: ${params.map(({ name }) => `${name} !== null && ${name} !== undefined`).join(" && ")},`;
 		return "";
 	},
 	getQueryPropertyForProp(prop, body) {
@@ -1412,7 +1438,8 @@ const withDefaults = (adapter) => ({
 			queryParams,
 			queryParam,
 			isReturnType: false,
-			initialData
+			initialData,
+			adapter
 		});
 		if (!isRequestOptions) return `${type ? "queryOptions" : "mutationOptions"}${initialData === "defined" ? "" : "?"}: ${definition}`;
 		const requestType = getQueryArgumentsRequestType(httpClient, mutator, useRuntimeFetcher);
@@ -1490,7 +1517,8 @@ const createFrameworkAdapter = ({ outputClient, packageJson, queryVersion }) =>
 			hasQueryV5WithInfiniteQueryOptionsError: _hasQueryV5WithInfiniteQueryOptionsError,
 			hasQueryV5WithMutationContextOnSuccess: _hasQueryV5WithMutationContextOnSuccess,
 			hasQueryV5WithRequiredContextOnSuccess: _hasQueryV5WithRequiredContextOnSuccess,
-			hasSolidQueryUsePrefix: isSolidQueryWithUsePrefix(packageJson)
+			hasSolidQueryUsePrefix: isSolidQueryWithUsePrefix(packageJson),
+			hasSolidQueryRenamedOptionsTypes: isSolidQueryWithRenamedOptionsTypes(packageJson)
 		}));
 		default: return withDefaults(createReactAdapter({
 			hasQueryV5: _hasQueryV5,
@@ -1545,10 +1573,12 @@ const findOperationInfo = (spec, operationName) => {
 			if (opId !== operationName && camel(opId) !== operationName) continue;
 			if (!routePath.includes("{")) return {
 				route: routePath,
+				method,
 				hasRequiredPathParams: false
 			};
 			return {
 				route: routePath,
+				method,
 				hasRequiredPathParams: [...Array.isArray(pathItem.parameters) ? pathItem.parameters : [], ...Array.isArray(operation.parameters) ? operation.parameters : []].filter((p) => p.in === "path").some((p) => p.schema?.default === void 0 && p.default === void 0)
 			};
 		}
@@ -1597,7 +1627,7 @@ const generateParamArgs = (params) => {
 * Create a generateInvalidateCall function that has access to the OpenAPI spec
 * for intelligent route-based invalidation when params are not specified.
 */
-const createGenerateInvalidateCall = (spec, shouldSplitQueryKey) => {
+const createGenerateInvalidateCall = (spec, shouldSplitQueryKey, useOperationIdAsQueryKey) => {
 	return (target) => {
 		const method = target.invalidateMode === "reset" ? "resetQueries" : "invalidateQueries";
 		const queryKeyFn = camel(`get-${target.query}-query-key`);
@@ -1606,7 +1636,15 @@ const createGenerateInvalidateCall = (spec, shouldSplitQueryKey) => {
 		if (info?.hasRequiredPathParams) {
 			const prefix = getStaticRoutePrefix(info.route);
 			if (prefix !== void 0) {
-				if (shouldSplitQueryKey) return `    queryClient.${method}({ queryKey: [${prefix.split("/").filter((s) => s !== "").map((s) => `'${s}'`).join(", ")}] });`;
+				const verbPrefix = getQueryKeyVerbPrefix({
+					verb: info.method,
+					useOperationIdAsQueryKey
+				});
+				if (shouldSplitQueryKey) {
+					const segments = prefix.split("/").filter((s) => s !== "").map((s) => `'${s}'`).join(", ");
+					return `    queryClient.${method}({ queryKey: ${verbPrefix ? `['${verbPrefix}', ${segments}]` : `[${segments}]`} });`;
+				}
+				if (verbPrefix) return `    queryClient.${method}({ predicate: (query) => query.queryKey[0] === '${verbPrefix}' && typeof query.queryKey[1] === 'string' && query.queryKey[1].startsWith('${prefix}') });`;
 				return `    queryClient.${method}({ predicate: (query) => typeof query.queryKey[0] === 'string' && query.queryKey[0].startsWith('${prefix}') });`;
 			}
 		}
@@ -1688,7 +1726,7 @@ ${hasInvalidation ? adapter.generateMutationOnSuccess({
 		operationName,
 		definitions,
 		isRequestOptions,
-		generateInvalidateCall: createGenerateInvalidateCall(context.spec, !!query.shouldSplitQueryKey),
+		generateInvalidateCall: createGenerateInvalidateCall(context.spec, !!query.shouldSplitQueryKey, !!query.useOperationIdAsQueryKey),
 		uniqueInvalidates
 	}) : ""}
 
@@ -1757,6 +1795,110 @@ const getMutationInvalidatesConflictWarning = ({ operationName, isMutation, isQu
 	if (!mutationInvalidates.find((rule) => rule.onMutations.includes(operationName))) return void 0;
 	return `mutationInvalidates rule references '${operationName}', but that operation is generated as a ${isQuery ? "Query hook" : "plain function (no hook)"}, not a Mutation. The invalidation will not fire. Either remove '${operationName}' from the rule's onMutations list, or configure '${operationName}' so that it is generated as a Mutation hook.`;
 };
+const escapeRegExpMetaChars = (value) => value.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+/**
+* Wraps the body parameter's type in a property string with the mutator's
+* `BodyType<T>` envelope so that user-facing Query helpers (hook signature,
+* `getXxxQueryOptions`, `getXxxQueryKey`, prefetch / invalidate / set+get
+* QueryData) match the request function's signature, which is already
+* wrapped by `client.ts`. Without this, callers that pass a plain body to
+* a non-GET Query hook (possible after #2376 routes non-GET verbs to
+* Query hooks) would hit a type mismatch against the underlying request
+* function.
+*
+* The pattern handles three prop shapes that the various
+* `toObjectString(props, ...)` callers can emit:
+*   - `name: T`                — required body
+*   - `name?: T`               — optional body
+*   - `name: undefined | T`    — `definedInitialData` overload transform
+*
+* `body.definition` is fully regex-escaped so types containing metachars
+* (e.g. `Pet[]`, `Foo | Bar`, anonymous object types) are matched
+* verbatim rather than reinterpreted as regex syntax.
+*
+* No-op when the operation has no body or the mutator does not export a
+* `BodyType<T>` wrapper, so existing GET-only Query keys are unchanged.
+*/
+const wrapPropsBodyWithMutatorBodyType = ({ propsString, body, mutator }) => {
+	if (!mutator?.bodyTypeName || !body.definition) return propsString;
+	const bodyDefinitionPattern = escapeRegExpMetaChars(body.definition);
+	return propsString.replace(new RegExp(String.raw`(\w+\??:\s*(?:undefined\s*\|\s*)?)${bodyDefinitionPattern}`), `$1${mutator.bodyTypeName}<${body.definition}>`);
+};
+/**
+* Widens a parameter signature to be optional. Skips params that already
+* carry a default value (`= ...`), since those are syntactically optional
+* and adding `?` on top would be a TypeScript error.
+*/
+const makeOptionalParam = (impl) => {
+	if (impl.includes("=")) return impl;
+	return impl.replace(/^(\w+):\s*/, "$1?: ");
+};
+/**
+* Widens a parameter type to also accept `undefined`. Already-optional
+* (`?:`) signatures are normalized to required-with-undefined, and params
+* with a default value pass through unchanged.
+*/
+const allowUndefinedParam = (impl) => {
+	if (impl.includes("=")) return impl;
+	const optional = /^(\w+)\?:\s*(.+)$/.exec(impl);
+	if (optional) return `${optional[1]}: ${optional[2]} | undefined`;
+	return impl.replace(/^(\w+):\s*(.+)$/, "$1: $2 | undefined");
+};
+/**
+* Renders the `setXxxQueryData` helper as either a React hook (returns a
+* setter) or a plain function taking `queryClient`. Both shapes share the
+* same body and signature, so this collapses what would otherwise be two
+* near-identical template literals.
+*/
+const renderSetQueryDataHelper = ({ doc, isReactQuery, fnName, propsSig, body }) => {
+	const docPrefix = doc ?? "";
+	if (isReactQuery) return `${docPrefix}export const ${fnName} = () => {
+  const queryClient = useQueryClient();
+  return (${propsSig}) => {
+    ${body}
+  };
+}\n`;
+	return `${docPrefix}export const ${fnName} = (queryClient: QueryClient, ${propsSig}) => {
+  ${body}
+}\n`;
+};
+/**
+* Renders the prop list shared by `getXxxQueryKey`, `setXxxQueryData` and
+* `getXxxQueryData` helpers: headers are dropped, path params stay required,
+* non-path params (query params, body) are passed through `widenNonPath`
+* (defaults to identity — pass `makeOptionalParam` or `allowUndefinedParam`
+* to relax the signature).
+*
+* Centralising this prevents the three call sites from drifting apart on
+* how they treat the same props.
+*/
+const buildKeyShapedProps = ({ props, body, mutator, widenNonPath = (impl) => impl }) => wrapPropsBodyWithMutatorBodyType({
+	propsString: toObjectString(props.filter((prop) => prop.type !== GetterPropType.HEADER).map((prop) => ({
+		...prop,
+		implementation: prop.type === GetterPropType.PARAM || prop.type === GetterPropType.NAMED_PATH_PARAMS ? prop.implementation : widenNonPath(prop.implementation)
+	})), "implementation"),
+	body,
+	mutator
+});
+/**
+* Computes a verb prefix segment for query keys when a non-GET operation is
+* routed to a Query hook. Without this prefix, two operations sharing a path
+* (e.g. `GET /pets` and `POST /pets`) would generate cache keys that both
+* begin with `'/pets'`, so TanStack Query would mix their cached data and
+* `invalidateQueries({ queryKey: ['/pets'] })` would match both.
+*
+* Skipped for GET (preserves existing keys) and when
+* `useOperationIdAsQueryKey` is enabled (operation IDs are already unique
+* across verb + path, so the prefix would be redundant).
+*
+* Returns the uppercased verb when a prefix should be inserted, or
+* `undefined` when no prefix is needed.
+*/
+const getQueryKeyVerbPrefix = ({ verb, useOperationIdAsQueryKey }) => {
+	if (useOperationIdAsQueryKey) return void 0;
+	if (verb === Verbs.GET) return void 0;
+	return verb.toUpperCase();
+};
 const getQueryFnArguments = ({ hasQueryParam, hasSignal, hasSignalParam = false }) => {
 	if (!hasQueryParam && !hasSignal) return "";
 	const signalDestructure = hasSignalParam ? "signal: querySignal" : "signal";
@@ -1787,20 +1929,32 @@ const generatePrefetch = ({ usePrefetch, type, useQuery, useInfinite, operationN
   return queryClient;
 }\n`;
 };
-const generateQueryImplementation = ({ queryOption: { name, queryParam, options, type, queryKeyFnName }, operationName, queryProperties, queryKeyProperties, queryParams, params, props, mutator, queryOptionsMutator, queryKeyMutator, isRequestOptions, response, httpClient, isExactOptionalPropertyTypes, hasSignal, useRuntimeFetcher, route, doc, usePrefetch, useQuery, useInfinite, useInvalidate, useSetQueryData, useGetQueryData, adapter }) => {
+const generateQueryImplementation = ({ queryOption: { name, queryParam, options, type, queryKeyFnName }, operationName, queryProperties, queryKeyProperties, queryParams, params, props, body, mutator, queryOptionsMutator, queryKeyMutator, isRequestOptions, response, httpClient, isExactOptionalPropertyTypes, hasSignal, useRuntimeFetcher, route, doc, usePrefetch, useQuery, useInfinite, useInvalidate, useSetQueryData, useGetQueryData, adapter }) => {
 	const { hasQueryV5, hasQueryV5WithDataTagError, hasQueryV5WithInfiniteQueryOptionsError } = adapter;
 	const hasSignalParam = props.some((prop) => prop.name === "signal");
-	const queryPropDefinitions = toObjectString(props, "definition");
-	const definedInitialDataQueryPropsDefinitions = toObjectString(props.map((prop) => {
-		const regex = new RegExp(String.raw`^${prop.name}\s*\?:`);
-		if (!regex.test(prop.definition)) return prop;
-		const definitionWithUndefined = prop.definition.replace(regex, `${prop.name}: undefined | `);
-		return {
-			...prop,
-			definition: definitionWithUndefined
-		};
-	}), "definition");
-	const queryProps = toObjectString(props, "implementation");
+	const queryPropDefinitions = wrapPropsBodyWithMutatorBodyType({
+		propsString: toObjectString(props, "definition"),
+		body,
+		mutator
+	});
+	const definedInitialDataQueryPropsDefinitions = wrapPropsBodyWithMutatorBodyType({
+		propsString: toObjectString(props.map((prop) => {
+			const regex = new RegExp(String.raw`^${prop.name}\s*\?:`);
+			if (!regex.test(prop.definition)) return prop;
+			const definitionWithUndefined = prop.definition.replace(regex, `${prop.name}: undefined | `);
+			return {
+				...prop,
+				definition: definitionWithUndefined
+			};
+		}), "definition"),
+		body,
+		mutator
+	});
+	const queryProps = wrapPropsBodyWithMutatorBodyType({
+		propsString: toObjectString(props, "implementation"),
+		body,
+		mutator
+	});
 	const hasInfiniteQueryParam = queryParam && queryParams?.schema.name;
 	const httpFunctionProps = queryParam ? adapter.getInfiniteQueryHttpProps(props, queryParam, !!mutator) : adapter.getHttpFunctionQueryProps(queryProperties, httpClient, !!mutator);
 	const definedInitialDataReturnType = adapter.getQueryReturnType({
@@ -1955,18 +2109,28 @@ export function ${queryHookName}<TData = ${TData}, TError = ${errorType}>(\n ${q
 	const isPrimaryQueryType = type === QueryType.QUERY || type === QueryType.INFINITE || type === QueryType.SUSPENSE_QUERY && !useQuery || type === QueryType.SUSPENSE_INFINITE && !useInfinite;
 	const buildBaseQueryKeyExpr = () => queryKeyMutator ? `${queryKeyMutator.name}({ ${queryProperties} }${queryKeyMutator.hasSecondArg ? `, { url: \`${route}\` }` : ""})` : `${queryKeyFnName}(${queryKeyProperties})`;
 	const applyQueryOptionsMutator = (baseExpr) => queryOptionsMutator && !queryOptionsMutator.isHook ? `${queryOptionsMutator.name}({ queryKey: ${baseExpr} }${queryOptionsMutator.hasSecondArg ? `, { ${queryProperties} }` : ""}${queryOptionsMutator.hasThirdArg ? `, { url: \`${route}\` }` : ""}).queryKey` : baseExpr;
+	const hasHookMutator = !!queryOptionsMutator?.isHook;
+	if (hasHookMutator && (useSetQueryData || useGetQueryData)) logWarning(`'${name}' has a hook-based queryOptions mutator, so the requested set/get-query-data helpers were skipped to avoid a cache-key mismatch with the query hook.`);
 	const shouldGenerateInvalidate = useInvalidate && isPrimaryQueryType;
 	const invalidateFnName = camel(`invalidate-${name}`);
 	const invalidateQueryKeyExpr = applyQueryOptionsMutator(buildBaseQueryKeyExpr());
-	const shouldGenerateSetQueryData = useSetQueryData && isPrimaryQueryType;
+	const shouldGenerateSetQueryData = useSetQueryData && isPrimaryQueryType && !hasHookMutator;
 	const isReactQuery = adapter.outputClient === OutputClient.REACT_QUERY;
 	const setQueryDataFnName = isReactQuery ? camel(`use-set-${name}-query-data`) : camel(`set-${name}-query-data`);
-	const setQueryDataKeyExpr = buildBaseQueryKeyExpr();
-	const setQueryDataProps = toObjectString(props.filter((prop) => prop.type !== GetterPropType.HEADER), "implementation").replaceAll("?:", ":");
-	const shouldGenerateGetQueryData = useGetQueryData && isPrimaryQueryType;
+	const setQueryDataKeyExpr = applyQueryOptionsMutator(buildBaseQueryKeyExpr());
+	const setQueryDataProps = buildKeyShapedProps({
+		props,
+		body,
+		mutator,
+		widenNonPath: allowUndefinedParam
+	});
+	const shouldGenerateGetQueryData = useGetQueryData && isPrimaryQueryType && !hasHookMutator;
 	const getQueryDataFnName = isReactQuery ? camel(`use-get-${name}-query-data`) : camel(`get-${name}-query-data`);
-	const getQueryDataKeyExpr = setQueryDataKeyExpr;
-	const getQueryDataProps = setQueryDataProps;
+	const getQueryDataProps = buildKeyShapedProps({
+		props,
+		body,
+		mutator
+	});
 	const queryInit = adapter.generateQueryInit({
 		queryOptionsFnName,
 		queryProperties,
@@ -1993,7 +2157,11 @@ export type ${pascal(name)}QueryError = ${errorType}
 
 ${adapter.shouldGenerateOverrideTypes() ? overrideTypes : ""}
 ${doc}
-export function ${queryHookName}<TData = ${TData}, TError = ${errorType}>(\n ${adapter.getHookPropsDefinitions(props)} ${queryArguments} ${optionalQueryClientArgument} \n ): ${returnType} {
+export function ${queryHookName}<TData = ${TData}, TError = ${errorType}>(\n ${wrapPropsBodyWithMutatorBodyType({
+		propsString: adapter.getHookPropsDefinitions(props),
+		body,
+		mutator
+	})} ${queryArguments} ${optionalQueryClientArgument} \n ): ${returnType} {
 
   ${queryInit}
 
@@ -2013,20 +2181,19 @@ ${shouldGenerateInvalidate ? `${doc}export const ${invalidateFnName} = async (\n
 
   return queryClient;
 }\n` : ""}
-${shouldGenerateSetQueryData ? isReactQuery ? `${doc}export const ${setQueryDataFnName} = () => {
-  const queryClient = useQueryClient();
-  return (${setQueryDataProps}updater: ${TData} | undefined | ((old: ${TData} | undefined) => ${TData} | undefined)) => {
-    queryClient.setQueryData(${setQueryDataKeyExpr}, updater);
-  };
-}\n` : `${doc}export const ${setQueryDataFnName} = (queryClient: QueryClient, ${setQueryDataProps}updater: ${TData} | undefined | ((old: ${TData} | undefined) => ${TData} | undefined)) => {
-  queryClient.setQueryData(${setQueryDataKeyExpr}, updater);
-}\n` : ""}
+${shouldGenerateSetQueryData ? renderSetQueryDataHelper({
+		doc,
+		isReactQuery,
+		fnName: setQueryDataFnName,
+		propsSig: `${setQueryDataProps}updater: ${TData} | undefined | ((old: ${TData} | undefined) => ${TData} | undefined)`,
+		body: `queryClient.setQueriesData<${TData}>({ queryKey: ${setQueryDataKeyExpr} }, updater);`
+	}) : ""}
 ${shouldGenerateGetQueryData ? isReactQuery ? `${doc}export const ${getQueryDataFnName} = () => {
   const queryClient = useQueryClient();
   return (${getQueryDataProps}) =>
-    queryClient.getQueryData<${TData}>(${getQueryDataKeyExpr});
+    queryClient.getQueryData<${TData}>(${setQueryDataKeyExpr});
 }\n` : `${doc}export const ${getQueryDataFnName} = (queryClient: QueryClient, ${getQueryDataProps}) =>
-  queryClient.getQueryData<${TData}>(${getQueryDataKeyExpr});\n` : ""}
+  queryClient.getQueryData<${TData}>(${setQueryDataKeyExpr});\n` : ""}
 `;
 };
 const generateQueryHook = async (verbOptions, options, outputClient, adapter) => {
@@ -2045,20 +2212,14 @@ const generateQueryHook = async (verbOptions, options, outputClient, adapter) =>
 	});
 	let implementation = "";
 	let mutators;
-	const hasOperationQueryOption = [
-		operationQueryOptions?.useQuery,
-		operationQueryOptions?.useSuspenseQuery,
-		operationQueryOptions?.useInfinite,
-		operationQueryOptions?.useSuspenseInfiniteQuery
-	].some(Boolean);
-	let isQuery = Verbs.GET === verb && [
-		override.query.useQuery,
-		override.query.useSuspenseQuery,
-		override.query.useInfinite,
-		override.query.useSuspenseInfiniteQuery
-	].some(Boolean) || hasOperationQueryOption;
-	let isMutation = override.query.useMutation && verb !== Verbs.GET;
-	if (operationQueryOptions?.useMutation !== void 0) isMutation = operationQueryOptions.useMutation;
+	const effectiveUseQuery = operationQueryOptions?.useQuery ?? override.query.useQuery ?? verb === Verbs.GET;
+	const effectiveUseMutation = operationQueryOptions?.useMutation ?? override.query.useMutation ?? verb !== Verbs.GET;
+	const globalSuspenseOrInfiniteOnlyForGet = (flag) => flag === true && verb === Verbs.GET;
+	const effectiveUseSuspenseQuery = operationQueryOptions?.useSuspenseQuery ?? globalSuspenseOrInfiniteOnlyForGet(override.query.useSuspenseQuery);
+	const effectiveUseInfinite = operationQueryOptions?.useInfinite ?? globalSuspenseOrInfiniteOnlyForGet(override.query.useInfinite);
+	const effectiveUseSuspenseInfiniteQuery = operationQueryOptions?.useSuspenseInfiniteQuery ?? globalSuspenseOrInfiniteOnlyForGet(override.query.useSuspenseInfiniteQuery);
+	let isQuery = effectiveUseQuery || effectiveUseSuspenseQuery || effectiveUseInfinite || effectiveUseSuspenseInfiniteQuery;
+	let isMutation = effectiveUseMutation;
 	if (verb !== Verbs.GET && isQuery) isMutation = false;
 	if (verb === Verbs.GET && isMutation) isQuery = false;
 	const conflictWarning = getMutationInvalidatesConflictWarning({
@@ -2090,26 +2251,26 @@ const generateQueryHook = async (verbOptions, options, outputClient, adapter) =>
 			return adapter.getQueryPropertyForProp(param, body);
 		}).join(",");
 		const queries = [
-			...query.useInfinite || operationQueryOptions?.useInfinite ? [{
+			...effectiveUseInfinite ? [{
 				name: camel(`${operationName}-infinite`),
 				options: query.options,
 				type: QueryType.INFINITE,
 				queryParam: query.useInfiniteQueryParam,
 				queryKeyFnName: camel(`get-${operationName}-infinite-query-key`)
 			}] : [],
-			...query.useQuery || operationQueryOptions?.useQuery ? [{
+			...effectiveUseQuery ? [{
 				name: operationName,
 				options: query.options,
 				type: QueryType.QUERY,
 				queryKeyFnName: camel(`get-${operationName}-query-key`)
 			}] : [],
-			...query.useSuspenseQuery || operationQueryOptions?.useSuspenseQuery ? [{
+			...effectiveUseSuspenseQuery ? [{
 				name: camel(`${operationName}-suspense`),
 				options: query.options,
 				type: QueryType.SUSPENSE_QUERY,
 				queryKeyFnName: camel(`get-${operationName}-query-key`)
 			}] : [],
-			...query.useSuspenseInfiniteQuery || operationQueryOptions?.useSuspenseInfiniteQuery ? [{
+			...effectiveUseSuspenseInfiniteQuery ? [{
 				name: camel(`${operationName}-suspense-infinite`),
 				options: query.options,
 				type: QueryType.SUSPENSE_INFINITE,
@@ -2120,22 +2281,25 @@ const generateQueryHook = async (verbOptions, options, outputClient, adapter) =>
 		const uniqueQueryOptionsByKeys = queries.filter((obj, index, self) => index === self.findIndex((t) => t.queryKeyFnName === obj.queryKeyFnName));
 		let queryKeyFns = "";
 		if (!queryKeyMutator) for (const queryOption of uniqueQueryOptionsByKeys) {
-			const makeOptionalParam = (impl) => {
-				if (impl.includes("=")) return impl;
-				return impl.replace(/^(\w+):\s*/, "$1?: ");
-			};
-			const queryKeyProps = toObjectString(props.filter((prop) => prop.type !== GetterPropType.HEADER).map((prop) => ({
-				...prop,
-				implementation: prop.type === GetterPropType.PARAM || prop.type === GetterPropType.NAMED_PATH_PARAMS ? prop.implementation : makeOptionalParam(prop.implementation)
-			})), "implementation");
+			const queryKeyProps = buildKeyShapedProps({
+				props,
+				body,
+				mutator,
+				widenNonPath: makeOptionalParam
+			});
 			const routeString = adapter.getQueryKeyRouteString(route, !!override.query.shouldSplitQueryKey);
 			const queryKeyIdentifier = override.query.useOperationIdAsQueryKey ? `"${operationName}"` : routeString;
 			const queryKeyParams = props.filter((p) => override.query.useOperationIdAsQueryKey ? true : p.type === GetterPropType.QUERY_PARAM).toSorted((a) => a.required ? -1 : 1).map((p) => `...(${p.name} ? [${p.name}] : [])`).join(", ");
+			const verbPrefix = getQueryKeyVerbPrefix({
+				verb,
+				useOperationIdAsQueryKey: override.query.useOperationIdAsQueryKey
+			});
 			queryKeyFns += `
 ${override.query.shouldExportQueryKey ? "export " : ""}const ${queryOption.queryKeyFnName} = (${queryKeyProps}) => {
     return [
     ${[
 				queryOption.type === QueryType.INFINITE || queryOption.type === QueryType.SUSPENSE_INFINITE ? `'infinite'` : "",
+				verbPrefix ? `'${verbPrefix}'` : "",
 				queryKeyIdentifier,
 				queryKeyParams,
 				body.implementation
@@ -2154,6 +2318,7 @@ ${queryKeyFns}`;
 			queryKeyProperties,
 			params,
 			props,
+			body,
 			mutator,
 			isRequestOptions,
 			queryParams,
@@ -2167,8 +2332,8 @@ ${queryKeyFns}`;
 			route,
 			doc,
 			usePrefetch: query.usePrefetch,
-			useQuery: query.useQuery,
-			useInfinite: query.useInfinite,
+			useQuery: effectiveUseQuery,
+			useInfinite: effectiveUseInfinite,
 			useInvalidate: query.useInvalidate,
 			useSetQueryData: operationQueryOptions?.useSetQueryData ?? query.useSetQueryData,
 			useGetQueryData: operationQueryOptions?.useGetQueryData ?? query.useGetQueryData,