@kubb/ast 5.0.0-alpha.12 → 5.0.0-alpha.14

package/dist/{visitor-C73H2CCg.d.ts → visitor-UlWOe-In.d.ts}

@@ -529,6 +529,10 @@ type OperationNode = BaseNode & {
    * Request body for OAS operations. Bundles the schema with optional keys to exclude.
    */
   requestBody?: {
+    /**
+     * Human-readable description of the request body (maps to `requestBody.description` in OAS).
+     */
+    description?: string;
     /**
      * The request body schema. For OAS, this is the schema of the first content entry.
      */
@@ -619,12 +623,19 @@ declare function createSchema<T extends DistributiveOmit<Exclude<SchemaNode, Obj
   kind: 'Schema';
 };
 declare function createSchema(props: DistributiveOmit<SchemaNode, 'kind'>): SchemaNode;
+/**
+ * Derives `schema.optional` and `schema.nullish` from `required` and `schema.nullable`.
+ * This keeps `PropertyNode.required` as the single source of truth for optionality.
+ */
+declare function syncPropertySchema(required: boolean, schema: SchemaNode): SchemaNode;
 /**
  * Creates a `PropertyNode`. `required` defaults to `false`.
+ * `schema.optional` and `schema.nullish` are auto-derived from `required` and `schema.nullable`.
  */
 declare function createProperty(props: Pick<PropertyNode, 'name' | 'schema'> & Partial<Omit<PropertyNode, 'kind' | 'name' | 'schema'>>): PropertyNode;
 /**
  * Creates a `ParameterNode`. `required` defaults to `false`.
+ * `schema.optional` is auto-derived from `required` and `schema.nullable`.
  */
 declare function createParameter(props: Pick<ParameterNode, 'name' | 'in' | 'schema'> & Partial<Omit<ParameterNode, 'kind' | 'name' | 'in' | 'schema'>>): ParameterNode;
 /**
@@ -848,69 +859,103 @@ declare function refMapToObject(refMap: RefMap): Record<string, SchemaNode>;
 //#endregion
 //#region src/visitor.d.ts
 /**
- * Shared options for `walk`, `transform`, and `collect`.
+ * Single source of truth: ordered list of `[NodeType, ParentType]` pairs
+ * describing which node types can be the parent of a given node in the AST.
+ *
+ * `ParentOf` walks this tuple and returns the parent type of the first matching entry.
  */
-type VisitorOptions = {
-  depth?: VisitorDepth;
-  /**
-   * Maximum number of sibling nodes visited concurrently inside `walk`.
-   * @default 30
-   */
-  concurrency?: number;
+type ParentNodeMap = [[RootNode, undefined], [OperationNode, RootNode], [SchemaNode, RootNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode], [PropertyNode, SchemaNode], [ParameterNode, OperationNode], [ResponseNode, OperationNode]];
+type ParentOf<T extends Node, TEntries extends ReadonlyArray<[Node, unknown]> = ParentNodeMap> = TEntries extends [infer TEntry extends [Node, unknown], ...infer TRest extends ReadonlyArray<[Node, unknown]>] ? T extends TEntry[0] ? TEntry[1] : ParentOf<T, TRest> : Node;
+/**
+ * Traversal context passed as the second argument to every visitor callback.
+ * The `parent` field is narrowed based on the node type being visited.
+ */
+type VisitorContext<T extends Node = Node> = {
+  parent?: ParentOf<T>;
 };
 /**
  * Synchronous visitor for `transform` and `walk`.
  */
 type Visitor = {
-  root?(node: RootNode): void | RootNode;
-  operation?(node: OperationNode): void | OperationNode;
-  schema?(node: SchemaNode): void | SchemaNode;
-  property?(node: PropertyNode): void | PropertyNode;
-  parameter?(node: ParameterNode): void | ParameterNode;
-  response?(node: ResponseNode): void | ResponseNode;
+  root?(node: RootNode, context: VisitorContext<RootNode>): void | RootNode;
+  operation?(node: OperationNode, context: VisitorContext<OperationNode>): void | OperationNode;
+  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): void | SchemaNode;
+  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): void | PropertyNode;
+  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): void | ParameterNode;
+  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): void | ResponseNode;
 };
 type MaybePromise<T> = T | Promise<T>;
 /**
  * Async visitor for `walk`. Synchronous `Visitor` objects are compatible.
  */
 type AsyncVisitor = {
-  root?(node: RootNode): MaybePromise<void | RootNode>;
-  operation?(node: OperationNode): MaybePromise<void | OperationNode>;
-  schema?(node: SchemaNode): MaybePromise<void | SchemaNode>;
-  property?(node: PropertyNode): MaybePromise<void | PropertyNode>;
-  parameter?(node: ParameterNode): MaybePromise<void | ParameterNode>;
-  response?(node: ResponseNode): MaybePromise<void | ResponseNode>;
+  root?(node: RootNode, context: VisitorContext<RootNode>): MaybePromise<void | RootNode>;
+  operation?(node: OperationNode, context: VisitorContext<OperationNode>): MaybePromise<void | OperationNode>;
+  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): MaybePromise<void | SchemaNode>;
+  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): MaybePromise<void | PropertyNode>;
+  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): MaybePromise<void | ParameterNode>;
+  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): MaybePromise<void | ResponseNode>;
 };
 /**
  * Visitor for `collect`.
  */
 type CollectVisitor<T> = {
-  root?(node: RootNode): T | undefined;
-  operation?(node: OperationNode): T | undefined;
-  schema?(node: SchemaNode): T | undefined;
-  property?(node: PropertyNode): T | undefined;
-  parameter?(node: ParameterNode): T | undefined;
-  response?(node: ResponseNode): T | undefined;
+  root?(node: RootNode, context: VisitorContext<RootNode>): T | undefined;
+  operation?(node: OperationNode, context: VisitorContext<OperationNode>): T | undefined;
+  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): T | undefined;
+  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): T | undefined;
+  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): T | undefined;
+  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): T | undefined;
+};
+/**
+ * Options for `transform` and `collect`. Extends `Visitor` with traversal settings.
+ */
+type TransformOptions = Visitor & {
+  depth?: VisitorDepth;
+  parent?: Node;
+};
+/**
+ * Options for `walk`. Extends `AsyncVisitor` with traversal settings.
+ */
+type WalkOptions = AsyncVisitor & {
+  depth?: VisitorDepth;
+  /**
+   * Maximum number of sibling nodes visited concurrently.
+   * @default 30
+   */
+  concurrency?: number;
+};
+/**
+ * Options for `collect`. Extends `CollectVisitor` with traversal settings.
+ */
+type CollectOptions<T> = CollectVisitor<T> & {
+  depth?: VisitorDepth;
+  parent?: Node;
 };
 /**
  * Depth-first traversal for side effects. Visitor return values are ignored.
  * Sibling nodes at each level are visited concurrently up to `options.concurrency` (default: 30).
  */
