@kubb/ast 5.0.0-beta.63 → 5.0.0-beta.64

package/src/nodes/index.ts

@@ -1,93 +0,0 @@
-import type { ArrowFunctionNode, ConstNode, FunctionNode, TypeNode } from './code.ts'
-import type { ContentNode } from './content.ts'
-import type { ExportNode, FileNode, ImportNode, SourceNode } from './file.ts'
-import type { FunctionParamNode } from './function.ts'
-import type { InputNode } from './input.ts'
-import type { OperationNode } from './operation.ts'
-import type { OutputNode } from './output.ts'
-import type { ParameterNode } from './parameter.ts'
-import type { PropertyNode } from './property.ts'
-import type { RequestBodyNode } from './requestBody.ts'
-import type { ResponseNode } from './response.ts'
-import type { SchemaNode } from './schema.ts'
-
-export type { NodeKind } from './base.ts'
-export type { ArrowFunctionNode, BreakNode, CodeNode, ConstNode, FunctionNode, JSDocNode, JsxNode, TextNode, TypeNode } from './code.ts'
-export type { ContentNode } from './content.ts'
-export type { ExportNode, FileNode, ImportNode, SourceNode, UserFileNode } from './file.ts'
-export type {
-  FunctionParamKind,
-  FunctionParameterNode,
-  FunctionParametersNode,
-  FunctionParamNode,
-  IndexedAccessTypeNode,
-  ObjectBindingPatternNode,
-  TypeExpression,
-  TypeLiteralNode,
-} from './function.ts'
-export type { InputMeta, InputNode } from './input.ts'
-export type { GenericOperationNode, HttpMethod, HttpOperationNode, OperationNode } from './operation.ts'
-export type { OutputNode } from './output.ts'
-export type { ParameterLocation, ParameterNode } from './parameter.ts'
-export type { PropertyNode } from './property.ts'
-export type { RequestBodyNode } from './requestBody.ts'
-export type { ResponseNode, StatusCode } from './response.ts'
-export type {
-  ArraySchemaNode,
-  DateSchemaNode,
-  DatetimeSchemaNode,
-  EnumSchemaNode,
-  IntersectionSchemaNode,
-  NumberSchemaNode,
-  ObjectSchemaNode,
-  PrimitiveSchemaType,
-  RefSchemaNode,
-  ScalarSchemaNode,
-  ScalarSchemaType,
-  SchemaNode,
-  SchemaNodeByType,
-  SchemaType,
-  StringSchemaNode,
-  TimeSchemaNode,
-  UnionSchemaNode,
-  UrlSchemaNode,
-} from './schema.ts'
-
-/**
- * Union of all AST node types.
- *
- * This lets TypeScript narrow types in `switch (node.kind)` blocks.
- *
- * @example
- * ```ts
- * function getKind(node: Node): string {
- *   switch (node.kind) {
- *     case 'Input':
- *       return 'input'
- *     case 'Output':
- *       return 'output'
- *     default:
- *       return 'other'
- *   }
- * }
- * ```
- */
-export type Node =
-  | InputNode
-  | OutputNode
-  | OperationNode
-  | SchemaNode
-  | PropertyNode
-  | ParameterNode
-  | ResponseNode
-  | RequestBodyNode
-  | ContentNode
-  | FunctionParamNode
-  | FileNode
-  | ImportNode
-  | ExportNode
-  | SourceNode
-  | ConstNode
-  | TypeNode
-  | FunctionNode
-  | ArrowFunctionNode

package/src/nodes/input.ts

