@kubb/ast 5.0.0-beta.56 → 5.0.0-beta.57

package/src/guards.ts

@@ -1,4 +1,4 @@
-import type { HttpOperationNode, InputNode, Node, NodeKind, OperationNode, OutputNode, SchemaNode, SchemaNodeByType } from './nodes/index.ts'
+import type { HttpOperationNode, OperationNode, SchemaNode, SchemaNodeByType } from './nodes/index.ts'
 
 /**
  * Narrows a `SchemaNode` to the variant that matches `type`.
@@ -13,46 +13,6 @@ export function narrowSchema<T extends SchemaNode['type']>(node: SchemaNode | un
   return node?.type === type ? (node as SchemaNodeByType[T]) : null
 }
 
-function isKind<T extends Node>(kind: NodeKind) {
-  return (node: unknown): node is T => (node as Node).kind === kind
-}
-
-/**
- * Returns `true` when the input is an `InputNode`.
- *
- * @example
- * ```ts
- * if (isInputNode(node)) {
- *   console.log(node.schemas.length)
- * }
- * ```
- */
-export const isInputNode = isKind<InputNode>('Input')
-
-/**
- * Returns `true` when the input is an `OutputNode`.
- *
- * @example
- * ```ts
- * if (isOutputNode(node)) {
- *   console.log(node.files.length)
- * }
- * ```
- */
-export const isOutputNode = isKind<OutputNode>('Output')
-
-/**
- * Returns `true` when the input is an `OperationNode`.
- *
- * @example
- * ```ts
- * if (isOperationNode(node)) {
- *   console.log(node.operationId)
- * }
- * ```
- */
-export const isOperationNode = isKind<OperationNode>('Operation')
-
 /**
  * Narrows an `OperationNode` to an `HttpOperationNode`, guaranteeing `method` and `path`.
  *
@@ -66,15 +26,3 @@ export const isOperationNode = isKind<OperationNode>('Operation')
 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`.
- *
- * @example
- * ```ts
- * if (isSchemaNode(node)) {
- *   console.log(node.type)
- * }
- * ```
- */
-export const isSchemaNode = isKind<SchemaNode>('Schema')

package/src/index.ts

@@ -1,34 +1,49 @@
 export { httpMethods, schemaTypes } from './constants.ts'
 export { applyDedupe, buildDedupePlan } from './dedupe.ts'
 export { defineSchemaDialect } from './dialect.ts'
+export { createFile, update } from './factory.ts'
+export { isHttpOperationNode, narrowSchema } from './guards.ts'
+export { defineNode } from './node.ts'
+export type { NodeDef } from './node.ts'
+export { syncOptionality } from './node.ts'
 export {
+  arrowFunctionDef,
+  breakDef,
+  constDef,
   createArrowFunction,
   createBreak,
   createConst,
-  createExport,
-  createFile,
   createFunction,
-  createFunctionParameter,
-  createFunctionParameters,
-  createImport,
-  createInput,
-  createStreamInput,
   createJsx,
-  createOperation,
-  createOutput,
-  createParameter,
-  createParameterGroup,
-  createParamsType,
-  createProperty,
-  createResponse,
-  createSchema,
-  createSource,
   createText,
   createType,
-  syncOptionality,
-  update,
-} from './factory.ts'
-export { isHttpOperationNode, isInputNode, isOperationNode, isOutputNode, isSchemaNode, narrowSchema } from './guards.ts'
+  functionDef,
+  jsxDef,
+  textDef,
+  typeDef,
+} from './nodes/code.ts'
+export { contentDef } from './nodes/content.ts'
+export { createExport, createImport, createSource, exportDef, fileDef, importDef, sourceDef } from './nodes/file.ts'
+export {
+  createFunctionParameter,
+  createFunctionParameters,
+  createIndexedAccessType,
+  createObjectBindingPattern,
+  createTypeLiteral,
+  functionParameterDef,
+  functionParametersDef,
+  indexedAccessTypeDef,
+  objectBindingPatternDef,
+  typeLiteralDef,
+} from './nodes/function.ts'
+export { createInput, createStreamInput, inputDef } from './nodes/input.ts'
+export { createOperation, operationDef } from './nodes/operation.ts'
+export { createOutput, outputDef } from './nodes/output.ts'
+export { createParameter, parameterDef } from './nodes/parameter.ts'
+export { createProperty, propertyDef } from './nodes/property.ts'
+export { requestBodyDef } from './nodes/requestBody.ts'
+export { createResponse, responseDef } from './nodes/response.ts'
+export { createSchema, schemaDef } from './nodes/schema.ts'
 export { createPrinterFactory, definePrinter } from './printer.ts'
 export { signatureOf } from './signature.ts'
 export { mergeAdjacentObjectsLazy, setDiscriminatorEnum, setEnumName, simplifyUnion } from './transformers.ts'

package/src/mocks.ts

@@ -1,5 +1,10 @@
-import { createInput, createOperation, createParameter, createProperty, createResponse, createSchema } from './factory.ts'
+import { createInput } from './nodes/input.ts'
 import type { InputNode } from './nodes/input.ts'
