@kubb/ast 5.0.0-alpha.4 → 5.0.0-alpha.40

package/src/printer.ts

@@ -1,14 +1,24 @@
 import type { SchemaNode, SchemaNodeByType, SchemaType } from './nodes/index.ts'
 
 /**
- * Handler context for `definePrinter` — mirrors `PluginContext` from `@kubb/core`.
- * Available as `this` inside each node handler.
+ * Runtime context passed as `this` to printer handlers.
+ *
+ * `this.transform` dispatches to node-level handlers from `nodes`.
+ *
+ * @example
+ * ```ts
+ * const context: PrinterHandlerContext<string, {}> = {
+ *   options: {},
+ *   transform: () => 'value',
+ * }
+ * ```
  */
 export type PrinterHandlerContext<TOutput, TOptions extends object> = {
   /**
-   * Recursively print a nested `SchemaNode`.
+   * Recursively transform a nested `SchemaNode` to `TOutput` using the node-level handlers.
+   * Use `this.transform` inside `nodes` handlers and inside the `print` override.
    */
-  print: (node: SchemaNode) => TOutput | null | undefined
+  transform: (node: SchemaNode) => TOutput | null | undefined
   /**
    * Options for this printer instance.
    */
@@ -16,8 +26,16 @@ export type PrinterHandlerContext<TOutput, TOptions extends object> = {
 }
 
 /**
- * Handler for a specific `SchemaNode` variant identified by `SchemaType` key `T`.
- * Use a regular function (not an arrow function) so that `this` is available.
+ * Handler for one schema node type.
+ *
+ * Use a regular function (not an arrow function) if you need `this`.
+ *
+ * @example
+ * ```ts
+ * const handler: PrinterHandler<string, {}, 'string'> = function () {
+ *   return 'string'
+ * }
+ * ```
  */
 export type PrinterHandler<TOutput, TOptions extends object, T extends SchemaType = SchemaType> = (
   this: PrinterHandlerContext<TOutput, TOptions>,
@@ -25,22 +43,56 @@ export type PrinterHandler<TOutput, TOptions extends object, T extends SchemaTyp
 ) => TOutput | null | undefined
 
 /**
- * Shape of the type parameter passed to `definePrinter`.
- * Mirrors `AdapterFactoryOptions` / `PluginFactoryOptions` from `@kubb/core`.
+ * Partial map of per-node-type handler overrides for a printer.
  *
- * - `TName` — unique string identifier (e.g. `'zod'`, `'ts'`)
- * - `TOptions` — options passed to and stored on the printer
- * - `TOutput` — the type emitted by `print` (typically `string`)
+ * Each key is a `SchemaType` string (e.g. `'date'`, `'string'`).
+ * Supply only the handlers you want to replace; the printer's built-in
+ * defaults fill in the rest.
+ *
+ * @example
+ * ```ts
+ * pluginZod({
+ *   printer: {
+ *     nodes: {
+ *       date(): string {
+ *         return 'z.string().date()'
+ *       },
+ *     } satisfies PrinterPartial<string, PrinterZodOptions>,
+ *   },
+ * })
+ * ```
+ */
+export type PrinterPartial<TOutput, TOptions extends object> = Partial<{
+  [K in SchemaType]: PrinterHandler<TOutput, TOptions, K>
+}>
+
+/**
+ * Generic shape used by `definePrinter`.
+ *
+ * - `TName`        — unique string identifier (e.g. `'zod'`, `'ts'`)
+ * - `TOptions`     — options passed to and stored on the printer instance
+ * - `TOutput`      — the type emitted by node handlers
+ * - `TPrintOutput` — type returned by public `print` (defaults to `TOutput`)
+ *
+ * @example
+ * ```ts
+ * type MyPrinter = PrinterFactoryOptions<'my', { strict: boolean }, string>
+ * ```
  */
-export type PrinterFactoryOptions<TName extends string = string, TOptions extends object = object, TOutput = unknown> = {
+export type PrinterFactoryOptions<TName extends string = string, TOptions extends object = object, TOutput = unknown, TPrintOutput = TOutput> = {
   name: TName
   options: TOptions
   output: TOutput
+  printOutput: TPrintOutput
 }
 
 /**
- * The object returned by calling a `definePrinter` instance.
- * Mirrors the shape of `Adapter` from `@kubb/core`.
+ * Printer instance returned by a printer factory.
+ *
+ * @example
+ * ```ts
+ * const printer = definePrinter((options: {}) => ({ name: 'x', options, nodes: {} }))({})
+ * ```
  */
 export type Printer<T extends PrinterFactoryOptions = PrinterFactoryOptions> = {
   /**
@@ -52,15 +104,33 @@ export type Printer<T extends PrinterFactoryOptions = PrinterFactoryOptions> = {
    */
   options: T['options']
   /**
-   * Emits `TOutput` from a `SchemaNode`. Returns `null | undefined` when no handler matches.
+   * Node-level dispatcher — converts a `SchemaNode` directly to `TOutput` using the `nodes` handlers.
+   * Always dispatches through the `nodes` map; never calls the `print` override.
+   * Use this when you need the raw output (e.g. `ts.TypeNode`) without declaration wrapping.
    */
-  print: (node: SchemaNode) => T['output'] | null | undefined
+  transform: (node: SchemaNode) => T['output'] | null | undefined
   /**
-   * Maps `print` over an array of `SchemaNode`s.
+   * Public printer. If the builder provides a root-level `print`, this calls that
+   * higher-level function (which may produce full declarations).
+   * Otherwise, falls back to the node-level dispatcher.
    */
-  for: (nodes: Array<SchemaNode>) => Array<T['output'] | null | undefined>
+  print: (node: SchemaNode) => T['printOutput'] | null | undefined
 }
 
+/**
+ * Builder function passed to `definePrinter`.
+ *
+ * It receives resolved options and returns:
+ * - `name`
+ * - `options`
+ * - `nodes` handlers
+ * - optional top-level `print` override
+ *
+ * @example
+ * ```ts
+ * const build = (options: {}) => ({ name: 'x' as const, options, nodes: {} })
+ * ```
+ */
 type PrinterBuilder<T extends PrinterFactoryOptions> = (options: T['options']) => {
   name: T['name']
   /**
@@ -70,60 +140,102 @@ type PrinterBuilder<T extends PrinterFactoryOptions> = (options: T['options']) =
   nodes: Partial<{
     [K in SchemaType]: PrinterHandler<T['output'], T['options'], K>
   }>
+  /**
+   * Optional root-level print override. When provided, becomes the public `printer.print`.
+   * Use `this.transform(node)` inside this function to dispatch to the node-level handlers (`nodes`),
+   * not the override itself — so recursion is safe.
+   */
+  print?: (this: PrinterHandlerContext<T['output'], T['options']>, node: SchemaNode) => T['printOutput'] | null
 }
 
 /**
- * Creates a named printer factory. Mirrors the `definePlugin` / `defineAdapter` pattern
- * from `@kubb/core` — wraps a builder to make options optional and separates raw options
- * from resolved options.
+ * Creates a schema printer factory.
  *
- * @example
+ * This function wraps a builder and makes options optional at call sites.
+ *
+ * The builder receives resolved options and returns:
+ * - `name` — a unique identifier for the printer
+ * - `options` — options stored on the returned printer instance
+ * - `nodes` — a map of `SchemaType` → handler functions that convert a `SchemaNode` to `TOutput`
+ * - `print` _(optional)_ — top-level override exposed as `printer.print`
+ *   - Inside this function, use `this.transform(node)` to dispatch to the `nodes` map
+ *   - This keeps recursion safe and avoids self-calls
+ *
+ * When no `print` override is provided, `printer.print` falls back to `printer.transform` (the node-level dispatcher).
+ *
+ * @example Basic usage — Zod schema printer
  * ```ts
- * type ZodPrinter = PrinterFactoryOptions<'zod', { strict?: boolean }, { strict: boolean }, string>
+ * type PrinterZod = PrinterFactoryOptions<'zod', { strict?: boolean }, string>
  *
- * export const zodPrinter = definePrinter<ZodPrinter>((options) => {
- *   const { strict = true } = options
- *   return {
- *     name: 'zod',
- *     options: { strict },
- *     nodes: {
- *       string(node) {
- *         return `z.string()`
- *       },
- *       object(node) {
- *         const props = node.properties
- *           ?.map(p => `${p.name}: ${this.print(p)}`)
- *           .join(', ') ?? ''
- *         return `z.object({ ${props} })`
- *       },
+ * export const zodPrinter = definePrinter<PrinterZod>((options) => ({
+ *   name: 'zod',
+ *   options: { strict: options.strict ?? true },
+ *   nodes: {
+ *     string: () => 'z.string()',
+ *     object(node) {
+ *       const props = node.properties.map(p => `${p.name}: ${this.transform(p.schema)}`).join(', ')
+ *       return `z.object({ ${props} })`
  *     },
- *   }
- * })
- *
- * const printer = zodPrinter({ strict: false })
- * printer.name            // 'zod'
- * printer.options         // { strict: false }
- * printer.print(node)     // 'z.string()'
+ *   },
+ * }))
  * ```
  */
 export function definePrinter<T extends PrinterFactoryOptions = PrinterFactoryOptions>(build: PrinterBuilder<T>): (options?: T['options']) => Printer<T> {
-  return (options) => {
-    const { name, options: resolvedOptions, nodes } = build(options ?? ({} as T['options']))
+  return createPrinterFactory<SchemaNode, SchemaType, SchemaNodeByType>((node) => node.type)(build) as (options?: T['options']) => Printer<T>
+}
 
-    const context: PrinterHandlerContext<T['output'], T['options']> = {
-      options: resolvedOptions,
-      print: (node: SchemaNode) => {
-        const type = node.type as SchemaType
-        const handler = nodes[type]
-        return handler ? (handler as PrinterHandler<T['output'], T['options']>).call(context, node as SchemaNodeByType[SchemaType]) : undefined
-      },
-    }
+/**
+ * Generic printer-factory function used by `definePrinter` and `defineFunctionPrinter`.
+ **
+ * @example
+ * ```ts
+ * export const defineFunctionPrinter = createPrinterFactory<FunctionNode, FunctionNodeType, FunctionNodeByType>(
+ *   (node) => kindToHandlerKey[node.kind],
+ * )
+ * ```
+ */
+export function createPrinterFactory<TNode, TKey extends string, TNodeByKey extends Partial<Record<TKey, TNode>>>(getKey: (node: TNode) => TKey | undefined) {
+  return function <T extends PrinterFactoryOptions>(
+    build: (options: T['options']) => {
+      name: T['name']
+      options: T['options']
+      nodes: Partial<{
+        [K in TKey]: (
+          this: { transform: (node: TNode) => T['output'] | null | undefined; options: T['options'] },
+          node: TNodeByKey[K],
+        ) => T['output'] | null | undefined
+      }>
+      print?: (this: { transform: (node: TNode) => T['output'] | null | undefined; options: T['options'] }, node: TNode) => T['printOutput'] | null | undefined
+    },
+  ): (options?: T['options']) => {
+    name: T['name']
+    options: T['options']
+    transform: (node: TNode) => T['output'] | null | undefined
+    print: (node: TNode) => T['printOutput'] | null | undefined
+  } {
+    return (options) => {
+      const { name, options: resolvedOptions, nodes, print: printOverride } = build(options ?? ({} as T['options']))
+
+      const context = {
+        options: resolvedOptions,
+        transform: (node: TNode): T['output'] | null | undefined => {
+          const key = getKey(node)
+          if (key === undefined) return null
+
+          const handler = nodes[key]
+
+          if (!handler) return null
+
+          return (handler as (this: typeof context, node: TNode) => T['output'] | null | undefined).call(context, node)
+        },
+      }
 
-    return {
-      name,
-      options: resolvedOptions,
-      print: context.print,
-      for: (nodes) => nodes.map(context.print),
+      return {
+        name,
+        options: resolvedOptions,
+        transform: context.transform,
+        print: (printOverride ? printOverride.bind(context) : context.transform) as (node: TNode) => T['printOutput'] | null | undefined,
+      }
     }
   }
 }

package/src/refs.ts

@@ -1,18 +1,40 @@
-import type { RootNode } from './nodes/root.ts'
+import type { InputNode } from './nodes/root.ts'
 import type { SchemaNode } from './nodes/schema.ts'
 
 /**
- * Schema name to `SchemaNode` mapping.
+ * Lookup map from schema name to `SchemaNode`.
  */
 export type RefMap = Map<string, SchemaNode>
 
 /**
- * Indexes named schemas from `root.schemas` by name. Unnamed schemas are skipped.
+ * Returns the last path segment of a reference string.
+ *
+ * Example: `#/components/schemas/Pet` becomes `Pet`.
+ *
+ * @example
+ * ```ts
+ * extractRefName('#/components/schemas/Pet') // 'Pet'
+ * ```
  */
-export function buildRefMap(root: RootNode): RefMap {
+export function extractRefName(ref: string): string {
+  return ref.split('/').at(-1) ?? ref
+}
+
+/**
+ * Builds a `RefMap` from `input.schemas` using each schema's `name`.
+ *
+ * Unnamed schemas are skipped.
+ *
+ * @example
+ * ```ts
+ * const refMap = buildRefMap(input)
+ * const pet = refMap.get('Pet')
+ * ```
+ */
+export function buildRefMap(input: InputNode): RefMap {
   const map: RefMap = new Map()
 
-  for (const schema of root.schemas) {
+  for (const schema of input.schemas) {
     if (schema.name) {
       map.set(schema.name, schema)
     }
@@ -21,14 +43,24 @@ export function buildRefMap(root: RootNode): RefMap {
 }
 
 /**
- * Looks up a schema by name. Prefer over `RefMap.get()` to keep the resolution strategy swappable.
+ * Resolves a schema by name from a `RefMap`.
+ *
+ * @example
+ * ```ts
+ * const petSchema = resolveRef(refMap, 'Pet')
+ * ```
  */
 export function resolveRef(refMap: RefMap, ref: string): SchemaNode | undefined {
   return refMap.get(ref)
 }
 
 /**
- * Converts a `RefMap` to a plain object.
+ * Converts a `RefMap` into a plain object.
+ *
+ * @example
+ * ```ts
+ * const refsObject = refMapToObject(refMap)
+ * ```
  */
 export function refMapToObject(refMap: RefMap): Record<string, SchemaNode> {
   return Object.fromEntries(refMap)

package/src/resolvers.ts

@@ -0,0 +1,45 @@
+import { pascalCase } from '@internals/utils'
+import { narrowSchema } from './guards.ts'
+import type { SchemaNode } from './nodes/schema.ts'
+import { extractRefName } from './refs.ts'
+import { collect } from './visitor.ts'
+
+export function findDiscriminator(mapping: Record<string, string> | undefined, ref: string | undefined): string | null {
+  if (!mapping || !ref) return null
+  return Object.entries(mapping).find(([, value]) => value === ref)?.[0] ?? null
+}
+
+export function childName(parentName: string | null | undefined, propName: string): string | null {
+  return parentName ? pascalCase([parentName, propName].join(' ')) : null
+}
+
+export function enumPropName(parentName: string | null | undefined, propName: string, enumSuffix: string): string {
+  return pascalCase([parentName, propName, enumSuffix].filter(Boolean).join(' '))
+}
+
+/**
+ * Collects import entries for all `ref` schema nodes in `node`.
+ */
+export function collectImports<TImport>({
+  node,
+  nameMapping,
+  resolve,
+}: {
+  node: SchemaNode
+  nameMapping: Map<string, string>
+  resolve: (schemaName: string) => TImport | undefined
+}): Array<TImport> {
+  return collect<TImport>(node, {
+    schema(schemaNode): TImport | undefined {
+      const schemaRef = narrowSchema(schemaNode, 'ref')
+      if (!schemaRef?.ref) return
+
+      const rawName = extractRefName(schemaRef.ref)
+      const schemaName = nameMapping.get(rawName) ?? rawName
+      const result = resolve(schemaName)
+      if (!result) return
+
+      return result
+    },
+  })
+}

package/src/transformers.ts

@@ -0,0 +1,156 @@
+import { isScalarPrimitive } from './constants.ts'
+import { createProperty, createSchema } from './factory.ts'
+import { narrowSchema } from './guards.ts'
+import type { SchemaNode } from './nodes/schema.ts'
+import { enumPropName } from './resolvers.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'] })
+ * ```
+ */
+export function setDiscriminatorEnum({
+  node,
+  propertyName,
+  values,
+  enumName,
+}: {
+  node: SchemaNode
+  propertyName: string
+  values: Array<string>
+  enumName?: string
+}): SchemaNode {
+  const objectNode = narrowSchema(node, 'object')
+  if (!objectNode?.properties?.length) {
+    return node
+  }
+
+  const hasProperty = objectNode.properties.some((prop) => prop.name === propertyName)
+  if (!hasProperty) {
+    return node
+  }
+
+  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,
+        }),
+      })
+    }),
+  })
+}
+
+/**
+ * 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' }) })] }),
+ * ])
+ * ```
+ */
+export function mergeAdjacentObjects(members: Array<SchemaNode>): Array<SchemaNode> {
+  return members.reduce<Array<SchemaNode>>((acc, member) => {
+    const objectMember = narrowSchema(member, 'object')
+    if (objectMember && !objectMember.name) {
+      const previous = acc.at(-1)
+      const previousObject = previous ? narrowSchema(previous, 'object') : undefined
+
+      if (previousObject && !previousObject.name) {
+        acc[acc.length - 1] = createSchema({
+          ...previousObject,
+          properties: [...(previousObject.properties ?? []), ...(objectMember.properties ?? [])],
+        })
+        return acc
+      }
+    }
+
+    acc.push(member)
+    return acc
+  }, [])
+}
+
+/**
+ * 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
+ * ```
+ */
+export function simplifyUnion(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
+  })
+}
+
+export function setEnumName(propNode: SchemaNode, parentName: string | null | undefined, propName: string, enumSuffix: string): SchemaNode {
+  const enumNode = narrowSchema(propNode, 'enum')
+
+  if (enumNode?.primitive === 'boolean') {
+    return { ...propNode, name: undefined }
+  }
+
+  if (enumNode) {
+    return { ...propNode, name: enumPropName(parentName, propName, enumSuffix) }
+  }
+
+  return propNode
+}

package/src/types.ts

@@ -1,41 +1,67 @@
 export type { VisitorDepth } from './constants.ts'
 export type { DistributiveOmit } from './factory.ts'
+export type { InferSchema, InferSchemaNode, ParserOptions } from './infer.ts'
 export type {
   ArraySchemaNode,
+  ArrowFunctionNode,
   BaseNode,
+  BreakNode,
+  CodeNode,
   ComplexSchemaType,
+  ConstNode,
   DateSchemaNode,
   DatetimeSchemaNode,
   EnumSchemaNode,
   EnumValueNode,
+  ExportNode,
+  FileNode,
+  FormatStringSchemaNode,
+  FunctionNode,
+  FunctionNodeType,
+  FunctionParameterNode,
+  FunctionParametersNode,
+  FunctionParamNode,
   HttpMethod,
   HttpStatusCode,
+  ImportNode,
+  InputMeta,
+  InputNode,
   IntersectionSchemaNode,
+  Ipv4SchemaNode,
+  Ipv6SchemaNode,
+  JSDocNode,
+  JsxNode,
   MediaType,
   Node,
   NodeKind,
   NumberSchemaNode,
   ObjectSchemaNode,
   OperationNode,
+  OutputNode,
+  ParameterGroupNode,
   ParameterLocation,
   ParameterNode,
+  ParamsTypeNode,
   PrimitiveSchemaType,
   PropertyNode,
   RefSchemaNode,
   ResponseNode,
-  RootMeta,
-  RootNode,
   ScalarSchemaNode,
   ScalarSchemaType,
   SchemaNode,
   SchemaNodeByType,
   SchemaType,
+  SourceNode,
   SpecialSchemaType,
   StatusCode,
   StringSchemaNode,
+  TextNode,
   TimeSchemaNode,
+  TypeDeclarationNode,
+  TypeNode,
   UnionSchemaNode,
+  UrlSchemaNode,
 } from './nodes/index.ts'
-export type { Printer, PrinterFactoryOptions, PrinterHandler, PrinterHandlerContext } from './printer.ts'
+export type { Printer, PrinterFactoryOptions, PrinterPartial } from './printer.ts'
 export type { RefMap } from './refs.ts'
-export type { AsyncVisitor, CollectVisitor, Visitor } from './visitor.ts'
+export type { AsyncVisitor, CollectOptions, CollectVisitor, ParentOf, TransformOptions, Visitor, VisitorContext, WalkOptions } from './visitor.ts'