@@ -1,144 +0,0 @@
-import type { Streamable } from '@internals/utils'
-import { defineNode } from '../defineNode.ts'
-import type { BaseNode } from './base.ts'
-import type { OperationNode } from './operation.ts'
-import type { SchemaNode } from './schema.ts'
-
-/**
- * Metadata for an API document, populated by the adapter and available to every generator.
- *
- * All fields are plain JSON-serializable values, no `Set`, no `Map`, no class instances.
- * Computed fields (`circularNames`, `enumNames`) are pre-calculated once during the adapter
- * pre-scan so generators never need to iterate the full schema list themselves.
- *
- * @example
- * ```ts
- * const meta: InputMeta = { title: 'Pet Store', version: '1.0.0', baseURL: 'https://petstore.swagger.io/v2', circularNames: [], enumNames: [] }
- * ```
- */
-export type InputMeta = {
-  /**
-   * API title from `info.title` in the source document.
-   */
-  title?: string
-  /**
-   * API description from `info.description` in the source document.
-   */
-  description?: string
-  /**
-   * API version string from `info.version` in the source document.
-   */
-  version?: string
-  /**
-   * Resolved base URL from the first matching server entry in the source document.
-   */
-  baseURL?: string | null
-  /**
-   * Names of schemas that participate in a circular reference chain.
-   * Computed once during the adapter pre-scan, so a generator never has to
-   * call `findCircularSchemas` itself.
-   *
-   * Convert to a `Set` once at the start of a generator, not per-schema,
-   * so lookups stay O(1) without repeated allocations.
-   *
-   * @example Wrap a circular schema in z.lazy()
-   * ```ts
-   * const circular = new Set(meta.circularNames)
-   * if (circular.has(schema.name)) { ... }
-   * ```
-   */
-  circularNames: ReadonlyArray<string>
-  /**
-   * Names of schemas whose type is `enum`.
-   * Computed once during the adapter pre-scan, so a generator never has to
-   * filter the schema list itself.
-   *
-   * Convert to a `Set` once at the start of a generator when you need repeated
-   * membership checks, so each check stays O(1) instead of an array scan.
-   *
-   * @example Check if a referenced schema is an enum
-   * `const enums = new Set(meta.enumNames)`
-   * `const isEnum = enums.has(schemaName)`
-   */
-  enumNames: ReadonlyArray<string>
-}
-
-/**
- * Input AST node that contains all schemas and operations for one API document.
- * Produced by the adapter and consumed by all Kubb plugins.
- *
- * `Stream` switches `schemas` and `operations` between eager `Array`s (the default) and lazy
- * `AsyncIterable`s. The streaming variant `InputNode<true>` yields nodes one at a time.
- *
- * @example
- * ```ts
- * const input: InputNode = {
- *   kind: 'Input',
- *   schemas: [],
- *   operations: [],
- *   meta: { circularNames: [], enumNames: [] },
- * }
- * ```
- *
- * @example Streaming variant for large specs
- * ```ts
- * for await (const schema of inputNode.schemas) {
- *   // only this one SchemaNode is live here. Previous ones are GC-eligible
- * }
- * ```
- */
-export type InputNode<Stream extends boolean = false> = BaseNode & {
-  /**
-   * Node kind.
-   */
-  kind: 'Input'
-  /**
-   * All schema nodes in the document.
-   */
-  schemas: Streamable<SchemaNode, Stream>
-  /**
-   * All operation nodes in the document.
-   */
-  operations: Streamable<OperationNode, Stream>
-  /**
-   * Document metadata populated by the adapter.
-   */
-  meta: InputMeta
-}
-
-/**
- * Definition for the {@link InputNode}.
- */
-export const inputDef = defineNode<InputNode, Partial<Omit<InputNode, 'kind'>>>({
-  kind: 'Input',
-  defaults: { schemas: [], operations: [], meta: { circularNames: [], enumNames: [] } },
-  children: ['schemas', 'operations'],
-  visitorKey: 'input',
-})
-
-/**
- * Creates an `InputNode`. Pass `stream: true` for the streaming variant whose `schemas` and
- * `operations` are `AsyncIterable` sources. Otherwise it builds the eager variant with array
- * `schemas`/`operations`. Both variants get the defaulted `meta`.
- *
- * @example Eager
- * ```ts
- * const input = createInput()
- * // { kind: 'Input', schemas: [], operations: [] }
- * ```
- *
- * @example Streaming
- * ```ts
- * const node = createInput({ stream: true, schemas: schemasIterable, operations: operationsIterable, meta: { title: 'My API' } })
- * ```
- */
-export function createInput<Stream extends boolean = false>(options: Partial<Omit<InputNode<Stream>, 'kind'>> & { stream?: Stream } = {}): InputNode<Stream> {
-  const { stream, ...overrides } = options
-  // Streaming inputs carry AsyncIterable sources, so skip the array defaults that
-  // inputDef.create applies for the eager variant. Keep the meta default.
-  if (stream) {
-    return { kind: 'Input', meta: { circularNames: [], enumNames: [] }, ...overrides } as InputNode<Stream>
-  }
-
-  return inputDef.create(overrides as Partial<Omit<InputNode, 'kind'>>) as InputNode<Stream>
-}