+import { createOperation } from './nodes/operation.ts'
+import { createParameter } from './nodes/parameter.ts'
+import { createProperty } from './nodes/property.ts'
+import { createResponse } from './nodes/response.ts'
+import { createSchema } from './nodes/schema.ts'
 
 /**
  * Builds a minimal sample AST with one `Pet` schema and one `getPetById` operation.

package/src/node.ts

@@ -0,0 +1,128 @@
+import type { BaseNode, NodeKind } from './nodes/base.ts'
+import type { SchemaNode } from './nodes/index.ts'
+
+/**
+ * Visitor callback names, one per traversable node kind. Kept in sync with the
+ * keys of `Visitor` in `visitor.ts`.
+ */
+type VisitorKey = 'input' | 'output' | 'operation' | 'schema' | 'property' | 'parameter' | 'response'
+
+/**
+ * Distributive `Omit` that preserves each member of a union.
+ *
+ * @example
+ * ```ts
+ * type A = { kind: 'a'; keep: string; drop: number }
+ * type B = { kind: 'b'; keep: boolean; drop: number }
+ * type Result = DistributiveOmit<A | B, 'drop'>
+ * // -> { kind: 'a'; keep: string } | { kind: 'b'; keep: boolean }
+ * ```
+ */
+export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never
+
+/**
+ * Builds a type guard that matches nodes of the given `kind`.
+ */
+export function isKind<T extends BaseNode>(kind: NodeKind) {
+  return (node: unknown): node is T => (node as BaseNode).kind === kind
+}
+
+/**
+ * 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.
+ *
+ * - 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
+
+  return {
+    ...schema,
+    optional: !required && !nullable ? true : undefined,
+    nullish: !required && nullable ? true : undefined,
+  }
+}
+
+/**
+ * The single definition derived from one {@link defineNode} call: the node's
+ * `create` builder, its `is` guard, and the traversal metadata the registry
+ * collects into the visitor tables.
+ */
+export type NodeDef<TNode extends BaseNode = BaseNode, TInput = never> = {
+  /**
+   * Node discriminator this definition owns.
+   */
+  kind: NodeKind
+  /**
+   * Builds a node from its input, applying `defaults` and the optional `build` hook.
+   */
+  create: (input: TInput) => TNode
+  /**
+   * Type guard matching this node kind.
+   */
+  is: (node: unknown) => node is TNode
+  /**
+   * Child node fields in traversal order. Feeds `VISITOR_KEYS`.
+   */
+  children?: ReadonlyArray<string>
+  /**
+   * Visitor callback name. Feeds `VISITOR_KEY_BY_KIND`.
+   */
+  visitorKey?: VisitorKey
+  /**
+   * When `true`, `create` is rerun after children are rebuilt so computed fields
+   * stay in sync. Feeds `nodeRebuilders`.
+   */
+  rebuild?: boolean
+}
+
+type DefineNodeConfig<TNode extends BaseNode, TInput, TBuilt extends object> = {
+  kind: TNode['kind']
+  defaults?: Partial<TNode>
+  build?: (input: TInput) => TBuilt
+  children?: ReadonlyArray<string>
+  visitorKey?: VisitorKey
+  rebuild?: boolean
+}
+
+/**
+ * Defines a node once and derives its `create` builder, `is` guard, and traversal
+ * metadata. `create` merges `defaults`, the `build` hook (or the raw input), and the
+ * `kind`, so node construction lives in one place without scattered `as` casts.
+ *
+ * Set `rebuild: true` when the `build` hook derives fields from children. After a
+ * transform rewrites those children, the registry reruns `create` so the derived
+ * fields stay correct.
+ *
+ * @example Simple node
+ * ```ts
+ * const importDef = defineNode<ImportNode>({ kind: 'Import' })
+ * const createImport = importDef.create
+ * ```
+ *
+ * @example Node with a build hook that is rerun on transform
+ * ```ts
+ * const propertyDef = defineNode<PropertyNode, UserPropertyNode>({
+ *   kind: 'Property',
+ *   build: (props) => ({ ...props, required: props.required ?? false }),
+ *   children: ['schema'],
+ *   visitorKey: 'property',
+ *   rebuild: true,
+ * })
+ * ```
+ */
+export function defineNode<TNode extends BaseNode, TInput = Omit<TNode, 'kind'>, TBuilt extends object = Omit<TNode, 'kind'>>(
+  config: DefineNodeConfig<TNode, TInput, TBuilt>,
+): NodeDef<TNode, TInput> {
+  const { kind, defaults, build, children, visitorKey, rebuild } = config
+
+  function create(input: TInput): TNode {
+    const base = build ? build(input) : input
+    return { ...defaults, ...(base as object), kind } as TNode
+  }
+
+  return { kind, create, is: isKind<TNode>(kind), children, visitorKey, rebuild }
+}

package/src/nodes/base.ts

