@kubb/ast 5.0.0-alpha.16 → 5.0.0-alpha.17

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({
@@ -33,8 +33,9 @@ export function buildSampleTree(): RootNode {
 }
 
 /**
- * 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' })

package/src/nodes/base.ts

@@ -1,5 +1,10 @@
 /**
- * Kind discriminant for every AST node.
+ * `kind` values used by AST nodes.
+ *
+ * @example
+ * ```ts
+ * const kind: NodeKind = 'Schema'
+ * ```
  */
 export type NodeKind =
   | 'Root'
@@ -13,13 +18,26 @@ export type NodeKind =
   | '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

@@ -1,28 +1,31 @@
 import type { BaseNode } from './base.ts'
 
 /**
- * A single named function parameter.
+ * AST node for one function parameter.
  *
- * @example Simple required param
+ * @example Required parameter
  * `name: Type`
  *
  * @example Optional param
  * `name?: Type`
  *
- * @example Param with default
+ * @example Parameter with default
  * `name: Type = defaultValue`
  *
- * @example Rest / spread param
+ * @example Rest parameter
  * `...name: Type[]`
  */
 export type FunctionParameterNode = BaseNode & {
+  /**
+   * Node kind.
+   */
   kind: 'FunctionParameter'
   /**
-   * The parameter name as it appears in the function signature.
+   * Parameter name in the generated signature.
    */
   name: string
   /**
-   * TypeScript type annotation (raw string, e.g. `"string"`, `"Pet[]"`, `"Partial<Config>"`).
+   * TypeScript type text, for example, `"string"` or `"Pet[]"`.
    * Omit for untyped JavaScript output.
    */
   type?: string
@@ -32,13 +35,13 @@ export type FunctionParameterNode = BaseNode & {
    */
   rest?: boolean
 } /**
- * Explicitly optional parameter — rendered with `?` in the signature.
- * Cannot be combined with `default`; a parameter with a default is implicitly optional.
+ * 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 a parameter with a default value (implicitly optional).
+     * Required parameter, or parameter with a default value.
      * @example Required: `name: Type`
      * @example With default: `name: Type = default`
      */
@@ -46,12 +49,12 @@ export type FunctionParameterNode = BaseNode & {
   )
 
 /**
- * An object-destructured function parameter group.
+ * AST node for object-destructured function parameters.
  *
- * Renders as `{ key1, key2 }: { key1: Type1; key2: Type2 } = {}` in a declaration,
- * or as individual top-level params when `inline` is `true`.
+ * This node renders as `{ key1, key2 }: { key1: Type1; key2: Type2 } = {}` in declarations,
+ * or as individual top-level parameters when `inline` is `true`.
  *
- * Replaces `mode: 'object'` / `mode: 'inlineSpread'` from the legacy `FunctionParams` API.
+ * 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 } = {}`
@@ -60,6 +63,9 @@ export type FunctionParameterNode = BaseNode & {
  * `id: string, name: string`
  */
 export type ObjectBindingParameterNode = BaseNode & {
+  /**
+   * Node kind.
+   */
   kind: 'ObjectBindingParameter'
   /**
    * The individual parameters that form the destructured object.
@@ -67,12 +73,12 @@ export type ObjectBindingParameterNode = BaseNode & {
    */
   properties: Array<FunctionParameterNode>
   /**
-   * Explicit TypeScript type annotation for the whole object param.
-   * When absent the printer auto-computes `{ key1: Type1; key2: Type2 }` from `params`.
+   * Optional type text for the full object parameter.
+   * When absent, the printer auto-computes `{ key1: Type1; key2: Type2 }` from `properties`.
    */
   type?: string
   /**
-   * When `true` the `params` are emitted as individual top-level parameters instead of
+   * 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.
@@ -80,8 +86,8 @@ export type ObjectBindingParameterNode = BaseNode & {
    */
   inline?: boolean
   /**
-   * Whether the whole object group is optional.
-   * When absent the printer auto-computes this: optional if every child param is optional.
+   * Whether the full object binding is optional.
+   * If omitted, printers infer this from child properties.
    */
   optional?: boolean
   /**
@@ -92,19 +98,25 @@ export type ObjectBindingParameterNode = BaseNode & {
 }
 
 /**
- * A complete ordered parameter list for a function.
+ * AST node for a complete function parameter list.
  *
- * The printer is responsible for sorting (required → optional → has-default).
- * Nodes themselves are treated as plain, immutable data.
+ * 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 = {})` — typed function parameter list
+ * - `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>
 }
 

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

@@ -39,10 +39,20 @@ export type {
 } 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 | FunctionNode

package/src/nodes/operation.ts

@@ -6,43 +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, e.g. `/pets/:petId`.
-   * Derived from the OpenAPI path by converting `{param}` tokens to `:param`.
+   * 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 for OAS operations. Bundles the schema with optional keys to exclude.
+   * Request body metadata for the operation.
    */
   requestBody?: {
     /**
-     * Human-readable description of the request body (maps to `requestBody.description` in OAS).
+     * Human-readable request body description.
      */
     description?: string
     /**
-     * The request body schema. For OAS, this is the schema of the first content entry.
+     * 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>`.
-     * Populated when the schema is a `$ref` and the referenced schema has `readOnly` properties
-     * that should not appear in request types.
+     * Set when a referenced schema has `readOnly` fields that should be omitted in request types.
      */
     keysToOmit?: Array<string>
   }
+  /**
+   * Operation responses.
+   */
   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,21 +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
+  /**
+   * Response body schema.
+   */
   schema: SchemaNode
+  /**
+   * Response media type.
+   */
   mediaType?: MediaType
   /**
    * Property keys to exclude from the generated type via `Omit<Type, Keys>`.
-   * Populated when the response schema is a `$ref` and the referenced schema has
-   * `writeOnly` properties that should not appear in response types.
+   * Set when a referenced schema has `writeOnly` fields that should not appear in response types.
    */
   keysToOmit?: Array<string>
 }

package/src/nodes/root.ts

@@ -3,8 +3,13 @@ import type { OperationNode } from './operation.ts'
 import type { SchemaNode } from './schema.ts'
 
 /**
- * Format-agnostic metadata about the API document.
- * Adapters populate whichever fields are available in their source format.
+ * Basic metadata for an API document.
+ * Adapters fill fields that exist in their source format.
+ *
+ * @example
+ * ```ts
+ * const meta: RootMeta = { title: 'Pet API', version: '1.0.0' }
+ * ```
  */
 export type RootMeta = {
   /**
@@ -20,23 +25,39 @@ export type RootMeta = {
    */
   version?: string
   /**
-   * Resolved base URL for the API.
-   * OAS: derived from `servers[serverIndex].url` with variable substitution.
-   * AsyncAPI: derived from `servers[serverIndex].url`.
-   * Drizzle / schema-only formats: not set.
+   * Resolved API base URL.
+   * For OpenAPI and AsyncAPI, this comes from the selected server URL.
    */
   baseURL?: string
 }
 
 /**
- * Top-level container for all schemas and operations in a single API document.
+ * Root AST node that contains all schemas and operations for one API document.
+ *
+ * @example
+ * ```ts
+ * const root: RootNode = {
+ *   kind: 'Root',
+ *   schemas: [],
+ *   operations: [],
+ * }
+ * ```
  */
 export type RootNode = BaseNode & {
+  /**
+   * Node kind.
+   */
   kind: 'Root'
+  /**
+   * All schema nodes in the document.
+   */
   schemas: Array<SchemaNode>
+  /**
+   * All operation nodes in the document.
+   */
   operations: Array<OperationNode>
   /**
-   * Format-agnostic document metadata populated by the adapter.
+   * Optional document metadata populated by the adapter.
    */
   meta?: RootMeta
 }