package/src/nodes/operation.ts

@@ -1,168 +0,0 @@
-import { defineNode } from '../defineNode.ts'
-import type { BaseNode } from './base.ts'
-import type { ParameterNode } from './parameter.ts'
-import { createRequestBody, type RequestBodyNode } from './requestBody.ts'
-import type { ResponseNode } from './response.ts'
-
-/**
- * HTTP method an operation responds to.
- */
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE'
-
-/**
- * Transport an operation belongs to.
- */
-type OperationProtocol = 'http'
-
-/**
- * Fields shared by every operation, regardless of transport.
- */
-type OperationNodeBase = BaseNode & {
-  /**
-   * Node kind.
-   */
-  kind: 'Operation'
-  /**
-   * Operation identifier, usually from OpenAPI `operationId`.
-   */
-  operationId: 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
-  /**
-   * Query, path, header, and cookie parameters for the operation.
-   */
-  parameters: Array<ParameterNode>
-  /**
-   * Request body for the operation.
-   */
-  requestBody?: RequestBodyNode
-  /**
-   * Operation responses.
-   */
-  responses: Array<ResponseNode>
-}
-
-/**
- * Operation served over HTTP/REST (OpenAPI). `method` and `path` are guaranteed.
- *
- * @example
- * ```ts
- * const operation: HttpOperationNode = {
- *   kind: 'Operation',
- *   operationId: 'listPets',
- *   protocol: 'http',
- *   method: 'GET',
- *   path: '/pets',
- *   tags: [],
- *   parameters: [],
- *   responses: [],
- * }
- * ```
- */
-export type HttpOperationNode = OperationNodeBase & {
-  /**
-   * Transport the operation belongs to.
-   */
-  protocol?: 'http'
-  /**
-   * HTTP method like `'GET'`.
-   */
-  method: HttpMethod
-  /**
-   * OpenAPI-style path string, for example `/pets/{petId}`, with `{param}` notation preserved.
-   */
-  path: string
-}
-
-/**
- * Operation for a non-HTTP transport. HTTP-only fields are forbidden.
- */
-export type GenericOperationNode = OperationNodeBase & {
-  /**
-   * Transport the operation belongs to.
-   */
-  protocol?: Exclude<OperationProtocol, 'http'>
-  method?: never
-  path?: never
-}
-
-/**
- * AST node representing one API operation.
- *
- * Discriminated on `protocol`: an {@link HttpOperationNode} (`protocol: 'http'`) guarantees
- * `method` and `path`, while a {@link GenericOperationNode} omits them. Narrow with
- * `isHttpOperationNode(node)` or `node.protocol === 'http'` before reading `method`/`path`.
- */
-export type OperationNode = HttpOperationNode | GenericOperationNode
-
-type OperationInput = {
-  operationId: string
-  method?: HttpOperationNode['method']
-  path?: HttpOperationNode['path']
-  requestBody?: Omit<RequestBodyNode, 'kind'>
-  [key: string]: unknown
-}
-
-/**
- * Definition for the {@link OperationNode}. HTTP operations (those carrying both
- * `method` and `path`) are tagged with `protocol: 'http'`, and the request body is
- * normalized into a `RequestBodyNode`.
- */
-export const operationDef = defineNode<OperationNode, OperationInput>({
-  kind: 'Operation',
-  build: (props) => {
-    const { requestBody, ...rest } = props
-    const isHttp = rest.method !== undefined && rest.path !== undefined
-
-    return {
-      tags: [],
-      parameters: [],
-      responses: [],
-      ...rest,
-      ...(isHttp ? { protocol: 'http' as const } : {}),
-      requestBody: requestBody ? createRequestBody(requestBody) : undefined,
-    }
-  },
-  children: ['parameters', 'requestBody', 'responses'],
-  visitorKey: 'operation',
-})
-
-/**
- * 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 []
- * ```
- */
-export function createOperation(
-  props: Pick<HttpOperationNode, 'operationId' | 'method' | 'path'> &
-    Partial<Omit<HttpOperationNode, 'kind' | 'operationId' | 'method' | 'path' | 'requestBody'>> & {
-      requestBody?: Omit<RequestBodyNode, 'kind'>
-    },
-): HttpOperationNode
-export function createOperation(
-  props: Pick<GenericOperationNode, 'operationId'> &
-    Partial<Omit<GenericOperationNode, 'kind' | 'operationId' | 'requestBody'>> & {
-      requestBody?: Omit<RequestBodyNode, 'kind'>
-    },
-): GenericOperationNode
-export function createOperation(props: OperationInput): OperationNode {
-  return operationDef.create(props)
-}

