@kubb/ast 5.0.0-beta.4 → 5.0.0-beta.40

package/src/factory.ts

@@ -6,14 +6,20 @@ import type {
   ArrowFunctionNode,
   BreakNode,
   ConstNode,
+  ContentNode,
   ExportNode,
   FileNode,
   FunctionNode,
   FunctionParameterNode,
   FunctionParametersNode,
+  GenericOperationNode,
+  HttpOperationNode,
   ImportNode,
+  InputMeta,
   InputNode,
+  InputStreamNode,
   JsxNode,
+  Node,
   ObjectSchemaNode,
   OperationNode,
   OutputNode,
@@ -22,6 +28,7 @@ import type {
   ParamsTypeNode,
   PrimitiveSchemaType,
   PropertyNode,
+  RequestBodyNode,
   ResponseNode,
   SchemaNode,
   SourceNode,
@@ -31,10 +38,13 @@ import type {
 import { combineExports, combineImports, combineSources, extractStringsFromNodes } from './utils.ts'
 
 /**
- * Syncs property/parameter schema optionality flags from `required` and `schema.nullable`.
+ * Updates a schema's `optional` and `nullish` flags from a parent's `required`
+ * value and the schema's own `nullable`. Mirrors how OpenAPI parameters and
+ * object properties combine "required" and "nullable" into a single AST.
  *
- * - `optional` is set for non-required, non-nullable schemas.
- * - `nullish` is set for non-required, nullable schemas.
+ * - Non-required + non-nullable → `optional: true`.
+ * - Non-required + nullable → `nullish: true`.
+ * - Required → both flags cleared.
  */
 export function syncOptionality(schema: SchemaNode, required: boolean): SchemaNode {
   const nullable = schema.nullable ?? false
@@ -59,6 +69,32 @@ export function syncOptionality(schema: SchemaNode, required: boolean): SchemaNo
  */
 export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never
 
+/**
+ * Identity-preserving node update: returns `node` unchanged when every field in
+ * `changes` already equals (by reference) the current value, otherwise a new node
+ * with the changes applied.
+ *
+ * Mirrors the TypeScript compiler's `factory.updateX` contract, pair it with the
+ * structural sharing in {@link transform} so a no-op rewrite doesn't allocate and
+ * downstream passes can detect "nothing changed" by identity. Comparison is
+ * shallow: a structurally-equal but newly-allocated array/object counts as a change.
+ *
+ * @example
+ * ```ts
+ * update(node, { name: node.name })        // -> same `node` reference
+ * update(node, { name: 'renamed' })        // -> new node, `name` replaced
+ * ```
+ */
+export function update<T extends Node>(node: T, changes: Partial<T>): T {
+  for (const key in changes) {
+    if (changes[key] !== node[key as keyof T]) {
+      return { ...node, ...changes }
+    }
+  }
+
+  return node
+}
+
 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> & {
@@ -84,11 +120,24 @@ export function createInput(overrides: Partial<Omit<InputNode, 'kind'>> = {}): I
   return {
     schemas: [],
     operations: [],
+    meta: { circularNames: [], enumNames: [] },
     ...overrides,
     kind: 'Input',
   }
 }
 
+/**
+ * Creates an `InputStreamNode` from pre-built `AsyncIterable` sources.
+ *
+ * @example
+ * ```ts
+ * const node = createStreamInput(schemasIterable, operationsIterable, { title: 'My API' })
+ * ```
+ */
+export function createStreamInput(schemas: AsyncIterable<SchemaNode>, operations: AsyncIterable<OperationNode>, meta?: InputMeta): InputStreamNode {
+  return { kind: 'Input', schemas, operations, meta }
+}
+
 /**
  * Creates an `OutputNode` with a stable default for `files`.
  *
@@ -134,21 +183,75 @@ export function createOutput(overrides: Partial<Omit<OutputNode, 'kind'>> = {}):
  * })
  * ```
  */
+/**
+ * Loosely-typed content entry accepted by the builders, normalized into a {@link ContentNode}.
+ */
+type UserContent = Omit<ContentNode, 'kind'>
+
+/**
+ * Creates a `ContentNode` for a single request-body or response content type.
+ */
+export function createContent(props: UserContent): ContentNode {
+  return {
+    ...props,
+    kind: 'Content',
+  }
+}
+
+/**
+ * Loosely-typed request body accepted by `createOperation`, normalized into a {@link RequestBodyNode}.
+ */
+type UserRequestBody = Omit<RequestBodyNode, 'kind' | 'content'> & {
+  content?: Array<UserContent>
+}
+
+/**
+ * Creates a `RequestBodyNode`, normalizing each content entry into a `ContentNode`.
+ */
+export function createRequestBody(props: UserRequestBody): RequestBodyNode {
+  return {
+    ...props,
+    kind: 'RequestBody',
+    content: props.content?.map(createContent),
+  }
+}
+
+export function createOperation(
+  props: Pick<HttpOperationNode, 'operationId' | 'method' | 'path'> &
+    Partial<Omit<HttpOperationNode, 'kind' | 'operationId' | 'method' | 'path' | 'requestBody'>> & {
+      requestBody?: UserRequestBody
+    },
+): HttpOperationNode
 export function createOperation(
-  props: Pick<OperationNode, 'operationId' | 'method' | 'path'> & Partial<Omit<OperationNode, 'kind' | 'operationId' | 'method' | 'path'>>,
-): OperationNode {
+  props: Pick<GenericOperationNode, 'operationId'> &
+    Partial<Omit<GenericOperationNode, 'kind' | 'operationId' | 'requestBody'>> & {
+      requestBody?: UserRequestBody
+    },
+): GenericOperationNode
+export function createOperation(props: {
+  operationId: string
+  method?: HttpOperationNode['method']
+  path?: HttpOperationNode['path']
+  requestBody?: UserRequestBody
+  [key: string]: unknown
+}): OperationNode {
+  const { requestBody, ...rest } = props
+  const isHttp = rest.method !== undefined && rest.path !== undefined
+
   return {
     tags: [],
     parameters: [],
     responses: [],
-    ...props,
+    ...rest,
+    ...(isHttp ? { protocol: 'http' } : {}),
     kind: 'Operation',
-  }
+    requestBody: requestBody ? createRequestBody(requestBody) : undefined,
+  } as OperationNode
 }
 
 /**
  * Maps schema `type` to its underlying `primitive`.
- * Primitive types map to themselves; special string formats map to `'string'`.
+ * 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>> = {
@@ -304,21 +407,34 @@ export function createParameter(
 /**
  * Creates a `ResponseNode`.
  *
+ * Response body schemas live inside `content`. For convenience a single legacy `schema`
+ * (with optional `mediaType`/`keysToOmit`) is normalized into one `content` entry, so the same
+ * schema is never stored both at the node root and inside `content`.
+ *
  * @example
  * ```ts
  * const response = createResponse({
  *   statusCode: '200',
- *   description: 'Success',
- *   schema: createSchema({ type: 'object', properties: [] }),
+ *   content: [{ contentType: 'application/json', schema: createSchema({ type: 'object', properties: [] }) }],
  * })
  * ```
  */
 export function createResponse(
-  props: Pick<ResponseNode, 'statusCode' | 'schema'> & Partial<Omit<ResponseNode, 'kind' | 'statusCode' | 'schema'>>,
+  props: Pick<ResponseNode, 'statusCode'> &
+    Partial<Omit<ResponseNode, 'kind' | 'statusCode' | 'content'>> & {
+      content?: Array<UserContent>
+      schema?: SchemaNode
+      mediaType?: string | null
+      keysToOmit?: Array<string> | null
+    },
 ): ResponseNode {
+  const { schema, mediaType, keysToOmit, content, ...rest } = props
+  const entries = content ?? (schema ? [{ contentType: mediaType ?? 'application/json', schema, keysToOmit: keysToOmit ?? null }] : undefined)
+
   return {
-    ...props,
+    ...rest,
     kind: 'Response',
+    content: entries?.map(createContent),
   }
 }
 
@@ -339,7 +455,7 @@ export function createResponse(
  * // → params?: QueryParams
  * ```
  *
- * @example Param with default (implicitly optional; cannot combine with `optional: true`)
+ * @example Param with default (implicitly optional. Cannot combine with `optional: true`)
  * ```ts
  * createFunctionParameter({ name: 'config', type: createParamsType({ variant: 'reference', name: 'RequestConfig' }), default: '{}' })
  * // → config: RequestConfig = {}
@@ -409,7 +525,7 @@ export function createParamsType(
  * // call        → { id, name }
  * ```
  *
- * @example Inline (spread) — children emitted as individual top-level parameters
+ * @example Inline (spread), children emitted as individual top-level parameters
  * ```ts
  * createParameterGroup({
  *   properties: [createFunctionParameter({ name: 'petId', type: createParamsType({ variant: 'reference', name: 'string' }), optional: false })],
@@ -512,9 +628,9 @@ export type UserFileNode<TMeta extends object = object> = Omit<FileNode<TMeta>,
  * Creates a fully resolved `FileNode` from a file input descriptor.
  *
  * Computes:
- * - `id` — SHA256 hash of the file path
- * - `name` — `baseName` without extension
- * - `extname` — extension extracted from `baseName`
+ * - `id` SHA256 hash of the file path
+ * - `name` `baseName` without extension
+ * - `extname` extension extracted from `baseName`
  *
  * Deduplicates:
  * - `sources` via `combineSources`

package/src/guards.ts

@@ -1,18 +1,4 @@
-import type {
-  FunctionParameterNode,
-  FunctionParametersNode,
-  InputNode,
-  Node,
-  NodeKind,
-  OperationNode,
-  OutputNode,
-  ParameterGroupNode,
-  ParameterNode,
-  PropertyNode,
-  ResponseNode,
-  SchemaNode,
-  SchemaNodeByType,
-} from './nodes/index.ts'
+import type { HttpOperationNode, InputNode, Node, NodeKind, OperationNode, OutputNode, SchemaNode, SchemaNodeByType } from './nodes/index.ts'
 
 /**
  * Narrows a `SchemaNode` to the variant that matches `type`.
@@ -20,11 +6,11 @@ import type {
  * @example
  * ```ts
  * const schema = createSchema({ type: 'string' })
- * const stringNode = narrowSchema(schema, 'string') // StringSchemaNode | undefined
+ * const stringNode = narrowSchema(schema, 'string') // StringSchemaNode | null
  * ```
  */
-export function narrowSchema<T extends SchemaNode['type']>(node: SchemaNode | undefined, type: T): SchemaNodeByType[T] | undefined {
-  return node?.type === type ? (node as SchemaNodeByType[T]) : undefined
+export function narrowSchema<T extends SchemaNode['type']>(node: SchemaNode | undefined, type: T): SchemaNodeByType[T] | null {
+  return node?.type === type ? (node as SchemaNodeByType[T]) : null
 }
 
 function isKind<T extends Node>(kind: NodeKind) {
@@ -67,6 +53,20 @@ export const isOutputNode = isKind<OutputNode>('Output')
  */
 export const isOperationNode = isKind<OperationNode>('Operation')
 
+/**
+ * Narrows an `OperationNode` to an `HttpOperationNode`, guaranteeing `method` and `path`.
+ *
+ * @example
+ * ```ts
+ * if (isHttpOperationNode(node)) {
+ *   console.log(node.method, node.path)
+ * }
+ * ```
+ */
+export function isHttpOperationNode(node: OperationNode): node is HttpOperationNode {
+  return node.protocol === 'http' || (node.method !== undefined && node.path !== undefined)
+}
+
 /**
  * Returns `true` when the input is a `SchemaNode`.
  *
@@ -78,33 +78,3 @@ export const isOperationNode = isKind<OperationNode>('Operation')
  * ```
  */
 export const isSchemaNode = isKind<SchemaNode>('Schema')
-
-/**
- * Returns `true` when the input is a `PropertyNode`.
- */
-export const isPropertyNode = isKind<PropertyNode>('Property')
-
-/**
- * Returns `true` when the input is a `ParameterNode`.
- */
-export const isParameterNode = isKind<ParameterNode>('Parameter')
-
-/**
- * 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')

package/src/index.ts

@@ -1,4 +1,7 @@
-export { httpMethods, isScalarPrimitive, mediaTypes, nodeKinds, schemaTypes } from './constants.ts'
+export { httpMethods, schemaTypes } from './constants.ts'
+export { applyDedupe, buildDedupePlan } from './dedupe.ts'
+export { defineSchemaDialect } from './dialect.ts'
+export { dispatch } from './dispatch.ts'
 export {
   createArrowFunction,
   createBreak,
@@ -10,6 +13,7 @@ export {
   createFunctionParameters,
   createImport,
   createInput,
+  createStreamInput,
   createJsx,
   createOperation,
   createOutput,
@@ -23,16 +27,17 @@ export {
   createText,
   createType,
   syncOptionality,
+  update,
 } from './factory.ts'
-export { isInputNode, isOperationNode, isOutputNode, isSchemaNode, narrowSchema } from './guards.ts'
+export { isHttpOperationNode, isInputNode, isOperationNode, isOutputNode, isSchemaNode, narrowSchema } from './guards.ts'
 export { createPrinterFactory, definePrinter } from './printer.ts'
 export { extractRefName } from './refs.ts'
 export { childName, collectImports, enumPropName, findDiscriminator } from './resolvers.ts'
-export { mergeAdjacentObjects, setDiscriminatorEnum, setEnumName, simplifyUnion } from './transformers.ts'
+export { schemaSignature } from './signature.ts'
+export { mergeAdjacentObjectsLazy, setDiscriminatorEnum, setEnumName, simplifyUnion } from './transformers.ts'
 export type * from './types.ts'
 export {
   caseParams,
-  collectReferencedSchemaNames,
   collectUsedSchemaNames,
   containsCircularRef,
   createDiscriminantNode,
@@ -40,7 +45,6 @@ export {
   extractStringsFromNodes,
   findCircularSchemas,
   isStringType,
-  resolveRefName,
   syncSchemaRef,
 } from './utils.ts'
 export { collect, transform, walk } from './visitor.ts'

package/src/infer.ts

@@ -20,15 +20,25 @@ import type {
  */
 export type ParserOptions = {
   /**
-   * How `format: 'date-time'` schemas are represented. `false` falls through to a plain string.
+   * How `format: 'date-time'` schemas are represented downstream.
+   * - `false` falls through to a plain `string` (no validation).
+   * - `'string'` emits a datetime string node.
+   * - `'stringOffset'` emits a datetime node with timezone offset.
+   * - `'stringLocal'` emits a local datetime node.
+   * - `'date'` emits a `date` node (JavaScript `Date` object).
    */
   dateType: false | 'string' | 'stringOffset' | 'stringLocal' | 'date'
   /**
-   * Whether `type: 'integer'` and `format: 'int64'` produce `number` or `bigint` nodes.
+   * How `type: 'integer'` (and `format: 'int64'`) maps to TypeScript.
+   * - `'number'` fits most JSON APIs. Loses precision above `Number.MAX_SAFE_INTEGER`.
+   * - `'bigint'` is exact for 64-bit IDs, but does not round-trip through JSON.
+   *
+   * @default 'number'
    */
   integerType?: 'number' | 'bigint'
   /**
-   * AST type used when no schema type can be inferred.
+   * AST type used when a schema's type cannot be inferred from the spec
+   * (`additionalProperties: true`, missing `type`, ...).
    */
   unknownType: 'any' | 'unknown' | 'void'
   /**
@@ -36,7 +46,8 @@ export type ParserOptions = {
    */
   emptySchemaType: 'any' | 'unknown' | 'void'
   /**
-   * Suffix appended to derived enum names when building property schema names.
+   * Suffix appended to derived enum names when Kubb has to invent one
+   * (typically for inline enums on object properties).
    */
   enumSuffix: 'enum' | (string & {})
 }
@@ -66,7 +77,7 @@ type ResolveDateTimeNode<TDateType extends ParserOptions['dateType']> = DateTime
 type SchemaNodeMap<TDateType extends ParserOptions['dateType'] = 'string'> = [
   [{ $ref: string }, RefSchemaNode],
   [{ allOf: ReadonlyArray<unknown>; properties: object }, IntersectionSchemaNode],
-  [{ allOf: readonly [unknown, unknown, ...unknown[]] }, IntersectionSchemaNode],
+  [{ allOf: readonly [unknown, unknown, ...Array<unknown>] }, IntersectionSchemaNode],
   [{ allOf: ReadonlyArray<unknown> }, SchemaNode],
   [{ oneOf: ReadonlyArray<unknown> }, UnionSchemaNode],
   [{ anyOf: ReadonlyArray<unknown> }, UnionSchemaNode],
@@ -119,12 +130,3 @@ export type InferSchemaNode<
     ? TEntry[1]
     : InferSchemaNode<TSchema, TDateType, TRest>
   : SchemaNode
-
-/**
- * Backward-compatible alias for `InferSchemaNode`.
- */
-export type InferSchema<
-  TSchema extends object,
-  TDateType extends ParserOptions['dateType'] = 'string',
-  TEntries extends ReadonlyArray<[object, SchemaNode]> = SchemaNodeMap<TDateType>,
-> = InferSchemaNode<TSchema, TDateType, TEntries>

package/src/nodes/base.ts

@@ -14,6 +14,8 @@ export type NodeKind =
   | 'Property'
   | 'Parameter'
   | 'Response'
+  | 'RequestBody'
+  | 'Content'
   | 'FunctionParameter'
   | 'ParameterGroup'
   | 'FunctionParameters'

package/src/nodes/code.ts

@@ -36,21 +36,21 @@ export type ConstNode = BaseNode & {
    * Whether the declaration should be exported.
    * @default false
    */
-  export?: boolean
+  export?: boolean | null
   /**
    * Optional explicit type annotation.
    * @example 'Pet'
    */
-  type?: string
+  type?: string | null
   /**
    * JSDoc documentation metadata.
    */
-  JSDoc?: JSDocNode
+  JSDoc?: JSDocNode | null
   /**
    * Whether to append `as const` to the declaration.
    * @default false
    */
-  asConst?: boolean
+  asConst?: boolean | null
   /**
    * Child nodes representing the value of the constant (children of the `Const` component).
    * Each entry is a {@link CodeNode}; use {@link TextNode} for raw string content.
@@ -83,11 +83,11 @@ export type TypeNode = BaseNode & {
    * Whether the declaration should be exported.
    * @default false
    */
-  export?: boolean
+  export?: boolean | null
   /**
    * JSDoc documentation metadata.
    */
-  JSDoc?: JSDocNode
+  JSDoc?: JSDocNode | null
   /**
    * Child nodes representing the type body (children of the `Type` component).
    * Each entry is a {@link CodeNode}; use {@link TextNode} for raw string content.
@@ -126,35 +126,35 @@ export type FunctionNode = BaseNode & {
    * Whether the function is a default export.
    * @default false
    */
-  default?: boolean
+  default?: boolean | null
   /**
    * Function parameter list rendered as a string (e.g. from `FunctionParams.toConstructor()`).
    */
-  params?: string
+  params?: string | null
   /**
    * Whether the function should be exported.
    * @default false
    */
-  export?: boolean
+  export?: boolean | null
   /**
    * Whether the function is async. When `true`, the return type is wrapped in `Promise<>`.
    * @default false
    */
-  async?: boolean
+  async?: boolean | null
   /**
    * TypeScript generic type parameters.
    * @example ['T', 'U extends string']
    */
-  generics?: string | string[]
+  generics?: string | Array<string> | null
   /**
    * Return type annotation.
    * @example 'Pet'
    */
-  returnType?: string
+  returnType?: string | null
   /**
    * JSDoc documentation metadata.
    */
-  JSDoc?: JSDocNode
+  JSDoc?: JSDocNode | null
   /**
    * Child nodes representing the function body (children of the `Function` component).
    * Each entry is a {@link CodeNode}; use {@link TextNode} for raw string content.
@@ -187,40 +187,40 @@ export type ArrowFunctionNode = BaseNode & {
    * Whether the function is a default export.
    * @default false
    */
-  default?: boolean
+  default?: boolean | null
   /**
    * Function parameter list rendered as a string (e.g. from `FunctionParams.toConstructor()`).
    */
-  params?: string
+  params?: string | null
   /**
    * Whether the arrow function should be exported.
    * @default false
    */
-  export?: boolean
+  export?: boolean | null
   /**
    * Whether the arrow function is async. When `true`, the return type is wrapped in `Promise<>`.
    * @default false
    */
-  async?: boolean
+  async?: boolean | null
   /**
    * TypeScript generic type parameters.
    * @example ['T', 'U extends string']
    */
-  generics?: string | string[]
+  generics?: string | Array<string> | null
   /**
    * Return type annotation.
    * @example 'Pet'
    */
-  returnType?: string
+  returnType?: string | null
   /**
    * JSDoc documentation metadata.
    */
-  JSDoc?: JSDocNode
+  JSDoc?: JSDocNode | null
   /**
    * Render the arrow function body as a single-line expression.
    * @default false
    */
-  singleLine?: boolean
+  singleLine?: boolean | null
   /**
    * Child nodes representing the function body (children of the `Function.Arrow` component).
    * Each entry is a {@link CodeNode}; use {@link TextNode} for raw string content.
@@ -255,7 +255,7 @@ export type TextNode = BaseNode & {
  * AST node representing a line break in the source output.
  *
  * Corresponds to `<br/>` in JSX components. When printed, produces an empty
- * string that — joined with `\n` by `printNodes` — creates a blank line
+ * string that, joined with `\n` by `printNodes` creates a blank line
  * between surrounding code nodes.
  *
  * @example

package/src/nodes/content.ts

@@ -0,0 +1,37 @@
+import type { BaseNode } from './base.ts'
+import type { SchemaNode } from './schema.ts'
+
+/**
+ * AST node representing one content-type entry of a request body or response.
+ *
+ * One entry per content type declared in the spec (e.g. `application/json`,
+ * `multipart/form-data`), each carrying its own body schema.
+ *
+ * @example
+ * ```ts
+ * const content: ContentNode = {
+ *   kind: 'Content',
+ *   contentType: 'application/json',
+ *   schema: createSchema({ type: 'string' }),
+ * }
+ * ```
+ */
+export type ContentNode = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'Content'
+  /**
+   * The content type for this entry (e.g. `'application/json'`).
+   */
+  contentType: string
+  /**
+   * Body schema for this content type.
+   */
+  schema?: SchemaNode
+  /**
+   * Property keys to exclude from the generated type via `Omit<Type, Keys>`.
+   * Set when a referenced schema has `readOnly`/`writeOnly` fields that should be omitted.
+   */
+  keysToOmit?: Array<string> | null
+}