@kubb/ast 5.0.0-beta.20 → 5.0.0-beta.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/ast",
-  "version": "5.0.0-beta.20",
+  "version": "5.0.0-beta.21",
   "description": "Spec-agnostic AST layer for Kubb. Defines the node tree, visitor pattern, factory functions, and type guards used across all code generation plugins.",
   "keywords": [
     "ast",

package/src/guards.ts

@@ -20,11 +20,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) {

package/src/nodes/operation.ts

@@ -101,7 +101,7 @@ export type OperationNode = BaseNode & {
        * Property keys to exclude from the generated request body type via `Omit<Type, Keys>`.
        * Set when a referenced schema has `readOnly` fields that should be omitted in request types.
        */
-      keysToOmit?: Array<string>
+      keysToOmit?: Array<string> | null
     }>
   }
   /**

package/src/nodes/response.ts

@@ -39,5 +39,5 @@ export type ResponseNode = BaseNode & {
    * Property keys to exclude from the generated type via `Omit<Type, Keys>`.
    * Set when a referenced schema has `writeOnly` fields that should not appear in response types.
    */
-  keysToOmit?: Array<string>
+  keysToOmit?: Array<string> | null
 }

package/src/nodes/root.ts

@@ -30,7 +30,7 @@ export type InputMeta = {
   /**
    * Resolved base URL from the first matching server entry in the source document.
    */
-  baseURL?: string
+  baseURL?: string | null
   /**
    * Names of schemas that participate in a circular reference chain.
    * Computed once during the adapter pre-scan — use this instead of calling

package/src/nodes/schema.ts

@@ -368,8 +368,9 @@ export type RefSchemaNode = SchemaNodeBase & {
   type: 'ref'
   /**
    * Referenced schema name.
+   * `null` means Kubb has processed this and determined there is no applicable name.
    */
-  name?: string
+  name?: string | null
   /**
    * Original `$ref` path, for example, `#/components/schemas/Order`.
    * Used to resolve names later.
@@ -382,12 +383,13 @@ export type RefSchemaNode = SchemaNodeBase & {
   /**
    * The fully-parsed schema that this ref resolves to.
    * Populated during OAS parsing when the referenced definition can be resolved.
-   * `undefined` when the ref cannot be resolved or is part of a circular chain.
+   * `null` when the ref cannot be resolved or is part of a circular chain.
+   * `undefined` when resolution has not been attempted.
    *
    * Useful for inspecting the referenced schema's structure (e.g. `primitive`, `properties`)
    * without following the reference manually.
    */
-  schema?: SchemaNode
+  schema?: SchemaNode | null
 }
 
 /**

package/src/printer.ts

@@ -18,7 +18,7 @@ export type PrinterHandlerContext<TOutput, TOptions extends object> = {
    * Recursively transform a nested `SchemaNode` to `TOutput` using the node-level handlers.
    * Use `this.transform` inside `nodes` handlers and inside the `print` override.
    */
-  transform: (node: SchemaNode) => TOutput | null | undefined
+  transform: (node: SchemaNode) => TOutput | null
   /**
    * Options for this printer instance.
    */
@@ -40,7 +40,7 @@ export type PrinterHandlerContext<TOutput, TOptions extends object> = {
 export type PrinterHandler<TOutput, TOptions extends object, T extends SchemaType = SchemaType> = (
   this: PrinterHandlerContext<TOutput, TOptions>,
   node: SchemaNodeByType[T],
-) => TOutput | null | undefined
+) => TOutput | null
 
 /**
  * Partial map of per-node-type handler overrides for a printer.
@@ -108,13 +108,13 @@ export type Printer<T extends PrinterFactoryOptions = PrinterFactoryOptions> = {
    * Always dispatches through the `nodes` map; never calls the `print` override.
    * Use this when you need the raw output (e.g. `ts.TypeNode`) without declaration wrapping.
    */
-  transform: (node: SchemaNode) => T['output'] | null | undefined
+  transform: (node: SchemaNode) => T['output'] | null
   /**
    * Public printer. If the builder provides a root-level `print`, this calls that
    * higher-level function (which may produce full declarations).
    * Otherwise, falls back to the node-level dispatcher.
    */
-  print: (node: SchemaNode) => T['printOutput'] | null | undefined
+  print: (node: SchemaNode) => T['printOutput'] | null
 }
 
 /**
@@ -147,7 +147,6 @@ type PrinterBuilder<T extends PrinterFactoryOptions> = (options: T['options']) =
    */
   print?: (this: PrinterHandlerContext<T['output'], T['options']>, node: SchemaNode) => T['printOutput'] | null
 }
-
 /**
  * Creates a schema printer factory.
  *
@@ -194,7 +193,7 @@ export function definePrinter<T extends PrinterFactoryOptions = PrinterFactoryOp
  * )
  * ```
  */