-declare function walk(node: Node, visitor: AsyncVisitor, options?: VisitorOptions): Promise<void>;
+declare function walk(node: Node, options: WalkOptions): Promise<void>;
 /**
  * Depth-first immutable transformation. Visitor return values replace nodes; `undefined` keeps the original.
  */
-declare function transform(node: RootNode, visitor: Visitor, options?: VisitorOptions): RootNode;
-declare function transform(node: OperationNode, visitor: Visitor, options?: VisitorOptions): OperationNode;
-declare function transform(node: SchemaNode, visitor: Visitor, options?: VisitorOptions): SchemaNode;
-declare function transform(node: PropertyNode, visitor: Visitor, options?: VisitorOptions): PropertyNode;
-declare function transform(node: ParameterNode, visitor: Visitor, options?: VisitorOptions): ParameterNode;
-declare function transform(node: ResponseNode, visitor: Visitor, options?: VisitorOptions): ResponseNode;
-declare function transform(node: Node, visitor: Visitor, options?: VisitorOptions): Node;
+declare function transform(node: RootNode, options: TransformOptions): RootNode;
+declare function transform(node: OperationNode, options: TransformOptions): OperationNode;
+declare function transform(node: SchemaNode, options: TransformOptions): SchemaNode;
+declare function transform(node: PropertyNode, options: TransformOptions): PropertyNode;
+declare function transform(node: ParameterNode, options: TransformOptions): ParameterNode;
+declare function transform(node: ResponseNode, options: TransformOptions): ResponseNode;
+declare function transform(node: Node, options: TransformOptions): Node;
+/**
+ * Combines multiple visitors into a single visitor that applies them sequentially (left to right).
+ * For each node kind, the output of one visitor becomes the input of the next.
+ */
+declare function composeTransformers(...visitors: Array<Visitor>): Visitor;
 /**
  * Depth-first synchronous reduction. Collects non-`undefined` visitor return values into an array.
  */
