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

package/src/infer.ts

@@ -0,0 +1,130 @@
+import type {
+  ArraySchemaNode,
+  DateSchemaNode,
+  DatetimeSchemaNode,
+  EnumSchemaNode,
+  IntersectionSchemaNode,
+  NumberSchemaNode,
+  ObjectSchemaNode,
+  RefSchemaNode,
+  ScalarSchemaNode,
+  SchemaNode,
+  StringSchemaNode,
+  TimeSchemaNode,
+  UnionSchemaNode,
+  UrlSchemaNode,
+} from './nodes/index.ts'
+
+/**
+ * Shared parser options used by OAS-to-AST inference and parser flows.
+ */
+export type ParserOptions = {
+  /**
+   * How `format: 'date-time'` schemas are represented. `false` falls through to a plain string.
+   */
+  dateType: false | 'string' | 'stringOffset' | 'stringLocal' | 'date'
+  /**
+   * Whether `type: 'integer'` and `format: 'int64'` produce `number` or `bigint` nodes.
+   */
+  integerType?: 'number' | 'bigint'
+  /**
+   * AST type used when no schema type can be inferred.
+   */
+  unknownType: 'any' | 'unknown' | 'void'
+  /**
+   * AST type used for completely empty schemas (`{}`).
+   */
+  emptySchemaType: 'any' | 'unknown' | 'void'
+  /**
+   * Suffix appended to derived enum names when building property schema names.
+   */
+  enumSuffix: 'enum' | (string & {})
+}
+
+/**
+ * Maps each `dateType` option value to the AST node produced by `format: 'date-time'`.
+ */
+type DateTimeNodeByDateType = {
+  date: DateSchemaNode
+  string: DatetimeSchemaNode
+  stringOffset: DatetimeSchemaNode
+  stringLocal: DatetimeSchemaNode
+  false: StringSchemaNode
+}
+
+/**
+ * Resolves the AST node produced by `format: 'date-time'` based on the `dateType` option.
+ */
+type ResolveDateTimeNode<TDateType extends ParserOptions['dateType']> = DateTimeNodeByDateType[TDateType extends keyof DateTimeNodeByDateType
+  ? TDateType
+  : 'string']
+
+/**
+ * Ordered list of `[schema-shape, SchemaNode]` pairs.
+ * `InferSchemaNode` walks this tuple in order and returns the first matching node type.
+ */
+type SchemaNodeMap<TDateType extends ParserOptions['dateType'] = 'string'> = [
+  [{ $ref: string }, RefSchemaNode],
+  [{ allOf: ReadonlyArray<unknown>; properties: object }, IntersectionSchemaNode],
+  [{ allOf: readonly [unknown, unknown, ...unknown[]] }, IntersectionSchemaNode],
+  [{ allOf: ReadonlyArray<unknown> }, SchemaNode],
+  [{ oneOf: ReadonlyArray<unknown> }, UnionSchemaNode],
+  [{ anyOf: ReadonlyArray<unknown> }, UnionSchemaNode],
+  [{ const: null }, ScalarSchemaNode],
+  [{ const: string | number | boolean }, EnumSchemaNode],
+  [{ type: ReadonlyArray<string> }, UnionSchemaNode],
+  [{ type: 'array'; enum: ReadonlyArray<unknown> }, ArraySchemaNode],
+  [{ enum: ReadonlyArray<unknown> }, EnumSchemaNode],
+  [{ type: 'enum' }, EnumSchemaNode],
+  [{ type: 'union' }, UnionSchemaNode],
+  [{ type: 'intersection' }, IntersectionSchemaNode],
+  [{ type: 'tuple' }, ArraySchemaNode],
+  [{ type: 'ref' }, RefSchemaNode],
+  [{ type: 'datetime' }, DatetimeSchemaNode],
+  [{ type: 'date' }, DateSchemaNode],
+  [{ type: 'time' }, TimeSchemaNode],
+  [{ type: 'url' }, UrlSchemaNode],
+  [{ type: 'object' }, ObjectSchemaNode],
+  [{ additionalProperties: boolean | {} }, ObjectSchemaNode],
+  [{ type: 'array' }, ArraySchemaNode],
+  [{ items: object }, ArraySchemaNode],
+  [{ prefixItems: ReadonlyArray<unknown> }, ArraySchemaNode],
+  [{ type: string; format: 'date-time' }, ResolveDateTimeNode<TDateType>],
+  [{ type: string; format: 'date' }, DateSchemaNode],
+  [{ type: string; format: 'time' }, TimeSchemaNode],
+  [{ format: 'date-time' }, ResolveDateTimeNode<TDateType>],
+  [{ format: 'date' }, DateSchemaNode],
+  [{ format: 'time' }, TimeSchemaNode],
+  [{ type: 'string' }, StringSchemaNode],
+  [{ type: 'number' }, NumberSchemaNode],
+  [{ type: 'integer' }, NumberSchemaNode],
+  [{ type: 'bigint' }, NumberSchemaNode],
+  [{ type: string }, ScalarSchemaNode],
+  [{ minLength: number }, StringSchemaNode],
+  [{ maxLength: number }, StringSchemaNode],
+  [{ pattern: string }, StringSchemaNode],
+  [{ minimum: number }, NumberSchemaNode],
+  [{ maximum: number }, NumberSchemaNode],
+]
+
+/**
+ * Infers the matching AST `SchemaNode` type from an input schema shape.
+ */
+export type InferSchemaNode<
+  TSchema extends object,
+  TDateType extends ParserOptions['dateType'] = 'string',
+  TEntries extends ReadonlyArray<[object, SchemaNode]> = SchemaNodeMap<TDateType>,
+> = TEntries extends [infer TEntry extends [object, SchemaNode], ...infer TRest extends ReadonlyArray<[object, SchemaNode]>]
+  ? TSchema extends TEntry[0]
+    ? TEntry[1]
+    : InferSchemaNode<TSchema, TDateType, TRest>
+  : SchemaNode
+
+/**
+ * Backward-compatible alias for `InferSchemaNode`.
+ */
+export type InferSchema<
+  TSchema extends object,
+  TDateType extends ParserOptions['dateType'] = 'string',
+  TEntries extends ReadonlyArray<[object, SchemaNode]> = SchemaNodeMap<TDateType>,
+> = InferSchemaNode<TSchema, TDateType, TEntries>

