@kubb/ast 4.36.1 → 5.0.0-alpha.10

package/src/functionPrinter.ts

@@ -0,0 +1,195 @@
+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 `FunctionNodeType` 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 named function-signature printer factory.
+ * Built on `createPrinterFactory` — dispatches on `node.kind` instead of `node.type`.
+ *
+ * @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])
+
+/**
+ * The four rendering modes for a `FunctionParametersNode`.
+ *
+ * | Mode          | Output example                              | Use case                        |
+ * |---------------|---------------------------------------------|---------------------------------|
+ * | `declaration` | `id: string, config: Config = {}`           | Function parameter declarations |
+ * | `call`        | `id, { method, url }`                       | Function call arguments         |
+ * | `keys`        | `{ id, config }`                            | Key names only (destructuring)  |
+ * | `values`      | `{ id: id, config: config }`                | Key → value pairs               |
+ */
+
+export type FunctionPrinterOptions = {
+  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 throughout Kubb plugins.
+ *
+ * @example
+ * ```ts
+ * const printer = functionSignaturePrinter({ 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/guards.ts

@@ -1,4 +1,17 @@
-import type { Node, NodeKind, OperationNode, ParameterNode, PropertyNode, ResponseNode, RootNode, SchemaNode, SchemaNodeByType } from './nodes/index.ts'
+import type {
+  FunctionParameterNode,
+  FunctionParametersNode,
+  Node,
+  NodeKind,
+  ObjectBindingParameterNode,
+  OperationNode,
+  ParameterNode,
+  PropertyNode,
+  ResponseNode,
+  RootNode,
+  SchemaNode,
+  SchemaNodeByType,
+} from './nodes/index.ts'
 
 /**
  * Narrows a `SchemaNode` to the specific variant matching `type`.
@@ -40,3 +53,18 @@ export const isParameterNode = isKind<ParameterNode>('Parameter')
  * Type guard for `ResponseNode`.
  */
 export const isResponseNode = isKind<ResponseNode>('Response')
+
+/**
+ * Type guard for `FunctionParameterNode`.
+ */
+export const isFunctionParameterNode = isKind<FunctionParameterNode>('FunctionParameter')
+
+/**
+ * Type guard for `ObjectBindingParameterNode`.
+ */
+export const isObjectBindingParameterNode = isKind<ObjectBindingParameterNode>('ObjectBindingParameter')
+
+/**
+ * Type guard for `FunctionParametersNode`.
+ */
+export const isFunctionParametersNode = isKind<FunctionParametersNode>('FunctionParameters')

package/src/index.ts

@@ -1,6 +1,29 @@
 export { httpMethods, mediaTypes, nodeKinds, schemaTypes } from './constants.ts'
-export { createOperation, createParameter, createProperty, createResponse, createRoot, createSchema } from './factory.ts'
-export { isOperationNode, isParameterNode, isPropertyNode, isResponseNode, isRootNode, isSchemaNode, narrowSchema } from './guards.ts'
+export {
+  createFunctionParameter,
+  createFunctionParameters,
+  createObjectBindingParameter,
+  createOperation,
+  createParameter,
+  createProperty,
+  createResponse,
+  createRoot,
+  createSchema,
+} from './factory.ts'
+export { functionPrinter } from './functionPrinter.ts'
+export {
+  isFunctionParameterNode,
+  isFunctionParametersNode,
+  isObjectBindingParameterNode,
+  isOperationNode,
+  isParameterNode,
+  isPropertyNode,
+  isResponseNode,
+  isRootNode,
+  isSchemaNode,
+  narrowSchema,
+} from './guards.ts'
 export { definePrinter } from './printer.ts'
 export { buildRefMap, refMapToObject, resolveRef } from './refs.ts'
+export { applyParamsCasing, isPlainStringType } from './utils.ts'
 export { collect, transform, walk } from './visitor.ts'

package/src/mocks.ts

@@ -20,7 +20,13 @@ export function buildSampleTree(): RootNode {
     path: '/pets/{petId}',
     tags: ['pets'],
     parameters: [createParameter({ name: 'petId', in: 'path', schema: createSchema({ type: 'integer' }), required: true })],
-    responses: [createResponse({ statusCode: '200', schema: createSchema({ type: 'ref', name: 'Pet' }) }), createResponse({ statusCode: '404' })],
+    responses: [
+      createResponse({ statusCode: '200', schema: createSchema({ type: 'ref', name: 'Pet' }) }),
+      createResponse({
+        statusCode: '404',
+        schema: createSchema({ type: 'ref', name: 'Error' }),
+      }),
+    ],
   })
 
   return createRoot({ schemas: [petSchema], operations: [operation] })

package/src/nodes/base.ts

@@ -1,7 +1,16 @@
 /**
  * Kind discriminant for every AST node.
  */
-export type NodeKind = 'Root' | 'Operation' | 'Schema' | 'Property' | 'Parameter' | 'Response'
+export type NodeKind =
+  | 'Root'
+  | 'Operation'
+  | 'Schema'
+  | 'Property'
+  | 'Parameter'
+  | 'Response'
+  | 'FunctionParameter'
+  | 'ObjectBindingParameter'
+  | 'FunctionParameters'
 
 /**
  * Common base for all AST nodes.

package/src/nodes/function.ts

@@ -0,0 +1,119 @@
+import type { BaseNode } from './base.ts'
+
+/**
+ * A single named function parameter.
+ *
+ * @example Simple required param
+ * `name: Type`
+ *
+ * @example Optional param
+ * `name?: Type`
+ *
+ * @example Param with default
+ * `name: Type = defaultValue`
+ *
+ * @example Rest / spread param
+ * `...name: Type[]`
+ */
+export type FunctionParameterNode = BaseNode & {
+  kind: 'FunctionParameter'
+  /**
+   * The parameter name as it appears in the function signature.
+   */
+  name: string
+  /**
+   * TypeScript type annotation (raw string, e.g. `"string"`, `"Pet[]"`, `"Partial<Config>"`).
+   * Omit for untyped JavaScript output.
+   */
+  type?: string
+  /**
+   * When `true` the parameter is emitted as a rest parameter (`...name`).
+   * @default false
+   */
+  rest?: boolean
+} /**
+ * Explicitly optional parameter — rendered with `?` in the signature.
+ * Cannot be combined with `default`; a parameter with a default is implicitly optional.
+ * @example `name?: Type`
+ */ & (
+    | { optional: true; default?: never }
+    /**
+     * Required parameter, or a parameter with a default value (implicitly optional).
+     * @example Required: `name: Type`
+     * @example With default: `name: Type = default`
+     */
+    | { optional?: false; default?: string }
+  )
+
+/**
+ * An object-destructured function parameter group.
+ *
+ * Renders as `{ key1, key2 }: { key1: Type1; key2: Type2 } = {}` in a declaration,
+ * or as individual top-level params when `inline` is `true`.
+ *
+ * Replaces `mode: 'object'` / `mode: 'inlineSpread'` from the legacy `FunctionParams` API.
+ *
+ * @example Object destructuring with auto-computed type (declaration)
+ * `{ id, name }: { id: string; name: string } = {}`
+ *
+ * @example Inline (spread) — children emitted as individual top-level params
+ * `id: string, name: string`
+ */
+export type ObjectBindingParameterNode = BaseNode & {
+  kind: 'ObjectBindingParameter'
+  /**
+   * The individual parameters that form the destructured object.
+   * Rendered as `{ key1, key2 }` in declarations, or spread inline when `inline` is `true`.
+   */
+  properties: Array<FunctionParameterNode>
+  /**
+   * Explicit TypeScript type annotation for the whole object param.
+   * When absent the printer auto-computes `{ key1: Type1; key2: Type2 }` from `params`.
+   */
+  type?: string
+  /**
+   * When `true` the `params` are emitted as individual top-level parameters instead of
+   * being wrapped in a destructuring pattern (`{ key1, key2 }`).
+   *
+   * Equivalent to `mode: 'inlineSpread'` in the legacy `FunctionParams` API.
+   * @default false
+   */
+  inline?: boolean
+  /**
+   * Whether the whole object group is optional.
+   * When absent the printer auto-computes this: optional if every child param is optional.
+   */
+  optional?: boolean
+  /**
+   * Default value for the object group, written verbatim after `=`.
+   * Commonly `'{}'` to allow omitting the argument entirely.
+   */
+  default?: string
+}
+
+/**
+ * A complete ordered parameter list for a function.
+ *
+ * The printer is responsible for sorting (required → optional → has-default).
+ * Nodes themselves are treated as plain, immutable data.
+ *
+ * Renders differently depending on the output mode:
+ * - `declaration` → `(id: string, config: Config = {})` — typed function parameter list
+ * - `call`        → `(id, { method, url })` — function call arguments
+ * - `keys`        → `{ id, config }` — key names only (for destructuring)
+ * - `values`      → `{ id: id, config: config }` — key → value pairs
+ */
+export type FunctionParametersNode = BaseNode & {
+  kind: 'FunctionParameters'
+  params: Array<FunctionParameterNode | ObjectBindingParameterNode>
+}
+
+/**
+ * The three function-signature AST node variants.
+ */
+export type FunctionNode = FunctionParameterNode | ObjectBindingParameterNode | FunctionParametersNode
+
+/**
+ * Handler map keys — one per `FunctionNode` kind.
+ */
+export type FunctionNodeType = 'functionParameter' | 'objectBindingParameter' | 'functionParameters'

package/src/nodes/index.ts

@@ -1,3 +1,4 @@
+import type { FunctionNode } from './function.ts'
 import type { OperationNode } from './operation.ts'
 import type { ParameterNode } from './parameter.ts'
 import type { PropertyNode } from './property.ts'
@@ -6,6 +7,7 @@ import type { RootNode } from './root.ts'
 import type { SchemaNode } from './schema.ts'
 
 export type { BaseNode, NodeKind } from './base.ts'
+export type { FunctionNode, FunctionNodeType, FunctionParameterNode, FunctionParametersNode, ObjectBindingParameterNode } from './function.ts'
 export type { HttpStatusCode, MediaType, StatusCode } from './http.ts'
 export type { HttpMethod, OperationNode } from './operation.ts'
 export type { ParameterLocation, ParameterNode } from './parameter.ts'
@@ -33,6 +35,7 @@ export type {
   StringSchemaNode,
   TimeSchemaNode,
   UnionSchemaNode,
+  UrlSchemaNode,
 } from './schema.ts'
 
 /**
@@ -42,4 +45,4 @@ export type {
  * TypeScript narrow the type automatically inside `switch (node.kind)`
  * blocks, eliminating the need for manual `as TypeName` casts.
  */
-export type Node = RootNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode
+export type Node = RootNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode | FunctionNode

package/src/nodes/operation.ts

@@ -15,6 +15,10 @@ export type OperationNode = BaseNode & {
    */
   operationId: string
   method: HttpMethod
+  /**
+   * Express-style path string, e.g. `/pets/:petId`.
+   * Derived from the OpenAPI path by converting `{param}` tokens to `:param`.
+   */
   path: string
   tags: Array<string>
   summary?: string

package/src/nodes/response.ts

@@ -12,6 +12,6 @@ export type ResponseNode = BaseNode & {
    */
   statusCode: StatusCode
   description?: string
-  schema?: SchemaNode
+  schema: SchemaNode
   mediaType?: MediaType
 }

package/src/nodes/root.ts

@@ -7,9 +7,17 @@ import type { SchemaNode } from './schema.ts'
  * Adapters populate whichever fields are available in their source format.
  */
 export type RootMeta = {
-  /** API title (from `info.title` in OAS/AsyncAPI). */
+  /**
+   * API title (from `info.title` in OAS/AsyncAPI).
+   */
   title?: string
-  /** API version string (from `info.version` in OAS/AsyncAPI). */
+  /**
+   * API description (from `info.description` in OAS/AsyncAPI).
+   */
+  description?: string
+  /**
+   * API version string (from `info.version` in OAS/AsyncAPI).
+   */
   version?: string
   /**
    * Resolved base URL for the API.
@@ -27,6 +35,8 @@ export type RootNode = BaseNode & {
   kind: 'Root'
   schemas: Array<SchemaNode>
   operations: Array<OperationNode>
-  /** Format-agnostic document metadata populated by the adapter. */
+  /**
+   * Format-agnostic document metadata populated by the adapter.
+   */
   meta?: RootMeta
 }

package/src/nodes/schema.ts

@@ -1,7 +1,20 @@
 import type { BaseNode } from './base.ts'
 import type { PropertyNode } from './property.ts'
 
-export type PrimitiveSchemaType = 'string' | 'number' | 'integer' | 'bigint' | 'boolean' | 'null' | 'any' | 'unknown' | 'void' | 'object' | 'array' | 'date'
+export type PrimitiveSchemaType =
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'bigint'
+  | 'boolean'
+  | 'null'
+  | 'any'
+  | 'unknown'
+  | 'void'
+  | 'never'
+  | 'object'
+  | 'array'
+  | 'date'
 
 export type ComplexSchemaType = 'tuple' | 'union' | 'intersection' | 'enum'
 
@@ -14,7 +27,7 @@ export type SchemaType = PrimitiveSchemaType | ComplexSchemaType | SpecialSchema
 
 export type ScalarSchemaType = Exclude<
   SchemaType,
-  'object' | 'array' | 'tuple' | 'union' | 'intersection' | 'enum' | 'ref' | 'datetime' | 'date' | 'time' | 'string' | 'number' | 'integer' | 'bigint'
+  'object' | 'array' | 'tuple' | 'union' | 'intersection' | 'enum' | 'ref' | 'datetime' | 'date' | 'time' | 'string' | 'number' | 'integer' | 'bigint' | 'url'
 >
 
 /**
@@ -206,6 +219,17 @@ export type ScalarSchemaNode = SchemaNodeBase & {
   type: ScalarSchemaType
 }
 
+/**
+ * URL schema, optionally carrying an Express-style path template for template literal generation.
+ */
+export type UrlSchemaNode = SchemaNodeBase & {
+  type: 'url'
+  /**
+   * Express-style path (e.g. `'/pets/:petId'`). When set, printers may emit a template literal type.
+   */
+  path?: string
+}
+
 /**
  * Maps each schema type string to its `SchemaNode` variant. Used by `narrowSchema`.
  */
@@ -229,9 +253,10 @@ export type SchemaNodeByType = {
   any: ScalarSchemaNode
   unknown: ScalarSchemaNode
   void: ScalarSchemaNode
+  never: ScalarSchemaNode
   uuid: ScalarSchemaNode
   email: ScalarSchemaNode
-  url: ScalarSchemaNode
+  url: UrlSchemaNode
   blob: ScalarSchemaNode
 }
 
@@ -250,4 +275,5 @@ export type SchemaNode =
   | TimeSchemaNode
   | StringSchemaNode
   | NumberSchemaNode
+  | UrlSchemaNode
   | ScalarSchemaNode