package/src/nodes/output.ts

@@ -1,49 +0,0 @@
-import { defineNode } from '../defineNode.ts'
-import type { BaseNode } from './base.ts'
-import type { FileNode } from './file.ts'
-
-/**
- * Output AST node that groups all generated file output for one API document.
- *
- * Produced by generators and consumed by the build pipeline to write files.
- *
- * @example
- * ```ts
- * const output: OutputNode = {
- *   kind: 'Output',
- *   files: [],
- * }
- * ```
- */
-export type OutputNode = BaseNode & {
-  /**
-   * Node kind.
-   */
-  kind: 'Output'
-  /**
-   * Generated file nodes.
-   */
-  files: Array<FileNode>
-}
-
-/**
- * Definition for the {@link OutputNode}.
- */
-export const outputDef = defineNode<OutputNode, Partial<Omit<OutputNode, 'kind'>>>({
-  kind: 'Output',
-  defaults: { files: [] },
-  visitorKey: 'output',
-})
-
-/**
- * Creates an `OutputNode` with a stable default for `files`.
- *
- * @example
- * ```ts
- * const output = createOutput()
- * // { kind: 'Output', files: [] }
- * ```
- */
-export function createOutput(overrides: Partial<Omit<OutputNode, 'kind'>> = {}): OutputNode {
-  return outputDef.create(overrides)
-}

package/src/nodes/parameter.ts

@@ -1,71 +0,0 @@
-import { defineNode } from '../defineNode.ts'
-import { optionality } from '../optionality.ts'
-import type { BaseNode } from './base.ts'
-import type { SchemaNode } from './schema.ts'
-
-export type ParameterLocation = 'path' | 'query' | 'header' | 'cookie'
-
-/**
- * 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 & {
-  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
-}
-
-type UserParameterNode = Pick<ParameterNode, 'name' | 'in' | 'schema'> & Partial<Omit<ParameterNode, 'kind' | 'name' | 'in' | 'schema'>>
-
-/**
- * Definition for the {@link ParameterNode}. `required` defaults to `false`, and the schema's
- * `optional`/`nullish` flags are derived from it through {@link optionality}.
- */
-export const parameterDef = defineNode<ParameterNode, UserParameterNode>({
-  kind: 'Parameter',
-  build: (props) => {
-    const required = props.required ?? false
-    return { ...props, required, schema: optionality(props.schema, required) }
-  },
-  children: ['schema'],
-  visitorKey: 'parameter',
-})
-
-/**
- * Creates a `ParameterNode`.
- *
- * @example
- * ```ts
- * const param = createParameter({
- *   name: 'petId',
- *   in: 'path',
- *   required: true,
- *   schema: createSchema({ type: 'string' }),
- * })
- * ```
- */
-export const createParameter = parameterDef.create

