@kubb/ast 5.0.0-beta.58 → 5.0.0-beta.59

package/src/utils/index.ts

@@ -1,341 +1,9 @@
-import { isIdentifier, pascalCase, singleQuote } from '@internals/utils'
-import { INDENT } from '../constants.ts'
-import type { OperationNode, ParameterNode } from '../nodes/index.ts'
-import type { OperationParamsResolver, ParamGroupType } from './ast.ts'
-
 export { isValidVarName } from '@internals/utils'
+export { buildJSDoc, buildList, buildObject, objectKey } from './codegen.ts'
 export { extractStringsFromNodes } from './extractStringsFromNodes.ts'
-export {
-  buildGroupParam,
-  buildTypeLiteral,
-  caseParams,
-  collectUsedSchemaNames,
-  containsCircularRef,
-  findCircularSchemas,
-  isStringType,
-  resolveParamType,
-  syncSchemaRef,
-} from './ast.ts'
-export type { BuildGroupArgs, ParamGroupType } from './ast.ts'
-
-/**
- * Strips a single matching pair of `"..."`, `'...'`, or `` `...` `` from both ends of `text`.
- * Returns the string unchanged when no balanced quote pair is found.
- *
- * @example
- * ```ts
- * trimQuotes('"hello"') // 'hello'
- * trimQuotes('hello')   // 'hello'
- * ```
- */
-export function trimQuotes(text: string): string {
-  if (text.length >= 2) {
-    const first = text[0]
-    const last = text[text.length - 1]
-    if ((first === '"' && last === '"') || (first === "'" && last === "'") || (first === '`' && last === '`')) {
-      return text.slice(1, -1)
-    }
-  }
-  return text
-}
-
-/**
- * Serializes a primitive value to a single-quoted string literal, stripping any surrounding quote
- * characters first. Escaping comes from `JSON.stringify`, then the quote style switches to single
- * quotes so generated code matches the repo style without a formatter.
- *
- * @example
- * ```ts
- * stringify('hello')   // "'hello'"
- * stringify('"hello"') // "'hello'"
- * ```
- */
-export function stringify(value: string | number | boolean | undefined): string {
-  if (value === undefined || value === null) return "''"
-  const json = JSON.stringify(trimQuotes(value.toString()))
-  const inner = json.slice(1, -1).replace(/\\"/g, '"').replace(/'/g, "\\'")
-  return `'${inner}'`
-}
-
-/**
- * Escapes characters that are not allowed inside JS string literals, covering quotes, backslashes,
- * and the Unicode line terminators U+2028 and U+2029.
- *
- * @see http://www.ecma-international.org/ecma-262/5.1/#sec-7.8.4
- *
- * @example
- * ```ts
- * jsStringEscape('say "hi"\nbye') // 'say \\"hi\\"\\nbye'
- * ```
- */
-export function jsStringEscape(input: unknown): string {
-  return `${input}`.replace(/["'\\\n\r\u2028\u2029]/g, (character) => {
-    switch (character) {
-      case '"':
-      case "'":
-      case '\\':
-        return `\\${character}`
-      case '\n':
-        return '\\n'
-      case '\r':
-        return '\\r'
-      case '\u2028':
-        return '\\u2028'
-      case '\u2029':
-        return '\\u2029'
-      default:
-        return ''
-    }
-  })
-}
-
-/**
- * Converts a pattern string into a `new RegExp(...)` constructor call or a regex literal string.
- * Inline flags expressed as a `^(?im)` prefix are extracted and applied to the resulting expression.
- * Pass `null` as the second argument to emit a `/pattern/flags` literal instead.
- *
- * @example
- * ```ts
- * toRegExpString('^(?im)foo')       // 'new RegExp("^foo", "im")'
- * toRegExpString('^(?im)foo', null) // '/^foo/im'
- * ```
- */
-export function toRegExpString(text: string, func: string | null = 'RegExp'): string {
-  const raw = trimQuotes(text)
-
-  const match = raw.match(/^\^(\(\?([igmsuy]+)\))/i)
-  const replacementTarget = match?.[1] ?? ''
-  const matchedFlags = match?.[2]
-  const cleaned = raw
-    .replace(/^\\?\//, '')
-    .replace(/\\?\/$/, '')
-    .replace(replacementTarget, '')
-
-  const { source, flags } = new RegExp(cleaned, matchedFlags)
-
-  if (func === null) return `/${source}/${flags}`
-
-  return `new ${func}(${JSON.stringify(source)}${flags ? `, ${JSON.stringify(flags)}` : ''})`
-}
-
-/**
- * Renders a plain object as multi-line `key: value` source for embedding in generated code. Nested
- * objects recurse with fixed indentation, so the result drops straight into an object literal
- * without re-parsing.
- *
- * @example
- * ```ts
- * stringifyObject({ foo: 'bar', nested: { a: 1 } })
- * // 'foo: bar,\nnested: {\n        a: 1\n      }'
- * ```
- */
-export function stringifyObject(value: Record<string, unknown>): string {
-  const items = Object.entries(value)
-    .map(([key, val]) => {
-      if (val !== null && typeof val === 'object') {
-        return `${key}: {\n        ${stringifyObject(val as Record<string, unknown>)}\n      }`
-      }
-      return `${key}: ${val}`
-    })
-    .filter(Boolean)
-  return items.join(',\n')
-}
-
-/**
- * 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']"
- * ```
- */
-export function getNestedAccessor(param: string | Array<string>, accessor: string): string | null {
-  const parts = Array.isArray(param) ? param : param.split('.')
-  if (parts.length === 0 || (parts.length === 1 && parts[0] === '')) return null
-  return `${accessor}?.['${`${parts.join("']?.['")}']`}`
-}
-
-/**
- * Builds a JSDoc comment block from an array of lines, returning `fallback` when there are no
- * comments so callers always get a usable string.
- *
- * @example
- * ```ts
- * buildJSDoc(['@type string', '@example hello'])
- * // '/**\n   * @type string\n   * @example hello\n   *\/\n  '
- * ```
- */
-export function buildJSDoc(
-  comments: Array<string>,
-  options: {
-    /**
-     * String used to indent each comment line.
-     * @default '   * '
-     */
-    indent?: string
-    /**
-     * String appended after the closing tag.
-     * @default '\n  '
-     */
-    suffix?: string
-    /**
-     * Returned as-is when `comments` is empty.
-     * @default '  '
-     */
-    fallback?: string
-  } = {},
-): string {
-  const { indent = '   * ', suffix = '\n  ', fallback = '  ' } = options
-
-  if (comments.length === 0) return fallback
-
-  return `/**\n${comments.map((c) => `${indent}${c}`).join('\n')}\n   */${suffix}`
-}
-
-/**
- * Indents every non-empty line of `text` by one indent level, leaving blank lines empty.
- */
-function indentLines(text: string): string {
-  if (!text) return ''
-  return text
-    .split('\n')
-    .map((line) => (line.trim() ? `${INDENT}${line}` : ''))
-    .join('\n')
-}
-
-/**
- * Renders an object key, quoting it with single quotes only when it is not a valid identifier.
- * Reserved words and globals (`name`, `class`, …) are valid bare keys and stay unquoted.
- *
- * @example
- * ```ts
- * objectKey('name')    // 'name'
- * objectKey('x-total') // "'x-total'"
- * ```
- */
-export function objectKey(name: string): string {
-  return isIdentifier(name) ? name : singleQuote(name)
-}
-
-/**
- * Assembles a multi-line object literal from already-rendered `entries`, indenting each entry one
- * level and closing the brace at column zero. Nested objects built the same way indent cumulatively,
- * so callers never re-parse the generated code. A trailing comma is added per entry to match the
- * formatter's multi-line style.
- *
- * @example
- * ```ts
- * buildObject(['id: z.number()', 'name: z.string()'])
- * // '{\n  id: z.number(),\n  name: z.string(),\n}'
- * ```
- */
-export function buildObject(entries: Array<string>): string {
-  if (entries.length === 0) return '{}'
-  const body = entries.map((entry) => `${indentLines(entry)},`).join('\n')
-
-  return `{\n${body}\n}`
-}
-
-/**
- * Assembles a bracketed list (array by default) from already-rendered `items`. Keeps everything on
- * one line when no item spans multiple lines, and otherwise puts each item on its own line, indented
- * one level with a trailing comma and the closing bracket at column zero. Use it for `z.union([…])`,
- * `z.array([…])`, and similar member lists so objects inside them nest correctly.
- *
- * @example
- * ```ts
- * buildList(['z.string()', 'z.number()'])
- * // '[z.string(), z.number()]'
- * ```
- */
-export function buildList(items: Array<string>, brackets: [open: string, close: string] = ['[', ']']): string {
-  const [open, close] = brackets
-  if (items.length === 0) return `${open}${close}`
-  if (!items.some((item) => item.includes('\n'))) return `${open}${items.join(', ')}${close}`
-  const body = items.map((item) => `${indentLines(item)},`).join('\n')
-
-  return `${open}\n${body}\n${close}`
-}
-
-/**
- * Returns the last path segment of a reference string.
- *
- * @example
- * ```ts
- * extractRefName('#/components/schemas/Pet') // 'Pet'
- * ```
- */
-export function extractRefName(ref: string): string {
-  return ref.split('/').at(-1) ?? ref
-}
-
-/**
- * Builds a PascalCase child schema name by joining a parent name and property name.
- * Returns `null` when there is no parent to nest under.
- *
- * @example
- * ```ts
- * childName('Order', 'shipping_address') // 'OrderShippingAddress'
- * childName(undefined, 'params')         // null
- * ```
- */
-export function childName(parentName: string | null | undefined, propName: string): string | null {
-  return parentName ? pascalCase([parentName, propName].join(' ')) : null
-}
-
-/**
- * Builds a PascalCase enum name from the parent name, property name, and a suffix, skipping any
- * empty parts.
- *
- * @example
- * ```ts
- * enumPropName('Order', 'status', 'enum') // 'OrderStatusEnum'
- * ```
- */
-export function enumPropName(parentName: string | null | undefined, propName: string, enumSuffix: string): string {
-  return pascalCase([parentName, propName, enumSuffix].filter(Boolean).join(' '))
-}
-
-/**
- * Returns the discriminator key whose mapping value matches `ref`, or `null` when there is no match.
- *
- * @example
- * ```ts
- * findDiscriminator({ dog: '#/components/schemas/Dog' }, '#/components/schemas/Dog') // 'dog'
- * ```
- */
-export function findDiscriminator(mapping: Record<string, string> | undefined, ref: string | undefined): string | null {
-  if (!mapping || !ref) return null
-  return Object.entries(mapping).find(([, value]) => value === ref)?.[0] ?? null
-}
-
-/**
- * Derives a {@link ParamGroupType} for a query or header group from the resolver.
- *
- * Returns `null` when there is no resolver, no params, or the group name equals the
- * individual param name (so there is no real group to emit).
- */
-export function resolveGroupType({
-  node,
-  params,
-  group,
-  resolver,
-}: {
-  node: OperationNode
-  params: Array<ParameterNode>
-  group: 'query' | 'header'
-  resolver: OperationParamsResolver | undefined
-}): ParamGroupType | null {
-  if (!resolver || !params.length) {
-    return null
-  }
-  const firstParam = params[0]!
-  const groupMethod = group === 'query' ? resolver.resolveQueryParamsName : resolver.resolveHeaderParamsName
-  const groupName = groupMethod.call(resolver, node, firstParam)
-  if (groupName === resolver.resolveParamName(node, firstParam)) {
-    return null
-  }
-  return { type: groupName, optional: params.every((p) => !p.required) }
-}
+export { childName, enumPropName, extractRefName, isStringType, resolveGroupType } from './refs.ts'
+export { syncSchemaRef } from '../transformers.ts'
+export { getNestedAccessor, jsStringEscape, stringify, stringifyObject, toRegExpString, trimQuotes } from './strings.ts'
+export { collectUsedSchemaNames, containsCircularRef, findCircularSchemas } from './schemaGraph.ts'
+export { buildGroupParam, buildTypeLiteral, caseParams, createOperationParams, resolveParamType } from './operationParams.ts'
+export type { BuildGroupArgs, ParamGroupType } from './operationParams.ts'

package/src/utils/operationParams.ts

@@ -0,0 +1,353 @@
+import { camelCase, isValidVarName, memoize } from '@internals/utils'
+import { createFunctionParameter, createFunctionParameters, createIndexedAccessType, createTypeLiteral } from '../nodes/function.ts'
+import type { FunctionParameterNode, FunctionParametersNode, OperationNode, ParameterNode, TypeExpression, TypeLiteralNode } from '../nodes/index.ts'
+import { resolveGroupType } from './refs.ts'
+
+/**
+ * Applies casing rules to parameter names and returns a new array without mutating the input.
+ *
+ * Run it before handing parameters to schema builders so output property keys get the right casing
+ * while `OperationNode.parameters` stays intact for other consumers. When `casing` is unset, the
+ * original array is returned unchanged.
+ */
+const caseParamsMemo = memoize(new WeakMap<Array<ParameterNode>, (casing: string) => Array<ParameterNode>>(), (params) =>
+  memoize(new Map<string, Array<ParameterNode>>(), (casing: string) =>
+    params.map((param) => {
+      const transformed = casing === 'camelcase' || !isValidVarName(param.name) ? camelCase(param.name) : param.name
+      return { ...param, name: transformed }
+    }),
+  ),
+)
+
+export function caseParams(params: Array<ParameterNode>, casing: 'camelcase' | undefined): Array<ParameterNode> {
+  if (!casing) return params
+  return caseParamsMemo(params)(casing)
+}
+
+/**
+ * Named type for a group of parameters (query or header) emitted as a single typed parameter.
+ */
+export type ParamGroupType = {
+  /**
+   * Type expression for the group, a plain group-name reference.
+   */
+  type: TypeExpression
+  /**
+   * Whether the parameter group is optional.
+   */
+  optional: boolean
+}
+
+/**
+ * A single member of a destructured parameter group, fed to `createFunctionParameter({ properties })`.
+ */
+type GroupProperty = {
+  name: string
+  type: TypeExpression
+  optional?: boolean
+}
+
+/**
+ * Resolver interface for {@link createOperationParams}.
+ *
+ * `ResolverTs` from `@kubb/plugin-ts` satisfies this interface and can be passed directly.
+ */
+export type OperationParamsResolver = {
+  /**
+   * Resolves the type name for an individual parameter.
+   *
+   * @example Individual path parameter name
+   * `resolver.resolveParamName(node, param) // → 'DeletePetPathPetId'`
+   */
+  resolveParamName(node: OperationNode, param: ParameterNode): string
+  /**
+   * Resolves the request body type name.
+   *
+   * @example Request body type name
+   * `resolver.resolveDataName(node) // → 'CreatePetData'`
+   */
+  resolveDataName(node: OperationNode): string
+  /**
+   * Resolves the grouped path parameters type name.
+   * When the return value equals `resolveParamName`, no indexed access is emitted.
+   *
+   * @example Grouped path params type name
+   * `resolver.resolvePathParamsName(node, param) // → 'DeletePetPathParams'`
+   */
+  resolvePathParamsName(node: OperationNode, param: ParameterNode): string
+  /**
+   * Resolves the grouped query parameters type name.
+   * When the return value equals `resolveParamName`, an inline struct type is emitted instead.
+   *
+   * @example Grouped query params type name
+   * `resolver.resolveQueryParamsName(node, param) // → 'FindPetsByStatusQueryParams'`
+   */
+  resolveQueryParamsName(node: OperationNode, param: ParameterNode): string
+  /**
+   * Resolves the grouped header parameters type name.
+   * When the return value equals `resolveParamName`, an inline struct type is emitted instead.
+   *
+   * @example Grouped header params type name
+   * `resolver.resolveHeaderParamsName(node, param) // → 'DeletePetHeaderParams'`
+   */
+  resolveHeaderParamsName(node: OperationNode, param: ParameterNode): string
+}
+
+/**
+ * Options for {@link createOperationParams}.
+ */
+export type CreateOperationParamsOptions = {
+  /**
+   * How all operation parameters are grouped in the function signature.
+   * - `'object'` wraps all params into a single destructured object `{ petId, data, params }`
+   * - `'inline'` emits each param category as a separate top-level parameter
+   */
+  paramsType: 'object' | 'inline'
+  /**
+   * How path parameters are emitted when `paramsType` is `'inline'`.
+   * - `'object'` groups them as `{ petId, storeId }: PathParams`
+   * - `'inline'` spreads them as individual parameters `petId: string, storeId: string`
+   * - `'inlineSpread'` emits a single rest parameter `...pathParams: PathParams`
+   */
+  pathParamsType: 'object' | 'inline' | 'inlineSpread'
+  /**
+   * Converts parameter names to camelCase before output.
+   */
+  paramsCasing?: 'camelcase'
+  /**
+   * Resolver for parameter and request body type names.
+   * Pass `ResolverTs` from `@kubb/plugin-ts` directly.
+   * When omitted, falls back to the schema primitive or `'unknown'`.
+   */
+  resolver?: OperationParamsResolver
+  /**
+   * Default value for the path parameters binding when `pathParamsType` is `'object'`.
+   * Falls back to `'{}'` when all path params are optional.
+   */
+  pathParamsDefault?: string
+  /**
+   * Extra parameters appended after the standard operation parameters.
+   *
+   * @example Plugin-specific trailing parameter
+   * ```ts
+   * extraParams: [createFunctionParameter({ name: 'options', type: 'Partial<RequestOptions>', default: '{}' })]
+   * ```
+   */
+  extraParams?: Array<FunctionParameterNode>
+  /**
+   * Override the default parameter names used for body, query, header, and rest-path groups.
+   *
+   * Useful when targeting languages or frameworks with different naming conventions.
+   *
+   * @default { data: 'data', params: 'params', headers: 'headers', path: 'pathParams' }
+   */
+  paramNames?: {
+    /**
+     * Name for the request body parameter.
+     * @default 'data'
+     */
+    data?: string
+    /**
+     * Name for the query parameters group parameter.
+     * @default 'params'
+     */
+    params?: string
+    /**
+     * Name for the header parameters group parameter.
+     * @default 'headers'
+     */
+    headers?: string
+    /**
+     * Name for the rest path-parameters parameter when `pathParamsType` is `'inlineSpread'`.
+     * @default 'pathParams'
+     */
+    path?: string
+  }
+  /**
+   * Transforms every resolved type name before it lands in a parameter node, for framework-level
+   * type wrappers.
+   *
+   * @example Vue Query, wrap every parameter type with `MaybeRefOrGetter`
+   * `typeWrapper: (t) => \`MaybeRefOrGetter<${t}>\``
+   */
+  typeWrapper?: (type: string) => string
+}
+
+/**
+ * Resolves the {@link TypeExpression} for an individual parameter.
+ *
+ * Without a resolver, it falls back to the schema primitive (a plain type-name string). When the
+ * parameter belongs to a named group, it emits an {@link IndexedAccessTypeNode} like
+ * `GroupParams['petId']`, otherwise the resolved individual name.
+ */
+export function resolveParamType({
+  node,
+  param,
+  resolver,
+}: {
+  node: OperationNode
+  param: ParameterNode
+  resolver: OperationParamsResolver | undefined
+}): TypeExpression {
+  if (!resolver) {
+    return param.schema.primitive ?? 'unknown'
+  }
+
+  const individualName = resolver.resolveParamName(node, param)
+
+  const groupLocation = param.in === 'path' || param.in === 'query' || param.in === 'header' ? param.in : undefined
+
+  const groupResolvers = {
+    path: resolver.resolvePathParamsName,
+    query: resolver.resolveQueryParamsName,
+    header: resolver.resolveHeaderParamsName,
+  } as const
+
+  const groupName = groupLocation ? groupResolvers[groupLocation].call(resolver, node, param) : undefined
+
+  if (groupName && groupName !== individualName) {
+    return createIndexedAccessType({ objectType: groupName, indexType: param.name })
+  }
+
+  return individualName
+}
+
+/**
+ * Converts an `OperationNode` into function parameters for code generation.
+ *
+ * Centralizes parameter grouping logic for all plugins. `paramsType` chooses between one
+ * destructured object parameter (`object`) and separate top-level parameters (`inline`), while
+ * `pathParamsType` controls how path params render in inline mode. Provide a `resolver` for type
+ * name resolution and `extraParams` for plugin-specific trailing parameters such as an `options` object.
+ */
+export function createOperationParams(node: OperationNode, options: CreateOperationParamsOptions): FunctionParametersNode {
+  const { paramsType, pathParamsType, paramsCasing, resolver, pathParamsDefault, extraParams = [], paramNames, typeWrapper } = options
+
+  const dataName = paramNames?.data ?? 'data'
+  const paramsName = paramNames?.params ?? 'params'
+  const headersName = paramNames?.headers ?? 'headers'
+  const pathName = paramNames?.path ?? 'pathParams'
+
+  const wrapType = (type: string): string => (typeWrapper ? typeWrapper(type) : type)
+  // Only plain type-name references are wrapped, they need casing applied.
+  // TypeLiteral and IndexedAccessType expressions are pre-resolved and pass through unchanged.
+  const wrapTypeExpression = (type: TypeExpression): TypeExpression => (typeof type === 'string' ? wrapType(type) : type)
+
+  const casedParams = caseParams(node.parameters, paramsCasing)
+  const pathParams = casedParams.filter((p) => p.in === 'path')
+  const queryParams = casedParams.filter((p) => p.in === 'query')
+  const headerParams = casedParams.filter((p) => p.in === 'header')
+
+  const toProperty = (param: ParameterNode): GroupProperty => ({
+    name: param.name,
+    type: wrapTypeExpression(resolveParamType({ node, param, resolver })),
+    optional: !param.required,
+  })
+  const emptyObjectDefault = (props: Array<GroupProperty>): string | undefined => (props.every((p) => p.optional) ? '{}' : undefined)
+
+  const bodyType = node.requestBody?.content?.[0]?.schema ? wrapType(resolver?.resolveDataName(node) ?? 'unknown') : undefined
+  const bodyProperty: Array<GroupProperty> = bodyType ? [{ name: dataName, type: bodyType, optional: !(node.requestBody?.required ?? false) }] : []
+
+  const trailingGroups: Array<BuildGroupArgs> = [
+    { name: paramsName, node, params: queryParams, groupType: resolveGroupType({ node, params: queryParams, group: 'query', resolver }), resolver, wrapType },
+    {
+      name: headersName,
+      node,
+      params: headerParams,
+      groupType: resolveGroupType({ node, params: headerParams, group: 'header', resolver }),
+      resolver,
+      wrapType,
+    },
+  ]
+
+  const params: Array<FunctionParameterNode> = []
+
+  if (paramsType === 'object') {
+    const children = [...pathParams.map(toProperty), ...bodyProperty, ...trailingGroups.flatMap(buildGroupProperty)]
+    if (children.length) {
+      params.push(createFunctionParameter({ properties: children, default: emptyObjectDefault(children) }))
+    }
+  } else {
+    if (pathParamsType === 'inlineSpread' && pathParams.length) {
+      const spreadType = resolver?.resolvePathParamsName(node, pathParams[0]!)
+      params.push(createFunctionParameter({ name: pathName, type: spreadType ? wrapType(spreadType) : undefined, rest: true }))
+    } else if (pathParamsType === 'inline') {
+      params.push(...pathParams.map((p) => createFunctionParameter(toProperty(p))))
+    } else if (pathParams.length) {
+      const pathChildren = pathParams.map(toProperty)
+      params.push(createFunctionParameter({ properties: pathChildren, default: pathParamsDefault ?? emptyObjectDefault(pathChildren) }))
+    }
+
+    params.push(...bodyProperty.map((p) => createFunctionParameter(p)))
+    params.push(...trailingGroups.flatMap(buildGroupParam))
+  }
+
+  params.push(...extraParams)
+
+  return createFunctionParameters({ params })
+}
+
+/**
+ * Shared arguments for building a query or header parameter group.
+ */
+export type BuildGroupArgs = {
+  name: string
+  node: OperationNode
+  params: Array<ParameterNode>
+  groupType: ParamGroupType | null
+  resolver: OperationParamsResolver | undefined
+  wrapType: (type: string) => string
+}
+
+/**
+ * Builds the property descriptor for a query or header group.
+ * Returns an empty array when there are no params to emit.
+ *
+ * A pre-resolved `groupType` emits `name: GroupType`. Otherwise it builds an inline
+ * {@link TypeLiteralNode} from the individual params.
+ */
+function buildGroupProperty({ name, node, params, groupType, resolver, wrapType }: BuildGroupArgs): Array<GroupProperty> {
+  if (groupType) {
+    const type = typeof groupType.type === 'string' ? wrapType(groupType.type) : groupType.type
+    return [{ name, type, optional: groupType.optional }]
+  }
+  if (params.length) {
+    return [{ name, type: buildTypeLiteral({ node, params, resolver }), optional: params.every((p) => !p.required) }]
+  }
+  return []
+}
+
+/**
+ * Builds a single {@link FunctionParameterNode} for a query or header group.
+ * Returns an empty array when there are no params to emit.
+ *
+ * A pre-resolved `groupType` emits `name: GroupType`. Otherwise it builds an inline
+ * {@link TypeLiteralNode} from the individual params.
+ */
+export function buildGroupParam(args: BuildGroupArgs): Array<FunctionParameterNode> {
+  return buildGroupProperty(args).map((p) => createFunctionParameter(p))
+}
+
+/**
+ * Builds a {@link TypeLiteralNode} for an inline anonymous type grouping named fields.
+ *
+ * Used when query or header parameters have no dedicated group type name.
+ * Each language printer renders this appropriately (TypeScript: `{ petId: string; name?: string }`).
+ */
+export function buildTypeLiteral({
+  node,
+  params,
+  resolver,
+}: {
+  node: OperationNode
+  params: Array<ParameterNode>
+  resolver: OperationParamsResolver | undefined
+}): TypeLiteralNode {
+  return createTypeLiteral({
+    members: params.map((p) => ({
+      name: p.name,
+      type: resolveParamType({ node, param: p, resolver }),
+      optional: !p.required,
+    })),
+  })
+}