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

package/src/dialect.ts

@@ -1,53 +1,86 @@
+import type { Node } from './nodes/index.ts'
+
 /**
  * The spec-specific questions a schema parser answers while turning a source document into Kubb
  * AST nodes. The rest of the pipeline is generic JSON Schema, so this is the one seam where
  * OpenAPI, AsyncAPI, and plain JSON Schema differ.
  */
 export type SchemaDialect<TSchema = unknown, TRef = TSchema, TDiscriminated = TSchema, TDocument = unknown> = {
-  /**
-   * Identifies the dialect in logs and diagnostics.
-   */
-  name: string
   /**
    * Whether the schema is nullable.
    */
-  isNullable: (schema?: TSchema) => boolean
+  isNullable(schema?: TSchema): boolean
   /**
    * Whether the value is a `$ref` pointer.
    */
-  isReference: (value?: unknown) => value is TRef
+  isReference(value?: unknown): value is TRef
   /**
    * Whether the schema carries a discriminator for polymorphism.
    */
-  isDiscriminator: (value?: unknown) => value is TDiscriminated
+  isDiscriminator(value?: unknown): value is TDiscriminated
   /**
    * Whether the schema is binary data, converted to a `blob` node.
    */
-  isBinary: (schema: TSchema) => boolean
+  isBinary(schema: TSchema): boolean
   /**
    * Resolves a local `$ref` against the document, or nullish when it cannot.
    */
-  resolveRef: <TResolved>(document: TDocument, ref: string) => TResolved | null | undefined
+  resolveRef<TResolved>(document: TDocument, ref: string): TResolved | null | undefined
+}
+
+/**
+ * How a dialect collapses structurally identical schemas into shared definitions. The contract is
+ * generic over the plan and context types, which the adapter supplies. The mechanics live in the
+ * adapter, not here, so `@kubb/ast` carries no dedupe logic. The returned plan owns the rewriting
+ * behavior, so callers interact with one object.
+ */
+export type Dedupe<TPlan = unknown, TContext = unknown> = {
+  /**
+   * Scans a forest of nodes and produces a plan describing which shapes to share.
+   */
+  plan(roots: ReadonlyArray<Node>, context: TContext): TPlan
+}
+
+/**
+ * A spec adapter's dialect. `name` identifies it in logs and diagnostics, `schema` holds the
+ * spec-specific schema questions the parser answers, and `dedupe` is the schema-sharing seam.
+ */
+export type Dialect<TSchema = unknown, TRef = TSchema, TDiscriminated = TSchema, TDocument = unknown, TDedupe extends Dedupe = Dedupe> = {
+  /**
+   * Identifies the dialect in logs and diagnostics.
+   */
+  name: string
+  /**
+   * The spec-specific schema behavior. See {@link SchemaDialect}.
+   */
+  schema: SchemaDialect<TSchema, TRef, TDiscriminated, TDocument>
+  /**
+   * The schema-sharing behavior. See {@link Dedupe}.
+   */
+  dedupe: TDedupe
 }
 
 /**
- * Types a {@link SchemaDialect} for an adapter. Adds no runtime behavior and only pins the
+ * Types a {@link Dialect} for an adapter. Adds no runtime behavior and only pins the
  * dialect's type for inference.
  *
  * @example
  * ```ts
- * export const oasDialect = defineSchemaDialect({
+ * export const oasDialect = defineDialect({
  *   name: 'oas',
- *   isNullable,
- *   isReference,
- *   isDiscriminator,
- *   isBinary: (schema) => schema.type === 'string' && schema.contentMediaType === 'application/octet-stream',
- *   resolveRef,
+ *   schema: {
+ *     isNullable,
+ *     isReference,
+ *     isDiscriminator,
+ *     isBinary: (schema) => schema.type === 'string' && schema.contentMediaType === 'application/octet-stream',
+ *     resolveRef,
+ *   },
+ *   dedupe: { plan },
  * })
  * ```
  */