-declare function collect<T>(node: Node, visitor: CollectVisitor<T>, options?: VisitorOptions): Array<T>;
+declare function collect<T>(node: Node, options: CollectOptions<T>): Array<T>;
 //#endregion
-export { TimeSchemaNode as $, HttpStatusCode as A, EnumValueNode as B, createSchema as C, HttpMethod as D, RootNode as E, ArraySchemaNode as F, RefSchemaNode as G, NumberSchemaNode as H, ComplexSchemaType as I, SchemaNode as J, ScalarSchemaNode as K, DateSchemaNode as L, StatusCode as M, ParameterLocation as N, OperationNode as O, ParameterNode as P, StringSchemaNode as Q, DatetimeSchemaNode as R, createRoot as S, RootMeta as T, ObjectSchemaNode as U, IntersectionSchemaNode as V, PrimitiveSchemaType as W, SchemaType as X, SchemaNodeByType as Y, SpecialSchemaType as Z, createObjectBindingParameter as _, transform as a, FunctionParameterNode as at, createProperty as b, buildRefMap as c, BaseNode as ct, Printer as d, httpMethods as dt, UnionSchemaNode as et, PrinterFactoryOptions as f, mediaTypes as ft, createFunctionParameters as g, createFunctionParameter as h, collect as i, FunctionNodeType as it, MediaType as j, ResponseNode as k, refMapToObject as l, NodeKind as lt, DistributiveOmit as m, schemaTypes as mt, CollectVisitor as n, PropertyNode as nt, walk as o, FunctionParametersNode as ot, definePrinter as p, nodeKinds as pt, ScalarSchemaType as q, Visitor as r, FunctionNode as rt, RefMap as s, ObjectBindingParameterNode as st, AsyncVisitor as t, UrlSchemaNode as tt, resolveRef as u, VisitorDepth as ut, createOperation as v, Node as w, createResponse as x, createParameter as y, EnumSchemaNode as z };
-//# sourceMappingURL=visitor-C73H2CCg.d.ts.map
+export { ScalarSchemaNode as $, syncPropertySchema as A, ParameterLocation as B, createObjectBindingParameter as C, createResponse as D, createProperty as E, OperationNode as F, DatetimeSchemaNode as G, ArraySchemaNode as H, ResponseNode as I, IntersectionSchemaNode as J, EnumSchemaNode as K, HttpStatusCode as L, RootMeta as M, RootNode as N, createRoot as O, HttpMethod as P, RefSchemaNode as Q, MediaType as R, createFunctionParameters as S, createParameter as T, ComplexSchemaType as U, ParameterNode as V, DateSchemaNode as W, ObjectSchemaNode as X, NumberSchemaNode as Y, PrimitiveSchemaType as Z, Printer as _, VisitorDepth as _t, TransformOptions as a, StringSchemaNode as at, DistributiveOmit as b, nodeKinds as bt, WalkOptions as c, UrlSchemaNode as ct, transform as d, FunctionNodeType as dt, ScalarSchemaType as et, walk as f, FunctionParameterNode as ft, resolveRef as g, NodeKind as gt, refMapToObject as h, BaseNode as ht, ParentOf as i, SpecialSchemaType as it, Node as j, createSchema as k, collect as l, PropertyNode as lt, buildRefMap as m, ObjectBindingParameterNode as mt, CollectOptions as n, SchemaNodeByType as nt, Visitor as o, TimeSchemaNode as ot, RefMap as p, FunctionParametersNode as pt, EnumValueNode as q, CollectVisitor as r, SchemaType as rt, VisitorContext as s, UnionSchemaNode as st, AsyncVisitor as t, SchemaNode as tt, composeTransformers as u, FunctionNode as ut, PrinterFactoryOptions as v, httpMethods as vt, createOperation as w, createFunctionParameter as x, schemaTypes as xt, definePrinter as y, mediaTypes as yt, StatusCode as z };
+//# sourceMappingURL=visitor-UlWOe-In.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/ast",
-  "version": "5.0.0-alpha.12",
+  "version": "5.0.0-alpha.14",
   "description": "Spec-agnostic AST layer for Kubb. Defines nodes, visitor pattern, and factory functions used across codegen plugins.",
   "keywords": [
     "kubb",

package/src/factory.ts

@@ -60,27 +60,48 @@ export function createSchema(props: Record<string, unknown>): Record<string, unk
   return { ...props, kind: 'Schema' }
 }
 