-export function createPrinterFactory<TNode, TKey extends string, TNodeByKey extends Partial<Record<TKey, TNode>>>(getKey: (node: TNode) => TKey | undefined) {
+export function createPrinterFactory<TNode, TKey extends string, TNodeByKey extends Partial<Record<TKey, TNode>>>(getKey: (node: TNode) => TKey | null) {
   return function <T extends PrinterFactoryOptions>(
     build: (options: T['options']) => {
       name: T['name']
@@ -202,40 +201,40 @@ export function createPrinterFactory<TNode, TKey extends string, TNodeByKey exte
       nodes: Partial<{
         [K in TKey]: (
           this: {
-            transform: (node: TNode) => T['output'] | null | undefined
+            transform: (node: TNode) => T['output'] | null
             options: T['options']
           },
           node: TNodeByKey[K],
-        ) => T['output'] | null | undefined
+        ) => T['output'] | null
       }>
       print?: (
         this: {
-          transform: (node: TNode) => T['output'] | null | undefined
+          transform: (node: TNode) => T['output'] | null
           options: T['options']
         },
         node: TNode,
-      ) => T['printOutput'] | null | undefined
+      ) => T['printOutput'] | null
     },
   ): (options?: T['options']) => {
     name: T['name']
     options: T['options']
-    transform: (node: TNode) => T['output'] | null | undefined
-    print: (node: TNode) => T['printOutput'] | null | undefined
+    transform: (node: TNode) => T['output'] | null
+    print: (node: TNode) => T['printOutput'] | null
   } {
     return (options) => {
       const { name, options: resolvedOptions, nodes, print: printOverride } = build(options ?? ({} as T['options']))
 
       const context = {
         options: resolvedOptions,
-        transform: (node: TNode): T['output'] | null | undefined => {
+        transform: (node: TNode): T['output'] | null => {
           const key = getKey(node)
-          if (key === undefined) return null
+          if (key === null) return null
 
           const handler = nodes[key]
 
           if (!handler) return null
 
-          return (handler as (this: typeof context, node: TNode) => T['output'] | null | undefined).call(context, node)
+          return (handler as (this: typeof context, node: TNode) => T['output'] | null).call(context, node)
         },
       }
 
@@ -243,7 +242,7 @@ export function createPrinterFactory<TNode, TKey extends string, TNodeByKey exte
         name,
         options: resolvedOptions,
         transform: context.transform,
-        print: (printOverride ? printOverride.bind(context) : context.transform) as (node: TNode) => T['printOutput'] | null | undefined,
+        print: (printOverride ? printOverride.bind(context) : context.transform) as (node: TNode) => T['printOutput'] | null,
       }
     }
   }

package/src/refs.ts