-export function defineSchemaDialect<TSchema, TRef, TDiscriminated, TDocument>(
-  dialect: SchemaDialect<TSchema, TRef, TDiscriminated, TDocument>,
-): SchemaDialect<TSchema, TRef, TDiscriminated, TDocument> {
+export function defineDialect<TSchema, TRef, TDiscriminated, TDocument, TDedupe extends Dedupe>(
+  dialect: Dialect<TSchema, TRef, TDiscriminated, TDocument, TDedupe>,
+): Dialect<TSchema, TRef, TDiscriminated, TDocument, TDedupe> {
   return dialect
 }

package/src/factory.ts

@@ -1,16 +1,12 @@
-import { hash } from 'node:crypto'
-import path from 'node:path'
-import { trimExtName } from '@internals/utils'
-import type { FileNode, Node } from './nodes/index.ts'
-import { extractStringsFromNodes } from './utils/extractStringsFromNodes.ts'
-import { combineExports, combineImports, combineSources } from './utils/fileMerge.ts'
+import type { Node } from './nodes/index.ts'
 
 // Node constructors, grouped under the `factory` namespace the way the TypeScript compiler exposes
 // `ts.factory.createX`. Aggregating them here lets `export * as factory from './factory.ts'` in the
 // barrel surface every `createX` alongside the `createFile`/`update` helpers from a single module.
 export { createArrowFunction, createBreak, createConst, createFunction, createJsx, createText, createType } from './nodes/code.ts'
 export { createContent } from './nodes/content.ts'
-export { createExport, createImport, createSource } from './nodes/file.ts'
+export { createExport, createFile, createImport, createSource } from './nodes/file.ts'
+export type { UserFileNode } from './nodes/file.ts'
 export { createFunctionParameter, createFunctionParameters, createIndexedAccessType, createObjectBindingPattern, createTypeLiteral } from './nodes/function.ts'
 export { createInput } from './nodes/input.ts'
 export { createOperation } from './nodes/operation.ts'
@@ -26,10 +22,10 @@ export { createSchema } from './nodes/schema.ts'
  * `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.
+ * Mirrors the TypeScript compiler's `factory.updateX` contract. Pair it with the
+ * structural sharing in {@link transform} so a no-op rewrite does not allocate and
+ * downstream passes can detect "nothing changed" by identity. Comparison is shallow,
+ * so a structurally equal but newly allocated array or object counts as a change.
  *
  * @example
  * ```ts
@@ -46,86 +42,3 @@ export function update<T extends Node>(node: T, changes: Partial<T>): T {
 
   return node
 }
-
-/**
- * Input descriptor for {@link createFile}, before `id`, `name`, and `extname` are computed
- * and `imports`/`exports`/`sources` are deduplicated.
- */
-export type UserFileNode<TMeta extends object = object> = Omit<FileNode<TMeta>, 'kind' | 'id' | 'name' | 'extname' | 'imports' | 'exports' | 'sources'> &
-  Pick<Partial<FileNode<TMeta>>, 'imports' | 'exports' | 'sources'>
-
-/**
- * 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`
- *
- * Deduplicates:
- * - `sources` via `combineSources`
- * - `exports` via `combineExports`
- * - `imports` via `combineImports` (also filters unused imports)
- *
- * @throws {Error} when `baseName` has no extension.
- *
- * @example
- * ```ts
- * const file = createFile({
- *   baseName: 'petStore.ts',
- *   path: 'src/models/petStore.ts',
- *   sources: [createSource({ name: 'Pet', nodes: [createText('export type Pet = { id: number }')] })],
- *   imports: [createImport({ name: ['z'], path: 'zod' })],
- *   exports: [createExport({ name: ['Pet'], path: './petStore' })],
- * })
- * // file.id      = SHA256 hash of 'src/models/petStore.ts'
- * // file.name    = 'petStore'
- * // file.extname = '.ts'
- * ```
- */
-export function createFile<TMeta extends object = object>(input: UserFileNode<TMeta>): FileNode<TMeta> {
-  const rawExtname = path.extname(input.baseName)
-  // Handle dotfile basename like '.ts' where path.extname returns ''
-  const extname = (rawExtname || (input.baseName.startsWith('.') ? input.baseName : '')) as `.${string}`
-  if (!extname) {
-    throw new Error(`No extname found for ${input.baseName}`)
-  }
-
-  const source = (input.sources ?? [])
-    .flatMap((item) => item.nodes ?? [])
-    .map((node) => extractStringsFromNodes([node]))
-    .filter(Boolean)
-    .join('\n\n')
-  const resolvedExports = input.exports?.length ? combineExports(input.exports) : []
-  const combinedImports = input.imports?.length ? combineImports(input.imports, resolvedExports, source || undefined) : []
-  const localNames = new Set((input.sources ?? []).map((item) => item.name).filter((name): name is string => Boolean(name)))
-  const nameOf = (item: string | { propertyName: string; name?: string }): string => (typeof item === 'string' ? item : (item.name ?? item.propertyName))
-  // Drop self-imports. Consolidating output (`mode: 'file'`) can place a symbol's
-  // definition and a cross-file import of it in the same file. The first pass catches imports that
-  // resolve to this file's own path. The second drops imports of names the file already defines,
-  // the case consolidation produces when the import path no longer matches `input.path`. Sources
-  // stay intact, so the local definition remains. Bare specifiers like `'zod'` never match a path.
-  const resolvedImports = combinedImports
-    .filter((imp) => imp.path !== input.path)
-    .flatMap((imp) => {
-      if (!Array.isArray(imp.name)) {
-        return typeof imp.name === 'string' && localNames.has(imp.name) ? [] : [imp]
-      }
-      const kept = imp.name.filter((item) => !localNames.has(nameOf(item)))
-      if (!kept.length) return []
-      return [kept.length === imp.name.length ? imp : { ...imp, name: kept }]
-    })
-  const resolvedSources = input.sources?.length ? combineSources(input.sources) : []
-
-  return {
-    kind: 'File',
-    ...input,
-    id: hash('sha256', input.path, 'hex'),
-    name: trimExtName(input.baseName),
-    extname,
-    imports: resolvedImports,
-    exports: resolvedExports,
-    sources: resolvedSources,
-    meta: input.meta ?? ({} as TMeta),
-  }
-}

package/src/index.ts

@@ -1,15 +1,13 @@
-export { httpMethods, schemaTypes } from './constants.ts'
-export { applyDedupe, buildDedupePlan } from './dedupe.ts'
-export { defineSchemaDialect } from './dialect.ts'
-export * as factory from './factory.ts'
+export { schemaTypes } from './constants.ts'
+export { defineDialect } from './dialect.ts'
 export { isHttpOperationNode, narrowSchema } from './guards.ts'
 export { applyMacros, composeMacros, defineMacro } from './defineMacro.ts'
-export { defineNode } from './node.ts'
-export { syncOptionality } from './node.ts'
-export * from './registry.ts'
-export { createPrinterFactory, definePrinter } from './printer.ts'
+export { defineNode } from './defineNode.ts'
+export { optionality } from './optionality.ts'
+export { createPrinterFactory, definePrinter } from './definePrinter.ts'
 export { signatureOf } from './signature.ts'
-export { extractStringsFromNodes } from './utils/extractStringsFromNodes.ts'
 export { collect, transform, walk } from './visitor.ts'
 
+export * as factory from './factory.ts'
+export * from './registry.ts'
 export type * from './types.ts'

package/src/infer.ts

@@ -16,7 +16,7 @@ import type {
 } from './nodes/index.ts'
 
 /**
- * Shared parser options used by OAS-to-AST inference and parser flows.
+ * Options that control how the adapter parser maps OpenAPI schemas to AST nodes.
  */
 export type ParserOptions = {
   /**

package/src/macros/macroDiscriminatorEnum.ts

@@ -3,6 +3,12 @@ import { narrowSchema } from '../guards.ts'
 import { createProperty } from '../nodes/property.ts'
 import { createSchema } from '../nodes/schema.ts'
 
+type Props = {
+  propertyName: string
+  values: Array<string>
+  enumName?: string
+}
+
 /**
  * Builds a macro that replaces a discriminator property's schema with a string enum of the given
  * values. Object schemas that lack the property are returned unchanged.
@@ -13,7 +19,7 @@ import { createSchema } from '../nodes/schema.ts'
  * const next = applyMacros(objectSchema, [macro], { depth: 'shallow' })
  * ```
  */
-export function macroDiscriminatorEnum({ propertyName, values, enumName }: { propertyName: string; values: Array<string>; enumName?: string }) {
+export function macroDiscriminatorEnum({ propertyName, values, enumName }: Props) {
   return defineMacro({
     name: 'discriminator-enum',
     schema(node) {

package/src/macros/macroEnumName.ts

@@ -2,9 +2,15 @@ import { defineMacro } from '../defineMacro.ts'
 import { narrowSchema } from '../guards.ts'
 import { enumPropName } from '../utils/refs.ts'
 
+type Props = {
+  parentName: string | null | undefined
+  propName: string
+  enumSuffix: string
+}
+
 /**
  * Builds a macro that names an inline enum schema from its parent and property name. Boolean enums
- * are left anonymous; non-enum nodes are returned unchanged.
+ * are left anonymous. Non-enum nodes are returned unchanged.
  *
  * @example
  * ```ts
@@ -12,13 +18,15 @@ import { enumPropName } from '../utils/refs.ts'
  * const named = applyMacros(propSchema, [macro], { depth: 'shallow' })
  * ```
  */
-export function macroEnumName({ parentName, propName, enumSuffix }: { parentName: string | null | undefined; propName: string; enumSuffix: string }) {
+export function macroEnumName({ parentName, propName, enumSuffix }: Props) {
   return defineMacro({
     name: 'enum-name',
     schema(node) {
       const enumNode = narrowSchema(node, 'enum')
+
       if (enumNode?.primitive === 'boolean') return { ...node, name: null }
       if (enumNode) return { ...node, name: enumPropName(parentName, propName, enumSuffix) }
+
       return undefined
     },
   })

package/src/macros/macroSimplifyUnion.ts

@@ -1,29 +1,17 @@
-import { isScalarPrimitive } from '../constants.ts'
 import { defineMacro } from '../defineMacro.ts'
 import { narrowSchema } from '../guards.ts'
 import type { SchemaNode } from '../nodes/schema.ts'
 
+type ScalarPrimitive = 'string' | 'number' | 'integer' | 'bigint' | 'boolean'
+
 /**
- * Removes union members a broader scalar primitive already covers, such as a multi-value string enum
- * sitting next to a plain `string`. Single-value enums are kept.
- *
- * @example
- * ```ts
- * const next = applyMacros(unionSchema, [macroSimplifyUnion], { depth: 'shallow' })
- * ```
+ * Scalar primitive schema types used for union simplification and type narrowing.
  */
-export const macroSimplifyUnion = defineMacro({
-  name: 'simplify-union',
-  schema(node) {
-    const unionNode = narrowSchema(node, 'union')
-    if (!unionNode?.members?.length) return undefined
-
-    const simplified = simplifyUnionMembers(unionNode.members)
-    if (simplified.length === unionNode.members.length) return undefined
+const SCALAR_PRIMITIVE_TYPES = new Set<ScalarPrimitive>(['string', 'number', 'integer', 'bigint', 'boolean'])
 
-    return { ...unionNode, members: simplified }
-  },
-})
+function isScalarPrimitive(type: string): type is ScalarPrimitive {
+  return SCALAR_PRIMITIVE_TYPES.has(type as ScalarPrimitive)
+}
 
 /**
  * Filters union members, dropping enum members that a broader scalar primitive already covers.
@@ -48,3 +36,25 @@ function simplifyUnionMembers(members: Array<SchemaNode>): Array<SchemaNode> {
     return true
   })
 }
+
+/**
+ * Removes union members a broader scalar primitive already covers, such as a multi-value string enum
+ * sitting next to a plain `string`. Single-value enums are kept.
+ *
+ * @example
+ * ```ts
+ * const next = applyMacros(unionSchema, [macroSimplifyUnion], { depth: 'shallow' })
+ * ```
+ */
+export const macroSimplifyUnion = defineMacro({
+  name: 'simplify-union',
+  schema(node) {
+    const unionNode = narrowSchema(node, 'union')
+    if (!unionNode?.members?.length) return undefined
+
+    const simplified = simplifyUnionMembers(unionNode.members)
+    if (simplified.length === unionNode.members.length) return undefined
+
+    return { ...unionNode, members: simplified }
+  },
+})

package/src/nodes/code.ts

@@ -1,4 +1,4 @@
-import { defineNode } from '../node.ts'
+import { defineNode } from '../defineNode.ts'
 import type { BaseNode } from './base.ts'
 
 /**
@@ -116,7 +116,10 @@ export type FunctionNode = BaseNode & {
    */
   default?: boolean | null
   /**
-   * Function parameter list rendered as a string (e.g. from `FunctionParams.toConstructor()`).
+   * Function parameter list as a pre-rendered string, written verbatim between the parentheses.
+   *
+   * @example
+   * `'id: string, config: Config = {}'`
    */
   params?: string | null
   /**
@@ -164,55 +167,12 @@ export type FunctionNode = BaseNode & {
  * // export const getPet = () => ...
  * ```
  */
-export type ArrowFunctionNode = BaseNode & {
+export type ArrowFunctionNode = Omit<FunctionNode, 'kind'> & {
   kind: 'ArrowFunction'
-  /**
-   * Name of the arrow function (used as the `const` variable name).
-   */
-  name: string
-  /**
-   * Whether the function is a default export.
-   */
-  default?: boolean | null
-  /**
-   * Function parameter list rendered as a string (e.g. from `FunctionParams.toConstructor()`).
-   */
-  params?: string | null
-  /**
-   * Whether the arrow function should be exported.
-   */
-  export?: boolean | null
-  /**
-   * Whether the arrow function is async. When `true`, the return type is wrapped in `Promise<>`.
-   */
-  async?: boolean | null
-  /**
-   * TypeScript generic type parameters.
-   *
-   * @example Constrained generics
-   * `['T', 'U extends string']`
-   */
-  generics?: string | Array<string> | null
-  /**
-   * Return type annotation.
-   *
-   * @example Type reference
-   * `'Pet'`
-   */
-  returnType?: string | null
-  /**
-   * JSDoc documentation metadata.
-   */
-  JSDoc?: JSDocNode | null
   /**
    * Render the arrow function body as a single-line expression.
    */
   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.
-   */
-  nodes?: Array<CodeNode>
 }
 
 /**
@@ -236,16 +196,16 @@ export type TextNode = BaseNode & {
 }
 
 /**
- * AST node representing a line break in the source output.
+ * AST node representing a blank line in the source output.
  *
- * Corresponds to `<br/>` in JSX components. When printed it produces an empty string,
- * so joining nodes with `\n` in `printNodes` leaves a blank line between the surrounding code.
+ * Corresponds to `<br/>` in JSX components. `printNodes` turns a `Break` between two
+ * statements into one blank line. Consecutive breaks, and breaks at the start or end of
+ * the list, are folded away, so a `Break` never produces more than one blank line.
  *
  * @example
  * ```ts
  * createBreak()
  * // { kind: 'Break' }
- * // prints as '' → blank line when surrounded by other nodes
  * ```
  */
 export type BreakNode = BaseNode & {
@@ -285,6 +245,36 @@ export type CodeNode = ConstNode | TypeNode | FunctionNode | ArrowFunctionNode |
  */
 export const constDef = defineNode<ConstNode>({ kind: 'Const' })
 
+/**
+ * Definition for the {@link TypeNode}.
+ */
+export const typeDef = defineNode<TypeNode>({ kind: 'Type' })
+
+/**
+ * Definition for the {@link FunctionNode}.
+ */
+export const functionDef = defineNode<FunctionNode>({ kind: 'Function' })
+
+/**
+ * Definition for the {@link ArrowFunctionNode}.
+ */
+export const arrowFunctionDef = defineNode<ArrowFunctionNode>({ kind: 'ArrowFunction' })
+
+/**
+ * Definition for the {@link TextNode}.
+ */
+export const textDef = defineNode<TextNode, string>({ kind: 'Text', build: (value) => ({ value }) })
+
+/**
+ * Definition for the {@link BreakNode}.
+ */
+export const breakDef = defineNode<BreakNode, void>({ kind: 'Break', build: () => ({}) })
+
+/**
+ * Definition for the {@link JsxNode}.
+ */
+export const jsxDef = defineNode<JsxNode, string>({ kind: 'Jsx', build: (value) => ({ value }) })
+
 /**
  * Creates a `ConstNode` representing a TypeScript `const` declaration.
  *
@@ -296,11 +286,6 @@ export const constDef = defineNode<ConstNode>({ kind: 'Const' })
  */
 export const createConst = constDef.create
 
-/**
- * Definition for the {@link TypeNode}.
- */
-export const typeDef = defineNode<TypeNode>({ kind: 'Type' })
-
 /**
  * Creates a `TypeNode` representing a TypeScript `type` alias declaration.
  *
@@ -312,11 +297,6 @@ export const typeDef = defineNode<TypeNode>({ kind: 'Type' })
  */
 export const createType = typeDef.create
 
-/**
- * Definition for the {@link FunctionNode}.
- */
-export const functionDef = defineNode<FunctionNode>({ kind: 'Function' })
-
 /**
  * Creates a `FunctionNode` representing a TypeScript `function` declaration.
  *
@@ -328,11 +308,6 @@ export const functionDef = defineNode<FunctionNode>({ kind: 'Function' })
  */
 export const createFunction = functionDef.create
 
-/**
- * Definition for the {@link ArrowFunctionNode}.
- */
-export const arrowFunctionDef = defineNode<ArrowFunctionNode>({ kind: 'ArrowFunction' })
-
 /**
  * Creates an `ArrowFunctionNode` representing a TypeScript arrow function.
  *
@@ -344,11 +319,6 @@ export const arrowFunctionDef = defineNode<ArrowFunctionNode>({ kind: 'ArrowFunc
  */
 export const createArrowFunction = arrowFunctionDef.create
 
-/**
- * Definition for the {@link TextNode}.
- */
-export const textDef = defineNode<TextNode, string>({ kind: 'Text', build: (value) => ({ value }) })
-
 /**
  * Creates a {@link TextNode} representing a raw string fragment in the source output.
  *
@@ -360,11 +330,6 @@ export const textDef = defineNode<TextNode, string>({ kind: 'Text', build: (valu
  */
 export const createText = textDef.create
 
-/**
- * Definition for the {@link BreakNode}.
- */
-export const breakDef = defineNode<BreakNode, void>({ kind: 'Break', build: () => ({}) })
-
 /**
  * Creates a {@link BreakNode} representing a line break in the source output.
  *
@@ -378,11 +343,6 @@ export function createBreak(): BreakNode {
   return breakDef.create()
 }
 
-/**
- * Definition for the {@link JsxNode}.
- */
-export const jsxDef = defineNode<JsxNode, string>({ kind: 'Jsx', build: (value) => ({ value }) })
-
 /**
  * Creates a {@link JsxNode} representing a raw JSX fragment in the source output.
  *

package/src/nodes/content.ts

@@ -1,4 +1,4 @@
-import { defineNode } from '../node.ts'
+import { defineNode } from '../defineNode.ts'
 import type { BaseNode } from './base.ts'
 import type { SchemaNode } from './schema.ts'
 
@@ -37,15 +37,10 @@ export type ContentNode = BaseNode & {
   keysToOmit?: Array<string> | null
 }
 
-/**
- * Loosely-typed content entry accepted by the builders, normalized into a {@link ContentNode}.
- */
-export type UserContent = Omit<ContentNode, 'kind'>
-
 /**
  * Definition for the {@link ContentNode}.
  */
-export const contentDef = defineNode<ContentNode, UserContent>({
+export const contentDef = defineNode<ContentNode>({
   kind: 'Content',
   children: ['schema'],
 })