@kubb/ast 5.0.0-alpha.9 → 5.0.0-beta.75

package/src/guards.ts

@@ -1,7 +1,27 @@
-import type { Node, NodeKind, OperationNode, ParameterNode, PropertyNode, ResponseNode, RootNode, SchemaNode, SchemaNodeByType } from './nodes/index.ts'
+import type {
+  FunctionParameterNode,
+  FunctionParametersNode,
+  InputNode,
+  Node,
+  NodeKind,
+  OperationNode,
+  OutputNode,
+  ParameterGroupNode,
+  ParameterNode,
+  PropertyNode,
+  ResponseNode,
+  SchemaNode,
+  SchemaNodeByType,
+} from './nodes/index.ts'
 
 /**
- * Narrows a `SchemaNode` to the specific variant matching `type`.
+ * Narrows a `SchemaNode` to the variant that matches `type`.
+ *
+ * @example
+ * ```ts
+ * const schema = createSchema({ type: 'string' })
+ * const stringNode = narrowSchema(schema, 'string') // StringSchemaNode | undefined
+ * ```
  */
 export function narrowSchema<T extends SchemaNode['type']>(node: SchemaNode | undefined, type: T): SchemaNodeByType[T] | undefined {
   return node?.type === type ? (node as SchemaNodeByType[T]) : undefined
@@ -12,31 +32,79 @@ function isKind<T extends Node>(kind: NodeKind) {
 }
 
 /**
- * Type guard for `RootNode`.
+ * Returns `true` when the input is an `InputNode`.
+ *
+ * @example
+ * ```ts
+ * if (isInputNode(node)) {
+ *   console.log(node.schemas.length)
+ * }
+ * ```
  */
-export const isRootNode = isKind<RootNode>('Root')
+export const isInputNode = isKind<InputNode>('Input')
 
 /**
- * Type guard for `OperationNode`.
+ * 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')
 
 /**
- * Type guard for `SchemaNode`.
+ * Returns `true` when the input is a `SchemaNode`.
+ *
+ * @example
+ * ```ts
+ * if (isSchemaNode(node)) {
+ *   console.log(node.type)
+ * }
+ * ```
  */
 export const isSchemaNode = isKind<SchemaNode>('Schema')
 
 /**
- * Type guard for `PropertyNode`.
+ * Returns `true` when the input is a `PropertyNode`.
  */
 export const isPropertyNode = isKind<PropertyNode>('Property')
 
 /**
- * Type guard for `ParameterNode`.
+ * Returns `true` when the input is a `ParameterNode`.
  */
 export const isParameterNode = isKind<ParameterNode>('Parameter')
 
 /**
- * Type guard for `ResponseNode`.
+ * 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')

package/src/index.ts

@@ -1,7 +1,45 @@
-export { httpMethods, mediaTypes, nodeKinds, schemaTypes } from './constants.ts'
-export { createOperation, createParameter, createProperty, createResponse, createRoot, createSchema } from './factory.ts'
-export { isOperationNode, isParameterNode, isPropertyNode, isResponseNode, isRootNode, isSchemaNode, narrowSchema } from './guards.ts'
-export { definePrinter } from './printer.ts'
-export { buildRefMap, refMapToObject, resolveRef } from './refs.ts'
-export { applyParamsCasing, isPlainStringType } from './utils.ts'
+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 { 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,
+  containsCircularRef,
+  createDiscriminantNode,
+  createOperationParams,
+  extractStringsFromNodes,
+  findCircularSchemas,
+  isStringType,
+  resolveRefName,
+  syncSchemaRef,
+} from './utils.ts'
 export { collect, transform, walk } from './visitor.ts'

package/src/infer.ts

@@ -0,0 +1,130 @@
+import type {
+  ArraySchemaNode,
+  DateSchemaNode,
+  DatetimeSchemaNode,
+  EnumSchemaNode,
+  IntersectionSchemaNode,
+  NumberSchemaNode,
+  ObjectSchemaNode,
+  RefSchemaNode,
+  ScalarSchemaNode,
+  SchemaNode,
+  StringSchemaNode,
+  TimeSchemaNode,
+  UnionSchemaNode,
+  UrlSchemaNode,
+} from './nodes/index.ts'
+
+/**
+ * Shared parser options used by OAS-to-AST inference and parser flows.
+ */
+export type ParserOptions = {
+  /**
+   * How `format: 'date-time'` schemas are represented. `false` falls through to a plain string.
+   */
+  dateType: false | 'string' | 'stringOffset' | 'stringLocal' | 'date'
+  /**
+   * Whether `type: 'integer'` and `format: 'int64'` produce `number` or `bigint` nodes.
+   */
+  integerType?: 'number' | 'bigint'
+  /**
+   * AST type used when no schema type can be inferred.
+   */
+  unknownType: 'any' | 'unknown' | 'void'
+  /**
+   * AST type used for completely empty schemas (`{}`).
+   */
+  emptySchemaType: 'any' | 'unknown' | 'void'
+  /**
+   * Suffix appended to derived enum names when building property schema names.
+   */
+  enumSuffix: 'enum' | (string & {})
+}
+
+/**
+ * Maps each `dateType` option value to the AST node produced by `format: 'date-time'`.
+ */
+type DateTimeNodeByDateType = {
+  date: DateSchemaNode
+  string: DatetimeSchemaNode
+  stringOffset: DatetimeSchemaNode
+  stringLocal: DatetimeSchemaNode
+  false: StringSchemaNode
+}
+
+/**
+ * Resolves the AST node produced by `format: 'date-time'` based on the `dateType` option.
+ */
+type ResolveDateTimeNode<TDateType extends ParserOptions['dateType']> = DateTimeNodeByDateType[TDateType extends keyof DateTimeNodeByDateType
+  ? TDateType
+  : 'string']
+
+/**
+ * Ordered list of `[schema-shape, SchemaNode]` pairs.
+ * `InferSchemaNode` walks this tuple in order and returns the first matching node type.
+ */
+type SchemaNodeMap<TDateType extends ParserOptions['dateType'] = 'string'> = [
+  [{ $ref: string }, RefSchemaNode],
+  [{ allOf: ReadonlyArray<unknown>; properties: object }, IntersectionSchemaNode],
+  [{ allOf: readonly [unknown, unknown, ...unknown[]] }, IntersectionSchemaNode],
+  [{ allOf: ReadonlyArray<unknown> }, SchemaNode],
+  [{ oneOf: ReadonlyArray<unknown> }, UnionSchemaNode],
+  [{ anyOf: ReadonlyArray<unknown> }, UnionSchemaNode],
+  [{ const: null }, ScalarSchemaNode],
+  [{ const: string | number | boolean }, EnumSchemaNode],
+  [{ type: ReadonlyArray<string> }, UnionSchemaNode],
+  [{ type: 'array'; enum: ReadonlyArray<unknown> }, ArraySchemaNode],
+  [{ enum: ReadonlyArray<unknown> }, EnumSchemaNode],
+  [{ type: 'enum' }, EnumSchemaNode],
+  [{ type: 'union' }, UnionSchemaNode],
+  [{ type: 'intersection' }, IntersectionSchemaNode],
+  [{ type: 'tuple' }, ArraySchemaNode],
+  [{ type: 'ref' }, RefSchemaNode],
+  [{ type: 'datetime' }, DatetimeSchemaNode],
+  [{ type: 'date' }, DateSchemaNode],
+  [{ type: 'time' }, TimeSchemaNode],
+  [{ type: 'url' }, UrlSchemaNode],
+  [{ type: 'object' }, ObjectSchemaNode],
+  [{ additionalProperties: boolean | {} }, ObjectSchemaNode],
+  [{ type: 'array' }, ArraySchemaNode],
+  [{ items: object }, ArraySchemaNode],
+  [{ prefixItems: ReadonlyArray<unknown> }, ArraySchemaNode],
+  [{ type: string; format: 'date-time' }, ResolveDateTimeNode<TDateType>],
+  [{ type: string; format: 'date' }, DateSchemaNode],
+  [{ type: string; format: 'time' }, TimeSchemaNode],
+  [{ format: 'date-time' }, ResolveDateTimeNode<TDateType>],
+  [{ format: 'date' }, DateSchemaNode],
+  [{ format: 'time' }, TimeSchemaNode],
+  [{ type: 'string' }, StringSchemaNode],
+  [{ type: 'number' }, NumberSchemaNode],
+  [{ type: 'integer' }, NumberSchemaNode],
+  [{ type: 'bigint' }, NumberSchemaNode],
+  [{ type: string }, ScalarSchemaNode],
+  [{ minLength: number }, StringSchemaNode],
+  [{ maxLength: number }, StringSchemaNode],
+  [{ pattern: string }, StringSchemaNode],
+  [{ minimum: number }, NumberSchemaNode],
+  [{ maximum: number }, NumberSchemaNode],
+]
+
+/**
+ * Infers the matching AST `SchemaNode` type from an input schema shape.
+ */
+export type InferSchemaNode<
+  TSchema extends object,
+  TDateType extends ParserOptions['dateType'] = 'string',
+  TEntries extends ReadonlyArray<[object, SchemaNode]> = SchemaNodeMap<TDateType>,
+> = TEntries extends [infer TEntry extends [object, SchemaNode], ...infer TRest extends ReadonlyArray<[object, SchemaNode]>]
+  ? TSchema extends TEntry[0]
+    ? 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/mocks.ts

@@ -1,16 +1,24 @@
-import { createOperation, createParameter, createProperty, createResponse, createRoot, createSchema } from './factory.ts'
-import type { RootNode } from './nodes/root.ts'
+import { createInput, createOperation, createParameter, createProperty, createResponse, createSchema } from './factory.ts'
+import type { InputNode } from './nodes/root.ts'
 
 /**
- * Minimal single-resource tree: one `Pet` schema and one `getPetById` operation.
+ * Builds a minimal sample AST with one `Pet` schema and one `getPetById` operation.
  */
-export function buildSampleTree(): RootNode {
+export function buildSampleTree(): InputNode {
   const petSchema = createSchema({
     type: 'object',
     name: 'Pet',
     properties: [
-      createProperty({ name: 'id', schema: createSchema({ type: 'integer' }), required: true }),
-      createProperty({ name: 'name', schema: createSchema({ type: 'string' }), required: true }),
+      createProperty({
+        name: 'id',
+        schema: createSchema({ type: 'integer' }),
+        required: true,
+      }),
+      createProperty({
+        name: 'name',
+        schema: createSchema({ type: 'string' }),
+        required: true,
+      }),
     ],
   })
 
@@ -19,9 +27,19 @@ export function buildSampleTree(): RootNode {
     method: 'GET',
     path: '/pets/{petId}',
     tags: ['pets'],
-    parameters: [createParameter({ name: 'petId', in: 'path', schema: createSchema({ type: 'integer' }), required: true })],
+    parameters: [
+      createParameter({
+        name: 'petId',
+        in: 'path',
+        schema: createSchema({ type: 'integer' }),
+        required: true,
+      }),
+    ],
     responses: [
-      createResponse({ statusCode: '200', schema: createSchema({ type: 'ref', name: 'Pet' }) }),
+      createResponse({
+        statusCode: '200',
+        schema: createSchema({ type: 'ref', name: 'Pet' }),
+      }),
       createResponse({
         statusCode: '404',
         schema: createSchema({ type: 'ref', name: 'Error' }),
@@ -29,31 +47,46 @@ export function buildSampleTree(): RootNode {
     ],
   })
 
-  return createRoot({ schemas: [petSchema], operations: [operation] })
+  return createInput({ schemas: [petSchema], operations: [operation] })
 }
 
 /**
- * PetStore-like tree: six named schemas (`Pet`, `NewPet`, `PetList`, `Error`, `PetOrError`, `FullPet`)
- * and two operations (`listPets`, `createPet`).
+ * Builds a PetStore-like fixture AST with:
+ * - six named schemas (`Pet`, `NewPet`, `PetList`, `Error`, `PetOrError`, `FullPet`)
+ * - two operations (`listPets`, `createPet`)
  */
-export function buildFixture(): RootNode {
+export function buildFixture(): InputNode {
   const refPet = createSchema({ type: 'ref', ref: 'Pet' })
   const refError = createSchema({ type: 'ref', ref: 'Error' })
 
-  return createRoot({
+  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 }),
+          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 })],
+        properties: [
+          createProperty({
+            name: 'name',
+            schema: createSchema({ type: 'string' }),
+            required: true,
+          }),
+        ],
       }),
       createSchema({
         name: 'PetList',
@@ -64,11 +97,23 @@ export function buildFixture(): RootNode {
         name: 'Error',
         type: 'object',
         properties: [
-          createProperty({ name: 'code', schema: createSchema({ type: 'integer' }), required: true }),
-          createProperty({ name: 'message', schema: createSchema({ type: 'string' }), required: true }),
+          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: 'PetOrError',
+        type: 'union',
+        members: [refPet, refError],
+      }),
       createSchema({
         name: 'FullPet',
         type: 'intersection',
@@ -76,7 +121,12 @@ export function buildFixture(): RootNode {
           refPet,
           createSchema({
             type: 'object',
-            properties: [createProperty({ name: 'createdAt', schema: createSchema({ type: 'datetime' }) })],
+            properties: [
+              createProperty({
+                name: 'createdAt',
+                schema: createSchema({ type: 'datetime' }),
+              }),
+            ],
           }),
         ],
       }),
@@ -87,10 +137,24 @@ export function buildFixture(): RootNode {
         method: 'GET',
         path: '/pets',
         tags: ['pets'],
-        parameters: [createParameter({ name: 'limit', in: 'query', schema: createSchema({ type: 'integer' }) })],
+        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' }),
+          createResponse({
+            statusCode: '200',
+            schema: createSchema({ type: 'ref', ref: 'PetList' }),
+            mediaType: 'application/json',
+          }),
+          createResponse({
+            statusCode: '400',
+            schema: refError,
+            mediaType: 'application/json',
+          }),
         ],
       }),
       createOperation({
@@ -98,8 +162,14 @@ export function buildFixture(): RootNode {
         method: 'POST',
         path: '/pets',
         tags: ['pets'],
-        requestBody: createSchema({ type: 'ref', ref: 'NewPet' }),
-        responses: [createResponse({ statusCode: '201', schema: refPet, mediaType: 'application/json' })],
+        requestBody: { content: [{ contentType: 'application/json', schema: createSchema({ type: 'ref', ref: 'NewPet' }) }] },
+        responses: [
+          createResponse({
+            statusCode: '201',
+            schema: refPet,
+            mediaType: 'application/json',
+          }),
+        ],
       }),
     ],
   })