package/src/mocks.ts

@@ -2,7 +2,7 @@ import { createOperation, createParameter, createProperty, createResponse, creat
 import type { RootNode } from './nodes/root.ts'
 
 /**
- * Minimal single-resource tree: one `Pet` schema and one `getPetById` operation.
+ * Builds a minimal sample AST with one `Pet` schema and one `getPetById` operation.
  */
 export function buildSampleTree(): RootNode {
   const petSchema = createSchema({
@@ -20,15 +20,22 @@ 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] })
 }
 
 /**
- * PetStore-like tree: six named schemas (`Pet`, `NewPet`, `PetList`, `Error`, `PetOrError`, `FullPet`)
- * and two operations (`listPets`, `createPet`).
+ * Builds a PetStore-like fixture AST with:
+ * - six named schemas (`Pet`, `NewPet`, `PetList`, `Error`, `PetOrError`, `FullPet`)
+ * - two operations (`listPets`, `createPet`)
  */
 export function buildFixture(): RootNode {
   const refPet = createSchema({ type: 'ref', ref: 'Pet' })
@@ -92,7 +99,7 @@ export function buildFixture(): RootNode {
         method: 'POST',
         path: '/pets',
         tags: ['pets'],
-        requestBody: createSchema({ type: 'ref', ref: 'NewPet' }),
+        requestBody: { schema: createSchema({ type: 'ref', ref: 'NewPet' }) },
         responses: [createResponse({ statusCode: '201', schema: refPet, mediaType: 'application/json' })],
       }),
     ],

package/src/nodes/base.ts

@@ -1,16 +1,43 @@
 /**
- * Kind discriminant for every AST node.
+ * `kind` values used by AST nodes.
+ *
+ * @example
+ * ```ts
+ * const kind: NodeKind = 'Schema'
+ * ```
  */
-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.
+ * Base shape shared by all AST nodes.
+ *
+ * @example
+ * ```ts
+ * const base: BaseNode = { kind: 'Root' }
+ * ```
  */
 export type BaseNode = {
+  /**
+   * Node discriminator.
+   */
   kind: NodeKind
 }
 
 /**
- * Any AST node.
+ * Minimal node type when only `kind` is needed.
+ *
+ * @example
+ * ```ts
+ * const node: Node = { kind: 'Operation' }
+ * ```
  */
 export type Node = BaseNode

package/src/nodes/function.ts

