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

package/src/nodes/schema.ts

@@ -2,236 +2,500 @@ import type { BaseNode } from './base.ts'
 import type { PropertyNode } from './property.ts'
 
 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' | '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
 }
 
 /**
- * URL schema, optionally carrying an Express-style path template for template literal generation.
+ * 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 (e.g. `'/pets/:petId'`). When set, printers may emit a template literal type.
+   * Express-style path template, for example, `'/pets/:petId'`.
    */
   path?: string
 }
 
 /**
- * Maps each schema type string to its `SchemaNode` variant. Used by `narrowSchema`.
+ * Mapping from schema type literals to concrete schema node types.
+ * Used by `narrowSchema`.
  */
 export type SchemaNodeByType = {
   object: ObjectSchemaNode
@@ -261,7 +525,7 @@ export type SchemaNodeByType = {
 }
 
 /**
- * Discriminated union of all schema variants.
+ * Union of all schema node types.
  */
 export type SchemaNode =
   | ObjectSchemaNode

package/src/{functionPrinter.ts → printers/functionPrinter.ts}

@@ -1,10 +1,10 @@
-import type { FunctionNode, FunctionNodeType } from './nodes/function.ts'
-import type { FunctionParameterNode, FunctionParametersNode, ObjectBindingParameterNode } from './nodes/index.ts'
+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.
+ * Maps each function-printer handler key to its concrete node type.
  */
 export type FunctionNodeByType = {
   functionParameter: FunctionParameterNode
@@ -19,8 +19,10 @@ const kindToHandlerKey = {
 } satisfies Record<string, FunctionNodeType>
 
 /**
- * Creates a named function-signature printer factory.
- * Built on `createPrinterFactory` — dispatches on `node.kind` instead of `node.type`.
+ * Creates a function-parameter printer factory.
+ *
+ * This wrapper uses `createPrinterFactory` and dispatches handlers by `node.kind`
+ * (for function nodes) rather than by `node.type` (for schema nodes).
  *
  * @example
  * ```ts
@@ -46,18 +48,17 @@ const kindToHandlerKey = {
  */
 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 = {
+  /**
+   * Rendering modes supported by `functionPrinter`.
+   *
+   * | Mode          | Output example                              | Use case                        |
+   * |---------------|---------------------------------------------|---------------------------------|
+   * | `declaration` | `id: string, config: Config = {}`           | Function parameter declaration |
+   * | `call`        | `id, { method, url }`                       | Function call arguments |
+   * | `keys`        | `{ id, config }`                            | Key names only (destructuring) |
+   * | `values`      | `{ id: id, config: config }`                | Key/value object entries |
+   */
   mode: 'declaration' | 'call' | 'keys' | 'values'
   /**
    * Optional transformation applied to every parameter name before printing.
@@ -91,12 +92,12 @@ function sortChildParams(params: Array<FunctionParameterNode>): Array<FunctionPa
 }
 
 /**
- * Default function-signature printer. Covers the four standard output modes
- * used throughout Kubb plugins.
+ * Default function-signature printer.
+ * Covers the four standard output modes used across Kubb plugins.
  *
  * @example
  * ```ts
- * const printer = functionSignaturePrinter({ mode: 'declaration' })
+ * const printer = functionPrinter({ mode: 'declaration' })
  *
  * const sig = createFunctionParameters({
  *   params: [

package/src/printers/index.ts

@@ -0,0 +1,3 @@
+export { defineFunctionPrinter, functionPrinter } from './functionPrinter.ts'
+export type { Printer, PrinterFactoryOptions } from './printer.ts'
+export { createPrinterFactory, definePrinter } from './printer.ts'