feat(query): add useFlatInput option to merge params into a single object

docs/content/docs/guides/angular-query.mdx

@@ -355,6 +355,10 @@ const request$ = http.get<Pets>(url, { params: httpParams })
 
 Validation is automatically skipped for primitive response types (`string`, `void`, etc.) and for operations using a custom mutator.
 
+## Flat Input
+
+When `useFlatInput: true` is set, Orval flattens path params, query params, and body into a single object argument.
+
 ## Full Example
 
 See the [Angular Query sample](https://github.com/orval-labs/orval/tree/master/samples/angular-query) on GitHub.

docs/content/docs/guides/react-query.mdx

@@ -149,6 +149,18 @@ export const useSetListPetsQueryData = () => {
 };
 ```
 
+## Flat Input
+
+When `useFlatInput: true` is set, Orval flattens path params, query params, and body into a single object argument:
+
+```ts
+// Before
+useGetUserOrders(userId, params, options);
+
+// After
+useGetUserOrders({ userId, status, page }, options);
+```
+
 ## Full Example
 
 See the [complete React Query example](https://github.com/orval-labs/orval/blob/master/samples/react-query/basic) on GitHub.

docs/content/docs/guides/solid-query.mdx

@@ -139,6 +139,10 @@ export const setListPetsQueryData = (
 };
 ```
 
+## Flat Input
+
+When `useFlatInput: true` is set, Orval flattens path params, query params, and body into a single object argument.
+
 ## Full Example
 
 See the [complete Solid Query example](https://github.com/orval-labs/orval/tree/master/samples/solid-query) on GitHub.

docs/content/docs/guides/svelte-query.mdx

@@ -118,6 +118,10 @@ export const setListPetsQueryData = (
 };
 ```
 
+## Flat Input
+
+When `useFlatInput: true` is set, Orval flattens path params, query params, and body into a single object argument.
+
 ## Full Example
 
 See the [complete Svelte Query example](https://github.com/orval-labs/orval/tree/master/samples/svelte-query) on GitHub.

docs/content/docs/guides/vue-query.mdx

@@ -146,6 +146,10 @@ export const setListPetsQueryData = (
 };
 ```
 
+## Flat Input
+
+When `useFlatInput: true` is set, Orval flattens path params, query params, and body into a single object argument.
+
 ## Full Example
 
 See the [complete Vue Query example](https://github.com/orval-labs/orval/tree/master/samples/vue-query) on GitHub.

docs/content/docs/reference/configuration/output.mdx

@@ -1286,6 +1286,15 @@ Use TypeScript `type` instead of `interface`.
 
 Use named parameters object instead of positional arguments.
 
+### useFlatInput
+
+**Type:** `Boolean`
+**Default:** `false`
+
+Flatten path params, query params, and body into a single object argument for query hooks and mutations. Uses TypeScript intersection types.
+
+Cannot be used together with `useNamedParameters`.
+
 ### useDeprecatedOperations
 
 **Type:** `Boolean`

packages/core/src/getters/query-params.ts

@@ -222,5 +222,6 @@ export function getQueryParams({
     deps: schemas,
     isOptional: allOptional,
     requiredNullableKeys,
+    fieldNames: types.map(({ name }) => name),
   };
 }

packages/core/src/types.ts

@@ -133,6 +133,7 @@ export interface NormalizedOverrideOutput {
   useDeprecatedOperations?: boolean;
   useBigInt?: boolean;
   useNamedParameters?: boolean;
+  useFlatInput?: boolean;
   enumGenerationType: EnumGeneration;
   suppressReadonlyModifier?: boolean;
   /**
@@ -521,6 +522,7 @@ export interface OverrideOutput {
   useDeprecatedOperations?: boolean;
   useBigInt?: boolean;
   useNamedParameters?: boolean;
+  useFlatInput?: boolean;
   enumGenerationType?: EnumGeneration;
   suppressReadonlyModifier?: boolean;
   /**
@@ -1203,6 +1205,7 @@ export interface GetterQueryParam {
   isOptional: boolean;
   originalSchema?: OpenApiSchemaObject;
   requiredNullableKeys?: string[];
+  fieldNames?: string[];
 }
 
 export type GetterPropType =

packages/query/src/flat-input.ts

@@ -0,0 +1,127 @@
+import {
+  type GetterProps,
+  GetterPropType,
+  type GetterQueryParam,
+} from '@orval/core';
+
+export interface FlatInputResult {
+  type: string;
+  destructure: string;
+  properties: string;
+  callArgs: string;
+}
+
+export function checkFlatInputCollisions(
+  operationName: string,
+  props: GetterProps,
+  queryParams?: GetterQueryParam,
+): void {
+  const pathParamNames = props
+    .filter(
+      (p) =>
+        p.type === GetterPropType.PARAM ||
+        p.type === GetterPropType.NAMED_PATH_PARAMS,
+    )
+    .map((p) => p.name);
+
+  const queryFieldNames = queryParams?.fieldNames ?? [];
+
+  const allNames = [...pathParamNames, ...queryFieldNames];
+  const seen = new Set<string>();
+
+  for (const name of allNames) {
+    if (seen.has(name)) {
+      throw new Error(
+        `useFlatInput: duplicate parameter name "${name}" found in operation "${operationName}". ` +
+          `Path params, query params, and body fields must have unique names when using useFlatInput.`,
+      );
+    }
+    seen.add(name);
+  }
+}
+
+export function buildFlatInput(
+  props: GetterProps,
+  queryParams?: GetterQueryParam,
+  bodyDefinition?: string,
+  bodyTypeName?: string,
+): FlatInputResult | undefined {
+  const pathParams = props.filter(
+    (p) =>
+      p.type === GetterPropType.PARAM ||
+      p.type === GetterPropType.NAMED_PATH_PARAMS,
+  );
+  const queryParamProp = props.find(
+    (p) => p.type === GetterPropType.QUERY_PARAM,
+  );
+  const bodyProp = props.find((p) => p.type === GetterPropType.BODY);
+  const hasHeaders = props.some((p) => p.type === GetterPropType.HEADER);
+
+  if (hasHeaders) {
+    return undefined;
+  }
+
+  const propCount =
+    pathParams.length + (queryParamProp ? 1 : 0) + (bodyProp ? 1 : 0);
+
+  if (propCount < 2 && pathParams.length < 2) {
+    return undefined;
+  }
+
+  const pathType =
+    pathParams.length > 0
+      ? `{ ${pathParams.map((p) => p.definition).join('; ')} }`
+      : '';
+  const queryType = queryParamProp ? (queryParams?.schema.name ?? '') : '';
+  const bodyType = bodyProp
+    ? bodyTypeName
+      ? `${bodyTypeName}<${bodyDefinition}>`
+      : (bodyDefinition ?? '')
+    : '';
+
+  const types = [pathType, queryType, bodyType].filter(Boolean);
+  const flatType = types.join(' & ');
+
+  if (!flatType) {
+    return undefined;
+  }
+
+  const pathNames = pathParams.map((p) => p.name);
+  const queryFieldNames = queryParams?.fieldNames ?? [];
+  const knownNames = [...pathNames, ...queryFieldNames];
+
+  let destructureNames: string[];
+  if (bodyProp) {
+    destructureNames = [...knownNames, '...data'];
+  } else if (queryParamProp) {
+    destructureNames = [...pathNames, '...params'];
+  } else {
+    destructureNames = [...pathNames];
+  }
+
+  const properties = destructureNames.join(', ');
+  const destructure = `{ ${properties} }: ${flatType},`;
+
+  const callArgs = props
+    .filter((p) => p.type !== GetterPropType.HEADER)
+    .map((p) => {
+      if (
+        p.type === GetterPropType.PARAM ||
+        p.type === GetterPropType.NAMED_PATH_PARAMS
+      ) {
+        return p.name;
+      }
+      if (p.type === GetterPropType.QUERY_PARAM) {
+        return queryFieldNames.length > 0
+          ? `{ ${queryFieldNames.join(', ')} }`
+          : p.name;
+      }
+      if (p.type === GetterPropType.BODY) {
+        return 'data';
+      }
+      return p.name;
+    })
+    .join(', ');
+
+  return { type: flatType, destructure, properties, callArgs };
+}

packages/query/src/framework-adapter.ts

@@ -207,6 +207,7 @@ export interface FrameworkAdapter {
   generateQueryArguments(args: {
     operationName: string;
     definitions: string;
+    overrideVariableType?: string;
     mutator?: GeneratorMutator;
     isRequestOptions: boolean;
     type?: (typeof QueryType)[keyof typeof QueryType];

packages/query/src/frameworks/angular.ts

@@ -191,6 +191,7 @@ export const createAngularAdapter = ({
     generateQueryArguments({
       operationName,
       definitions,
+      overrideVariableType,
       mutator,
       isRequestOptions,
       type,
@@ -205,6 +206,7 @@ export const createAngularAdapter = ({
         operationName,
         mutator,
         definitions,
+        overrideVariableType,
         type,
         prefix,
         hasQueryV5,

packages/query/src/frameworks/index.ts

@@ -116,6 +116,7 @@ const withDefaults = (adapter: FrameworkAdapterConfig): FrameworkAdapter => ({
   generateQueryArguments({
     operationName,
     definitions,
+    overrideVariableType,
     mutator,
     isRequestOptions,
     type,
@@ -130,6 +131,7 @@ const withDefaults = (adapter: FrameworkAdapterConfig): FrameworkAdapter => ({
       operationName,
       mutator,
       definitions,
+      overrideVariableType,
       type,
       prefix,
       hasQueryV5: adapter.hasQueryV5,

packages/query/src/frameworks/svelte.ts

@@ -166,6 +166,7 @@ export const createSvelteAdapter = ({
     generateQueryArguments({
       operationName,
       definitions,
+      overrideVariableType,
       mutator,
       isRequestOptions,
       type,
@@ -180,6 +181,7 @@ export const createSvelteAdapter = ({
         operationName,
         mutator,
         definitions,
+        overrideVariableType,
         type,
         prefix,
         hasQueryV5,

packages/query/src/mutation-generator.ts

@@ -17,6 +17,7 @@ import {
   getMutationRequestArgs,
   getQueryErrorType,
 } from './client';
+import { buildFlatInput, checkFlatInputCollisions } from './flat-input';
 import type { FrameworkAdapter } from './framework-adapter';
 import { getQueryOptionsDefinition } from './query-options';
 
@@ -102,6 +103,7 @@ export const generateMutationHook = async ({
     response,
     operationId,
     override,
+    queryParams,
   } = verbOptions;
   const { route, context, output } = options;
   const query = override.query;
@@ -116,6 +118,15 @@ export const generateMutationHook = async ({
       })
     : undefined;
 
+  const useFlatInput = !!override.useFlatInput;
+
+  if (useFlatInput) {
+    checkFlatInputCollisions(operationName, props, queryParams);
+  }
+  const flatInput = useFlatInput
+    ? buildFlatInput(props, queryParams, body.definition, mutator?.bodyTypeName)
+    : undefined;
+
   const definitions = props
     .map(({ definition, type }) =>
       type === GetterPropType.BODY
@@ -126,9 +137,11 @@ export const generateMutationHook = async ({
     )
     .join(';');
 
-  const properties = props
-    .map(({ name, type }) => (type === GetterPropType.BODY ? 'data' : name))
-    .join(',');
+  const properties = flatInput
+    ? flatInput.properties
+    : props
+        .map(({ name, type }) => (type === GetterPropType.BODY ? 'data' : name))
+        .join(',');
 
   const errorType = getQueryErrorType(
     operationName,
@@ -145,6 +158,7 @@ export const generateMutationHook = async ({
     operationName,
     mutator,
     definitions,
+    overrideVariableType: flatInput?.type,
     prefix: adapter.getQueryOptionsDefinitionPrefix(),
     hasQueryV5: adapter.hasQueryV5,
     hasQueryV5WithInfiniteQueryOptionsError:
@@ -171,6 +185,7 @@ export const generateMutationHook = async ({
   const mutationArguments = adapter.generateQueryArguments({
     operationName,
     definitions,
+    overrideVariableType: flatInput?.type,
     mutator,
     isRequestOptions,
     httpClient,
@@ -181,6 +196,7 @@ export const generateMutationHook = async ({
   const mutationArgumentsForOptions = adapter.generateQueryArguments({
     operationName,
     definitions,
+    overrideVariableType: flatInput?.type,
     mutator,
     isRequestOptions,
     httpClient,
@@ -221,11 +237,11 @@ ${hooksOptionImplementation}
 
 
       const mutationFn: MutationFunction<Awaited<ReturnType<${dataType}>>, ${
-        definitions ? `{${definitions}}` : 'void'
+        flatInput?.type ?? (definitions ? `{${definitions}}` : 'void')
       }> = (${properties ? 'props' : ''}) => {
           ${properties ? `const {${properties}} = props ?? {};` : ''}
 
-          return  ${operationName}(${adapter.getMutationHttpPrefix(mutator)}${properties}${
+          return  ${operationName}(${adapter.getMutationHttpPrefix(mutator)}${flatInput?.callArgs ?? properties}${
             properties ? ',' : ''
           }${getMutationRequestArgs(isRequestOptions, httpClient, mutator)})
         }
@@ -282,7 +298,8 @@ ${
 
   const mutationReturnType = adapter.getMutationReturnType({
     dataType,
-    variableType: definitions ? `{${definitions}}` : 'void',
+    variableType:
+      flatInput?.type ?? (definitions ? `{${definitions}}` : 'void'),
   });
 
   const mutationHookBody = adapter.generateMutationHookBody({