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

package/dist/index.d.ts

@@ -729,12 +729,14 @@ type FileNode<TMeta extends object = object> = BaseNode & {
   meta?: TMeta;
   /**
    * Optional banner prepended to the generated file content.
+   * Accepts `null` so `resolver.resolveBanner()` results can be passed directly.
    */
-  banner?: string;
+  banner?: string | null;
   /**
    * Optional footer appended to the generated file content.
+   * Accepts `null` so `resolver.resolveFooter()` results can be passed directly.
    */
-  footer?: string;
+  footer?: string | null;
 };
 //#endregion
 //#region src/nodes/function.d.ts
@@ -1326,8 +1328,9 @@ 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.
@@ -1340,12 +1343,13 @@ 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;
 };
 /**
  * Datetime schema.
@@ -1693,7 +1697,7 @@ 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;
 };
 //#endregion
 //#region src/nodes/operation.d.ts
@@ -1794,7 +1798,7 @@ 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;
     }>;
   };
   /**
@@ -1857,7 +1861,7 @@ 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
@@ -2657,10 +2661,10 @@ declare function createJsx(value: string): JsxNode;
  * @example
  * ```ts
  * const schema = createSchema({ type: 'string' })
- * const stringNode = narrowSchema(schema, 'string') // StringSchemaNode | undefined
+ * const stringNode = narrowSchema(schema, 'string') // StringSchemaNode | null
  * ```
  */
-declare function narrowSchema<T extends SchemaNode['type']>(node: SchemaNode | undefined, type: T): SchemaNodeByType[T] | undefined;
+declare function narrowSchema<T extends SchemaNode['type']>(node: SchemaNode | undefined, type: T): SchemaNodeByType[T] | null;
 /**
  * Returns `true` when the input is an `InputNode`.
  *
@@ -2725,7 +2729,7 @@ 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.
    */
@@ -2743,7 +2747,7 @@ type PrinterHandlerContext<TOutput, TOptions extends object> = {
  * }
  * ```
  */
-type PrinterHandler<TOutput, TOptions extends object, T extends SchemaType = SchemaType> = (this: PrinterHandlerContext<TOutput, TOptions>, node: SchemaNodeByType[T]) => TOutput | null | undefined;
+type PrinterHandler<TOutput, TOptions extends object, T extends SchemaType = SchemaType> = (this: PrinterHandlerContext<TOutput, TOptions>, node: SchemaNodeByType[T]) => TOutput | null;
 /**
  * Partial map of per-node-type handler overrides for a printer.
  *
@@ -2806,13 +2810,13 @@ 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;
 };
 /**
  * Builder function passed to `definePrinter`.
@@ -2885,22 +2889,22 @@ declare function definePrinter<T extends PrinterFactoryOptions = PrinterFactoryO
  * )
  * ```
  */
-declare function createPrinterFactory<TNode, TKey extends string, TNodeByKey extends Partial<Record<TKey, TNode>>>(getKey: (node: TNode) => TKey | undefined): <T extends PrinterFactoryOptions>(build: (options: T["options"]) => {
+declare function createPrinterFactory<TNode, TKey extends string, TNodeByKey extends Partial<Record<TKey, TNode>>>(getKey: (node: TNode) => TKey | null): <T extends PrinterFactoryOptions>(build: (options: T["options"]) => {
   name: T["name"];
   options: T["options"];
   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 }>;
+  }, node: TNodeByKey[K]) => 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;
+  }, node: TNode) => 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;
 };
 //#endregion
 //#region src/refs.d.ts
@@ -2934,7 +2938,7 @@ declare function collectImports<TImport>({
 }: {
   node: SchemaNode;
   nameMapping: Map<string, string>;
-  resolve: (schemaName: string) => TImport | undefined;
+  resolve: (schemaName: string) => TImport | null;
 }): Array<TImport>;
 //#endregion
 //#region src/transformers.d.ts
