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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/ast",
-  "version": "5.0.0-alpha.3",
+  "version": "5.0.0-alpha.31",
   "description": "Spec-agnostic AST layer for Kubb. Defines nodes, visitor pattern, and factory functions used across codegen plugins.",
   "keywords": [
     "kubb",
@@ -45,7 +45,8 @@
     "!/**/__snapshots__/**"
   ],
   "devDependencies": {
-    "@types/node": "^22.19.15"
+    "@types/node": "^22.19.17",
+    "@internals/utils": "0.0.0"
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

package/src/constants.ts

@@ -5,7 +5,7 @@ import type { ParameterLocation } from './nodes/parameter.ts'
 import type { SchemaType } from './nodes/schema.ts'
 
 /**
- * Depth for schema traversal in visitor functions.
+ * Traversal depth used by AST visitor utilities.
  */
 export type VisitorDepth = 'shallow' | 'deep'
 
@@ -21,9 +21,26 @@ export const nodeKinds = {
   property: 'Property',
   parameter: 'Parameter',
   response: 'Response',
-} as const satisfies Record<Lowercase<NodeKind>, NodeKind>
+  functionParameter: 'FunctionParameter',
+  parameterGroup: 'ParameterGroup',
+  functionParameters: 'FunctionParameters',
+} as const satisfies Record<string, NodeKind>
 
+/**
+ * Canonical schema type strings used by AST schema nodes.
+ *
+ * These values are used across the AST as stable discriminators
+ * (for example `schema.type === schemaTypes.object`).
+ *
+ * The map is grouped by intent:
+ * - primitives (`string`, `number`, `boolean`, ...)
+ * - structural/composite (`object`, `array`, `union`, ...)
+ * - special OpenAPI-oriented types (`ref`, `datetime`, `uuid`, ...)
+ */
 export const schemaTypes = {
+  /**
+   * Text value.
+   */
   string: 'string',
   /**
    * Floating-point number (`float`, `double`).
@@ -37,27 +54,110 @@ export const schemaTypes = {
    * 64-bit integer (`int64`). Only used when `integerType` is set to `'bigint'`.
    */
   bigint: 'bigint',
+  /**
+   * Boolean value
+   */
   boolean: 'boolean',
+  /**
+   * Explicit null value.
+   */
   null: 'null',
+  /**
+   * Any value (no type restriction).
+   */
   any: 'any',
+  /**
+   * Unknown value (must be narrowed before usage).
+   */
   unknown: 'unknown',
+  /**
+   * No return value (`void`).
+   */
   void: 'void',
+  /**
+   * Object with named properties.
+   */
   object: 'object',
+  /**
+   * Sequential list of items.
+   */
   array: 'array',
+  /**
+   * Fixed-length list with position-specific items.
+   */
   tuple: 'tuple',
+  /**
+   * "One of" multiple schema members.
+   */
   union: 'union',
+  /**
+   * "All of" multiple schema members.
+   */
   intersection: 'intersection',
+  /**
+   * Enum schema.
+   */
   enum: 'enum',
+  /**
+   * Reference to another schema.
+   */
   ref: 'ref',
+  /**
+   * Calendar date (for example `2026-03-24`).
+   */
   date: 'date',
+  /**
+   * Date-time value (for example `2026-03-24T09:00:00Z`).
+   */
   datetime: 'datetime',
+  /**
+   * Time-only value (for example `09:00:00`).
+   */
   time: 'time',
+  /**
+   * UUID value.
+   */
   uuid: 'uuid',
+  /**
+   * Email address value.
+   */
   email: 'email',
+  /**
+   * URL value.
+   */
   url: 'url',
+  /**
+   * IPv4 address value.
+   */
+  ipv4: 'ipv4',
+  /**
+   * IPv6 address value.
+   */
+  ipv6: 'ipv6',
+  /**
+   * Binary/blob value.
+   */
   blob: 'blob',
+  /**
+   * Impossible value (`never`).
+   */
+  never: 'never',
 } as const satisfies Record<SchemaType, SchemaType>
 
