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

package/src/guards.ts

@@ -1,18 +1,4 @@
-import type {
-  FunctionParameterNode,
-  FunctionParametersNode,
-  InputNode,
-  Node,
-  NodeKind,
-  OperationNode,
-  OutputNode,
-  ParameterGroupNode,
-  ParameterNode,
-  PropertyNode,
-  ResponseNode,
-  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`.
@@ -20,91 +6,23 @@ 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) {
-  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`.
+ * Narrows an `OperationNode` to an `HttpOperationNode` so `method` and `path` are present.
  *
  * @example
  * ```ts
- * if (isOutputNode(node)) {
- *   console.log(node.files.length)
+ * if (isHttpOperationNode(node)) {
+ *   console.log(node.method, node.path)
  * }
  * ```
  */
-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')
-
-/**
- * Returns `true` when the input is a `SchemaNode`.
- *
- * @example
- * ```ts
- * if (isSchemaNode(node)) {
- *   console.log(node.type)
- * }
- * ```
- */
-export const isSchemaNode = isKind<SchemaNode>('Schema')
-
-/**
- * Returns `true` when the input is a `PropertyNode`.
- */
-export const isPropertyNode = isKind<PropertyNode>('Property')
-
-/**
- * Returns `true` when the input is a `ParameterNode`.
- */
-export const isParameterNode = isKind<ParameterNode>('Parameter')
-
-/**
- * Returns `true` when the input is a `ResponseNode`.
- */
-export const isResponseNode = isKind<ResponseNode>('Response')
-
-/**
- * Returns `true` when the input is a `FunctionParameterNode`.
- */
-export const isFunctionParameterNode = isKind<FunctionParameterNode>('FunctionParameter')
-
-/**
- * Returns `true` when the input is a `ParameterGroupNode`.
- */
-export const isParameterGroupNode = isKind<ParameterGroupNode>('ParameterGroup')
-
-/**
- * Returns `true` when the input is a `FunctionParametersNode`.
- */
-export const isFunctionParametersNode = isKind<FunctionParametersNode>('FunctionParameters')
+export function isHttpOperationNode(node: OperationNode): node is HttpOperationNode {
+  return node.protocol === 'http' || (node.method !== undefined && node.path !== undefined)
+}

package/src/index.ts

@@ -1,46 +1,15 @@
-export { httpMethods, isScalarPrimitive, mediaTypes, nodeKinds, schemaTypes } from './constants.ts'
-export {
-  createArrowFunction,
-  createBreak,
-  createConst,
-  createExport,
-  createFile,
-  createFunction,
-  createFunctionParameter,
-  createFunctionParameters,
-  createImport,
-  createInput,
-  createJsx,
-  createOperation,
-  createOutput,
-  createParameter,
-  createParameterGroup,
-  createParamsType,
-  createProperty,
-  createResponse,
-  createSchema,
-  createSource,
-  createText,
-  createType,
-  syncOptionality,
-} from './factory.ts'
-export { isInputNode, isOperationNode, isOutputNode, isSchemaNode, narrowSchema } from './guards.ts'
+export { httpMethods, schemaTypes } from './constants.ts'
+export { applyDedupe, buildDedupePlan } from './dedupe.ts'
+export { defineSchemaDialect } from './dialect.ts'
+export * as factory from './factory.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 { extractRefName } from './refs.ts'
-export { childName, collectImports, enumPropName, findDiscriminator } from './resolvers.ts'
-export { mergeAdjacentObjects, setDiscriminatorEnum, setEnumName, simplifyUnion } from './transformers.ts'
-export type * from './types.ts'
-export {
-  caseParams,
-  collectReferencedSchemaNames,
-  collectUsedSchemaNames,
-  containsCircularRef,
-  createDiscriminantNode,
-  createOperationParams,
-  extractStringsFromNodes,
-  findCircularSchemas,
-  isStringType,
-  resolveRefName,
-  syncSchemaRef,
-} from './utils.ts'
+export { signatureOf } from './signature.ts'
+export { extractStringsFromNodes } from './utils/extractStringsFromNodes.ts'
 export { collect, transform, walk } from './visitor.ts'
+
+export type * from './types.ts'

package/src/infer.ts

@@ -20,15 +20,25 @@ import type {
  */
 export type ParserOptions = {
   /**
-   * How `format: 'date-time'` schemas are represented. `false` falls through to a plain string.
+   * How `format: 'date-time'` schemas are represented downstream.
+   * - `false` falls through to a plain `string` (no validation).
+   * - `'string'` emits a datetime string node.
+   * - `'stringOffset'` emits a datetime node with timezone offset.
+   * - `'stringLocal'` emits a local datetime node.
+   * - `'date'` emits a `date` node (JavaScript `Date` object).
    */
   dateType: false | 'string' | 'stringOffset' | 'stringLocal' | 'date'
   /**
-   * Whether `type: 'integer'` and `format: 'int64'` produce `number` or `bigint` nodes.
+   * How `type: 'integer'` (and `format: 'int64'`) maps to TypeScript.
+   * - `'bigint'` is exact for 64-bit IDs, but does not round-trip through JSON.
+   * - `'number'` fits most JSON APIs. Loses precision above `Number.MAX_SAFE_INTEGER`.
+   *
+   * @default 'bigint'
    */
   integerType?: 'number' | 'bigint'
   /**
-   * AST type used when no schema type can be inferred.
+   * AST type used when a schema's type cannot be inferred from the spec
+   * (`additionalProperties: true`, missing `type`, ...).
    */
   unknownType: 'any' | 'unknown' | 'void'
   /**
@@ -36,7 +46,8 @@ export type ParserOptions = {
    */
   emptySchemaType: 'any' | 'unknown' | 'void'
   /**
-   * Suffix appended to derived enum names when building property schema names.
+   * Suffix appended to derived enum names when Kubb has to invent one
+   * (typically for inline enums on object properties).
    */
   enumSuffix: 'enum' | (string & {})
 }
@@ -66,7 +77,7 @@ type ResolveDateTimeNode<TDateType extends ParserOptions['dateType']> = DateTime
 type SchemaNodeMap<TDateType extends ParserOptions['dateType'] = 'string'> = [
   [{ $ref: string }, RefSchemaNode],
   [{ allOf: ReadonlyArray<unknown>; properties: object }, IntersectionSchemaNode],
-  [{ allOf: readonly [unknown, unknown, ...unknown[]] }, IntersectionSchemaNode],
+  [{ allOf: readonly [unknown, unknown, ...Array<unknown>] }, IntersectionSchemaNode],
   [{ allOf: ReadonlyArray<unknown> }, SchemaNode],
   [{ oneOf: ReadonlyArray<unknown> }, UnionSchemaNode],
   [{ anyOf: ReadonlyArray<unknown> }, UnionSchemaNode],
@@ -119,12 +130,3 @@ export type InferSchemaNode<
     ? TEntry[1]
     : InferSchemaNode<TSchema, TDateType, TRest>
   : SchemaNode
-
-/**
- * Backward-compatible alias for `InferSchemaNode`.
- */
-export type InferSchema<
-  TSchema extends object,
-  TDateType extends ParserOptions['dateType'] = 'string',
-  TEntries extends ReadonlyArray<[object, SchemaNode]> = SchemaNodeMap<TDateType>,
-> = InferSchemaNode<TSchema, TDateType, TEntries>

package/src/macros/index.ts

@@ -0,0 +1,3 @@
+export { macroDiscriminatorEnum } from './macroDiscriminatorEnum.ts'
+export { macroEnumName } from './macroEnumName.ts'
+export { macroSimplifyUnion } from './macroSimplifyUnion.ts'

package/src/macros/macroDiscriminatorEnum.ts

@@ -0,0 +1,44 @@
+import { defineMacro } from '../defineMacro.ts'
+import { narrowSchema } from '../guards.ts'
+import { createProperty } from '../nodes/property.ts'
+import { createSchema } from '../nodes/schema.ts'
+
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const macro = macroDiscriminatorEnum({ propertyName: 'type', values: ['dog', 'cat'] })
+ * const next = applyMacros(objectSchema, [macro], { depth: 'shallow' })
+ * ```
+ */
+export function macroDiscriminatorEnum({ propertyName, values, enumName }: { propertyName: string; values: Array<string>; enumName?: string }) {
+  return defineMacro({
+    name: 'discriminator-enum',
+    schema(node) {
+      const objectNode = narrowSchema(node, 'object')
+      if (!objectNode?.properties?.length) return undefined
+      if (!objectNode.properties.some((prop) => prop.name === propertyName)) return undefined
+
+      return createSchema({
+        ...objectNode,
+        properties: objectNode.properties.map((prop) => {
+          if (prop.name !== propertyName) return prop
+
+          return createProperty({
+            ...prop,
+            schema: createSchema({
+              type: 'enum',
+              primitive: 'string',
+              enumValues: values,
+              name: enumName,
+              readOnly: prop.schema.readOnly,
+              writeOnly: prop.schema.writeOnly,
+            }),
+          })
+        }),
+      })
+    },
+  })
+}

package/src/macros/macroEnumName.ts

@@ -0,0 +1,25 @@
+import { defineMacro } from '../defineMacro.ts'
+import { narrowSchema } from '../guards.ts'
+import { enumPropName } from '../utils/refs.ts'
+
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const macro = macroEnumName({ parentName: 'Pet', propName: 'status', enumSuffix: 'enum' })
+ * const named = applyMacros(propSchema, [macro], { depth: 'shallow' })
+ * ```
+ */
+export function macroEnumName({ parentName, propName, enumSuffix }: { parentName: string | null | undefined; propName: string; enumSuffix: string }) {
+  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

@@ -0,0 +1,50 @@
+import { isScalarPrimitive } from '../constants.ts'
+import { defineMacro } from '../defineMacro.ts'
+import { narrowSchema } from '../guards.ts'
+import type { SchemaNode } from '../nodes/schema.ts'
+
+/**
+ * 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 }
+  },
+})
+
+/**
+ * Filters union members, dropping enum members that a broader scalar primitive already covers.
+ */
+function simplifyUnionMembers(members: Array<SchemaNode>): Array<SchemaNode> {
+  const scalarPrimitives = new Set(members.filter((member) => isScalarPrimitive(member.type)).map((m) => m.type))
+  if (!scalarPrimitives.size) return members
+
+  return members.filter((member) => {
+    const enumNode = narrowSchema(member, 'enum')
+    if (!enumNode) return true
+
+    const primitive = enumNode.primitive
+    if (!primitive) return true
+
+    const enumValueCount = enumNode.namedEnumValues?.length ?? enumNode.enumValues?.length ?? 0
+    if (enumValueCount <= 1) return true
+
+    if (scalarPrimitives.has(primitive)) return false
+    if ((primitive === 'integer' || primitive === 'number') && (scalarPrimitives.has('integer') || scalarPrimitives.has('number'))) return false
+
+    return true
+  })
+}

package/src/mocks.ts

@@ -1,5 +1,10 @@
-import { createInput, createOperation, createParameter, createProperty, createResponse, createSchema } from './factory.ts'
-import type { InputNode } from './nodes/root.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.
@@ -49,128 +54,3 @@ export function buildSampleTree(): InputNode {
 
   return createInput({ schemas: [petSchema], operations: [operation] })
 }
-
-/**
- * Builds a PetStore-like fixture AST with:
- * - six named schemas (`Pet`, `NewPet`, `PetList`, `Error`, `PetOrError`, `FullPet`)
- * - two operations (`listPets`, `createPet`)
- */
-export function buildFixture(): InputNode {
-  const refPet = createSchema({ type: 'ref', ref: 'Pet' })
-  const refError = createSchema({ type: 'ref', ref: 'Error' })
-
-  return createInput({
-    schemas: [
-      createSchema({
-        name: 'Pet',
-        type: 'object',
-        properties: [
-          createProperty({
-            name: 'id',
-            schema: createSchema({ type: 'integer' }),
-            required: true,
-          }),
-          createProperty({
-            name: 'name',
-            schema: createSchema({ type: 'string' }),
-            required: true,
-          }),
-        ],
-      }),
-      createSchema({
-        name: 'NewPet',
-        type: 'object',
-        properties: [
-          createProperty({
-            name: 'name',
-            schema: createSchema({ type: 'string' }),
-            required: true,
-          }),
-        ],
-      }),
-      createSchema({
-        name: 'PetList',
-        type: 'array',
-        items: [refPet],
-      }),
-      createSchema({
-        name: 'Error',
-        type: 'object',
-        properties: [
-          createProperty({
-            name: 'code',
-            schema: createSchema({ type: 'integer' }),
-            required: true,
-          }),
-          createProperty({
-            name: 'message',
-            schema: createSchema({ type: 'string' }),
-            required: true,
-          }),
-        ],
-      }),
-      createSchema({
-        name: 'PetOrError',
-        type: 'union',
-        members: [refPet, refError],
-      }),
-      createSchema({
-        name: 'FullPet',
-        type: 'intersection',
-        members: [
-          refPet,
-          createSchema({
-            type: 'object',
-            properties: [
-              createProperty({
-                name: 'createdAt',
-                schema: createSchema({ type: 'datetime' }),
-              }),
-            ],
-          }),
-        ],
-      }),
-    ],
-    operations: [
-      createOperation({
-        operationId: 'listPets',
-        method: 'GET',
-        path: '/pets',
-        tags: ['pets'],
-        parameters: [
-          createParameter({
-            name: 'limit',
-            in: 'query',
-            schema: createSchema({ type: 'integer' }),
-          }),
-        ],
-        responses: [
-          createResponse({
-            statusCode: '200',
-            schema: createSchema({ type: 'ref', ref: 'PetList' }),
-            mediaType: 'application/json',
-          }),
-          createResponse({
-            statusCode: '400',
-            schema: refError,
-            mediaType: 'application/json',
-          }),
-        ],
-      }),
-      createOperation({
-        operationId: 'createPet',
-        method: 'POST',
-        path: '/pets',
-        tags: ['pets'],
-        requestBody: { content: [{ contentType: 'application/json', schema: createSchema({ type: 'ref', ref: 'NewPet' }) }] },
-        responses: [
-          createResponse({
-            statusCode: '201',
-            schema: refPet,
-            mediaType: 'application/json',
-          }),
-        ],
-      }),
-    ],
-  })
-}

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`.
+ */
+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

@@ -14,11 +14,14 @@ export type NodeKind =
   | 'Property'
   | 'Parameter'
   | 'Response'
+  | 'RequestBody'
+  | 'Content'
   | 'FunctionParameter'
-  | 'ParameterGroup'
   | 'FunctionParameters'
+  | 'TypeLiteral'
+  | 'IndexedAccessType'
+  | 'ObjectBindingPattern'
   | 'Type'
-  | 'ParamsType'
   | 'File'
   | 'Import'
   | 'Export'
@@ -44,13 +47,3 @@ export type BaseNode = {
    */
   kind: NodeKind
 }
-
-/**
- * Minimal node type when only `kind` is needed.
- *
- * @example
- * ```ts
- * const node: Node = { kind: 'Operation' }
- * ```
- */
-export type Node = BaseNode