@@ -45,13 +45,15 @@ export function buildRefMap(input: InputNode): RefMap {
 /**
  * Resolves a schema by name from a `RefMap`.
  *
+ * Returns `null` when the ref is not found.
+ *
  * @example
  * ```ts
  * const petSchema = resolveRef(refMap, 'Pet')
  * ```
  */
-export function resolveRef(refMap: RefMap, ref: string): SchemaNode | undefined {
-  return refMap.get(ref)
+export function resolveRef(refMap: RefMap, ref: string): SchemaNode | null {
+  return refMap.get(ref) ?? null
 }
 
 /**

package/src/resolvers.ts

@@ -27,17 +27,17 @@ export function collectImports<TImport>({
 }: {
   node: SchemaNode
   nameMapping: Map<string, string>
-  resolve: (schemaName: string) => TImport | undefined
+  resolve: (schemaName: string) => TImport | null
 }): Array<TImport> {
   return collect<TImport>(node, {
-    schema(schemaNode): TImport | undefined {
+    schema(schemaNode): TImport | null {
       const schemaRef = narrowSchema(schemaNode, 'ref')
-      if (!schemaRef?.ref) return
+      if (!schemaRef?.ref) return null
 
       const rawName = extractRefName(schemaRef.ref)
       const schemaName = nameMapping.get(rawName) ?? rawName
       const result = resolve(schemaName)
-      if (!result) return
+      if (!result) return null
 
       return result
     },

package/src/transformers.ts

@@ -150,7 +150,7 @@ export function setEnumName(propNode: SchemaNode, parentName: string | null | un
   const enumNode = narrowSchema(propNode, 'enum')
 
   if (enumNode?.primitive === 'boolean') {
-    return { ...propNode, name: undefined }
+    return { ...propNode, name: null }
   }
 
   if (enumNode) {

package/src/utils.ts

@@ -394,7 +394,7 @@ export function createOperationParams(node: OperationNode, options: CreateOperat
   } else {
     if (pathParams.length) {
       if (pathParamsType === 'inlineSpread') {
-        const spreadType = resolver?.resolvePathParamsName(node, pathParams[0]!) ?? undefined
+        const spreadType = resolver?.resolvePathParamsName(node, pathParams[0]!)
         params.push(
           createFunctionParameter({
             name: pathName,
@@ -476,7 +476,7 @@ function buildGroupParam({
   name: string
   node: OperationNode
   params: Array<ParameterNode>
-  groupType: ParamGroupType | undefined
+  groupType: ParamGroupType | null | undefined
   resolver: OperationParamsResolver | undefined
   wrapType: (type: string) => ParamsTypeNode
 }): Array<FunctionParameterNode> {
@@ -498,7 +498,7 @@ function buildGroupParam({
 
 /**
  * Derives a {@link ParamGroupType} from the resolver's group method.
- * Returns `undefined` when the group name equals the individual param name (no real group).
+ * Returns `null` when the group name equals the individual param name (no real group).
  */
 function resolveGroupType({
   node,
@@ -510,14 +510,14 @@ function resolveGroupType({
   params: Array<ParameterNode>
   groupMethod: (_node: OperationNode, _param: ParameterNode) => string
   resolver: OperationParamsResolver
-}): ParamGroupType | undefined {
+}): ParamGroupType | null {
   if (!params.length) {
-    return undefined
+    return null
   }
   const firstParam = params[0]!
   const groupName = groupMethod.call(resolver, node, firstParam)
   if (groupName === resolver.resolveParamName(node, firstParam)) {
-    return undefined
+    return null
   }
   const allOptional = params.every((p) => !p.required)
   return {
@@ -746,7 +746,7 @@ export function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): str
 /**
  * Resolves the schema name of a ref node, falling back through `ref` → `name` → nested `schema.name`.
  *
- * Returns `undefined` for non-ref nodes or when no name can be resolved. Use this to get a schema's
+ * Returns `null` for non-ref nodes or when no name can be resolved. Use this to get a schema's
  * identifier for type definitions or error messages.
  *
  * @example
@@ -755,11 +755,11 @@ export function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): str
  * // => 'Pet'
  * ```
  */
-export function resolveRefName(node: SchemaNode | undefined): string | undefined {
-  if (!node || node.type !== 'ref') return undefined
-  if (node.ref) return extractRefName(node.ref) ?? node.name ?? node.schema?.name ?? undefined
+export function resolveRefName(node: SchemaNode | undefined): string | null {
+  if (!node || node.type !== 'ref') return null
+  if (node.ref) return extractRefName(node.ref) ?? node.name ?? node.schema?.name ?? null
 
-  return node.name ?? node.schema?.name ?? undefined
+  return node.name ?? node.schema?.name ?? null
 }
 
 /**
@@ -926,9 +926,9 @@ export function containsCircularRef(
 
   for (const _ of collectLazy<true>(node, {
     schema(child) {
-      if (child.type !== 'ref') return undefined
+      if (child.type !== 'ref') return null
       const name = resolveRefName(child)
-      return name && name !== excludeName && circularSchemas.has(name) ? true : undefined
+      return name && name !== excludeName && circularSchemas.has(name) ? true : null
     },
   })) {
     return true

package/src/visitor.ts

@@ -176,13 +176,13 @@ export type AsyncVisitor = {
  * ```
  */
 export type CollectVisitor<T> = {
-  input?(node: InputNode, context: VisitorContext<InputNode>): T | undefined
-  output?(node: OutputNode, context: VisitorContext<OutputNode>): 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
+  input?(node: InputNode, context: VisitorContext<InputNode>): T | null | undefined
+  output?(node: OutputNode, context: VisitorContext<OutputNode>): T | null | undefined
+  operation?(node: OperationNode, context: VisitorContext<OperationNode>): T | null | undefined
+  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): T | null | undefined
+  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): T | null | undefined
+  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): T | null | undefined
+  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): T | null | undefined
 }
 
 /**
@@ -487,7 +487,7 @@ export function transform(node: Node, options: TransformOptions): Node {
 /**
  * Runs a depth-first synchronous collection pass.
  *
- * Non-`undefined` values returned by visitor callbacks are appended to the result.
+ * Non-`null` values returned by visitor callbacks are appended to the result.
  *
  * @example
  * ```ts
@@ -508,7 +508,7 @@ export function* collectLazy<T>(node: Node, options: CollectOptions<T>): Generat
   const { depth, parent, ...visitor } = options
   const recurse = (depth ?? visitorDepths.deep) === visitorDepths.deep
 
-  let v: T | undefined
+  let v: T | null | undefined
   switch (node.kind) {
     case 'Input':
       v = visitor.input?.(node, { parent: parent as ParentOf<InputNode> })
@@ -532,7 +532,7 @@ export function* collectLazy<T>(node: Node, options: CollectOptions<T>): Generat
       v = visitor.response?.(node, { parent: parent as ParentOf<ResponseNode> })
       break
   }
-  if (v !== undefined) yield v
+  if (v != null) yield v
 
   for (const child of getChildren(node, recurse)) {
     yield* collectLazy(child, { ...options, parent: node })