@@ -3103,13 +3107,13 @@ type AsyncVisitor = {
  * ```
  */
 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;
 };
 /**
  * Options for `transform`.
@@ -3228,7 +3232,7 @@ declare 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
@@ -3430,7 +3434,7 @@ declare function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): st
 /**
  * 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
@@ -3439,7 +3443,7 @@ declare function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): st
  * // => 'Pet'
  * ```
  */
-declare function resolveRefName(node: SchemaNode | undefined): string | undefined;
+declare function resolveRefName(node: SchemaNode | undefined): string | null;
 declare function collectReferencedSchemaNames(node: SchemaNode | undefined, out?: Set<string>): Set<string>;
 declare function collectUsedSchemaNames(operations: ReadonlyArray<OperationNode>, schemas: ReadonlyArray<SchemaNode>): Set<string>;
 /**

package/dist/index.js

@@ -432,11 +432,11 @@ function trimExtName(text) {
 * @example
 * ```ts
 * const schema = createSchema({ type: 'string' })
-* const stringNode = narrowSchema(schema, 'string') // StringSchemaNode | undefined
+* const stringNode = narrowSchema(schema, 'string') // StringSchemaNode | null
 * ```
 */
 function narrowSchema(node, type) {
-	return node?.type === type ? node : void 0;
+	return node?.type === type ? node : null;
 }
 function isKind(kind) {
 	return (node) => node.kind === kind;
@@ -727,7 +727,7 @@ function transform(node, options) {
 /**
 * 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
@@ -771,7 +771,7 @@ function* collectLazy(node, options) {
 			v = visitor.response?.(node, { parent });
 			break;
 	}
-	if (v !== void 0) yield v;
+	if (v != null) yield v;
 	for (const child of getChildren(node, recurse)) yield* collectLazy(child, {
 		...options,
 		parent: node
@@ -970,7 +970,7 @@ function createOperationParams(node, options) {
 		}));
 	} else {
 		if (pathParams.length) if (pathParamsType === "inlineSpread") {
-			const spreadType = resolver?.resolvePathParamsName(node, pathParams[0]) ?? void 0;
+			const spreadType = resolver?.resolvePathParamsName(node, pathParams[0]);
 			params.push(createFunctionParameter({
 				name: pathName,
 				type: spreadType ? wrapType(spreadType) : void 0,
@@ -1046,13 +1046,13 @@ function buildGroupParam({ name, node, params, groupType, resolver, wrapType })
 }
 /**
 * 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, params, groupMethod, resolver }) {
-	if (!params.length) return;
+	if (!params.length) return null;
 	const firstParam = params[0];
 	const groupName = groupMethod.call(resolver, node, firstParam);
-	if (groupName === resolver.resolveParamName(node, firstParam)) return;
+	if (groupName === resolver.resolveParamName(node, firstParam)) return null;
 	const allOptional = params.every((p) => !p.required);
 	return {
 		type: createParamsType({
@@ -1245,7 +1245,7 @@ function extractStringsFromNodes(nodes) {
 /**
 * 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
@@ -1255,9 +1255,9 @@ function extractStringsFromNodes(nodes) {
 * ```
 */
 function resolveRefName(node) {
-	if (!node || node.type !== "ref") return void 0;
-	if (node.ref) return extractRefName(node.ref) ?? node.name ?? node.schema?.name ?? void 0;
-	return node.name ?? node.schema?.name ?? void 0;
+	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 ?? null;
 }
 /**
 * Collects every named schema referenced (transitively) from a node via ref edges.
@@ -1393,9 +1393,9 @@ function findCircularSchemas(schemas) {
 function containsCircularRef(node, { circularSchemas, excludeName }) {
 	if (!node || circularSchemas.size === 0) return false;
 	for (const _ of collectLazy(node, { schema(child) {
-		if (child.type !== "ref") return void 0;
+		if (child.type !== "ref") return null;
 		const name = resolveRefName(child);
-		return name && name !== excludeName && circularSchemas.has(name) ? true : void 0;
+		return name && name !== excludeName && circularSchemas.has(name) ? true : null;
 	} })) return true;
 	return false;
 }
@@ -2097,7 +2097,7 @@ function createPrinterFactory(getKey) {
 				options: resolvedOptions,
 				transform: (node) => {
 					const key = getKey(node);
-					if (key === void 0) return null;
+					if (key === null) return null;
 					const handler = nodes[key];
 					if (!handler) return null;
 					return handler.call(context, node);
@@ -2134,10 +2134,10 @@ function enumPropName(parentName, propName, enumSuffix) {
 function collectImports({ node, nameMapping, resolve }) {
 	return collect(node, { schema(schemaNode) {
 		const schemaRef = narrowSchema(schemaNode, "ref");
-		if (!schemaRef?.ref) return;
+		if (!schemaRef?.ref) return null;
 		const rawName = extractRefName(schemaRef.ref);
 		const result = resolve(nameMapping.get(rawName) ?? rawName);
-		if (!result) return;
+		if (!result) return null;
 		return result;
 	} });
 }
@@ -2243,7 +2243,7 @@ function setEnumName(propNode, parentName, propName, enumSuffix) {
 	const enumNode = narrowSchema(propNode, "enum");
 	if (enumNode?.primitive === "boolean") return {
 		...propNode,
-		name: void 0
+		name: null
 	};
 	if (enumNode) return {
 		...propNode,