@@ -0,0 +1,131 @@
+import type { BaseNode } from './base.ts'
+
+/**
+ * AST node for one function parameter.
+ *
+ * @example Required parameter
+ * `name: Type`
+ *
+ * @example Optional param
+ * `name?: Type`
+ *
+ * @example Parameter with default
+ * `name: Type = defaultValue`
+ *
+ * @example Rest parameter
+ * `...name: Type[]`
+ */
+export type FunctionParameterNode = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'FunctionParameter'
+  /**
+   * Parameter name in the generated signature.
+   */
+  name: string
+  /**
+   * TypeScript type text, for example, `"string"` or `"Pet[]"`.
+   * Omit for untyped JavaScript output.
+   */
+  type?: string
+  /**
+   * When `true` the parameter is emitted as a rest parameter (`...name`).
+   * @default false
+   */
+  rest?: boolean
+} /**
+ * Optional parameter, rendered with `?` in declarations.
+ * Cannot be combined with `default` because defaulted parameters are already optional.
+ * @example `name?: Type`
+ */ & (
+    | { optional: true; default?: never }
+    /**
+     * Required parameter, or parameter with a default value.
+     * @example Required: `name: Type`
+     * @example With default: `name: Type = default`
+     */
+    | { optional?: false; default?: string }
+  )
+
+/**
+ * AST node for object-destructured function parameters.
+ *
+ * This node renders as `{ key1, key2 }: { key1: Type1; key2: Type2 } = {}` in declarations,
+ * or as individual top-level parameters when `inline` is `true`.
+ *
+ * This replaces `mode: 'object'` and `mode: 'inlineSpread'` from the old `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 & {
+  /**
+   * Node kind.
+   */
+  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>
+  /**
+   * Optional type text for the full object parameter.
+   * When absent, the printer auto-computes `{ key1: Type1; key2: Type2 }` from `properties`.
+   */
+  type?: string
+  /**
+   * When `true`, `properties` 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 full object binding is optional.
+   * If omitted, printers infer this from child properties.
+   */
+  optional?: boolean
+  /**
+   * Default value for the object group, written verbatim after `=`.
+   * Commonly `'{}'` to allow omitting the argument entirely.
+   */
+  default?: string
+}
+
+/**
+ * AST node for a complete function parameter list.
+ *
+ * Printers are responsible for sorting (`required` → `optional` → `defaulted`).
+ * Nodes are plain immutable data.
+ *
+ * Renders differently depending on the output mode:
+ * - `declaration` → `(id: string, config: Config = {})` — function declaration parameters
+ * - `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 & {
+  /**
+   * Node kind.
+   */
+  kind: 'FunctionParameters'
+  /**
+   * Ordered parameter nodes.
+   */
+  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/http.ts

@@ -1,6 +1,6 @@
 /**
- * All IANA-registered HTTP status codes as string literals, matching how
- * they appear as keys in API specifications (e.g. `"200"`, `"404"`).
+ * All supported HTTP status code literals as strings, as used in API specs
+ * (for example, `"200"` and `"404"`).
  */
 export type HttpStatusCode =
   // 1xx Informational
@@ -72,13 +72,25 @@ export type HttpStatusCode =
   | '511'
 
 /**
- * A status code as used in an operation response: a specific HTTP status
- * code string or `"default"` as a catch-all fallback.
+ * Response status code literal used by operations.
+ *
+ * Includes specific HTTP status code strings and `"default"` for catch-all responses.
+ *
+ * @example
+ * ```ts
+ * const status: StatusCode = '200'
+ * const fallback: StatusCode = 'default'
+ * ```
  */
 export type StatusCode = HttpStatusCode | 'default'
 
 /**
- * Common IANA media types used in API request/response bodies.
+ * Supported media type strings used in request and response bodies.
+ *
+ * @example
+ * ```ts
+ * const mediaType: MediaType = 'application/json'
+ * ```
  */
 export type MediaType =
   // Application

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,13 +35,24 @@ export type {
   StringSchemaNode,
   TimeSchemaNode,
   UnionSchemaNode,
+  UrlSchemaNode,
 } from './schema.ts'
 
 /**
- * Discriminated union of every AST node.
+ * Union of all AST node types.
  *
- * Using a concrete union (instead of the bare `BaseNode` alias) lets
- * TypeScript narrow the type automatically inside `switch (node.kind)`
- * blocks, eliminating the need for manual `as TypeName` casts.
+ * This lets TypeScript narrow types in `switch (node.kind)` blocks.
+ *
+ * @example
+ * ```ts
+ * function getKind(node: Node): string {
+ *   switch (node.kind) {
+ *     case 'Root':
+ *       return 'root'
+ *     default:
+ *       return 'other'
+ *   }
+ * }
+ * ```
  */
-export type Node = RootNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode
+export type Node = RootNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode | FunctionNode

package/src/nodes/operation.ts