package/src/nodes/property.ts

@@ -1,67 +0,0 @@
-import { defineNode } from '../defineNode.ts'
-import { optionality } from '../optionality.ts'
-import type { BaseNode } from './base.ts'
-import type { SchemaNode } from './schema.ts'
-
-/**
- * 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 & {
-  kind: 'Property'
-  /**
-   * Property key.
-   */
-  name: string
-  /**
-   * Property schema.
-   */
-  schema: SchemaNode
-  /**
-   * Whether the property is required.
-   */
-  required: boolean
-}
-
-/**
- * Loosely-typed property accepted by `createProperty`, with `required` optional.
- */
-export type UserPropertyNode = Pick<PropertyNode, 'name' | 'schema'> & Partial<Omit<PropertyNode, 'kind' | 'name' | 'schema'>>
-
-/**
- * Definition for the {@link PropertyNode}. `required` defaults to `false`, and the schema's
- * `optional`/`nullish` flags are derived from it through {@link optionality}.
- */
-export const propertyDef = defineNode<PropertyNode, UserPropertyNode>({
-  kind: 'Property',
-  build: (props) => {
-    const required = props.required ?? false
-    return { ...props, required, schema: optionality(props.schema, required) }
-  },
-  children: ['schema'],
-  visitorKey: 'property',
-})
-
-/**
- * Creates a `PropertyNode`.
- *
- * @example
- * ```ts
- * const property = createProperty({
- *   name: 'status',
- *   required: true,
- *   schema: createSchema({ type: 'string', nullable: true }),
- * })
- * // required=true, no optional/nullish
- * ```
- */
-export const createProperty = propertyDef.create

package/src/nodes/requestBody.ts

@@ -1,54 +0,0 @@
-import { defineNode } from '../defineNode.ts'
-import type { BaseNode } from './base.ts'
-import type { ContentNode } from './content.ts'
-
-/**
- * AST node representing an operation request body.
- *
- * Body schemas live exclusively inside the `content` array (one entry per content type),
- * mirroring {@link ResponseNode}.
- *
- * @example
- * ```ts
- * const requestBody: RequestBodyNode = {
- *   kind: 'RequestBody',
- *   required: true,
- *   content: [{ kind: 'Content', contentType: 'application/json', schema: createSchema({ type: 'string' }) }],
- * }
- * ```
- */
-export type RequestBodyNode = BaseNode & {
-  kind: 'RequestBody'
-  /**
-   * Request body description carried over from the spec.
-   */
-  description?: string
-  /**
-   * Whether the request body is required (`requestBody.required: true` in the spec).
-   * When `false` or absent, the generated `data` parameter should be optional.
-   */
-  required?: boolean
-  /**
-   * Content type entries for this request body.
-   *
-   * When the adapter `contentType` option is set, this array contains exactly one entry for
-   * that content type. Otherwise it contains one entry per content type declared in the spec,
-   * so plugins can generate code for every variant (for example, separate hooks for
-   * `application/json` and `multipart/form-data`).
-   */
-  content?: Array<ContentNode>
-}
-
-/**
- * Definition for the {@link RequestBodyNode}. Content entries are built upfront with
- * {@link createContent}, mirroring how `parameters` and `responses` take prebuilt nodes.
- */
-export const requestBodyDef = defineNode<RequestBodyNode>({
-  kind: 'RequestBody',
-  children: ['content'],
-})
-
-/**
- * Creates a `RequestBodyNode`.
- */
-export const createRequestBody = requestBodyDef.create