package/src/nodes/base.ts

@@ -1,16 +1,56 @@
 /**
- * Kind discriminant for every AST node.
+ * `kind` values used by AST nodes.
+ *
+ * @example
+ * ```ts
+ * const kind: NodeKind = 'Schema'
+ * ```
  */
-export type NodeKind = 'Root' | 'Operation' | 'Schema' | 'Property' | 'Parameter' | 'Response'
+export type NodeKind =
+  | 'Input'
+  | 'Output'
+  | 'Operation'
+  | 'Schema'
+  | 'Property'
+  | 'Parameter'
+  | 'Response'
+  | 'FunctionParameter'
+  | 'ParameterGroup'
+  | 'FunctionParameters'
+  | 'Type'
+  | 'ParamsType'
+  | 'File'
+  | 'Import'
+  | 'Export'
+  | 'Source'
+  | 'Const'
+  | 'Function'
+  | 'ArrowFunction'
+  | 'Text'
+  | 'Break'
+  | 'Jsx'
 
 /**
- * Common base for all AST nodes.
+ * Base shape shared by all AST nodes.
+ *
+ * @example
+ * ```ts
+ * const base: BaseNode = { kind: 'Input' }
+ * ```
  */
 export type BaseNode = {
+  /**
+   * Node discriminator.
+   */
   kind: NodeKind
 }
 
 /**
- * Any AST node.
+ * Minimal node type when only `kind` is needed.
+ *
+ * @example
+ * ```ts
+ * const node: Node = { kind: 'Operation' }
+ * ```
  */
 export type Node = BaseNode