@@ -6,24 +6,81 @@ import type { SchemaNode } from './schema.ts'
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE'
 
 /**
- * A spec-agnostic representation of a single API operation.
+ * AST node representing one API operation.
+ *
+ * @example
+ * ```ts
+ * const operation: OperationNode = {
+ *   kind: 'Operation',
+ *   operationId: 'listPets',
+ *   method: 'GET',
+ *   path: '/pets',
+ *   tags: [],
+ *   parameters: [],
+ *   responses: [],
+ * }
+ * ```
  */
 export type OperationNode = BaseNode & {
+  /**
+   * Node kind.
+   */
   kind: 'Operation'
   /**
-   * Unique operation identifier (maps to `operationId` in OAS).
+   * Operation identifier, usually from OpenAPI `operationId`.
    */
   operationId: string
+  /**
+   * HTTP Method like 'GET'
+   */
   method: HttpMethod
+  /**
+   * Express-style path string, for example `/pets/:petId`.
+   * OpenAPI `{param}` parts are converted to `:param`.
+   */
   path: string
+  /**
+   * Group labels for the operation.
+   * Usually copied from OpenAPI `tags`.
+   */
   tags: Array<string>
+  /**
+   * Short one-line operation summary.
+   */
   summary?: string
+  /**
+   * Full operation description.
+   */
   description?: string
+  /**
+   * Marks the operation as deprecated.
+   */
   deprecated?: boolean
+  /**
+   * Parameters that could be used, we have QueryParams, PathParams, HeaderParams and CookieParams
+   */
   parameters: Array<ParameterNode>
   /**
-   * Request body schema. For OAS, this is the schema of the first content entry.
+   * Request body metadata for the operation.
+   */
+  requestBody?: {
+    /**
+     * Human-readable request body description.
+     */
+    description?: string
+    /**
+     * Request body schema.
+     * For OpenAPI, this is the schema from the first `content` entry.
+     */
+    schema?: SchemaNode
+    /**
+     * Property keys to exclude from the generated request body type via `Omit<Type, Keys>`.
+     * Set when a referenced schema has `readOnly` fields that should be omitted in request types.
+     */
+    keysToOmit?: Array<string>
+  }
+  /**
+   * Operation responses.
    */
-  requestBody?: SchemaNode
   responses: Array<ResponseNode>
 }

package/src/nodes/parameter.ts

@@ -4,12 +4,38 @@ import type { SchemaNode } from './schema.ts'
 export type ParameterLocation = 'path' | 'query' | 'header' | 'cookie'
 
 /**
- * A single input parameter for an operation.
+ * AST node representing one operation parameter.
+ *
+ * @example
+ * ```ts
+ * const param: ParameterNode = {
+ *   kind: 'Parameter',
+ *   name: 'petId',
+ *   in: 'path',
+ *   schema: createSchema({ type: 'string' }),
+ *   required: true,
+ * }
+ * ```
  */
 export type ParameterNode = BaseNode & {
+  /**
+   * Node kind.
+   */
   kind: 'Parameter'
+  /**
+   * Parameter name.
+   */
   name: string
+  /**
+   * Parameter location (`path`, `query`, `header`, or `cookie`).
+   */
   in: ParameterLocation
+  /**
+   * Parameter schema.
+   */
   schema: SchemaNode
+  /**
+   * Whether the parameter is required.
+   */
   required: boolean
 }

package/src/nodes/property.ts

@@ -2,11 +2,33 @@ import type { BaseNode } from './base.ts'
 import type { SchemaNode } from './schema.ts'
 
 /**
- * A named property within an object schema.
+ * AST node representing one named object property.
+ *
+ * @example
+ * ```ts
+ * const property: PropertyNode = {
+ *   kind: 'Property',
+ *   name: 'id',
+ *   schema: createSchema({ type: 'integer' }),
+ *   required: true,
+ * }
+ * ```
  */
 export type PropertyNode = BaseNode & {
+  /**
+   * Node kind.
+   */
   kind: 'Property'
+  /**
+   * Property key.
+   */
   name: string
+  /**
+   * Property schema.
+   */
   schema: SchemaNode
+  /**
+   * Whether the property is required.
+   */
   required: boolean
 }

package/src/nodes/response.ts

@@ -3,15 +3,41 @@ import type { MediaType, StatusCode } from './http.ts'
 import type { SchemaNode } from './schema.ts'
 
 /**
- * A single response variant for an operation.
+ * AST node representing one operation response variant.
+ *
+ * @example
+ * ```ts
+ * const response: ResponseNode = {
+ *   kind: 'Response',
+ *   statusCode: '200',
+ *   schema: createSchema({ type: 'string' }),
+ * }
+ * ```
  */
 export type ResponseNode = BaseNode & {
+  /**
+   * Node kind.
+   */
   kind: 'Response'
   /**
    * HTTP status code or `'default'` for a fallback response.
    */
   statusCode: StatusCode
+  /**
+   * Optional response description.
+   */
   description?: string
-  schema?: SchemaNode
-  mediaType?: MediaType
+  /**
+   * Response body schema.
+   */
+  schema: SchemaNode
+  /**
+   * Response media type.
+   */
+  mediaType?: MediaType | null
+  /**
+   * Property keys to exclude from the generated type via `Omit<Type, Keys>`.
+   * Set when a referenced schema has `writeOnly` fields that should not appear in response types.
+   */
+  keysToOmit?: Array<string>
 }