@kubb/ast 5.0.0-alpha.2 → 5.0.0-alpha.20

package/src/printers/functionPrinter.ts

@@ -0,0 +1,196 @@
+import type { FunctionNode, FunctionNodeType } from '../nodes/function.ts'
+import type { FunctionParameterNode, FunctionParametersNode, ObjectBindingParameterNode } from '../nodes/index.ts'
+import type { PrinterFactoryOptions } from './printer.ts'
+import { createPrinterFactory } from './printer.ts'
+
+/**
+ * Maps each function-printer handler key to its concrete node type.
+ */
+export type FunctionNodeByType = {
+  functionParameter: FunctionParameterNode
+  objectBindingParameter: ObjectBindingParameterNode
+  functionParameters: FunctionParametersNode
+}
+
+const kindToHandlerKey = {
+  FunctionParameter: 'functionParameter',
+  ObjectBindingParameter: 'objectBindingParameter',
+  FunctionParameters: 'functionParameters',
+} satisfies Record<string, FunctionNodeType>
+
+/**
+ * Creates a function-parameter printer factory.
+ *
+ * This wrapper uses `createPrinterFactory` and dispatches handlers by `node.kind`
+ * (for function nodes) rather than by `node.type` (for schema nodes).
+ *
+ * @example
+ * ```ts
+ * type MyPrinter = PrinterFactoryOptions<'my', { mode: 'declaration' | 'call' }, string>
+ *
+ * export const myPrinter = defineFunctionPrinter<MyPrinter>((options) => ({
+ *   name: 'my',
+ *   options,
+ *   nodes: {
+ *     functionParameter(node) {
+ *       return options.mode === 'declaration' && node.type ? `${node.name}: ${node.type}` : node.name
+ *     },
+ *     objectBindingParameter(node) {
+ *       const inner = node.properties.map(p => this.print(p)).filter(Boolean).join(', ')
+ *       return `{ ${inner} }`
+ *     },
+ *     functionParameters(node) {
+ *       return node.params.map(p => this.print(p)).filter(Boolean).join(', ')
+ *     },
+ *   },
+ * }))
+ * ```
+ */
+export const defineFunctionPrinter = createPrinterFactory<FunctionNode, FunctionNodeType, FunctionNodeByType>((node) => kindToHandlerKey[node.kind])
+
+export type FunctionPrinterOptions = {
+  /**
+   * Rendering modes supported by `functionPrinter`.
+   *
+   * | Mode          | Output example                              | Use case                        |
+   * |---------------|---------------------------------------------|---------------------------------|
+   * | `declaration` | `id: string, config: Config = {}`           | Function parameter declaration |
+   * | `call`        | `id, { method, url }`                       | Function call arguments |
+   * | `keys`        | `{ id, config }`                            | Key names only (destructuring) |
+   * | `values`      | `{ id: id, config: config }`                | Key/value object entries |
+   */
+  mode: 'declaration' | 'call' | 'keys' | 'values'
+  /**
+   * Optional transformation applied to every parameter name before printing.
+   */
+  transformName?: (name: string) => string
+  /**
+   * Optional transformation applied to every type string before printing.
+   */
+  transformType?: (type: string) => string
+}
+
+type DefaultPrinter = PrinterFactoryOptions<'functionParameters', FunctionPrinterOptions, string>
+
+function rank(param: FunctionParameterNode | ObjectBindingParameterNode): number {
+  if (param.kind === 'ObjectBindingParameter') {
+    if (param.default) return 2
+    const isOptional = param.optional ?? param.properties.every((p) => p.optional || p.default !== undefined)
+    return isOptional ? 1 : 0
+  }
+  if (param.rest) return 3
+  if (param.default) return 2
+  return param.optional ? 1 : 0
+}
+
+function sortParams(params: Array<FunctionParameterNode | ObjectBindingParameterNode>): Array<FunctionParameterNode | ObjectBindingParameterNode> {
+  return [...params].sort((a, b) => rank(a) - rank(b))
+}
+
+function sortChildParams(params: Array<FunctionParameterNode>): Array<FunctionParameterNode> {
+  return [...params].sort((a, b) => rank(a) - rank(b))
+}
+
+/**
+ * Default function-signature printer.
+ * Covers the four standard output modes used across Kubb plugins.
+ *
+ * @example
+ * ```ts
+ * const printer = functionPrinter({ mode: 'declaration' })
+ *
+ * const sig = createFunctionParameters({
+ *   params: [
+ *     createFunctionParameter({ name: 'petId', type: 'string', optional: false }),
+ *     createFunctionParameter({ name: 'config', type: 'Config', optional: false, default: '{}' }),
+ *   ],
+ * })
+ *
+ * printer.print(sig)  // → "petId: string, config: Config = {}"
+ * ```
+ */
+export const functionPrinter = defineFunctionPrinter<DefaultPrinter>((options) => ({
+  name: 'functionParameters',
+  options,
+  nodes: {
+    functionParameter(node) {
+      const { mode, transformName, transformType } = this.options
+      const name = transformName ? transformName(node.name) : node.name
+      const type = node.type && transformType ? transformType(node.type) : node.type
+
+      if (mode === 'keys' || mode === 'values') {
+        return node.rest ? `...${name}` : name
+      }
+
+      if (mode === 'call') {
+        return node.rest ? `...${name}` : name
+      }
+
+      if (node.rest) {
+        return type ? `...${name}: ${type}` : `...${name}`
+      }
+      if (type) {
+        if (node.optional) return `${name}?: ${type}`
+        return node.default ? `${name}: ${type} = ${node.default}` : `${name}: ${type}`
+      }
+      return node.default ? `${name} = ${node.default}` : name
+    },
+    objectBindingParameter(node) {
+      const { mode, transformName, transformType } = this.options
+      const sorted = sortChildParams(node.properties)
+      const isOptional = node.optional ?? sorted.every((p) => p.optional || p.default !== undefined)
+
+      if (node.inline) {
+        return sorted
+          .map((p) => this.print(p))
+          .filter(Boolean)
+          .join(', ')
+      }
+
+      if (mode === 'keys' || mode === 'values') {
+        const keys = sorted.map((p) => p.name).join(', ')
+        return `{ ${keys} }`
+      }
+
+      if (mode === 'call') {
+        const keys = sorted.map((p) => p.name).join(', ')
+        return `{ ${keys} }`
+      }
+
+      const names = sorted.map((p) => {
+        const n = transformName ? transformName(p.name) : p.name
+
+        return n
+      })
+
+      const nameStr = names.length ? `{ ${names.join(', ')} }` : undefined
+      if (!nameStr) return null
+
+      let typeAnnotation = node.type
+      if (!typeAnnotation) {
+        const typeParts = sorted
+          .filter((p) => p.type)
+          .map((p) => {
+            const t = transformType && p.type ? transformType(p.type) : p.type!
+            return p.optional || p.default !== undefined ? `${p.name}?: ${t}` : `${p.name}: ${t}`
+          })
+        typeAnnotation = typeParts.length ? `{ ${typeParts.join('; ')} }` : undefined
+      }
+
+      if (typeAnnotation) {
+        if (isOptional) return `${nameStr}: ${typeAnnotation} = ${node.default ?? '{}'}`
+        return node.default ? `${nameStr}: ${typeAnnotation} = ${node.default}` : `${nameStr}: ${typeAnnotation}`
+      }
+
+      return node.default ? `${nameStr} = ${node.default}` : nameStr
+    },
+    functionParameters(node) {
+      const sorted = sortParams(node.params)
+
+      return sorted
+        .map((p) => this.print(p))
+        .filter(Boolean)
+        .join(', ')
+    },
+  },
+}))

