@kubb/ast 5.0.0-beta.6 → 5.0.0-beta.61

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,
+    })),
+  })
+}

package/src/utils/refs.ts

@@ -0,0 +1,138 @@
+import { pascalCase } from '@internals/utils'
+import { narrowSchema } from '../guards.ts'
+import type { OperationNode, ParameterNode, SchemaNode } from '../nodes/index.ts'
+import { createSchema, type SchemaType } from '../nodes/schema.ts'
+import type { OperationParamsResolver, ParamGroupType } from './operationParams.ts'
+
+const plainStringTypes = new Set<SchemaType>(['string', 'uuid', 'email', 'url', 'datetime'] as const)
+
+/**
+ * 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
+}
+
+/**
+ * Resolves the schema name of a ref node, falling back through `ref` → `name` → nested `schema.name`.
+ *
+ * Returns `null` for non-ref nodes or when no name resolves.
+ *
+ * @example
+ * ```ts
+ * resolveRefName({ kind: 'Schema', type: 'ref', ref: '#/components/schemas/Pet' })
+ * // => 'Pet'
+ * ```
+ */
+export function resolveRefName(node: SchemaNode | undefined): string | null {
+  if (!node || node.type !== 'ref') return null
+  if (node.ref) return extractRefName(node.ref) ?? node.name ?? node.schema?.name ?? null
+
+  return node.name ?? node.schema?.name ?? null
+}
+
+/**
+ * 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(' '))
+}
+
+/**
+ * Merges a ref node with its resolved schema, giving usage-site fields precedence.
+ *
+ * Usage-site fields (`description`, `readOnly`, `nullable`, `deprecated`) on the ref node override
+ * the same fields in the resolved `node.schema`. Non-ref nodes are returned unchanged.
+ *
+ * @example
+ * ```ts
+ * const ref = createSchema({ type: 'ref', ref: '#/components/schemas/Pet', description: 'A cute pet' })
+ * const merged = syncSchemaRef(ref) // merges with resolved Pet schema
+ * ```
+ */
+export function syncSchemaRef(node: SchemaNode): SchemaNode {
+  const ref = narrowSchema(node, 'ref')
+
+  if (!ref) return node
+  if (!ref.schema) return node
+
+  const { kind: _kind, type: _type, name: _name, ref: _ref, schema: _schema, ...overrides } = ref
+
+  // Filter out undefined override values so they don't shadow the resolved schema's fields.
+  const definedOverrides = Object.fromEntries(Object.entries(overrides).filter(([, v]) => v !== undefined))
+
+  return createSchema({ ...ref.schema, ...definedOverrides })
+}
+
+/**
+ * Type guard that returns `true` when a schema emits as a plain `string` type.
+ *
+ * Covers `string`, `uuid`, `email`, `url`, and `datetime` types. For `date` and `time`
+ * types, returns `true` only when `representation` is `'string'` rather than `'date'`.
+ */
+export function isStringType(node: SchemaNode): boolean {
+  if (plainStringTypes.has(node.type)) {
+    return true
+  }
+
+  const temporal = narrowSchema(node, 'date') ?? narrowSchema(node, 'time')
+  if (temporal) {
+    return temporal.representation !== 'date'
+  }
+
+  return false
+}
+
+/**
+ * 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) }
+}

package/src/utils/schemaGraph.ts

@@ -0,0 +1,169 @@
+import { memoize } from '@internals/utils'
+import type { OperationNode, SchemaNode } from '../nodes/index.ts'
+import { collect, collectLazy } from '../visitor.ts'
+import { resolveRefName } from './refs.ts'
+
+/**
+ * Collects every named schema referenced transitively from a node through its ref edges.
+ *
+ * Refs are followed by name only, so the resolved `node.schema` is never traversed inline.
+ *
+ * @example Collect refs from a single schema
+ * ```ts
+ * const names = collectReferencedSchemaNames(petSchema)
+ * // → Set { 'Category', 'Tag' }
+ * ```
+ *
+ * @example Accumulate refs from multiple schemas into one set
+ * ```ts
+ * const out = new Set<string>()
+ * for (const schema of schemas) {
+ *   collectReferencedSchemaNames(schema, out)
+ * }
+ * ```
+ */
+const collectSchemaRefs = memoize(new WeakMap<SchemaNode, ReadonlySet<string>>(), (node: SchemaNode): ReadonlySet<string> => {
+  const refs = new Set<string>()
+  collect<void>(node, {
+    schema(child) {
+      if (child.type === 'ref') {
+        const name = resolveRefName(child)
+        if (name) refs.add(name)
+      }
+    },
+  })
+  return refs
+})
+
+export function collectReferencedSchemaNames(node: SchemaNode | undefined, out: Set<string> = new Set()): Set<string> {
+  if (!node) return out
+  for (const name of collectSchemaRefs(node)) out.add(name)
+  return out
+}
+
+/**
+ * Collects the names of all top-level schemas transitively used by a set of operations.
+ *
+ * An operation uses a schema when its parameters, request body, or responses reference it, directly
+ * or through other named schemas. The walk is iterative, so reference cycles are safe.
+ *
+ * Pair it with `include` filters so schemas reachable only from excluded operations stay ungenerated.
+ *
+ * @example Only generate schemas referenced by included operations
+ * ```ts
+ * const includedOps = operations.filter((op) => resolver.resolveOptions(op, { options, include }) !== null)
+ * const allowed = collectUsedSchemaNames(includedOps, schemas)
+ *
+ * for (const schema of schemas) {
+ *   if (schema.name && !allowed.has(schema.name)) continue
+ *   // … generate schema
+ * }
+ * ```
+ */
+const collectUsedSchemaNamesMemo = memoize(new WeakMap<ReadonlyArray<OperationNode>, (schemas: ReadonlyArray<SchemaNode>) => Set<string>>(), (ops) =>
+  memoize(new WeakMap<ReadonlyArray<SchemaNode>, Set<string>>(), (schemas) => computeUsedSchemaNames(ops, schemas)),
+)
+
+function computeUsedSchemaNames(operations: ReadonlyArray<OperationNode>, schemas: ReadonlyArray<SchemaNode>): Set<string> {
+  const schemaMap = new Map<string, SchemaNode>()
+  for (const schema of schemas) {
+    if (schema.name) schemaMap.set(schema.name, schema)
+  }
+
+  const result = new Set<string>()
+
+  function visitSchema(schema: SchemaNode): void {
+    const directRefs = collectReferencedSchemaNames(schema)
+    for (const name of directRefs) {
+      if (!result.has(name)) {
+        result.add(name)
+        const namedSchema = schemaMap.get(name)
+        if (namedSchema) visitSchema(namedSchema)
+      }
+    }
+  }
+
+  for (const op of operations) {
+    for (const schema of collectLazy<SchemaNode>(op, { depth: 'shallow', schema: (node) => node })) {
+      visitSchema(schema)
+    }
+  }
+
+  return result
+}
+
+export function collectUsedSchemaNames(operations: ReadonlyArray<OperationNode>, schemas: ReadonlyArray<SchemaNode>): Set<string> {
+  return collectUsedSchemaNamesMemo(operations)(schemas)
+}
+
+const EMPTY_CIRCULAR_SET = new Set<string>()
+
+const findCircularSchemasMemo = memoize(new WeakMap<ReadonlyArray<SchemaNode>, Set<string>>(), (schemas: ReadonlyArray<SchemaNode>): Set<string> => {
+  const graph = new Map<string, Set<string>>()
+
+  for (const schema of schemas) {
+    if (!schema.name) continue
+    graph.set(schema.name, collectReferencedSchemaNames(schema))
+  }
+
+  const circular = new Set<string>()
+  for (const start of graph.keys()) {
+    const visited = new Set<string>()
+    const stack: Array<string> = [...(graph.get(start) ?? [])]
+    while (stack.length > 0) {
+      const node = stack.pop()!
+      if (node === start) {
+        circular.add(start)
+        break
+      }
+      if (visited.has(node)) continue
+      visited.add(node)
+
+      const next = graph.get(node)
+      if (next) for (const r of next) stack.push(r)
+    }
+  }
+
+  return circular
+})
+
+/**
+ * Finds every schema that takes part in a circular dependency chain, including direct self-loops.
+ *
+ * Wrap the returned schema positions in a deferred construct (a lazy getter or `z.lazy(() => …)`) so
+ * the generated code does not recurse forever. Refs are followed by name only, so the walk stays
+ * linear in the size of the schema graph.
+ *
+ * @note Call this once on the full graph, then check individual schemas with `containsCircularRef()`.
+ */
+export function findCircularSchemas(schemas: ReadonlyArray<SchemaNode>): Set<string> {
+  if (schemas.length === 0) return EMPTY_CIRCULAR_SET
+  return findCircularSchemasMemo(schemas)
+}
+
+/**
+ * Returns `true` when a schema, or anything nested inside it, references a circular schema.
+ *
+ * Pass `excludeName` to skip refs to a specific schema, which helps when self-references are handled
+ * on their own. Pair it with `findCircularSchemas()` to decide where lazy wrappers go.
+ *
+ * @note Stops at the first matching circular ref.
+ */
+export function containsCircularRef(
+  node: SchemaNode | undefined,
+  { circularSchemas, excludeName }: { circularSchemas: ReadonlySet<string>; excludeName?: string },
+): boolean {
+  if (!node || circularSchemas.size === 0) return false
+
+  for (const _ of collectLazy<true>(node, {
+    schema(child) {
+      if (child.type !== 'ref') return null
+      const name = resolveRefName(child)
+      return name && name !== excludeName && circularSchemas.has(name) ? true : null
+    },
+  })) {
+    return true
+  }
+
+  return false
+}