@@ -17,10 +17,11 @@ export type NodeKind =
   | 'RequestBody'
   | 'Content'
   | 'FunctionParameter'
-  | 'ParameterGroup'
   | 'FunctionParameters'
+  | 'TypeLiteral'
+  | 'IndexedAccessType'
+  | 'ObjectBindingPattern'
   | 'Type'
-  | 'ParamsType'
   | 'File'
   | 'Import'
   | 'Export'

package/src/nodes/code.ts

@@ -1,3 +1,4 @@
+import { defineNode } from '../node.ts'
 import type { BaseNode } from './base.ts'
 
 /**
@@ -296,3 +297,117 @@ export type JsxNode = BaseNode & {
  * structured children in {@link SourceNode.nodes}.
  */
 export type CodeNode = ConstNode | TypeNode | FunctionNode | ArrowFunctionNode | TextNode | BreakNode | JsxNode
+
+/**
+ * Definition for the {@link ConstNode}.
+ */
+export const constDef = defineNode<ConstNode>({ kind: 'Const' })
+
+/**
+ * Creates a `ConstNode` representing a TypeScript `const` declaration.
+ *
+ * @example Exported constant with type and `as const`
+ * ```ts
+ * createConst({ name: 'pets', export: true, type: 'Pet[]', asConst: true })
+ * // export const pets: Pet[] = ... as 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.
+ *
+ * @example
+ * ```ts
+ * createType({ name: 'Pet', export: true })
+ * // export type Pet = ...
+ * ```
+ */
+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.
+ *
+ * @example
+ * ```ts
+ * createFunction({ name: 'fetchPet', export: true, async: true, returnType: 'Pet' })
+ * // export async function fetchPet(): Promise<Pet> { ... }
+ * ```
+ */
+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.
+ *
+ * @example
+ * ```ts
+ * createArrowFunction({ name: 'double', export: true, params: 'n: number', singleLine: true })
+ * // export const double = (n: number) => ...
+ * ```
+ */
+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.
+ *
+ * @example
+ * ```ts
+ * createText('return fetch(id)')
+ * // { kind: 'Text', value: 'return fetch(id)' }
+ * ```
+ */
+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.
+ *
+ * @example
+ * ```ts
+ * createBreak()
+ * // { kind: 'Break' }
+ * ```
+ */
+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.
+ *
+ * @example
+ * ```ts
+ * createJsx('<>\n  <a href={href}>Open</a>\n</>')
+ * // { kind: 'Jsx', value: '<>\n  <a href={href}>Open</a>\n</>' }
+ * ```
+ */
+export const createJsx = jsxDef.create

package/src/nodes/content.ts

@@ -1,3 +1,4 @@
+import { defineNode } from '../node.ts'
 import type { BaseNode } from './base.ts'
 import type { SchemaNode } from './schema.ts'
 
@@ -35,3 +36,21 @@ 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>({
+  kind: 'Content',
+  children: ['schema'],
+})
+
+/**
+ * Creates a `ContentNode` for a single request-body or response content type.
+ */
+export const createContent = contentDef.create

package/src/nodes/file.ts

@@ -1,3 +1,4 @@
+import { defineNode } from '../node.ts'
 import type { BaseNode } from './base.ts'
 import type { CodeNode } from './code.ts'
 
@@ -230,3 +231,56 @@ export type FileNode<TMeta extends object = object> = BaseNode & {
    */
   footer?: string | null
 }
+
+/**
+ * Definition for the {@link ImportNode}.
+ */
+export const importDef = defineNode<ImportNode>({ kind: 'Import' })
+
+/**
+ * Creates an `ImportNode` representing a language-agnostic import/dependency declaration.
+ *
+ * @example Named import
+ * ```ts
+ * createImport({ name: ['useState'], path: 'react' })
+ * // import { useState } from 'react'
+ * ```
+ */
+export const createImport = importDef.create
+
+/**
+ * Definition for the {@link ExportNode}.
+ */
+export const exportDef = defineNode<ExportNode>({ kind: 'Export' })
+
+/**
+ * Creates an `ExportNode` representing a language-agnostic export/public API declaration.
+ *
+ * @example Named export
+ * ```ts
+ * createExport({ name: ['Pet'], path: './Pet' })
+ * // export { Pet } from './Pet'
+ * ```
+ */
+export const createExport = exportDef.create
+
+/**
+ * Definition for the {@link SourceNode}.
+ */
+export const sourceDef = defineNode<SourceNode>({ kind: 'Source' })
+
+/**
+ * Creates a `SourceNode` representing a fragment of source code within a file.
+ *
+ * @example
+ * ```ts
+ * createSource({ name: 'Pet', nodes: [createText('export type Pet = { id: number }')], isExportable: true })
+ * ```
+ */
+export const createSource = sourceDef.create
+
+/**
+ * Definition for the {@link FileNode}. The fully resolved builder lives in
+ * `createFile`, so this definition only supplies the guard.
+ */
+export const fileDef = defineNode<FileNode>({ kind: 'File' })