package/src/printers/index.ts

@@ -0,0 +1,3 @@
+export { defineFunctionPrinter, functionPrinter } from './functionPrinter.ts'
+export type { Printer, PrinterFactoryOptions } from './printer.ts'
+export { createPrinterFactory, definePrinter } from './printer.ts'

package/src/printers/printer.ts

@@ -0,0 +1,204 @@
+import type { SchemaNode, SchemaNodeByType, SchemaType } from '../nodes/index.ts'
+
+/**
+ * Runtime context passed as `this` to printer handlers.
+ *
+ * `this.print` always dispatches to node-level handlers from `nodes`.
+ *
+ * @example
+ * ```ts
+ * const context: PrinterHandlerContext<string, {}> = {
+ *   options: {},
+ *   print: () => 'value',
+ * }
+ * ```
+ */
+export type PrinterHandlerContext<TOutput, TOptions extends object> = {
+  /**
+   * Recursively print a nested `SchemaNode` using the node-level handlers.
+   */
+  print: (node: SchemaNode) => TOutput | null | undefined
+  /**
+   * Options for this printer instance.
+   */
+  options: TOptions
+}
+
+/**
+ * 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>,
+  node: SchemaNodeByType[T],
+) => TOutput | null | undefined
+
+/**
+ * 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, TPrintOutput = TOutput> = {
+  name: TName
+  options: TOptions
+  output: TOutput
+  printOutput: TPrintOutput
+}
+
+/**
+ * Printer instance returned by a printer factory.
+ *
+ * @example
+ * ```ts
+ * const printer = definePrinter((options: {}) => ({ name: 'x', options, nodes: {} }))({})
+ * ```
+ */
+export type Printer<T extends PrinterFactoryOptions = PrinterFactoryOptions> = {
+  /**
+   * Unique identifier supplied at creation time.
+   */
+  name: T['name']
+  /**
+   * Options for this printer instance.
+   */
+  options: T['options']
+  /**
+   * 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.
+   */
+  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']
+  /**
+   * Options to store on the printer.
+   */
+  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`.
+   * `this.print(node)` inside this function calls the node-level dispatcher (`nodes` handlers),
+   * not the override itself — so recursion is safe.
+   */
+  print?: (this: PrinterHandlerContext<T['output'], T['options']>, node: SchemaNode) => T['printOutput'] | null | undefined
+}
+
+/**
+ * Creates a schema printer factory.
+ *
+ * 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, `this.print(node)` still dispatches to the `nodes` map
+ *   - This keeps recursion safe and avoids self-calls
+ *
+ * When no `print` override is provided, `printer.print` is the node-level dispatcher directly.
+ *
+ * @example Basic usage — Zod schema printer
+ * ```ts
+ * type ZodPrinter = PrinterFactoryOptions<'zod', { strict?: boolean }, string>
+ *
+ * export const zodPrinter = definePrinter<ZodPrinter>((options) => ({
+ *   name: 'zod',
+ *   options: { strict: options.strict ?? true },
+ *   nodes: {
+ *     string: () => 'z.string()',
+ *     object(node) {
+ *       const props = node.properties.map(p => `${p.name}: ${this.print(p.schema)}`).join(', ')
+ *       return `z.object({ ${props} })`
+ *     },
+ *   },
+ * }))
+ * ```
+ */
+export function definePrinter<T extends PrinterFactoryOptions = PrinterFactoryOptions>(build: PrinterBuilder<T>): (options?: T['options']) => Printer<T> {
+  return createPrinterFactory<SchemaNode, SchemaType, SchemaNodeByType>((node) => node.type)(build) as (options?: T['options']) => Printer<T>
+}
+
+/**
+ * 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: { print: (node: TNode) => T['output'] | null | undefined; options: T['options'] },
+          node: TNodeByKey[K],
+        ) => T['output'] | null | undefined
+      }>
+      print?: (this: { print: (node: TNode) => T['output'] | null | undefined; options: T['options'] }, node: TNode) => T['printOutput'] | null | undefined
+    },
+  ): (options?: T['options']) => { name: T['name']; options: T['options']; 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,
+        print: (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: (printOverride ? printOverride.bind(context) : context.print) as (node: TNode) => T['printOutput'] | null | undefined,
+      }
+    }
+  }
+}

package/src/refs.ts

@@ -2,12 +2,34 @@ import type { RootNode } 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 extractRefName(ref: string): string {
+  return ref.split('/').at(-1) ?? ref
+}
+
+/**
+ * Builds a `RefMap` from `root.schemas` using each schema's `name`.
+ *
+ * Unnamed schemas are skipped.
+ *
+ * @example
+ * ```ts
+ * const refMap = buildRefMap(root)
+ * const pet = refMap.get('Pet')
+ * ```
  */
 export function buildRefMap(root: RootNode): RefMap {
   const map: RefMap = new Map()
@@ -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
+    },
+  })
+}