package/src/utils/schemaMerge.ts

@@ -0,0 +1,34 @@
+import { narrowSchema } from '../guards.ts'
+import { createSchema, type SchemaNode } from '../nodes/schema.ts'
+
+/**
+ * Merges a run of adjacent anonymous object members into one. Named or non-object members break the
+ * run and pass through. Stays a construction-time helper, not a macro, so callers keep control of the
+ * member boundaries (such as keeping synthetic discriminant objects out of a run).
+ *
+ * @example
+ * ```ts
+ * const merged = [...mergeAdjacentObjectsLazy([objectA, objectB])]
+ * ```
+ */
+export function* mergeAdjacentObjectsLazy(members: Iterable<SchemaNode>): Generator<SchemaNode, void, undefined> {
+  let acc: SchemaNode | undefined
+
+  for (const member of members) {
+    const objectMember = narrowSchema(member, 'object')
+    if (objectMember && !objectMember.name && acc !== undefined) {
+      const accObject = narrowSchema(acc, 'object')
+      if (accObject && !accObject.name) {
+        acc = createSchema({
+          ...accObject,
+          properties: [...(accObject.properties ?? []), ...(objectMember.properties ?? [])],
+        })
+        continue
+      }
+    }
+    if (acc !== undefined) yield acc
+    acc = member
+  }
+
+  if (acc !== undefined) yield acc
+}