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

package/dist/visitor-DpKZ9Tk0.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"visitor-DpKZ9Tk0.cjs","names":["pascalCase","createSchema","inputDef","outputDef","operationDef","requestBodyDef","contentDef","responseDef","schemaDef","propertyDef","parameterDef","functionParameterDef","functionParametersDef","typeLiteralDef","indexedAccessTypeDef","objectBindingPatternDef","constDef","typeDef","functionDef","arrowFunctionDef","textDef","breakDef","jsxDef","importDef","exportDef","sourceDef","fileDef"],"sources":["../src/constants.ts","../src/guards.ts","../src/utils/refs.ts","../src/registry.ts","../src/visitor.ts"],"sourcesContent":["import type { HttpMethod } from './nodes/operation.ts'\nimport type { SchemaType } from './nodes/schema.ts'\n\n/**\n * Traversal depth for AST visitor utilities.\n *\n * - `'shallow'` visits only the immediate node, skipping children.\n * - `'deep'` recursively visits all descendant nodes.\n */\nexport type VisitorDepth = 'shallow' | 'deep'\n\nexport const visitorDepths = {\n  shallow: 'shallow',\n  deep: 'deep',\n} as const satisfies Record<VisitorDepth, VisitorDepth>\n\n/**\n * Schema type discriminators used by all AST schema nodes.\n *\n * Each value is a stable discriminator across the AST (for example `schema.type === schemaTypes.object`).\n * Call `isScalarPrimitive()` to check for the scalar types.\n */\nexport const schemaTypes = {\n  /**\n   * Text value.\n   */\n  string: 'string',\n  /**\n   * Floating-point number (`float`, `double`).\n   */\n  number: 'number',\n  /**\n   * Whole number (`int32`). Use `bigint` for `int64`.\n   */\n  integer: 'integer',\n  /**\n   * 64-bit integer (`int64`). Only used when `integerType` is set to `'bigint'`.\n   */\n  bigint: 'bigint',\n  /**\n   * Boolean value.\n   */\n  boolean: 'boolean',\n  /**\n   * Explicit null value.\n   */\n  null: 'null',\n  /**\n   * Any value (no type restriction).\n   */\n  any: 'any',\n  /**\n   * Unknown value (must be narrowed before usage).\n   */\n  unknown: 'unknown',\n  /**\n   * No return value (`void`).\n   */\n  void: 'void',\n  /**\n   * Object with named properties.\n   */\n  object: 'object',\n  /**\n   * Sequential list of items.\n   */\n  array: 'array',\n  /**\n   * Fixed-length list with position-specific items.\n   */\n  tuple: 'tuple',\n  /**\n   * \"One of\" multiple schema members.\n   */\n  union: 'union',\n  /**\n   * \"All of\" multiple schema members.\n   */\n  intersection: 'intersection',\n  /**\n   * Enum schema.\n   */\n  enum: 'enum',\n  /**\n   * Reference to another schema.\n   */\n  ref: 'ref',\n  /**\n   * Calendar date (for example `2026-03-24`).\n   */\n  date: 'date',\n  /**\n   * Date-time value (for example `2026-03-24T09:00:00Z`).\n   */\n  datetime: 'datetime',\n  /**\n   * Time-only value (for example `09:00:00`).\n   */\n  time: 'time',\n  /**\n   * UUID value.\n   */\n  uuid: 'uuid',\n  /**\n   * Email address value.\n   */\n  email: 'email',\n  /**\n   * URL value.\n   */\n  url: 'url',\n  /**\n   * IPv4 address value.\n   */\n  ipv4: 'ipv4',\n  /**\n   * IPv6 address value.\n   */\n  ipv6: 'ipv6',\n  /**\n   * Binary/blob value.\n   */\n  blob: 'blob',\n  /**\n   * Impossible value (`never`).\n   */\n  never: 'never',\n} as const satisfies Record<SchemaType, SchemaType>\n\nexport type ScalarPrimitive = 'string' | 'number' | 'integer' | 'bigint' | 'boolean'\n\n/**\n * Scalar primitive schema types used for union simplification and type narrowing.\n */\nconst SCALAR_PRIMITIVE_TYPES = new Set<ScalarPrimitive>(['string', 'number', 'integer', 'bigint', 'boolean'])\n\n/**\n * Returns `true` when `type` is a scalar primitive that can be assigned without wrapping\n * (for example `string | number | boolean`).\n */\nexport function isScalarPrimitive(type: string): type is ScalarPrimitive {\n  return SCALAR_PRIMITIVE_TYPES.has(type as ScalarPrimitive)\n}\n\n/**\n * HTTP method identifiers used by operation nodes.\n */\nexport const httpMethods = {\n  get: 'GET',\n  post: 'POST',\n  put: 'PUT',\n  patch: 'PATCH',\n  delete: 'DELETE',\n  head: 'HEAD',\n  options: 'OPTIONS',\n  trace: 'TRACE',\n} as const satisfies Record<Lowercase<HttpMethod>, HttpMethod>\n\n/**\n * Default concurrency limit for the `walk()` traversal utility.\n *\n * Set to 30 to balance I/O-bound resolver parallelism against event-loop and memory pressure\n * during large spec traversals. Override it for different hardware constraints.\n *\n * @example\n * ```ts\n * import { walk, WALK_CONCURRENCY } from '@kubb/ast'\n *\n * walk(root, { concurrency: WALK_CONCURRENCY, root: () => {} })\n * ```\n */\nexport const WALK_CONCURRENCY = 30\n\n/**\n * Number of spaces in one indentation level when assembling multi-line code as strings.\n * Set to 2, 3, … to change the indent width used by `buildObject`/`buildList`.\n */\nconst INDENT_SIZE = 2\n\n/**\n * One indentation level, derived from {@link INDENT_SIZE}.\n */\nexport const INDENT = Array.from({ length: INDENT_SIZE }, () => ' ').join('')\n","import type { HttpOperationNode, OperationNode, SchemaNode, SchemaNodeByType } from './nodes/index.ts'\n\n/**\n * Narrows a `SchemaNode` to the variant that matches `type`.\n *\n * @example\n * ```ts\n * const schema = createSchema({ type: 'string' })\n * const stringNode = narrowSchema(schema, 'string') // StringSchemaNode | null\n * ```\n */\nexport function narrowSchema<T extends SchemaNode['type']>(node: SchemaNode | undefined, type: T): SchemaNodeByType[T] | null {\n  return node?.type === type ? (node as SchemaNodeByType[T]) : null\n}\n\n/**\n * Narrows an `OperationNode` to an `HttpOperationNode` so `method` and `path` are present.\n *\n * @example\n * ```ts\n * if (isHttpOperationNode(node)) {\n *   console.log(node.method, node.path)\n * }\n * ```\n */\nexport function isHttpOperationNode(node: OperationNode): node is HttpOperationNode {\n  return node.protocol === 'http' || (node.method !== undefined && node.path !== undefined)\n}\n","import { pascalCase } from '@internals/utils'\nimport { narrowSchema } from '../guards.ts'\nimport type { OperationNode, ParameterNode, SchemaNode } from '../nodes/index.ts'\nimport { createSchema, type SchemaType } from '../nodes/schema.ts'\nimport type { OperationParamsResolver, ParamGroupType } from './operationParams.ts'\n\nconst plainStringTypes = new Set<SchemaType>(['string', 'uuid', 'email', 'url', 'datetime'] as const)\n\n/**\n * Returns the last path segment of a reference string.\n *\n * @example\n * ```ts\n * extractRefName('#/components/schemas/Pet') // 'Pet'\n * ```\n */\nexport function extractRefName(ref: string): string {\n  return ref.split('/').at(-1) ?? ref\n}\n\n/**\n * Resolves the schema name of a ref node, falling back through `ref` → `name` → nested `schema.name`.\n *\n * Returns `null` for non-ref nodes or when no name resolves.\n *\n * @example\n * ```ts\n * resolveRefName({ kind: 'Schema', type: 'ref', ref: '#/components/schemas/Pet' })\n * // => 'Pet'\n * ```\n */\nexport function resolveRefName(node: SchemaNode | undefined): string | null {\n  if (!node || node.type !== 'ref') return null\n  if (node.ref) return extractRefName(node.ref) ?? node.name ?? node.schema?.name ?? null\n\n  return node.name ?? node.schema?.name ?? null\n}\n\n/**\n * Builds a PascalCase child schema name by joining a parent name and property name.\n * Returns `null` when there is no parent to nest under.\n *\n * @example\n * ```ts\n * childName('Order', 'shipping_address') // 'OrderShippingAddress'\n * childName(undefined, 'params')         // null\n * ```\n */\nexport function childName(parentName: string | null | undefined, propName: string): string | null {\n  return parentName ? pascalCase([parentName, propName].join(' ')) : null\n}\n\n/**\n * Builds a PascalCase enum name from the parent name, property name, and a suffix, skipping any\n * empty parts.\n *\n * @example\n * ```ts\n * enumPropName('Order', 'status', 'enum') // 'OrderStatusEnum'\n * ```\n */\nexport function enumPropName(parentName: string | null | undefined, propName: string, enumSuffix: string): string {\n  return pascalCase([parentName, propName, enumSuffix].filter(Boolean).join(' '))\n}\n\n/**\n * Merges a ref node with its resolved schema, giving usage-site fields precedence.\n *\n * Usage-site fields (`description`, `readOnly`, `nullable`, `deprecated`) on the ref node override\n * the same fields in the resolved `node.schema`. Non-ref nodes are returned unchanged.\n *\n * @example\n * ```ts\n * const ref = createSchema({ type: 'ref', ref: '#/components/schemas/Pet', description: 'A cute pet' })\n * const merged = syncSchemaRef(ref) // merges with resolved Pet schema\n * ```\n */\nexport function syncSchemaRef(node: SchemaNode): SchemaNode {\n  const ref = narrowSchema(node, 'ref')\n\n  if (!ref) return node\n  if (!ref.schema) return node\n\n  const { kind: _kind, type: _type, name: _name, ref: _ref, schema: _schema, ...overrides } = ref\n\n  // Filter out undefined override values so they don't shadow the resolved schema's fields.\n  const definedOverrides = Object.fromEntries(Object.entries(overrides).filter(([, v]) => v !== undefined))\n\n  return createSchema({ ...ref.schema, ...definedOverrides })\n}\n\n/**\n * Type guard that returns `true` when a schema emits as a plain `string` type.\n *\n * Covers `string`, `uuid`, `email`, `url`, and `datetime` types. For `date` and `time`\n * types, returns `true` only when `representation` is `'string'` rather than `'date'`.\n */\nexport function isStringType(node: SchemaNode): boolean {\n  if (plainStringTypes.has(node.type)) {\n    return true\n  }\n\n  const temporal = narrowSchema(node, 'date') ?? narrowSchema(node, 'time')\n  if (temporal) {\n    return temporal.representation !== 'date'\n  }\n\n  return false\n}\n\n/**\n * Derives a {@link ParamGroupType} for a query or header group from the resolver.\n *\n * Returns `null` when there is no resolver, no params, or the group name equals the\n * individual param name (so there is no real group to emit).\n */\nexport function resolveGroupType({\n  node,\n  params,\n  group,\n  resolver,\n}: {\n  node: OperationNode\n  params: Array<ParameterNode>\n  group: 'query' | 'header'\n  resolver: OperationParamsResolver | undefined\n}): ParamGroupType | null {\n  if (!resolver || !params.length) {\n    return null\n  }\n  const firstParam = params[0]!\n  const groupMethod = group === 'query' ? resolver.resolveQueryParamsName : resolver.resolveHeaderParamsName\n  const groupName = groupMethod.call(resolver, node, firstParam)\n  if (groupName === resolver.resolveParamName(node, firstParam)) {\n    return null\n  }\n  return { type: groupName, optional: params.every((p) => !p.required) }\n}\n","import type { NodeDef } from './node.ts'\nimport { arrowFunctionDef, breakDef, constDef, functionDef, jsxDef, textDef, typeDef } from './nodes/code.ts'\nimport { contentDef } from './nodes/content.ts'\nimport { exportDef, fileDef, importDef, sourceDef } from './nodes/file.ts'\nimport { functionParameterDef, functionParametersDef, indexedAccessTypeDef, objectBindingPatternDef, typeLiteralDef } from './nodes/function.ts'\nimport { inputDef } from './nodes/input.ts'\nimport { operationDef } from './nodes/operation.ts'\nimport { outputDef } from './nodes/output.ts'\nimport { parameterDef } from './nodes/parameter.ts'\nimport { propertyDef } from './nodes/property.ts'\nimport { requestBodyDef } from './nodes/requestBody.ts'\nimport { responseDef } from './nodes/response.ts'\nimport { schemaDef } from './nodes/schema.ts'\n\n// Surface every def from one place so the package barrel re-exports them with `export * from './registry.ts'`.\n// Adding a node means adding its `defineNode` to a `nodes/*.ts` file and listing it in `nodeDefs` below, nothing else.\nexport {\n  arrowFunctionDef,\n  breakDef,\n  constDef,\n  contentDef,\n  exportDef,\n  fileDef,\n  functionDef,\n  functionParameterDef,\n  functionParametersDef,\n  importDef,\n  indexedAccessTypeDef,\n  inputDef,\n  jsxDef,\n  objectBindingPatternDef,\n  operationDef,\n  outputDef,\n  parameterDef,\n  propertyDef,\n  requestBodyDef,\n  responseDef,\n  schemaDef,\n  sourceDef,\n  textDef,\n  typeDef,\n  typeLiteralDef,\n}\n\n/**\n * Every node definition. Adding a node means adding its `defineNode` to one\n * `nodes/*.ts` file and listing it here. The visitor tables in `visitor.ts` derive from it.\n */\nexport const nodeDefs = [\n  inputDef,\n  outputDef,\n  operationDef,\n  requestBodyDef,\n  contentDef,\n  responseDef,\n  schemaDef,\n  propertyDef,\n  parameterDef,\n  functionParameterDef,\n  functionParametersDef,\n  typeLiteralDef,\n  indexedAccessTypeDef,\n  objectBindingPatternDef,\n  constDef,\n  typeDef,\n  functionDef,\n  arrowFunctionDef,\n  textDef,\n  breakDef,\n  jsxDef,\n  importDef,\n  exportDef,\n  sourceDef,\n  fileDef,\n] satisfies ReadonlyArray<NodeDef>\n","import type { VisitorDepth } from './constants.ts'\nimport { visitorDepths, WALK_CONCURRENCY } from './constants.ts'\nimport type { NodeDef } from './node.ts'\nimport type {\n  ContentNode,\n  InputNode,\n  Node,\n  NodeKind,\n  OperationNode,\n  OutputNode,\n  ParameterNode,\n  PropertyNode,\n  RequestBodyNode,\n  ResponseNode,\n  SchemaNode,\n} from './nodes/index.ts'\nimport { nodeDefs } from './registry.ts'\n\n/**\n * Child node fields per node kind, in traversal order (Babel's `VISITOR_KEYS`).\n * Derived from each definition's `children`.\n */\nconst VISITOR_KEYS = Object.fromEntries(nodeDefs.flatMap((def) => (def.children ? [[def.kind, def.children] as const] : []))) as Partial<\n  Record<NodeKind, ReadonlyArray<string>>\n>\n\n/**\n * Maps a node kind to the matching visitor callback name. Derived from each\n * definition's `visitorKey`.\n */\nconst VISITOR_KEY_BY_KIND = Object.fromEntries(nodeDefs.flatMap((def) => (def.visitorKey ? [[def.kind, def.visitorKey] as const] : []))) as Partial<\n  Record<NodeKind, NonNullable<NodeDef['visitorKey']>>\n>\n\n/**\n * Per-kind builders rerun after children are rebuilt. Derived from each\n * definition's `rebuild` flag.\n */\nconst nodeRebuilders = Object.fromEntries(\n  nodeDefs.flatMap((def) => (def.rebuild ? [[def.kind, def.create as unknown as (node: Node) => Node] as const] : [])),\n) as Partial<Record<NodeKind, (node: Node) => Node>>\n\n/**\n * Creates a small async concurrency limiter.\n *\n * At most `concurrency` tasks are in flight at once. Extra tasks are queued.\n *\n * @example\n * ```ts\n * const limit = createLimit(2)\n * for (const task of [taskA, taskB, taskC]) {\n *   await limit(() => task())\n * }\n * // only 2 tasks run at the same time\n * ```\n */\nfunction createLimit(concurrency: number) {\n  let active = 0\n  const queue: Array<() => void> = []\n\n  function next() {\n    if (active < concurrency && queue.length > 0) {\n      active++\n      queue.shift()!()\n    }\n  }\n\n  return function limit<T>(fn: () => Promise<T> | T): Promise<T> {\n    return new Promise<T>((resolve, reject) => {\n      queue.push(() => {\n        Promise.resolve(fn())\n          .then(resolve, reject)\n          .finally(() => {\n            active--\n            next()\n          })\n      })\n      next()\n    })\n  }\n}\n\ntype LimitFn = ReturnType<typeof createLimit>\n\n/**\n * Ordered mapping of `[NodeType, ParentType]` pairs.\n *\n * `ParentOf` uses this map to find parent types.\n */\ntype ParentNodeMap = [\n  [InputNode, undefined],\n  [OutputNode, undefined],\n  [OperationNode, InputNode],\n  [RequestBodyNode, OperationNode],\n  [ContentNode, RequestBodyNode | ResponseNode],\n  [SchemaNode, InputNode | ContentNode | SchemaNode | PropertyNode | ParameterNode],\n  [PropertyNode, SchemaNode],\n  [ParameterNode, OperationNode],\n  [ResponseNode, OperationNode],\n]\n\n/**\n * Resolves the parent node type for a given AST node type.\n *\n * Visitor context relies on this so `ctx.parent` is typed for each callback.\n *\n * @example\n * ```ts\n * type InputParent = ParentOf<InputNode>\n * // undefined\n * ```\n *\n * @example\n * ```ts\n * type PropertyParent = ParentOf<PropertyNode>\n * // SchemaNode\n * ```\n *\n * @example\n * ```ts\n * type SchemaParent = ParentOf<SchemaNode>\n * // InputNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode\n * ```\n */\nexport type ParentOf<T extends Node, TEntries extends ReadonlyArray<[Node, unknown]> = ParentNodeMap> = TEntries extends [\n  infer TEntry extends [Node, unknown],\n  ...infer TRest extends ReadonlyArray<[Node, unknown]>,\n]\n  ? T extends TEntry[0]\n    ? TEntry[1]\n    : ParentOf<T, TRest>\n  : Node\n\n/**\n * Traversal context passed as the second argument to every visitor callback.\n * `parent` is typed from the current node type.\n *\n * @example\n * ```ts\n * const visitor: Visitor = {\n *   schema(node, { parent }) {\n *     // parent type is narrowed by node kind\n *   },\n * }\n * ```\n */\nexport type VisitorContext<T extends Node = Node> = {\n  /**\n   * Parent node of the currently visited node.\n   * For `InputNode`, this is `undefined`.\n   */\n  parent?: ParentOf<T>\n}\n\n/**\n * Synchronous visitor consumed by `transform`. Each optional callback runs\n * for the matching node type. Return a new node to replace it, or `undefined`\n * to leave it untouched.\n *\n * Plugins typically expose `transformer` so users can supply a `Visitor` that\n * rewrites the AST before printing.\n *\n * @example Prefix every operationId\n * ```ts\n * const visitor: Visitor = {\n *   operation(node) {\n *     return { ...node, operationId: `api_${node.operationId}` }\n *   },\n * }\n * ```\n *\n * @example Strip schema descriptions\n * ```ts\n * const visitor: Visitor = {\n *   schema(node) {\n *     return { ...node, description: undefined }\n *   },\n * }\n * ```\n */\nexport type Visitor = {\n  input?(node: InputNode, context: VisitorContext<InputNode>): undefined | null | InputNode\n  output?(node: OutputNode, context: VisitorContext<OutputNode>): undefined | null | OutputNode\n  operation?(node: OperationNode, context: VisitorContext<OperationNode>): undefined | null | OperationNode\n  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): undefined | null | SchemaNode\n  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): undefined | null | PropertyNode\n  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): undefined | null | ParameterNode\n  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): undefined | null | ResponseNode\n}\n\n/**\n * A visitor callback result that may be sync or async.\n */\ntype MaybePromise<T> = T | Promise<T>\n\n/**\n * Async visitor for `walk`. Synchronous `Visitor` objects are compatible.\n *\n * @example\n * ```ts\n * const visitor: AsyncVisitor = {\n *   async operation(node) {\n *     await Promise.resolve(node.operationId)\n *   },\n * }\n * ```\n */\ntype AsyncVisitor = {\n  input?(node: InputNode, context: VisitorContext<InputNode>): MaybePromise<undefined | null | InputNode>\n  output?(node: OutputNode, context: VisitorContext<OutputNode>): MaybePromise<undefined | null | OutputNode>\n  operation?(node: OperationNode, context: VisitorContext<OperationNode>): MaybePromise<undefined | null | OperationNode>\n  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): MaybePromise<undefined | null | SchemaNode>\n  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): MaybePromise<undefined | null | PropertyNode>\n  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): MaybePromise<undefined | null | ParameterNode>\n  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): MaybePromise<undefined | null | ResponseNode>\n}\n\n/**\n * Visitor used by `collect`.\n *\n * @example\n * ```ts\n * const visitor: CollectVisitor<string> = {\n *   operation(node) {\n *     return node.operationId\n *   },\n * }\n * ```\n */\ntype CollectVisitor<T> = {\n  input?(node: InputNode, context: VisitorContext<InputNode>): T | null | undefined\n  output?(node: OutputNode, context: VisitorContext<OutputNode>): T | null | undefined\n  operation?(node: OperationNode, context: VisitorContext<OperationNode>): T | null | undefined\n  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): T | null | undefined\n  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): T | null | undefined\n  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): T | null | undefined\n  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): T | null | undefined\n}\n\n/**\n * Options for `transform`.\n *\n * @example\n * ```ts\n * const options: TransformOptions = { depth: 'deep', schema: (node) => node }\n * ```\n *\n * @example\n * ```ts\n * // Only transform the current node, not nested children\n * const options: TransformOptions = { depth: 'shallow', schema: (node) => node }\n * ```\n */\nexport type TransformOptions = Visitor & {\n  /**\n   * Traversal depth.\n   * @default 'deep'\n   */\n  depth?: VisitorDepth\n  /**\n   * Internal parent override used during recursion.\n   */\n  parent?: Node\n}\n\n/**\n * Options for `walk`.\n *\n * @example\n * ```ts\n * const options: WalkOptions = { depth: 'deep', concurrency: 10, root: () => {} }\n * ```\n */\nexport type WalkOptions = AsyncVisitor & {\n  /**\n   * Traversal depth.\n   * @default 'deep'\n   */\n  depth?: VisitorDepth\n  /**\n   * Maximum number of sibling nodes visited concurrently.\n   * @default 30\n   */\n  concurrency?: number\n}\n\n/**\n * Options for `collect`.\n *\n * @example\n * ```ts\n * const options: CollectOptions<string> = { depth: 'shallow', schema: () => undefined }\n * ```\n */\nexport type CollectOptions<T> = CollectVisitor<T> & {\n  /**\n   * Traversal depth.\n   * @default 'deep'\n   */\n  depth?: VisitorDepth\n  /**\n   * Internal parent override used during recursion.\n   */\n  parent?: Node\n}\n\nconst visitorKeysByKind = VISITOR_KEYS as Record<string, ReadonlyArray<string> | undefined>\n\n/**\n * Returns `true` when `value` is an AST node (an object carrying a `kind`).\n */\nfunction isNode(value: unknown): value is Node {\n  return typeof value === 'object' && value !== null && 'kind' in value\n}\n\n/**\n * Returns the immediate traversable children of `node` based on {@link VISITOR_KEYS}.\n *\n * `Schema` children are only included when `recurse` is `true`. Shallow mode skips them.\n *\n * @example\n * ```ts\n * const children = getChildren(operationNode, true)\n * // returns parameters, the request body, and responses\n * ```\n */\nfunction* getChildren(node: Node, recurse: boolean): Generator<Node, void, undefined> {\n  if (node.kind === 'Schema' && !recurse) return\n\n  const keys = visitorKeysByKind[node.kind]\n  if (!keys) return\n\n  const record = node as unknown as Record<string, unknown>\n  for (const key of keys) {\n    const value = record[key]\n    if (Array.isArray(value)) {\n      for (const item of value) if (isNode(item)) yield item\n    } else if (isNode(value)) {\n      yield value\n    }\n  }\n}\n\n/**\n * Runs the visitor callback that matches `node.kind` with the traversal\n * context. The result is a replacement node, a collected value, or `undefined`\n * when no callback is registered for the kind.\n *\n * Shared by `walk`, `transform`, and `collectLazy` so node-kind dispatch lives\n * in one place. `TResult` is the caller's expected return: the same node type\n * for `transform`, the collected value type for `collectLazy`, ignored for `walk`.\n */\nfunction applyVisitor<TResult>(node: Node, visitor: Visitor | AsyncVisitor | CollectVisitor<unknown>, parent: Node | undefined): TResult | null | undefined {\n  const key = VISITOR_KEY_BY_KIND[node.kind]\n  if (!key) return undefined\n\n  const fn = visitor[key] as ((node: Node, context: VisitorContext) => TResult | null | undefined) | undefined\n\n  return fn?.(node, { parent })\n}\n\n/**\n * Async depth-first traversal for side effects. Visitor return values are\n * ignored. Use `transform` when you want to rewrite nodes.\n *\n * Sibling nodes at each depth run concurrently up to `options.concurrency`\n * (defaults to `WALK_CONCURRENCY`). Higher values overlap I/O-bound visitor\n * work. Lower values reduce memory pressure.\n *\n * @example Log every operation\n * ```ts\n * await walk(root, {\n *   operation(node) {\n *     console.log(node.operationId)\n *   },\n * })\n * ```\n *\n * @example Only visit the root node\n * ```ts\n * await walk(root, { depth: 'shallow', input: () => {} })\n * ```\n */\nexport async function walk(node: Node, options: WalkOptions): Promise<void> {\n  const recurse = (options.depth ?? visitorDepths.deep) === visitorDepths.deep\n  const limit = createLimit(options.concurrency ?? WALK_CONCURRENCY)\n\n  return _walk(node, options, recurse, limit, undefined)\n}\n\nasync function _walk(node: Node, visitor: AsyncVisitor, recurse: boolean, limit: LimitFn, parent: Node | undefined): Promise<void> {\n  await limit(() => applyVisitor(node, visitor, parent))\n\n  // Visit siblings concurrently and let the shared `limit` cap how many callbacks\n  // run at once. Awaiting each child sequentially here would serialize the whole\n  // traversal and make `concurrency` inert. Every visitor callback would run one\n  // at a time regardless of the limit.\n  const children = Array.from(getChildren(node, recurse))\n  if (children.length === 0) return\n\n  await Promise.all(children.map((child) => _walk(child, visitor, recurse, limit, node)))\n}\n\n/**\n * Synchronous depth-first transform. Each visitor callback can return a\n * replacement node. Returning `undefined` keeps the original.\n *\n * The original tree is never mutated, a new tree is returned. Pass\n * `depth: 'shallow'` to skip recursion into children.\n *\n * @example Prefix every operationId\n * ```ts\n * const next = transform(root, {\n *   operation(node) {\n *     return { ...node, operationId: `prefixed_${node.operationId}` }\n *   },\n * })\n * ```\n *\n * @example Replace only the root node\n * ```ts\n * const next = transform(root, {\n *   depth: 'shallow',\n *   input: (node) => ({ ...node, meta: { ...node.meta, title: 'Rewritten' } }),\n * })\n * ```\n */\nexport function transform(node: InputNode, options: TransformOptions): InputNode\nexport function transform(node: OutputNode, options: TransformOptions): OutputNode\nexport function transform(node: OperationNode, options: TransformOptions): OperationNode\nexport function transform(node: SchemaNode, options: TransformOptions): SchemaNode\nexport function transform(node: PropertyNode, options: TransformOptions): PropertyNode\nexport function transform(node: ParameterNode, options: TransformOptions): ParameterNode\nexport function transform(node: ResponseNode, options: TransformOptions): ResponseNode\nexport function transform(node: Node, options: TransformOptions): Node\nexport function transform(node: Node, options: TransformOptions): Node {\n  const { depth, parent, ...visitor } = options\n  const recurse = (depth ?? visitorDepths.deep) === visitorDepths.deep\n\n  const visited = applyVisitor<Node>(node, visitor, parent) ?? node\n  const rebuilt = transformChildren(visited, options, recurse)\n\n  // Structural sharing: when the visitor and child rebuild both left this node\n  // untouched, return the original reference so callers can detect \"nothing\n  // changed\" by identity and ancestors can avoid reallocating.\n  if (rebuilt === node) return node\n\n  const rebuild = nodeRebuilders[rebuilt.kind]\n  return rebuild ? rebuild(rebuilt) : rebuilt\n}\n\n/**\n * Immutably rebuilds a node's children using {@link VISITOR_KEYS}, transforming\n * each child node and leaving non-node values (e.g. `additionalProperties: true`) intact.\n * `Schema` children are skipped in shallow mode.\n */\nfunction transformChildren(node: Node, options: TransformOptions, recurse: boolean): Node {\n  if (node.kind === 'Schema' && !recurse) return node\n\n  const keys = visitorKeysByKind[node.kind]\n  if (!keys) return node\n\n  const record = node as unknown as Record<string, unknown>\n  const childOptions = { ...options, parent: node }\n  let updates: Record<string, unknown> | undefined\n\n  for (const key of keys) {\n    if (!(key in record)) continue\n    const value = record[key]\n    if (Array.isArray(value)) {\n      let changed = false\n      const mapped = value.map((item) => {\n        if (!isNode(item)) return item\n        const next = transform(item, childOptions)\n        if (next !== item) changed = true\n        return next\n      })\n      if (changed) (updates ??= {})[key] = mapped\n    } else if (isNode(value)) {\n      const next = transform(value, childOptions)\n      if (next !== value) (updates ??= {})[key] = next\n    }\n  }\n\n  return updates ? ({ ...node, ...updates } as Node) : node\n}\n/**\n * Lazy depth-first collection pass. Yields every non-null value returned by\n * the visitor callbacks. Use `collect` for the eager array form.\n *\n * @example Collect every operationId\n * ```ts\n * const ids: string[] = []\n * for (const id of collectLazy<string>(root, {\n *   operation(node) {\n *     return node.operationId\n *   },\n * })) {\n *   ids.push(id)\n * }\n * ```\n */\nexport function* collectLazy<T>(node: Node, options: CollectOptions<T>): Generator<T, void, undefined> {\n  const { depth, parent, ...visitor } = options\n  const recurse = (depth ?? visitorDepths.deep) === visitorDepths.deep\n\n  const v = applyVisitor<T>(node, visitor, parent)\n  if (v != null) yield v\n\n  for (const child of getChildren(node, recurse)) {\n    yield* collectLazy(child, { ...options, parent: node })\n  }\n}\n\n/**\n * Eager depth-first collection pass. Gathers every non-null value the visitor\n * callbacks return into an array.\n *\n * @example Collect every operationId\n * ```ts\n * const ids = collect<string>(root, {\n *   operation(node) {\n *     return node.operationId\n *   },\n * })\n * ```\n */\nexport function collect<T>(node: Node, options: CollectOptions<T>): Array<T> {\n  return Array.from(collectLazy(node, options))\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/ast",
-  "version": "5.0.0-beta.60",
+  "version": "5.0.0-beta.61",
   "description": "Spec-agnostic AST layer for Kubb. Defines the node tree, visitor pattern, factory functions, and type guards used across all code generation plugins.",
   "keywords": [
     "ast",
@@ -35,6 +35,10 @@
       "import": "./dist/factory.js",
       "require": "./dist/factory.cjs"
     },
+    "./macros": {
+      "import": "./dist/macros.js",
+      "require": "./dist/macros.cjs"
+    },
     "./types": {
       "import": "./dist/types.js",
       "require": "./dist/types.cjs"

package/src/defineMacro.ts

@@ -0,0 +1,132 @@
+import type { VisitorDepth } from './constants.ts'
+import type { Node } from './nodes/index.ts'
+import type { Visitor, VisitorContext } from './visitor.ts'
+import { transform } from './visitor.ts'
+
+/**
+ * Visitor callback names a macro can implement, one per traversable node kind.
+ * Mirrors the keys of {@link Visitor}.
+ */
+const macroKeys = ['input', 'output', 'operation', 'schema', 'property', 'parameter', 'response'] as const
+
+type MacroKey = (typeof macroKeys)[number]
+
+/**
+ * Sort weight for an `enforce` hint. `pre` sorts before unmarked items and `post` after, so a plain
+ * list keeps its authored order.
+ */
+function enforceWeight(enforce?: 'pre' | 'post'): number {
+  if (enforce === 'pre') return 0
+  if (enforce === 'post') return 2
+  return 1
+}
+
+/**
+ * A named, composable transform over the Kubb AST. It carries the same per-kind callbacks as a
+ * {@link Visitor} (`schema`, `operation`, …), plus a `name`, an optional `enforce` order, and an
+ * optional `when` gate. Macros run on the shared AST, so the same macro works across every adapter
+ * and output target. Exports follow the `macro<Name>` convention, mirroring plugins (`pluginTs`).
+ */
+export type Macro = Visitor & {
+  /**
+   * Macro identifier, surfaced in diagnostics. Follows the `macro<Name>` convention.
+   */
+  name: string
+  /**
+   * Ordering hint. `pre` macros run before unmarked macros, `post` macros run after.
+   * Ordering within a bucket follows list order.
+   */
+  enforce?: 'pre' | 'post'
+  /**
+   * Gate checked against the current node before any callback runs. When it returns `false`
+   * the macro is skipped for that node.
+   */
+  when?: (node: Node) => boolean
+}
+
+/**
+ * Types a macro for inference and a single construction site, mirroring `definePlugin`.
+ * Adds no runtime behavior.
+ *
+ * @example
+ * ```ts
+ * const macroUntagged = defineMacro({
+ *   name: 'untagged',
+ *   operation(node) {
+ *     return node.tags?.length ? undefined : { ...node, tags: ['untagged'] }
+ *   },
+ * })
+ * ```
+ */
+export function defineMacro(macro: Macro): Macro {
+  return macro
+}
+
+type MacroCallback = (node: Node, context: VisitorContext) => Node | null | undefined
+
+/**
+ * Runs every macro's callback for one node kind in order, chaining the result so each macro sees
+ * the previous macro's output. Returns `undefined` when nothing changed, so `transform` keeps the
+ * original reference (structural sharing).
+ */
+function chain(macros: ReadonlyArray<Macro>, key: MacroKey, node: Node, context: VisitorContext): Node | undefined {
+  let current = node
+
+  for (const macro of macros) {
+    const callback = macro[key] as MacroCallback | undefined
+    if (!callback) continue
+    if (macro.when && !macro.when(current)) continue
+
+    const next = callback(current, context)
+    if (next != null) current = next
+  }
+
+  return current === node ? undefined : current
+}
+
+/**
+ * Folds an ordered list of macros into a single {@link Visitor} that `transform` (and the per-plugin
+ * transform layer in `@kubb/core`) can run. Macros are stable-sorted by `enforce`, then applied
+ * sequentially per node so later macros see earlier output. This differs from a plain visitor, which
+ * has no names, ordering, or composition.
+ *
+ * @example
+ * ```ts
+ * const visitor = composeMacros([macroSimplifyUnion, macroDiscriminatorEnum])
+ * const next = transform(root, visitor)
+ * ```
+ */
+export function composeMacros(macros: ReadonlyArray<Macro>): Visitor {
+  const ordered = [...macros].sort((a, b) => enforceWeight(a.enforce) - enforceWeight(b.enforce))
+
+  const visitor: Visitor = {}
+  for (const key of macroKeys) {
+    if (!ordered.some((macro) => typeof macro[key] === 'function')) continue
+
+    const callback = (node: Node, context: VisitorContext) => chain(ordered, key, node, context)
+    ;(visitor as Record<MacroKey, MacroCallback>)[key] = callback
+  }
+
+  return visitor
+}
+
+/**
+ * Runs a list of macros over a node tree and returns the rewritten tree. Keeps `transform`'s
+ * structural sharing, so an empty or no-op macro list returns the same reference. Pass
+ * `depth: 'shallow'` to rewrite the root node only.
+ *
+ * @example
+ * ```ts
+ * const next = applyMacros(root, [macroIntegerToString])
+ * ```
+ *
+ * @example Apply to the root node only
+ * ```ts
+ * const named = applyMacros(node, [macroEnumName({ parentName, propName, enumSuffix })], { depth: 'shallow' })
+ * ```
+ */
+export function applyMacros<TNode extends Node>(root: TNode, macros: ReadonlyArray<Macro>, options?: { depth?: VisitorDepth }): TNode {
+  if (macros.length === 0) return root
+
+  return transform(root, { ...composeMacros(macros), depth: options?.depth }) as TNode
+}

package/src/index.ts

@@ -1,19 +1,15 @@
 export { httpMethods, schemaTypes } from './constants.ts'
 export { applyDedupe, buildDedupePlan } from './dedupe.ts'
 export { defineSchemaDialect } from './dialect.ts'
-// Node constructors, also published as the `@kubb/ast/factory` subpath, mirroring `ts.factory.createX`.
 export * as factory from './factory.ts'
 export { isHttpOperationNode, narrowSchema } from './guards.ts'
+export { applyMacros, composeMacros, defineMacro } from './defineMacro.ts'
 export { defineNode } from './node.ts'
-export type { NodeDef } from './node.ts'
 export { syncOptionality } from './node.ts'
-// Every node def plus `nodeDefs` in one line, so adding a node never edits this barrel. The visitor
-// tables derived from `nodeDefs` stay internal to `visitor.ts`.
 export * from './registry.ts'
 export { createPrinterFactory, definePrinter } from './printer.ts'
 export { signatureOf } from './signature.ts'
-export { mergeAdjacentObjectsLazy, setDiscriminatorEnum, setEnumName, simplifyUnion } from './transformers.ts'
-export type * from './types.ts'
-// The node/AST helpers in ./utils/ live on the `@kubb/ast/utils` subpath, not the root barrel.
 export { extractStringsFromNodes } from './utils/extractStringsFromNodes.ts'
 export { collect, transform, walk } from './visitor.ts'
+
+export type * from './types.ts'

package/src/macros/index.ts

@@ -0,0 +1,3 @@
+export { macroDiscriminatorEnum } from './macroDiscriminatorEnum.ts'
+export { macroEnumName } from './macroEnumName.ts'
+export { macroSimplifyUnion } from './macroSimplifyUnion.ts'

package/src/macros/macroDiscriminatorEnum.ts

@@ -0,0 +1,44 @@
+import { defineMacro } from '../defineMacro.ts'
+import { narrowSchema } from '../guards.ts'
+import { createProperty } from '../nodes/property.ts'
+import { createSchema } from '../nodes/schema.ts'
+
+/**
+ * Builds a macro that replaces a discriminator property's schema with a string enum of the given
+ * values. Object schemas that lack the property are returned unchanged.
+ *
+ * @example
+ * ```ts
+ * const macro = macroDiscriminatorEnum({ propertyName: 'type', values: ['dog', 'cat'] })
+ * const next = applyMacros(objectSchema, [macro], { depth: 'shallow' })
+ * ```
+ */
+export function macroDiscriminatorEnum({ propertyName, values, enumName }: { propertyName: string; values: Array<string>; enumName?: string }) {
+  return defineMacro({
+    name: 'discriminator-enum',
+    schema(node) {
+      const objectNode = narrowSchema(node, 'object')
+      if (!objectNode?.properties?.length) return undefined
+      if (!objectNode.properties.some((prop) => prop.name === propertyName)) return undefined
+
+      return createSchema({
+        ...objectNode,
+        properties: objectNode.properties.map((prop) => {
+          if (prop.name !== propertyName) return prop
+
+          return createProperty({
+            ...prop,
+            schema: createSchema({
+              type: 'enum',
+              primitive: 'string',
+              enumValues: values,
+              name: enumName,
+              readOnly: prop.schema.readOnly,
+              writeOnly: prop.schema.writeOnly,
+            }),
+          })
+        }),
+      })
+    },
+  })
+}

package/src/macros/macroEnumName.ts

@@ -0,0 +1,25 @@
+import { defineMacro } from '../defineMacro.ts'
+import { narrowSchema } from '../guards.ts'
+import { enumPropName } from '../utils/refs.ts'
+
+/**
+ * Builds a macro that names an inline enum schema from its parent and property name. Boolean enums
+ * are left anonymous; non-enum nodes are returned unchanged.
+ *
+ * @example
+ * ```ts
+ * const macro = macroEnumName({ parentName: 'Pet', propName: 'status', enumSuffix: 'enum' })
+ * const named = applyMacros(propSchema, [macro], { depth: 'shallow' })
+ * ```
+ */
+export function macroEnumName({ parentName, propName, enumSuffix }: { parentName: string | null | undefined; propName: string; enumSuffix: string }) {
+  return defineMacro({
+    name: 'enum-name',
+    schema(node) {
+      const enumNode = narrowSchema(node, 'enum')
+      if (enumNode?.primitive === 'boolean') return { ...node, name: null }
+      if (enumNode) return { ...node, name: enumPropName(parentName, propName, enumSuffix) }
+      return undefined
+    },
+  })
+}

package/src/macros/macroSimplifyUnion.ts

@@ -0,0 +1,50 @@
+import { isScalarPrimitive } from '../constants.ts'
+import { defineMacro } from '../defineMacro.ts'
+import { narrowSchema } from '../guards.ts'
+import type { SchemaNode } from '../nodes/schema.ts'
+
+/**
+ * Removes union members a broader scalar primitive already covers, such as a multi-value string enum
+ * sitting next to a plain `string`. Single-value enums are kept.
+ *
+ * @example
+ * ```ts
+ * const next = applyMacros(unionSchema, [macroSimplifyUnion], { depth: 'shallow' })
+ * ```
+ */
+export const macroSimplifyUnion = defineMacro({
+  name: 'simplify-union',
+  schema(node) {
+    const unionNode = narrowSchema(node, 'union')
+    if (!unionNode?.members?.length) return undefined
+
+    const simplified = simplifyUnionMembers(unionNode.members)
+    if (simplified.length === unionNode.members.length) return undefined
+
+    return { ...unionNode, members: simplified }
+  },
+})
+
+/**
+ * Filters union members, dropping enum members that a broader scalar primitive already covers.
+ */
+function simplifyUnionMembers(members: Array<SchemaNode>): Array<SchemaNode> {
+  const scalarPrimitives = new Set(members.filter((member) => isScalarPrimitive(member.type)).map((m) => m.type))
+  if (!scalarPrimitives.size) return members
+
+  return members.filter((member) => {
+    const enumNode = narrowSchema(member, 'enum')
+    if (!enumNode) return true
+
+    const primitive = enumNode.primitive
+    if (!primitive) return true
+
+    const enumValueCount = enumNode.namedEnumValues?.length ?? enumNode.enumValues?.length ?? 0
+    if (enumValueCount <= 1) return true
+
+    if (scalarPrimitives.has(primitive)) return false
+    if ((primitive === 'integer' || primitive === 'number') && (scalarPrimitives.has('integer') || scalarPrimitives.has('number'))) return false
+
+    return true
+  })
+}

package/src/types.ts

@@ -1,9 +1,10 @@
 export type { DedupeCanonical, DedupeLookups, DedupePlan } from './dedupe.ts'
 export type { SchemaDialect } from './dialect.ts'
-export type { DistributiveOmit } from './node.ts'
+export type { DistributiveOmit, NodeDef } from './node.ts'
 export type { InferSchemaNode, ParserOptions } from './infer.ts'
 export type * from './nodes/index.ts'
 export type { ParentOf, Visitor, VisitorContext } from './visitor.ts'
 export type { Printer, PrinterFactoryOptions, PrinterPartial } from './printer.ts'
 export type { OperationParamsResolver } from './utils/operationParams.ts'
 export type { UserFileNode } from './factory.ts'
+export type { Macro } from './defineMacro.ts'

package/src/utils/index.ts

@@ -1,8 +1,8 @@
 export { isValidVarName } from '@internals/utils'
 export { buildJSDoc, buildList, buildObject, objectKey } from './codegen.ts'
 export { extractStringsFromNodes } from './extractStringsFromNodes.ts'
-export { childName, enumPropName, extractRefName, isStringType, resolveGroupType, resolveRefName } from './refs.ts'
-export { syncSchemaRef } from '../transformers.ts'
+export { childName, enumPropName, extractRefName, isStringType, resolveGroupType, resolveRefName, syncSchemaRef } from './refs.ts'
+export { mergeAdjacentObjectsLazy } from './schemaMerge.ts'
 export { getNestedAccessor, jsStringEscape, stringify, stringifyObject, toRegExpString, trimQuotes } from './strings.ts'
 export { collectUsedSchemaNames, containsCircularRef, findCircularSchemas } from './schemaGraph.ts'
 export { lazyGetter, mapSchemaItems, mapSchemaMembers, mapSchemaProperties } from './schemaTraversal.ts'

package/src/utils/refs.ts

@@ -1,7 +1,7 @@
 import { pascalCase } from '@internals/utils'
 import { narrowSchema } from '../guards.ts'
 import type { OperationNode, ParameterNode, SchemaNode } from '../nodes/index.ts'
-import type { SchemaType } from '../nodes/schema.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)
@@ -63,6 +63,32 @@ export function enumPropName(parentName: string | null | undefined, propName: st
   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.
  *

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

package/dist/extractStringsFromNodes-WMYJ8nQL.d.ts

@@ -1,82 +0,0 @@
-import { n as __name } from "./chunk-CNktS9qV.js";
-import { Pt as CodeNode, _t as SchemaNode } from "./index-BzjwdK2M.js";
-
-//#region src/transformers.d.ts
-/**
- * Replaces a discriminator property's schema with a string enum of allowed values.
- *
- * If `node` is not an object schema, or if the property does not exist, the input
- * node is returned as-is.
- *
- * @example
- * ```ts
- * const schema = createSchema({
- *   type: 'object',
- *   properties: [createProperty({ name: 'type', required: true, schema: createSchema({ type: 'string' }) })],
- * })
- * const result = setDiscriminatorEnum({ node: schema, propertyName: 'type', values: ['dog', 'cat'] })
- * ```
- */
-declare function setDiscriminatorEnum({
-  node,
-  propertyName,
-  values,
-  enumName
-}: {
-  node: SchemaNode;
-  propertyName: string;
-  values: Array<string>;
-  enumName?: string;
-}): SchemaNode;
-/**
- * Merges adjacent anonymous object members into a single anonymous object member.
- *
- * @example
- * ```ts
- * const merged = mergeAdjacentObjects([
- *   createSchema({ type: 'object', properties: [createProperty({ name: 'a', schema: createSchema({ type: 'string' }) })] }),
- *   createSchema({ type: 'object', properties: [createProperty({ name: 'b', schema: createSchema({ type: 'number' }) })] }),
- * ])
- * ```
- */
-declare function mergeAdjacentObjectsLazy(members: Iterable<SchemaNode>): Generator<SchemaNode, void, undefined>;
-/**
- * Removes enum members that are covered by broader scalar primitives in the same union.
- *
- * @example
- * ```ts
- * const simplified = simplifyUnion([
- *   createSchema({ type: 'enum', primitive: 'string', enumValues: ['active'] }),
- *   createSchema({ type: 'string' }),
- * ])
- * // keeps only string member
- * ```
- */
-declare function simplifyUnion(members: Array<SchemaNode>): Array<SchemaNode>;
-declare function setEnumName(propNode: SchemaNode, parentName: string | null | undefined, propName: string, enumSuffix: string): SchemaNode;
-/**
- * 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
- * // Ref with description override
- * const ref = createSchema({ type: 'ref', ref: '#/components/schemas/Pet', description: 'A cute pet' })
- * const merged = syncSchemaRef(ref)  // merges with resolved Pet schema
- * ```
- */
-declare function syncSchemaRef(node: SchemaNode): SchemaNode;
-//#endregion
-//#region src/utils/extractStringsFromNodes.d.ts
-/**
- * Extracts all string content from a `CodeNode` tree recursively.
- *
- * Collects text node values, identifier references in string fields (`params`, `generics`, `returnType`, `type`),
- * and nested node content. Used to build the full source string for import filtering.
- */
-declare function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): string;
-//#endregion
-export { simplifyUnion as a, setEnumName as i, mergeAdjacentObjectsLazy as n, syncSchemaRef as o, setDiscriminatorEnum as r, extractStringsFromNodes as t };
-//# sourceMappingURL=extractStringsFromNodes-WMYJ8nQL.d.ts.map