@kubb/ast 5.0.0-beta.62 → 5.0.0-beta.63

package/src/nodes/operation.ts

@@ -4,6 +4,9 @@ import type { ParameterNode } from './parameter.ts'
 import { createRequestBody, type RequestBodyNode } from './requestBody.ts'
 import type { ResponseNode } from './response.ts'
 
+/**
+ * HTTP method an operation responds to.
+ */
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE'
 
 /**

package/src/nodes/parameter.ts

@@ -1,4 +1,5 @@
 import { defineNode } from '../defineNode.ts'
+import { optionality } from '../optionality.ts'
 import type { BaseNode } from './base.ts'
 import type { SchemaNode } from './schema.ts'
 
@@ -41,15 +42,14 @@ export type ParameterNode = BaseNode & {
 type UserParameterNode = Pick<ParameterNode, 'name' | 'in' | 'schema'> & Partial<Omit<ParameterNode, 'kind' | 'name' | 'in' | 'schema'>>
 
 /**
- * Definition for the {@link ParameterNode}. `required` defaults to `false`. When a `dialect` is
- * passed to `create`, the schema's `optional`/`nullish` flags are derived through its
- * `optionality`; without one, the schema is left as-is.
+ * Definition for the {@link ParameterNode}. `required` defaults to `false`, and the schema's
+ * `optional`/`nullish` flags are derived from it through {@link optionality}.
  */
 export const parameterDef = defineNode<ParameterNode, UserParameterNode>({
   kind: 'Parameter',
-  build: (props, dialect) => {
+  build: (props) => {
     const required = props.required ?? false
-    return { ...props, required, schema: dialect ? dialect.schema.optionality(props.schema, required) : props.schema }
+    return { ...props, required, schema: optionality(props.schema, required) }
   },
   children: ['schema'],
   visitorKey: 'parameter',

package/src/nodes/property.ts

@@ -1,4 +1,5 @@
 import { defineNode } from '../defineNode.ts'
+import { optionality } from '../optionality.ts'
 import type { BaseNode } from './base.ts'
 import type { SchemaNode } from './schema.ts'
 
@@ -37,15 +38,14 @@ export type PropertyNode = BaseNode & {
 export type UserPropertyNode = Pick<PropertyNode, 'name' | 'schema'> & Partial<Omit<PropertyNode, 'kind' | 'name' | 'schema'>>
 
 /**
- * Definition for the {@link PropertyNode}. `required` defaults to `false`. When a `dialect` is
- * passed to `create`, the schema's `optional`/`nullish` flags are derived through its
- * `optionality`; without one, the schema is left as-is.
+ * Definition for the {@link PropertyNode}. `required` defaults to `false`, and the schema's
+ * `optional`/`nullish` flags are derived from it through {@link optionality}.
  */
 export const propertyDef = defineNode<PropertyNode, UserPropertyNode>({
   kind: 'Property',
-  build: (props, dialect) => {
+  build: (props) => {
     const required = props.required ?? false
-    return { ...props, required, schema: dialect ? dialect.schema.optionality(props.schema, required) : props.schema }
+    return { ...props, required, schema: optionality(props.schema, required) }
   },
   children: ['schema'],
   visitorKey: 'property',

package/src/nodes/schema.ts

@@ -107,7 +107,7 @@ type SchemaNodeBase = BaseNode & {
   /**
    * Schema name for named definitions (for example, `"Pet"`).
    * Inline schemas omit this field.
-   * `null` means kubb has processed this and determined there is no applicable name.
+   * `null` means Kubb has processed this and determined there is no applicable name.
    * `undefined` means the name has not been set yet.
    */
   name?: string | null
@@ -190,7 +190,7 @@ export type ObjectSchemaNode = SchemaNodeBase & {
   /**
    * Additional object properties behavior:
    * - `true`: allow any value
-   * - `false`: reject unknown properties (maps to `.strict()` in Zod)
+   * - `false`: reject unknown properties
    * - `SchemaNode`: allow values that match that schema
    * - `undefined`: no additional properties constraint (open object)
    */
@@ -669,8 +669,8 @@ type CreateSchemaOutput<T extends CreateSchemaInput> = InferSchemaNode<T> & {
 
 /**
  * Maps schema `type` to its underlying `primitive`.
- * Primitive types map to themselves. Special string formats map to `'string'`.
- * Complex types (`ref`, `enum`, `union`, `intersection`, `tuple`, `blob`) are left unset.
+ * Primitive types map to themselves and special string formats map to `'string'`.
+ * Any type not listed here (such as `ref`, `enum`, `union`, `intersection`, `tuple`, `ipv4`, `ipv6`, `blob`) has no `primitive`.
  */
 const TYPE_TO_PRIMITIVE: Partial<Record<SchemaNode['type'], PrimitiveSchemaType>> = {
   string: 'string',

package/src/optionality.ts

@@ -0,0 +1,15 @@
+import type { SchemaNode } from './nodes/schema.ts'
+
+/**
+ * Generic JSON Schema optionality: a non-required field is optional, and a
+ * non-required nullable field is nullish.
+ */
+export function optionality(schema: SchemaNode, required: boolean): SchemaNode {
+  const nullable = schema.nullable ?? false
+
+  return {
+    ...schema,
+    optional: !required && !nullable ? true : undefined,
+    nullish: !required && nullable ? true : undefined,
+  }
+}

package/src/types.ts

@@ -1,5 +1,4 @@
-export type { DedupeCanonical, DedupeLookups, DedupePlan } from './dedupe.ts'
-export type { Dialect, SchemaDialect } from './dialect.ts'
+export type { Dedupe, Dialect, SchemaDialect } from './dialect.ts'
 export type { DistributiveOmit, NodeDef } from './defineNode.ts'
 export type { InferSchemaNode, ParserOptions } from './infer.ts'
 export type * from './nodes/index.ts'

package/src/utils/codegen.ts

@@ -2,8 +2,8 @@ import { isIdentifier, singleQuote } from '@internals/utils'
 import { INDENT } from '../constants.ts'
 
 /**
- * Builds a JSDoc comment block from an array of lines, returning `fallback` when there are no
- * comments so callers always get a usable string.
+ * Builds a JSDoc comment block from an array of lines. Returns `fallback` when there are no
+ * comments.
  *
  * @example
  * ```ts
@@ -65,9 +65,8 @@ export function objectKey(name: string): string {
 
 /**
  * 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.
+ * level and closing the brace at column zero. Entries that are themselves multi-line objects indent
+ * cumulatively. Each entry ends with a trailing comma to match the formatter's multi-line style.
  *
  * @example
  * ```ts
@@ -85,8 +84,8 @@ export function buildObject(entries: Array<string>): string {
 /**
  * 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.
+ * one level with a trailing comma and the closing bracket at column zero. Used for member lists such
+ * as `z.union([…])` and `z.array([…])`.
  *
  * @example
  * ```ts

package/src/utils/fileMerge.ts

@@ -1,9 +1,8 @@
 /**
- * File-member merging. `combineImports`, `combineExports`, and `combineSources` deduplicate and sort
- * the import, export, and source entries of one file, and drop imports nothing references. This works
- * on a file's members, not on schema content.
- *
- * For collapsing duplicate schema shapes by structural signature, see `dedupe.ts`.
+ * File-member merging. `combineImports` and `combineExports` deduplicate and sort the import and
+ * export entries of one file, while `combineSources` deduplicates source entries in original order.
+ * `combineImports` also drops imports nothing references. This works on a file's members, not on
+ * schema content.
  */
 import type { ExportNode, ImportNode, SourceNode } from '../nodes/index.ts'
 import { extractStringsFromNodes } from './extractStringsFromNodes.ts'
@@ -38,9 +37,9 @@ function sortKey(node: { name?: string | Array<unknown> | null; isTypeOnly?: boo
 }
 
 /**
- * Deduplicates and merges `SourceNode` objects by `name + isExportable + isTypeOnly`.
- *
- * Unnamed sources are deduplicated by object reference. Returns a deduplicated array in original order.
+ * Deduplicates `SourceNode` objects by `name + isExportable + isTypeOnly`, keeping the first of each
+ * key. Unnamed sources fall back to their extracted node strings as the name part of the key. Returns
+ * the deduplicated array in original order.
  */
 export function combineSources(sources: Array<SourceNode>): Array<SourceNode> {
   const seen = new Map<string, SourceNode>()

package/src/utils/operationParams.ts

@@ -3,13 +3,6 @@ import { createFunctionParameter, createFunctionParameters, createIndexedAccessT
 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) => {
@@ -19,6 +12,13 @@ const caseParamsMemo = memoize(new WeakMap<Array<ParameterNode>, (casing: string
   ),
 )
 
+/**
+ * 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.
+ */
 export function caseParams(params: Array<ParameterNode>, casing: 'camelcase' | undefined): Array<ParameterNode> {
   if (!casing) return params
   return caseParamsMemo(params)(casing)
@@ -229,7 +229,7 @@ export function createOperationParams(node: OperationNode, options: CreateOperat
   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.
+  // typeWrapper takes a type-name string, so only plain references are wrapped.
   // TypeLiteral and IndexedAccessType expressions are pre-resolved and pass through unchanged.
   const wrapTypeExpression = (type: TypeExpression): TypeExpression => (typeof type === 'string' ? wrapType(type) : type)
 

package/src/utils/refs.ts

@@ -10,24 +10,20 @@ const plainStringTypes = new Set<SchemaType>(['string', 'uuid', 'email', 'url',
  * Returns the last path segment of a reference string.
  *
  * @example
- * ```ts
- * extractRefName('#/components/schemas/Pet') // 'Pet'
- * ```
+ * `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`.
+ * Resolves the schema name of a ref node. Uses the last segment of `ref` when set, otherwise falls
+ * back to `name` then 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'
- * ```
+ * `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
@@ -40,11 +36,11 @@ export function resolveRefName(node: SchemaNode | undefined): string | 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
- * ```
+ * @example Nested under a parent
+ * `childName('Order', 'shipping_address') // 'OrderShippingAddress'`
+ *
+ * @example No parent
+ * `childName(undefined, 'params') // null`
  */
 export function childName(parentName: string | null | undefined, propName: string): string | null {
   return parentName ? pascalCase([parentName, propName].join(' ')) : null
@@ -55,9 +51,7 @@ export function childName(parentName: string | null | undefined, propName: strin
  * empty parts.
  *
  * @example
- * ```ts
- * enumPropName('Order', 'status', 'enum') // 'OrderStatusEnum'
- * ```
+ * `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(' '))
@@ -66,8 +60,10 @@ export function enumPropName(parentName: string | null | undefined, propName: st
 /**
  * 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.
+ * Every field set on the ref node except `kind`, `type`, `name`, `ref`, and `schema` overrides the
+ * same field in the resolved `node.schema` (for example `description`, `nullable`, `readOnly`,
+ * `deprecated`). Fields left `undefined` on the ref do not shadow the resolved schema. Non-ref
+ * nodes and refs without a resolved `schema` are returned unchanged.
  *
  * @example
  * ```ts

package/src/utils/schemaGraph.ts

@@ -4,23 +4,7 @@ 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)
- * }
- * ```
+ * Memoized inner pass that walks a single node and returns the names of every schema it references.
  */
 const collectSchemaRefs = memoize(new WeakMap<SchemaNode, ReadonlySet<string>>(), (node: SchemaNode): ReadonlySet<string> => {
   const refs = new Set<string>()
@@ -35,31 +19,35 @@ const collectSchemaRefs = memoize(new WeakMap<SchemaNode, ReadonlySet<string>>()
   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.
+ * Collects the names of every ref found anywhere inside a node's own subtree.
  *
- * 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.
+ * Each ref contributes its name only, so the schema it points to is never traversed here. Pass `out`
+ * to accumulate names from several nodes into one set.
  *
- * Pair it with `include` filters so schemas reachable only from excluded operations stay ungenerated.
- *
- * @example Only generate schemas referenced by included operations
+ * @example Collect refs from a single schema
  * ```ts
- * const includedOps = operations.filter((op) => resolver.resolveOptions(op, { options, include }) !== null)
- * const allowed = collectUsedSchemaNames(includedOps, schemas)
+ * 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) {
- *   if (schema.name && !allowed.has(schema.name)) continue
- *   // … generate schema
+ *   collectReferencedSchemaNames(schema, out)
  * }
  * ```
  */
+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
+}
+
+/**
+ * Memoized two-level cache keyed first on the operations array, then on the schemas array.
+ */
 const collectUsedSchemaNamesMemo = memoize(new WeakMap<ReadonlyArray<OperationNode>, (schemas: ReadonlyArray<SchemaNode>) => Set<string>>(), (ops) =>
   memoize(new WeakMap<ReadonlyArray<SchemaNode>, Set<string>>(), (schemas) => computeUsedSchemaNames(ops, schemas)),
 )
@@ -92,6 +80,26 @@ function computeUsedSchemaNames(operations: ReadonlyArray<OperationNode>, schema
   return result
 }
 
+/**
+ * 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. Once a name is added to the result it is not revisited, so
+ * reference cycles terminate.
+ *
+ * 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
+ * }
+ * ```
+ */
 export function collectUsedSchemaNames(operations: ReadonlyArray<OperationNode>, schemas: ReadonlyArray<SchemaNode>): Set<string> {
   return collectUsedSchemaNamesMemo(operations)(schemas)
 }

package/src/utils/schemaMerge.ts

@@ -3,8 +3,8 @@ 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).
+ * run and pass through unchanged. The merge follows member order, so callers control which members
+ * combine by where they place them in the sequence.
  *
  * @example
  * ```ts

package/src/visitor.ts

@@ -111,7 +111,7 @@ type ParentNodeMap = [
  * @example
  * ```ts
  * type SchemaParent = ParentOf<SchemaNode>
- * // InputNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode
+ * // InputNode | ContentNode | SchemaNode | PropertyNode | ParameterNode
  * ```
  */
 export type ParentOf<T extends Node, TEntries extends ReadonlyArray<[Node, unknown]> = ParentNodeMap> = TEntries extends [

package/dist/defineMacro-BryDiuQl.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"defineMacro-BryDiuQl.cjs","names":["visitorKeys","transform"],"sources":["../src/defineMacro.ts"],"sourcesContent":["import type { VisitorDepth } from './constants.ts'\nimport type { VisitorKey } from './defineNode.ts'\nimport { visitorKeys } from './defineNode.ts'\nimport type { Node } from './nodes/index.ts'\nimport type { Visitor, VisitorContext } from './visitor.ts'\nimport { transform } from './visitor.ts'\n\n/**\n * Ordering hint shared by macros and plugins. `pre` runs before unmarked items, `post` after,\n * and `undefined` keeps declaration order.\n */\nexport type Enforce = 'pre' | 'post'\n\n/**\n * Sort weight for an `enforce` hint. `pre` sorts before unmarked items and `post` after, so a plain\n * list keeps its authored order.\n */\nfunction enforceWeight(enforce?: Enforce): number {\n  if (enforce === 'pre') return 0\n  if (enforce === 'post') return 2\n  return 1\n}\n\n/**\n * A named, composable transform over the Kubb AST. It carries the same per-kind callbacks as a\n * {@link Visitor} (`schema`, `operation`, …), plus a `name`, an optional `enforce` order, and an\n * optional `when` gate. Macros run on the shared AST, so the same macro works across every adapter\n * and output target. Exports follow the `macro<Name>` convention, mirroring plugins (`pluginTs`).\n */\nexport type Macro = Visitor & {\n  /**\n   * Macro identifier, surfaced in diagnostics. Follows the `macro<Name>` convention.\n   */\n  name: string\n  /**\n   * Ordering hint. `pre` macros run before unmarked macros, `post` macros run after.\n   * Ordering within a bucket follows list order.\n   */\n  enforce?: Enforce\n  /**\n   * Gate checked against the current node before any callback runs. When it returns `false`\n   * the macro is skipped for that node.\n   */\n  when?: (node: Node) => boolean\n}\n\n/**\n * Types a macro for inference and a single construction site, mirroring `definePlugin`.\n * Adds no runtime behavior.\n *\n * @example\n * ```ts\n * const macroUntagged = defineMacro({\n *   name: 'untagged',\n *   operation(node) {\n *     return node.tags?.length ? undefined : { ...node, tags: ['untagged'] }\n *   },\n * })\n * ```\n */\nexport function defineMacro(macro: Macro): Macro {\n  return macro\n}\n\ntype MacroCallback = (node: Node, context: VisitorContext) => Node | null | undefined\n\ntype ChainProps = {\n  macros: ReadonlyArray<Macro>\n  key: VisitorKey\n  node: Node\n  context: VisitorContext\n}\n\n/**\n * Runs every macro's callback for one node kind in order, chaining the result so each macro sees\n * the previous macro's output. Returns `undefined` when nothing changed, so `transform` keeps the\n * original reference (structural sharing).\n */\nfunction chain({ macros, key, node, context }: ChainProps): Node | undefined {\n  let current = node\n\n  for (const macro of macros) {\n    const callback = macro[key] as MacroCallback | undefined\n    if (!callback) continue\n    if (macro.when && !macro.when(current)) continue\n\n    const next = callback(current, context)\n    if (next != null) current = next\n  }\n\n  return current === node ? undefined : current\n}\n\n/**\n * Folds an ordered list of macros into a single {@link Visitor} that `transform` (and the per-plugin\n * transform layer in `@kubb/core`) can run. Macros are stable-sorted by `enforce`, then applied\n * sequentially per node so later macros see earlier output. This differs from a plain visitor, which\n * has no names, ordering, or composition.\n *\n * @example\n * ```ts\n * const visitor = composeMacros([macroSimplifyUnion, macroDiscriminatorEnum])\n * const next = transform(root, visitor)\n * ```\n */\nexport function composeMacros(macros: ReadonlyArray<Macro>): Visitor {\n  const ordered = [...macros].sort((a, b) => enforceWeight(a.enforce) - enforceWeight(b.enforce))\n\n  const visitor: Visitor = {}\n  for (const key of visitorKeys) {\n    if (!ordered.some((macro) => typeof macro[key] === 'function')) continue\n\n    const callback = (node: Node, context: VisitorContext) => chain({ macros: ordered, key, node, context })\n    ;(visitor as Record<VisitorKey, MacroCallback>)[key] = callback\n  }\n\n  return visitor\n}\n\n/**\n * Runs a list of macros over a node tree and returns the rewritten tree. Keeps `transform`'s\n * structural sharing, so an empty or no-op macro list returns the same reference. Pass\n * `depth: 'shallow'` to rewrite the root node only.\n *\n * @example\n * ```ts\n * const next = applyMacros(root, [macroIntegerToString])\n * ```\n *\n * @example Apply to the root node only\n * ```ts\n * const named = applyMacros(node, [macroEnumName({ parentName, propName, enumSuffix })], { depth: 'shallow' })\n * ```\n */\nexport function applyMacros<TNode extends Node>(root: TNode, macros: ReadonlyArray<Macro>, options?: { depth?: VisitorDepth }): TNode {\n  if (macros.length === 0) return root\n\n  return transform(root, { ...composeMacros(macros), ...options }) as TNode\n}\n"],"mappings":";;;;;;;AAiBA,SAAS,cAAc,SAA2B;CAChD,IAAI,YAAY,OAAO,OAAO;CAC9B,IAAI,YAAY,QAAQ,OAAO;CAC/B,OAAO;AACT;;;;;;;;;;;;;;;AAuCA,SAAgB,YAAY,OAAqB;CAC/C,OAAO;AACT;;;;;;AAgBA,SAAS,MAAM,EAAE,QAAQ,KAAK,MAAM,WAAyC;CAC3E,IAAI,UAAU;CAEd,KAAK,MAAM,SAAS,QAAQ;EAC1B,MAAM,WAAW,MAAM;EACvB,IAAI,CAAC,UAAU;EACf,IAAI,MAAM,QAAQ,CAAC,MAAM,KAAK,OAAO,GAAG;EAExC,MAAM,OAAO,SAAS,SAAS,OAAO;EACtC,IAAI,QAAQ,MAAM,UAAU;CAC9B;CAEA,OAAO,YAAY,OAAO,KAAA,IAAY;AACxC;;;;;;;;;;;;;AAcA,SAAgB,cAAc,QAAuC;CACnE,MAAM,UAAU,CAAC,GAAG,MAAM,CAAC,CAAC,MAAM,GAAG,MAAM,cAAc,EAAE,OAAO,IAAI,cAAc,EAAE,OAAO,CAAC;CAE9F,MAAM,UAAmB,CAAC;CAC1B,KAAK,MAAM,OAAOA,iBAAAA,aAAa;EAC7B,IAAI,CAAC,QAAQ,MAAM,UAAU,OAAO,MAAM,SAAS,UAAU,GAAG;EAEhE,MAAM,YAAY,MAAY,YAA4B,MAAM;GAAE,QAAQ;GAAS;GAAK;GAAM;EAAQ,CAAC;EACtG,QAA+C,OAAO;CACzD;CAEA,OAAO;AACT;;;;;;;;;;;;;;;;AAiBA,SAAgB,YAAgC,MAAa,QAA8B,SAA2C;CACpI,IAAI,OAAO,WAAW,GAAG,OAAO;CAEhC,OAAOC,gBAAAA,UAAU,MAAM;EAAE,GAAG,cAAc,MAAM;EAAG,GAAG;CAAQ,CAAC;AACjE"}

package/dist/defineMacro-CNkUpxia.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"defineMacro-CNkUpxia.js","names":[],"sources":["../src/defineMacro.ts"],"sourcesContent":["import type { VisitorDepth } from './constants.ts'\nimport type { VisitorKey } from './defineNode.ts'\nimport { visitorKeys } from './defineNode.ts'\nimport type { Node } from './nodes/index.ts'\nimport type { Visitor, VisitorContext } from './visitor.ts'\nimport { transform } from './visitor.ts'\n\n/**\n * Ordering hint shared by macros and plugins. `pre` runs before unmarked items, `post` after,\n * and `undefined` keeps declaration order.\n */\nexport type Enforce = 'pre' | 'post'\n\n/**\n * Sort weight for an `enforce` hint. `pre` sorts before unmarked items and `post` after, so a plain\n * list keeps its authored order.\n */\nfunction enforceWeight(enforce?: Enforce): number {\n  if (enforce === 'pre') return 0\n  if (enforce === 'post') return 2\n  return 1\n}\n\n/**\n * A named, composable transform over the Kubb AST. It carries the same per-kind callbacks as a\n * {@link Visitor} (`schema`, `operation`, …), plus a `name`, an optional `enforce` order, and an\n * optional `when` gate. Macros run on the shared AST, so the same macro works across every adapter\n * and output target. Exports follow the `macro<Name>` convention, mirroring plugins (`pluginTs`).\n */\nexport type Macro = Visitor & {\n  /**\n   * Macro identifier, surfaced in diagnostics. Follows the `macro<Name>` convention.\n   */\n  name: string\n  /**\n   * Ordering hint. `pre` macros run before unmarked macros, `post` macros run after.\n   * Ordering within a bucket follows list order.\n   */\n  enforce?: Enforce\n  /**\n   * Gate checked against the current node before any callback runs. When it returns `false`\n   * the macro is skipped for that node.\n   */\n  when?: (node: Node) => boolean\n}\n\n/**\n * Types a macro for inference and a single construction site, mirroring `definePlugin`.\n * Adds no runtime behavior.\n *\n * @example\n * ```ts\n * const macroUntagged = defineMacro({\n *   name: 'untagged',\n *   operation(node) {\n *     return node.tags?.length ? undefined : { ...node, tags: ['untagged'] }\n *   },\n * })\n * ```\n */\nexport function defineMacro(macro: Macro): Macro {\n  return macro\n}\n\ntype MacroCallback = (node: Node, context: VisitorContext) => Node | null | undefined\n\ntype ChainProps = {\n  macros: ReadonlyArray<Macro>\n  key: VisitorKey\n  node: Node\n  context: VisitorContext\n}\n\n/**\n * Runs every macro's callback for one node kind in order, chaining the result so each macro sees\n * the previous macro's output. Returns `undefined` when nothing changed, so `transform` keeps the\n * original reference (structural sharing).\n */\nfunction chain({ macros, key, node, context }: ChainProps): Node | undefined {\n  let current = node\n\n  for (const macro of macros) {\n    const callback = macro[key] as MacroCallback | undefined\n    if (!callback) continue\n    if (macro.when && !macro.when(current)) continue\n\n    const next = callback(current, context)\n    if (next != null) current = next\n  }\n\n  return current === node ? undefined : current\n}\n\n/**\n * Folds an ordered list of macros into a single {@link Visitor} that `transform` (and the per-plugin\n * transform layer in `@kubb/core`) can run. Macros are stable-sorted by `enforce`, then applied\n * sequentially per node so later macros see earlier output. This differs from a plain visitor, which\n * has no names, ordering, or composition.\n *\n * @example\n * ```ts\n * const visitor = composeMacros([macroSimplifyUnion, macroDiscriminatorEnum])\n * const next = transform(root, visitor)\n * ```\n */\nexport function composeMacros(macros: ReadonlyArray<Macro>): Visitor {\n  const ordered = [...macros].sort((a, b) => enforceWeight(a.enforce) - enforceWeight(b.enforce))\n\n  const visitor: Visitor = {}\n  for (const key of visitorKeys) {\n    if (!ordered.some((macro) => typeof macro[key] === 'function')) continue\n\n    const callback = (node: Node, context: VisitorContext) => chain({ macros: ordered, key, node, context })\n    ;(visitor as Record<VisitorKey, MacroCallback>)[key] = callback\n  }\n\n  return visitor\n}\n\n/**\n * Runs a list of macros over a node tree and returns the rewritten tree. Keeps `transform`'s\n * structural sharing, so an empty or no-op macro list returns the same reference. Pass\n * `depth: 'shallow'` to rewrite the root node only.\n *\n * @example\n * ```ts\n * const next = applyMacros(root, [macroIntegerToString])\n * ```\n *\n * @example Apply to the root node only\n * ```ts\n * const named = applyMacros(node, [macroEnumName({ parentName, propName, enumSuffix })], { depth: 'shallow' })\n * ```\n */\nexport function applyMacros<TNode extends Node>(root: TNode, macros: ReadonlyArray<Macro>, options?: { depth?: VisitorDepth }): TNode {\n  if (macros.length === 0) return root\n\n  return transform(root, { ...composeMacros(macros), ...options }) as TNode\n}\n"],"mappings":";;;;;;;;AAiBA,SAAS,cAAc,SAA2B;CAChD,IAAI,YAAY,OAAO,OAAO;CAC9B,IAAI,YAAY,QAAQ,OAAO;CAC/B,OAAO;AACT;;;;;;;;;;;;;;;AAuCA,SAAgB,YAAY,OAAqB;CAC/C,OAAO;AACT;;;;;;AAgBA,SAAS,MAAM,EAAE,QAAQ,KAAK,MAAM,WAAyC;CAC3E,IAAI,UAAU;CAEd,KAAK,MAAM,SAAS,QAAQ;EAC1B,MAAM,WAAW,MAAM;EACvB,IAAI,CAAC,UAAU;EACf,IAAI,MAAM,QAAQ,CAAC,MAAM,KAAK,OAAO,GAAG;EAExC,MAAM,OAAO,SAAS,SAAS,OAAO;EACtC,IAAI,QAAQ,MAAM,UAAU;CAC9B;CAEA,OAAO,YAAY,OAAO,KAAA,IAAY;AACxC;;;;;;;;;;;;;AAcA,SAAgB,cAAc,QAAuC;CACnE,MAAM,UAAU,CAAC,GAAG,MAAM,CAAC,CAAC,MAAM,GAAG,MAAM,cAAc,EAAE,OAAO,IAAI,cAAc,EAAE,OAAO,CAAC;CAE9F,MAAM,UAAmB,CAAC;CAC1B,KAAK,MAAM,OAAO,aAAa;EAC7B,IAAI,CAAC,QAAQ,MAAM,UAAU,OAAO,MAAM,SAAS,UAAU,GAAG;EAEhE,MAAM,YAAY,MAAY,YAA4B,MAAM;GAAE,QAAQ;GAAS;GAAK;GAAM;EAAQ,CAAC;EACtG,QAA+C,OAAO;CACzD;CAEA,OAAO;AACT;;;;;;;;;;;;;;;;AAiBA,SAAgB,YAAgC,MAAa,QAA8B,SAA2C;CACpI,IAAI,OAAO,WAAW,GAAG,OAAO;CAEhC,OAAO,UAAU,MAAM;EAAE,GAAG,cAAc,MAAM;EAAG,GAAG;CAAQ,CAAC;AACjE"}