@kubb/ast 5.0.0-alpha.3 → 5.0.0-alpha.30

package/src/nodes/schema.ts

@@ -1,213 +1,604 @@
 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'
+export type SpecialSchemaType = 'ref' | 'datetime' | 'time' | 'uuid' | 'email' | 'url' | 'ipv4' | 'ipv6' | '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'
+  | 'uuid'
+  | 'email'
 >
 
 /**
- * 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'
+  /**
+   * Primitive type — always `'object'` for object schemas.
+   */
+  primitive: '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
+   * - `false`: reject unknown properties (maps to `.strict()` in Zod)
+   * - `SchemaNode`: allow values that match that schema
+   * - `undefined`: no additional properties constraint (open object)
+   */
+  additionalProperties?: SchemaNode | boolean
+  /**
+   * Pattern-based property schemas.
    */
-  additionalProperties?: SchemaNode | true
   patternProperties?: Record<string, SchemaNode>
+  /**
+   * Minimum number of properties allowed.
+   */
+  minProperties?: number
+  /**
+   * Maximum number of properties allowed.
+   */
+  maxProperties?: number
 }
 
 /**
- * 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
+  /**
+   * The fully-parsed schema that this ref resolves to.
+   * Populated during OAS parsing when the referenced definition can be resolved.
+   * `undefined` when the ref cannot be resolved or is part of a circular chain.
+   *
+   * Useful for inspecting the referenced schema's structure (e.g. `primitive`, `properties`)
+   * without following the reference manually.
+   */
+  schema?: SchemaNode
 }
 
 /**
  * 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
+  /**
+   * The value must be a multiple of this number.
+   */
+  multipleOf?: 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 OpenAPI-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'
+  /**
+   * OpenAPI-style path template, for example, `'/pets/{petId}'`.
+   */
+  path?: string
+  /**
+   * Minimum string length.
+   */
+  min?: number
+  /**
+   * Maximum string length.
+   */
+  max?: number
+}
+
+/**
+ * Format-string schema for string-based formats that support length constraints.
+ *
+ * @example
+ * ```ts
+ * const uuidSchema: FormatStringSchemaNode = { kind: 'Schema', type: 'uuid', min: 36, max: 36 }
+ * ```
+ */
+export type FormatStringSchemaNode = SchemaNodeBase & {
+  /**
+   * Schema type discriminator.
+   */
+  type: 'uuid' | 'email'
+  /**
+   * Minimum string length.
+   */
+  min?: number
+  /**
+   * Maximum string length.
+   */
+  max?: number
+}
+
+/**
+ * IPv4 address schema node.
+ *
+ * @example
+ * ```ts
+ * const ipv4Schema: Ipv4SchemaNode = { kind: 'Schema', type: 'ipv4' }
+ * ```
+ */
+export type Ipv4SchemaNode = SchemaNodeBase & {
+  /**
+   * Schema type discriminator.
+   */
+  type: 'ipv4'
+}
+
+/**
+ * IPv6 address schema node.
+ *
+ * @example
+ * ```ts
+ * const ipv6Schema: Ipv6SchemaNode = { kind: 'Schema', type: 'ipv6' }
+ * ```
+ */
+export type Ipv6SchemaNode = SchemaNodeBase & {
+  /**
+   * Schema type discriminator.
+   */
+  type: 'ipv6'
+}
+
+/**
+ * Mapping from schema type literals to concrete schema node types.
+ * Used by `narrowSchema`.
  */
 export type SchemaNodeByType = {
   object: ObjectSchemaNode
@@ -229,14 +620,17 @@ export type SchemaNodeByType = {
   any: ScalarSchemaNode
   unknown: ScalarSchemaNode
   void: ScalarSchemaNode
-  uuid: ScalarSchemaNode
-  email: ScalarSchemaNode
-  url: ScalarSchemaNode
+  never: ScalarSchemaNode
+  uuid: FormatStringSchemaNode
+  email: FormatStringSchemaNode
+  url: UrlSchemaNode
+  ipv4: Ipv4SchemaNode
+  ipv6: Ipv6SchemaNode
   blob: ScalarSchemaNode
 }
 
 /**
- * Discriminated union of all schema variants.
+ * Union of all schema node types.
  */
 export type SchemaNode =
   | ObjectSchemaNode
@@ -250,4 +644,8 @@ export type SchemaNode =
   | TimeSchemaNode
   | StringSchemaNode
   | NumberSchemaNode
+  | UrlSchemaNode
+  | FormatStringSchemaNode
+  | Ipv4SchemaNode
+  | Ipv6SchemaNode
   | ScalarSchemaNode