+export type ScalarPrimitive = 'string' | 'number' | 'integer' | 'bigint' | 'boolean'
+
+/**
+ * Primitive scalar schema types used when simplifying union members.
+ */
+export const SCALAR_PRIMITIVE_TYPES = new Set<ScalarPrimitive>(['string', 'number', 'integer', 'bigint', 'boolean'])
+
+/**
+ * Returns `true` when `type` is a scalar primitive schema type.
+ */
+export function isScalarPrimitive(type: string): type is ScalarPrimitive {
+  return SCALAR_PRIMITIVE_TYPES.has(type as ScalarPrimitive)
+}
+
 export const httpMethods = {
   get: 'GET',
   post: 'POST',
@@ -77,12 +177,26 @@ export const parameterLocations = {
 } as const satisfies Record<ParameterLocation, ParameterLocation>
 
 /**
- * Default max concurrent visitor calls in `walk`.
+ * Default maximum number of concurrent callbacks used by `walk`.
+ *
+ * 30 is chosen to allow enough parallelism to overlap I/O-bound resolver calls
+ * without overwhelming the event loop or causing excessive memory pressure during
+ * large spec traversals.
+ *
+ * @example
+ * ```ts
+ * walk(root, { concurrency: WALK_CONCURRENCY, root: () => {} })
+ * ```
  */
 export const WALK_CONCURRENCY = 30
 
 /**
- * Fallback status code string for API spec responses.
+ * Fallback response status code used for catch-all responses.
+ *
+ * @example
+ * ```ts
+ * const status = DEFAULT_STATUS_CODE // 'default'
+ * ```
  */
 export const DEFAULT_STATUS_CODE = 'default' as const
 

package/src/factory.ts

@@ -1,12 +1,66 @@
-import type { ObjectSchemaNode, OperationNode, ParameterNode, PropertyNode, ResponseNode, RootNode, SchemaNode } from './nodes/index.ts'
+import type { InferSchemaNode } from './infer.ts'
+import type {
+  FunctionParameterNode,
+  FunctionParametersNode,
+  ObjectSchemaNode,
+  OperationNode,
+  ParameterGroupNode,
+  ParameterNode,
+  PrimitiveSchemaType,
+  PropertyNode,
+  ResponseNode,
+  RootNode,
+  SchemaNode,
+  TypeNode,
+} from './nodes/index.ts'
 
 /**
- * Distributive variant of `Omit` that preserves union members.
+ * Syncs property/parameter schema optionality flags from `required` and `schema.nullable`.
+ *
+ * - `optional` is set for non-required, non-nullable schemas.
+ * - `nullish` is set for non-required, nullable schemas.
+ */
+export function syncOptionality(schema: SchemaNode, required: boolean): SchemaNode {
+  const nullable = schema.nullable ?? false
+
+  return {
+    ...schema,
+    optional: !required && !nullable ? true : undefined,
+    nullish: !required && nullable ? true : undefined,
+  }
+}
+
+/**
+ * Distributive `Omit` that preserves each member of a union.
+ *
+ * @example
+ * ```ts
+ * type A = { kind: 'a'; keep: string; drop: number }
+ * type B = { kind: 'b'; keep: boolean; drop: number }
+ * type Result = DistributiveOmit<A | B, 'drop'>
+ * // -> { kind: 'a'; keep: string } | { kind: 'b'; keep: boolean }
+ * ```
  */
 export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never
 
+type CreateSchemaObjectInput = Omit<ObjectSchemaNode, 'kind' | 'properties' | 'primitive'> & { properties?: Array<PropertyNode>; primitive?: 'object' }
+type CreateSchemaInput = CreateSchemaObjectInput | DistributiveOmit<Exclude<SchemaNode, ObjectSchemaNode>, 'kind'>
+type CreateSchemaOutput<T extends CreateSchemaInput> = InferSchemaNode<T> & { kind: 'Schema' }
+
 /**
- * Creates a `RootNode`.
+ * Creates a `RootNode` with stable defaults for `schemas` and `operations`.
+ *
+ * @example
+ * ```ts
+ * const root = createRoot()
+ * // { kind: 'Root', schemas: [], operations: [] }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const root = createRoot({ schemas: [petSchema] })
+ * // keeps default operations: []
+ * ```
  */
 export function createRoot(overrides: Partial<Omit<RootNode, 'kind'>> = {}): RootNode {
   return {
@@ -18,7 +72,27 @@ export function createRoot(overrides: Partial<Omit<RootNode, 'kind'>> = {}): Roo
 }
 
 /**
- * Creates an `OperationNode`.
+ * Creates an `OperationNode` with default empty arrays for `tags`, `parameters`, and `responses`.
+ *
+ * @example
+ * ```ts
+ * const operation = createOperation({
+ *   operationId: 'getPetById',
+ *   method: 'GET',
+ *   path: '/pet/{petId}',
+ * })
+ * // tags, parameters, and responses are []
+ * ```
+ *
+ * @example
+ * ```ts
+ * const operation = createOperation({
+ *   operationId: 'findPets',
+ *   method: 'GET',
+ *   path: '/pet/findByStatus',
+ *   tags: ['pet'],
+ * })
+ * ```
  */
 export function createOperation(
   props: Pick<OperationNode, 'operationId' | 'method' | 'path'> & Partial<Omit<OperationNode, 'kind' | 'operationId' | 'method' | 'path'>>,
@@ -32,53 +106,293 @@ export function createOperation(
   }
 }
 
+/**
+ * Maps schema `type` to its underlying `primitive`.
+ * Primitive types map to themselves; special string formats map to `'string'`.
+ * Complex types (`ref`, `enum`, `union`, `intersection`, `tuple`, `blob`) are left unset.
+ */
+const TYPE_TO_PRIMITIVE: Partial<Record<SchemaNode['type'], PrimitiveSchemaType>> = {
+  string: 'string',
+  number: 'number',
+  integer: 'integer',
+  bigint: 'bigint',
+  boolean: 'boolean',
+  null: 'null',
+  any: 'any',
+  unknown: 'unknown',
+  void: 'void',
+  never: 'never',
+  object: 'object',
+  array: 'array',
+  date: 'date',
+  uuid: 'string',
+  email: 'string',
+  url: 'string',
+  datetime: 'string',
+  time: 'string',
+}
+
 /**
  * Creates a `SchemaNode`, narrowed to the variant of `props.type`.
- * For object schemas, `properties` defaults to `[]` when not provided.
+ * For object schemas, `properties` defaults to an empty array.
+ * `primitive` is automatically inferred from `type` when not explicitly provided.
+ *
+ * @example
+ * ```ts
+ * const scalar = createSchema({ type: 'string' })
+ * // { kind: 'Schema', type: 'string', primitive: 'string' }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const uuid = createSchema({ type: 'uuid' })
+ * // { kind: 'Schema', type: 'uuid', primitive: 'string' }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const object = createSchema({ type: 'object' })
+ * // { kind: 'Schema', type: 'object', primitive: 'object', properties: [] }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const enumSchema = createSchema({
+ *   type: 'enum',
+ *   primitive: 'string',
+ *   enumValues: ['available', 'pending'],
+ * })
+ * ```
  */
-export function createSchema<T extends Omit<ObjectSchemaNode, 'kind' | 'properties'> & { properties?: Array<PropertyNode> }>(
-  props: T,
-): Omit<T, 'properties'> & { properties: Array<PropertyNode>; kind: 'Schema' }
-export function createSchema<T extends DistributiveOmit<Exclude<SchemaNode, ObjectSchemaNode>, 'kind'>>(props: T): T & { kind: 'Schema' }
-export function createSchema(props: DistributiveOmit<SchemaNode, 'kind'>): SchemaNode
-export function createSchema(props: Record<string, unknown>): Record<string, unknown> {
+export function createSchema<T extends CreateSchemaInput>(props: T): CreateSchemaOutput<T>
+export function createSchema(props: CreateSchemaInput): SchemaNode
+export function createSchema(props: CreateSchemaInput): SchemaNode {
+  const inferredPrimitive = TYPE_TO_PRIMITIVE[props.type as keyof typeof TYPE_TO_PRIMITIVE]
+
   if (props['type'] === 'object') {
-    return { properties: [], ...props, kind: 'Schema' }
+    return { properties: [], primitive: 'object', ...props, kind: 'Schema' } as CreateSchemaOutput<typeof props>
   }
 
-  return { ...props, kind: 'Schema' }
+  return { primitive: inferredPrimitive, ...props, kind: 'Schema' } as CreateSchemaOutput<typeof props>
 }
 
 /**
- * Creates a `PropertyNode`. `required` defaults to `false`.
+ * Creates a `PropertyNode`.
+ *
+ * `required` defaults to `false`.
+ * `schema.optional` and `schema.nullish` are derived from `required` and `schema.nullable`.
+ *
+ * @example
+ * ```ts
+ * const property = createProperty({
+ *   name: 'status',
+ *   schema: createSchema({ type: 'string' }),
+ * })
+ * // required=false, schema.optional=true
+ * ```
+ *
+ * @example
+ * ```ts
+ * const property = createProperty({
+ *   name: 'status',
+ *   required: true,
+ *   schema: createSchema({ type: 'string', nullable: true }),
+ * })
+ * // required=true, no optional/nullish
+ * ```
  */
 export function createProperty(props: Pick<PropertyNode, 'name' | 'schema'> & Partial<Omit<PropertyNode, 'kind' | 'name' | 'schema'>>): PropertyNode {
+  const required = props.required ?? false
+
   return {
-    required: false,
     ...props,
     kind: 'Property',
+    required,
+    schema: syncOptionality(props.schema, required),
   }
 }
 
 /**
- * Creates a `ParameterNode`. `required` defaults to `false`.
+ * Creates a `ParameterNode`.
+ *
+ * `required` defaults to `false`.
+ * Nested schema flags are set from `required` and `schema.nullable`.
+ *
+ * @example
+ * ```ts
+ * const param = createParameter({
+ *   name: 'petId',
+ *   in: 'path',
+ *   required: true,
+ *   schema: createSchema({ type: 'string' }),
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * const param = createParameter({
+ *   name: 'status',
+ *   in: 'query',
+ *   schema: createSchema({ type: 'string', nullable: true }),
+ * })
+ * // required=false, schema.nullish=true
+ * ```
  */
 export function createParameter(
   props: Pick<ParameterNode, 'name' | 'in' | 'schema'> & Partial<Omit<ParameterNode, 'kind' | 'name' | 'in' | 'schema'>>,
 ): ParameterNode {
+  const required = props.required ?? false
   return {
-    required: false,
     ...props,
     kind: 'Parameter',
+    required,
+    schema: syncOptionality(props.schema, required),
   }
 }
 
 /**
  * Creates a `ResponseNode`.
+ *
+ * @example
+ * ```ts
+ * const response = createResponse({
+ *   statusCode: '200',
+ *   description: 'Success',
+ *   schema: createSchema({ type: 'object', properties: [] }),
+ * })
+ * ```
  */
-export function createResponse(props: Pick<ResponseNode, 'statusCode'> & Partial<Omit<ResponseNode, 'kind' | 'statusCode'>>): ResponseNode {
+export function createResponse(
+  props: Pick<ResponseNode, 'statusCode' | 'schema'> & Partial<Omit<ResponseNode, 'kind' | 'statusCode' | 'schema'>>,
+): ResponseNode {
   return {
     ...props,
     kind: 'Response',
   }
 }
+
+/**
+ * Creates a `FunctionParameterNode`.
+ *
+ * `optional` defaults to `false`.
+ *
+ * @example Required typed param
+ * ```ts
+ * createFunctionParameter({ name: 'petId', type: createTypeNode({ variant: 'reference', name: 'string' }) })
+ * // → petId: string
+ * ```
+ *
+ * @example Optional param
+ * ```ts
+ * createFunctionParameter({ name: 'params', type: createTypeNode({ variant: 'reference', name: 'QueryParams' }), optional: true })
+ * // → params?: QueryParams
+ * ```
+ *
+ * @example Param with default (implicitly optional; cannot combine with `optional: true`)
+ * ```ts
+ * createFunctionParameter({ name: 'config', type: createTypeNode({ variant: 'reference', name: 'RequestConfig' }), default: '{}' })
+ * // → config: RequestConfig = {}
+ * ```
+ */
+export function createFunctionParameter(
+  props: { name: string; type?: TypeNode; rest?: boolean } & ({ optional: true; default?: never } | { optional?: false; default?: string }),
+): FunctionParameterNode {
+  return {
+    optional: false,
+    ...props,
+    kind: 'FunctionParameter',
+  } as FunctionParameterNode
+}
+
+/**
+ * Creates a {@link TypeNode} representing a language-agnostic structured type expression.
+ *
+ * Use `variant: 'struct'` for inline anonymous types and `variant: 'member'` for a single
+ * named field accessed from a group type. Each language's printer renders the variant
+ * into its own syntax (TypeScript, Python, C#, Kotlin, …).
+ *
+ * @example Reference type (TypeScript: `QueryParams`)
+ * ```ts
+ * createTypeNode({ variant: 'reference', name: 'QueryParams' })
+ * ```
+ *
+ * @example Struct type (TypeScript: `{ petId: string }`)
+ * ```ts
+ * createTypeNode({ variant: 'struct', properties: [{ name: 'petId', optional: false, type: createTypeNode({ variant: 'reference', name: 'string' }) }] })
+ * ```
+ *
+ * @example Member type (TypeScript: `DeletePetPathParams['petId']`)
+ * ```ts
+ * createTypeNode({ variant: 'member', base: 'DeletePetPathParams', key: 'petId' })
+ * ```
+ */
+export function createTypeNode(
+  props:
+    | { variant: 'reference'; name: string }
+    | { variant: 'struct'; properties: Array<{ name: string; optional: boolean; type: TypeNode }> }
+    | { variant: 'member'; base: string; key: string },
+): TypeNode {
+  return { ...props, kind: 'Type' } as TypeNode
+}
+
+/**
+ * Creates a `ParameterGroupNode` representing a group of related parameters treated as a unit.
+ *
+ * @example Grouped param (TypeScript declaration)
+ * ```ts
+ * createParameterGroup({
+ *   properties: [
+ *     createFunctionParameter({ name: 'id', type: createTypeNode({ variant: 'reference', name: 'string' }), optional: false }),
+ *     createFunctionParameter({ name: 'name', type: createTypeNode({ variant: 'reference', name: 'string' }), optional: true }),
+ *   ],
+ *   default: '{}',
+ * })
+ * // declaration → { id, name? }: { id: string; name?: string } = {}
+ * // call        → { id, name }
+ * ```
+ *
+ * @example Inline (spread) — children emitted as individual top-level parameters
+ * ```ts
+ * createParameterGroup({
+ *   properties: [createFunctionParameter({ name: 'petId', type: createTypeNode({ variant: 'reference', name: 'string' }), optional: false })],
+ *   inline: true,
+ * })
+ * // declaration → petId: string
+ * // call        → petId
+ * ```
+ */
+export function createParameterGroup(
+  props: Pick<ParameterGroupNode, 'properties'> & Partial<Omit<ParameterGroupNode, 'kind' | 'properties'>>,
+): ParameterGroupNode {
+  return {
+    ...props,
+    kind: 'ParameterGroup',
+  }
+}
+
+/**
+ * Creates a `FunctionParametersNode` from an ordered list of parameters.
+ *
+ * @example
+ * ```ts
+ * createFunctionParameters({
+ *   params: [
+ *     createFunctionParameter({ name: 'petId', type: createTypeNode({ variant: 'reference', name: 'string' }), optional: false }),
+ *     createFunctionParameter({ name: 'config', type: createTypeNode({ variant: 'reference', name: 'RequestConfig' }), optional: false, default: '{}' }),
+ *   ],
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * const empty = createFunctionParameters()
+ * // { kind: 'FunctionParameters', params: [] }
+ * ```
+ */
+export function createFunctionParameters(props: Partial<Omit<FunctionParametersNode, 'kind'>> = {}): FunctionParametersNode {
+  return {
+    params: [],
+    ...props,
+    kind: 'FunctionParameters',
+  }
+}

package/src/guards.ts

@@ -1,7 +1,26 @@
-import type { Node, NodeKind, OperationNode, ParameterNode, PropertyNode, ResponseNode, RootNode, SchemaNode, SchemaNodeByType } from './nodes/index.ts'
+import type {
+  FunctionParameterNode,
+  FunctionParametersNode,
+  Node,
+  NodeKind,
+  OperationNode,
+  ParameterGroupNode,
+  ParameterNode,
+  PropertyNode,
+  ResponseNode,
+  RootNode,
+  SchemaNode,
+  SchemaNodeByType,
+} from './nodes/index.ts'
 
 /**
- * Narrows a `SchemaNode` to the specific variant matching `type`.
+ * Narrows a `SchemaNode` to the variant that matches `type`.
+ *
+ * @example
+ * ```ts
+ * const schema = createSchema({ type: 'string' })
+ * const stringNode = narrowSchema(schema, 'string') // StringSchemaNode | undefined
+ * ```
  */
 export function narrowSchema<T extends SchemaNode['type']>(node: SchemaNode | undefined, type: T): SchemaNodeByType[T] | undefined {
   return node?.type === type ? (node as SchemaNodeByType[T]) : undefined
@@ -12,31 +31,67 @@ function isKind<T extends Node>(kind: NodeKind) {
 }
 
 /**
- * Type guard for `RootNode`.
+ * Returns `true` when the input is a `RootNode`.
+ *
+ * @example
+ * ```ts
+ * if (isRootNode(node)) {
+ *   console.log(node.schemas.length)
+ * }
+ * ```
  */
 export const isRootNode = isKind<RootNode>('Root')
 
 /**
- * Type guard for `OperationNode`.
+ * Returns `true` when the input is an `OperationNode`.
+ *
+ * @example
+ * ```ts
+ * if (isOperationNode(node)) {
+ *   console.log(node.operationId)
+ * }
+ * ```
  */
 export const isOperationNode = isKind<OperationNode>('Operation')
 
 /**
- * Type guard for `SchemaNode`.
+ * Returns `true` when the input is a `SchemaNode`.
+ *
+ * @example
+ * ```ts
+ * if (isSchemaNode(node)) {
+ *   console.log(node.type)
+ * }
+ * ```
  */
 export const isSchemaNode = isKind<SchemaNode>('Schema')
 
 /**
- * Type guard for `PropertyNode`.
+ * Returns `true` when the input is a `PropertyNode`.
  */
 export const isPropertyNode = isKind<PropertyNode>('Property')
 
 /**
- * Type guard for `ParameterNode`.
+ * Returns `true` when the input is a `ParameterNode`.
  */
 export const isParameterNode = isKind<ParameterNode>('Parameter')
 
 /**
- * Type guard for `ResponseNode`.
+ * Returns `true` when the input is a `ResponseNode`.
  */
 export const isResponseNode = isKind<ResponseNode>('Response')
+
+/**
+ * Returns `true` when the input is a `FunctionParameterNode`.
+ */
+export const isFunctionParameterNode = isKind<FunctionParameterNode>('FunctionParameter')
+
+/**
+ * Returns `true` when the input is a `ParameterGroupNode`.
+ */
+export const isParameterGroupNode = isKind<ParameterGroupNode>('ParameterGroup')
+
+/**
+ * Returns `true` when the input is a `FunctionParametersNode`.
+ */
+export const isFunctionParametersNode = isKind<FunctionParametersNode>('FunctionParameters')