+/**
+ * Derives `schema.optional` and `schema.nullish` from `required` and `schema.nullable`.
+ * This keeps `PropertyNode.required` as the single source of truth for optionality.
+ */
+export function syncPropertySchema(required: boolean, schema: SchemaNode): SchemaNode {
+  const nullable = schema.nullable ?? false
+
+  return {
+    ...schema,
+    optional: !required && !nullable ? true : undefined,
+    nullish: !required && nullable ? true : undefined,
+  }
+}
+
 /**
  * Creates a `PropertyNode`. `required` defaults to `false`.
+ * `schema.optional` and `schema.nullish` are auto-derived from `required` and `schema.nullable`.
  */
 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: syncPropertySchema(required, props.schema),
   }
 }
 
 /**
  * Creates a `ParameterNode`. `required` defaults to `false`.
+ * `schema.optional` is auto-derived from `required` and `schema.nullable`.
  */
 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: syncPropertySchema(required, props.schema),
   }
 }
 

package/src/index.ts

@@ -9,6 +9,7 @@ export {
   createResponse,
   createRoot,
   createSchema,
+  syncPropertySchema,
 } from './factory.ts'
 export { functionPrinter } from './functionPrinter.ts'
 export {
@@ -26,4 +27,4 @@ export {
 export { definePrinter } from './printer.ts'
 export { buildRefMap, refMapToObject, resolveRef } from './refs.ts'
 export { applyParamsCasing, isPlainStringType } from './utils.ts'
-export { collect, transform, walk } from './visitor.ts'
+export { collect, composeTransformers, transform, walk } from './visitor.ts'

package/src/nodes/operation.ts

@@ -29,6 +29,10 @@ export type OperationNode = BaseNode & {
    * Request body for OAS operations. Bundles the schema with optional keys to exclude.
    */
   requestBody?: {
+    /**
+     * Human-readable description of the request body (maps to `requestBody.description` in OAS).
+     */
+    description?: string
     /**
      * The request body schema. For OAS, this is the schema of the first content entry.
      */

package/src/types.ts

@@ -44,4 +44,4 @@ export type {
 } from './nodes/index.ts'
 export type { Printer, PrinterFactoryOptions } from './printer.ts'
 export type { RefMap } from './refs.ts'
-export type { AsyncVisitor, CollectVisitor, Visitor } from './visitor.ts'
+export type { AsyncVisitor, CollectOptions, CollectVisitor, ParentOf, TransformOptions, Visitor, VisitorContext, WalkOptions } from './visitor.ts'