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

package/src/nodes/root.ts

@@ -3,30 +3,61 @@ 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 = {
-  /** 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.
-   * 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
 }

package/src/nodes/schema.ts

@@ -1,213 +1,501 @@
 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 =
+  /**
+   * Text value.
+   */
+  | 'string'
+  /**
+   * Floating-point number.
+   */
+  | 'number'
+  /**
+   * Integer number.
+   */
+  | 'integer'
+  /**
+   * Big integer number.
+   */
+  | 'bigint'
+  /**
+   * Boolean value.
+   */
+  | 'boolean'
+  /**
+   * Null value.
+   */
+  | 'null'
+  /**
+   * Any value.
+   */
+  | 'any'
+  /**
+   * Unknown value.
+   */
+  | 'unknown'
+  /**
+   * No value (`void`).
+   */
+  | 'void'
+  /**
+   * Never value.
+   */
+  | 'never'
+  /**
+   * Object value.
+   */
+  | 'object'
+  /**
+   * Array value.
+   */
+  | 'array'
+  /**
+   * Date value.
+   */
+  | 'date'
 
+/**
+ * Composite schema types.
+ */
 export type ComplexSchemaType = 'tuple' | 'union' | 'intersection' | 'enum'
 
 /**
- * Semantic types requiring special handling in code generation (e.g. generating a `Date` object or a branded type).
+ * Schema types that need special handling in generators.
  */
 export type SpecialSchemaType = 'ref' | 'datetime' | 'time' | 'uuid' | 'email' | 'url' | 'blob'
 
+/**
+ * All schema type strings.
+ */
 export type SchemaType = PrimitiveSchemaType | ComplexSchemaType | SpecialSchemaType
 
+/**
+ * Scalar schema types without extra object/array/ref structure.
+ */
 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'
 >
 
 /**
- * Base fields shared by every schema variant. Does not include spec-specific fields.
+ * Fields shared by all schema nodes.
  */
 type SchemaNodeBase = BaseNode & {
+  /**
+   * Node kind.
+   */
   kind: 'Schema'
   /**
-   * Named schema identifier (e.g. `"Pet"` from `#/components/schemas/Pet`). `undefined` for inline schemas.
+   * Schema name for named definitions (for example, `"Pet"`).
+   * Inline schemas omit this field.
+   * `null` means kubb has processed this and determined there is no applicable name.
+   * `undefined` means the name has not been set yet.
+   */
+  name?: string | null
+  /**
+   * Short schema title.
    */
-  name?: string
   title?: string
+  /**
+   * Schema description text.
+   */
   description?: string
+  /**
+   * Whether `null` is allowed.
+   */
   nullable?: boolean
+  /**
+   * Whether the field is optional.
+   */
   optional?: boolean
   /**
    * Both optional and nullable (`optional` + `nullable`).
    */
   nullish?: boolean
+  /**
+   * Whether the schema is deprecated.
+   */
   deprecated?: boolean
+  /**
+   * Whether the schema is read-only.
+   */
   readOnly?: boolean
+  /**
+   * Whether the schema is write-only.
+   */
   writeOnly?: boolean
+  /**
+   * Default value.
+   */
   default?: unknown
+  /**
+   * Example value.
+   */
   example?: unknown
   /**
-   * Underlying primitive before format/semantic promotion (e.g. `'string'` for a `uuid` node).
+   * Base primitive type.
+   * For example, this is `'string'` for a `uuid` schema.
    */
   primitive?: PrimitiveSchemaType
 }
 
 /**
- * Object schema with ordered property definitions.
+ * Object schema with ordered properties.
+ *
+ * @example
+ * ```ts
+ * const objectSchema: ObjectSchemaNode = {
+ *   kind: 'Schema',
+ *   type: 'object',
+ *   properties: [],
+ * }
+ * ```
  */
 export type ObjectSchemaNode = SchemaNodeBase & {
+  /**
+   * Schema type discriminator.
+   */
   type: 'object'
+  /**
+   * Ordered object properties.
+   */
   properties: Array<PropertyNode>
   /**
-   * `true` allows any value; a `SchemaNode` constrains it; absent means not permitted.
+   * Additional object properties behavior:
+   * - `true`: allow any value
+   * - `SchemaNode`: allow values that match that schema
+   * - `undefined`: no additional properties
    */
   additionalProperties?: SchemaNode | true
+  /**
+   * Pattern-based property schemas.
+   */
   patternProperties?: Record<string, SchemaNode>
 }
 
 /**
- * Array or tuple schema.
+ * Array-like schema (`array` or `tuple`).
+ *
+ * @example
+ * ```ts
+ * const arraySchema: ArraySchemaNode = {
+ *   kind: 'Schema',
+ *   type: 'array',
+ *   items: [],
+ * }
+ * ```
  */
 export type ArraySchemaNode = SchemaNodeBase & {
+  /**
+   * Schema type discriminator (`array` or `tuple`).
+   */
   type: 'array' | 'tuple'
+  /**
+   * Item schemas.
+   */
   items?: Array<SchemaNode>
   /**
-   * Additional items beyond positional `items` in a tuple.
+   * Tuple rest-item schema for elements beyond positional `items`.
    */
   rest?: SchemaNode
+  /**
+   * Minimum item count (or tuple length).
+   */
   min?: number
+  /**
+   * Maximum item count (or tuple length).
+   */
   max?: number
+  /**
+   * Whether all items must be unique.
+   */
   unique?: boolean
 }
 
 /**
- * Shared base for union and intersection schemas.
+ * Shared shape for union and intersection schemas.
  */
 type CompositeSchemaNodeBase = SchemaNodeBase & {
+  /**
+   * Member schemas.
+   */
   members?: Array<SchemaNode>
 }
 
 /**
- * Union schema (`oneOf` / `anyOf`).
+ * Union schema, often from `oneOf` or `anyOf`.
+ *
+ * @example
+ * ```ts
+ * const unionSchema: UnionSchemaNode = {
+ *   kind: 'Schema',
+ *   type: 'union',
+ *   members: [],
+ * }
+ * ```
  */
 export type UnionSchemaNode = CompositeSchemaNodeBase & {
+  /**
+   * Schema type discriminator.
+   */
   type: 'union'
   /**
-   * Discriminator property from OAS `discriminator.propertyName`.
+   * Discriminator property name from OpenAPI `discriminator.propertyName`.
    */
   discriminatorPropertyName?: string
 }
 
 /**
- * Intersection schema (`allOf`).
+ * Intersection schema, often from `allOf`.
+ *
+ * @example
+ * ```ts
+ * const intersectionSchema: IntersectionSchemaNode = {
+ *   kind: 'Schema',
+ *   type: 'intersection',
+ *   members: [],
+ * }
+ * ```
  */
 export type IntersectionSchemaNode = CompositeSchemaNodeBase & {
+  /**
+   * Schema type discriminator.
+   */
   type: 'intersection'
 }
 
 /**
- * A named enum variant.
+ * One named enum item.
  */
 export type EnumValueNode = {
+  /**
+   * Enum item name.
+   */
   name: string
+  /**
+   * Enum item value.
+   */
   value: string | number | boolean
-  format: 'string' | 'number' | 'boolean'
+  /**
+   * Primitive type of the enum value.
+   */
+  primitive: Extract<PrimitiveSchemaType, 'string' | 'number' | 'boolean'>
 }
 
 /**
- * Enum schema.
+ * Enum schema node.
+ *
+ * @example
+ * ```ts
+ * const enumSchema: EnumSchemaNode = {
+ *   kind: 'Schema',
+ *   type: 'enum',
+ *   enumValues: ['a', 'b'],
+ * }
+ * ```
  */
 export type EnumSchemaNode = SchemaNodeBase & {
-  type: 'enum'
   /**
-   * Enum member type. Generators should use const assertions for `'number'` / `'boolean'`.
+   * Schema type discriminator.
    */
-  enumType?: 'string' | 'number' | 'boolean'
+  type: 'enum'
   /**
-   * Allowed values (simple form).
+   * Enum values in simple form.
    */
   enumValues?: Array<string | number | boolean | null>
   /**
-   * Named variants (rich form). Takes priority over `enumValues` when present.
+   * Enum values in named form.
+   * If present, this is used instead of `enumValues`.
    */
   namedEnumValues?: Array<EnumValueNode>
 }
 
 /**
- * Ref schema — pointer to another schema definition.
+ * Reference schema that points to another schema definition.
+ *
+ * @example
+ * ```ts
+ * const refSchema: RefSchemaNode = {
+ *   kind: 'Schema',
+ *   type: 'ref',
+ *   ref: '#/components/schemas/Pet',
+ * }
+ * ```
  */
 export type RefSchemaNode = SchemaNodeBase & {
+  /**
+   * Schema type discriminator.
+   */
   type: 'ref'
+  /**
+   * Referenced schema name.
+   */
   name?: string
   /**
-   * Original `$ref` path (e.g. `#/components/schemas/Order`). Used for name resolution.
+   * Original `$ref` path, for example, `#/components/schemas/Order`.
+   * Used to resolve names later.
    */
   ref?: string
   /**
-   * Pattern constraint propagated from a sibling `pattern` field next to the `$ref`.
+   * Pattern copied from a sibling `pattern` field.
    */
   pattern?: string
 }
 
 /**
  * Datetime schema.
+ *
+ * @example
+ * ```ts
+ * const datetimeSchema: DatetimeSchemaNode = { kind: 'Schema', type: 'datetime' }
+ * ```
  */
 export type DatetimeSchemaNode = SchemaNodeBase & {
+  /**
+   * Schema type discriminator.
+   */
   type: 'datetime'
   /**
-   * Includes timezone offset (`dateType: 'stringOffset'`).
+   * Whether the datetime includes a timezone offset (`dateType: 'stringOffset'`).
    */
   offset?: boolean
   /**
-   * Local datetime without timezone (`dateType: 'stringLocal'`).
+   * Whether the datetime is local (no timezone, `dateType: 'stringLocal'`).
    */
   local?: boolean
 }
 
 /**
- * Base for `date` and `time` schemas.
+ * Shared base for `date` and `time` schemas.
  */
 type TemporalSchemaNodeBase<T extends 'date' | 'time'> = SchemaNodeBase & {
+  /**
+   * Schema type discriminator.
+   */
   type: T
   /**
-   * Representation in generated code: native `Date` or plain string.
+   * Output representation in generated code.
    */
   representation: 'date' | 'string'
 }
 
 /**
- * Date schema.
+ * Date schema node.
+ *
+ * @example
+ * ```ts
+ * const dateSchema: DateSchemaNode = { kind: 'Schema', type: 'date', representation: 'string' }
+ * ```
  */
 export type DateSchemaNode = TemporalSchemaNodeBase<'date'>
 
 /**
- * Time schema.
+ * Time schema node.
+ *
+ * @example
+ * ```ts
+ * const timeSchema: TimeSchemaNode = { kind: 'Schema', type: 'time', representation: 'string' }
+ * ```
  */
 export type TimeSchemaNode = TemporalSchemaNodeBase<'time'>
 
 /**
- * String schema.
+ * String schema node.
+ *
+ * @example
+ * ```ts
+ * const stringSchema: StringSchemaNode = { kind: 'Schema', type: 'string' }
+ * ```
  */
 export type StringSchemaNode = SchemaNodeBase & {
+  /**
+   * Schema type discriminator.
+   */
   type: 'string'
+  /**
+   * Minimum string length.
+   */
   min?: number
+  /**
+   * Maximum string length.
+   */
   max?: number
+  /**
+   * Regex pattern.
+   */
   pattern?: string
 }
 
 /**
- * Number, integer, or bigint schema.
+ * Numeric schema (`number`, `integer`, or `bigint`).
+ *
+ * @example
+ * ```ts
+ * const numberSchema: NumberSchemaNode = { kind: 'Schema', type: 'number' }
+ * ```
  */
 export type NumberSchemaNode = SchemaNodeBase & {
+  /**
+   * Schema type discriminator.
+   */
   type: 'number' | 'integer' | 'bigint'
+  /**
+   * Minimum value.
+   */
   min?: number
+  /**
+   * Maximum value.
+   */
   max?: number
+  /**
+   * Exclusive minimum value.
+   */
   exclusiveMinimum?: number
+  /**
+   * Exclusive maximum value.
+   */
   exclusiveMaximum?: number
 }
 
 /**
- * Schema for scalar types with no additional constraints.
+ * Scalar schema with no extra constraints.
+ *
+ * @example
+ * ```ts
+ * const anySchema: ScalarSchemaNode = { kind: 'Schema', type: 'any' }
+ * ```
  */
 export type ScalarSchemaNode = SchemaNodeBase & {
+  /**
+   * Schema type discriminator.
+   */
   type: ScalarSchemaType
 }
 
 /**
- * Maps each schema type string to its `SchemaNode` variant. Used by `narrowSchema`.
+ * URL schema node.
+ * Can include an Express-style path template for template literal types.
+ *
+ * @example
+ * ```ts
+ * const urlSchema: UrlSchemaNode = { kind: 'Schema', type: 'url', path: '/pets/:petId' }
+ * ```
+ */
+export type UrlSchemaNode = SchemaNodeBase & {
+  /**
+   * Schema type discriminator.
+   */
+  type: 'url'
+  /**
+   * Express-style path template, for example, `'/pets/:petId'`.
+   */
+  path?: string
+}
+
+/**
+ * Mapping from schema type literals to concrete schema node types.
+ * Used by `narrowSchema`.
  */
 export type SchemaNodeByType = {
   object: ObjectSchemaNode
@@ -229,14 +517,15 @@ export type SchemaNodeByType = {
   any: ScalarSchemaNode
   unknown: ScalarSchemaNode
   void: ScalarSchemaNode
+  never: ScalarSchemaNode
   uuid: ScalarSchemaNode
   email: ScalarSchemaNode
-  url: ScalarSchemaNode
+  url: UrlSchemaNode
   blob: ScalarSchemaNode
 }
 
 /**
- * Discriminated union of all schema variants.
+ * Union of all schema node types.
  */
 export type SchemaNode =
   | ObjectSchemaNode
@@ -250,4 +539,5 @@ export type SchemaNode =
   | TimeSchemaNode
   | StringSchemaNode
   | NumberSchemaNode
+  | UrlSchemaNode
   | ScalarSchemaNode