@kubb/plugin-ts 5.0.0-alpha.4 → 5.0.0-alpha.6

package/src/printer.ts

@@ -1,28 +1,57 @@
-import { jsStringEscape, stringify } from '@internals/utils'
+import { jsStringEscape, pascalCase, stringify } from '@internals/utils'
 import { isPlainStringType } from '@kubb/ast'
 import type { ArraySchemaNode, SchemaNode } from '@kubb/ast/types'
 import type { PrinterFactoryOptions } from '@kubb/core'
 import { definePrinter } from '@kubb/core'
 import type ts from 'typescript'
+import { ENUM_TYPES_WITH_KEY_SUFFIX, OPTIONAL_ADDS_QUESTION_TOKEN, OPTIONAL_ADDS_UNDEFINED } from './constants.ts'
 import * as factory from './factory.ts'
+import type { PluginTs } from './types.ts'
 
 type TsOptions = {
   /**
    * @default `'questionToken'`
    */
-  optionalType: 'questionToken' | 'undefined' | 'questionTokenAndUndefined'
+  optionalType: PluginTs['resolvedOptions']['optionalType']
   /**
    * @default `'array'`
    */
-  arrayType: 'array' | 'generic'
+  arrayType: PluginTs['resolvedOptions']['arrayType']
   /**
    * @default `'inlineLiteral'`
    */
-  enumType: 'enum' | 'asConst' | 'asPascalConst' | 'constEnum' | 'literal' | 'inlineLiteral'
+  enumType: PluginTs['resolvedOptions']['enumType']
+  /**
+   * Controls whether a `type` alias or `interface` declaration is emitted.
+   * @default `'type'`
+   */
+  syntaxType?: PluginTs['resolvedOptions']['syntaxType']
+  /**
+   * When set, `printer.print(node)` produces a full `type Name = …` declaration.
+   * When omitted, `printer.print(node)` returns the raw type node.
+   */
+  typeName?: string
+
+  /**
+   * JSDoc `@description` comment added to the generated type or interface declaration.
+   */
+  description?: string
+  /**
+   * Property keys to exclude from the generated type via `Omit<Type, Keys>`.
+   * Forces type-alias syntax even when `syntaxType` is `'interface'`.
+   */
+  keysToOmit?: Array<string>
 }
 
-type TsPrinter = PrinterFactoryOptions<'typescript', TsOptions, ts.TypeNode>
+/**
+ * TypeScript printer factory options: maps `SchemaNode` → `ts.TypeNode` (raw) or `ts.Node` (full declaration).
+ */
+type TsPrinter = PrinterFactoryOptions<'typescript', TsOptions, ts.TypeNode, ts.Node>
 
+/**
+ * Converts a primitive const value to a TypeScript literal type node.
+ * Handles negative numbers via a prefix unary expression.
+ */
 function constToTypeNode(value: string | number | boolean, format: 'string' | 'number' | 'boolean'): ts.TypeNode | undefined {
   if (format === 'boolean') {
     return factory.createLiteralTypeNode(value === true ? factory.createTrue() : factory.createFalse())
@@ -36,16 +65,26 @@ function constToTypeNode(value: string | number | boolean, format: 'string' | 'n
   return factory.createLiteralTypeNode(factory.createStringLiteral(String(value)))
 }
 
+/**
+ * Returns a `Date` reference type node when `representation` is `'date'`, otherwise falls back to `string`.
+ */
 function dateOrStringNode(node: { representation?: string }): ts.TypeNode {
   return node.representation === 'date' ? factory.createTypeReferenceNode(factory.createIdentifier('Date')) : factory.keywordTypeNodes.string
 }
 
+/**
+ * Maps an array of `SchemaNode`s through the printer, filtering out `null` and `undefined` results.
+ */
 function buildMemberNodes(members: Array<SchemaNode> | undefined, print: (node: SchemaNode) => ts.TypeNode | null | undefined): Array<ts.TypeNode> {
-  return (members ?? []).map(print).filter(Boolean) as Array<ts.TypeNode>
+  return (members ?? []).map(print).filter(Boolean)
 }
 
+/**
+ * Builds a TypeScript tuple type node from an array schema's `items`,
+ * applying min/max slice and optional/rest element rules.
+ */
 function buildTupleNode(node: ArraySchemaNode, print: (node: SchemaNode) => ts.TypeNode | null | undefined): ts.TypeNode | undefined {
-  let items = (node.items ?? []).map(print).filter(Boolean) as Array<ts.TypeNode>
+  let items = (node.items ?? []).map(print).filter(Boolean)
 
   const restNode = node.rest ? (print(node.rest) ?? undefined) : undefined
   const { min, max } = node
@@ -68,25 +107,31 @@ function buildTupleNode(node: ArraySchemaNode, print: (node: SchemaNode) => ts.T
   return factory.createTupleTypeNode(items)
 }
 
+/**
+ * Applies `nullable` and optional/nullish `| undefined` union modifiers to a property's resolved base type.
+ */
 function buildPropertyType(schema: SchemaNode, baseType: ts.TypeNode, optionalType: TsOptions['optionalType']): ts.TypeNode {
-  const addsUndefined = ['undefined', 'questionTokenAndUndefined'].includes(optionalType)
+  const addsUndefined = OPTIONAL_ADDS_UNDEFINED.has(optionalType)
 
   let type = baseType
 
   if (schema.nullable) {
-    type = factory.createUnionDeclaration({ nodes: [type, factory.keywordTypeNodes.null] }) as ts.TypeNode
+    type = factory.createUnionDeclaration({ nodes: [type, factory.keywordTypeNodes.null] })
   }
 
   if ((schema.nullish || schema.optional) && addsUndefined) {
-    type = factory.createUnionDeclaration({ nodes: [type, factory.keywordTypeNodes.undefined] }) as ts.TypeNode
+    type = factory.createUnionDeclaration({ nodes: [type, factory.keywordTypeNodes.undefined] })
   }
 
   return type
 }
 
+/**
+ * Collects JSDoc annotation strings (description, deprecated, min/max, pattern, default, example, type) for a schema node.
+ */
 function buildPropertyJSDocComments(schema: SchemaNode): Array<string | undefined> {
   return [
-    'description' in schema && schema.description ? `@description ${jsStringEscape(schema.description as string)}` : undefined,
+    'description' in schema && schema.description ? `@description ${jsStringEscape(schema.description)}` : undefined,
     'deprecated' in schema && schema.deprecated ? '@deprecated' : undefined,
     'min' in schema && schema.min !== undefined ? `@minLength ${schema.min}` : undefined,
     'max' in schema && schema.max !== undefined ? `@maxLength ${schema.max}` : undefined,
@@ -101,6 +146,9 @@ function buildPropertyJSDocComments(schema: SchemaNode): Array<string | undefine
   ]
 }
 
+/**
+ * Creates TypeScript index signatures for `additionalProperties` and `patternProperties` on an object schema node.
+ */
 function buildIndexSignatures(
   node: { additionalProperties?: SchemaNode | boolean; patternProperties?: Record<string, SchemaNode> },
   propertyCount: number,
@@ -109,7 +157,8 @@ function buildIndexSignatures(
   const elements: Array<ts.TypeElement> = []
 
   if (node.additionalProperties && node.additionalProperties !== true) {
-    const additionalType = (print(node.additionalProperties as SchemaNode) ?? factory.keywordTypeNodes.unknown) as ts.TypeNode
+    const additionalType = print(node.additionalProperties) ?? factory.keywordTypeNodes.unknown
+
     elements.push(factory.createIndexSignature(propertyCount > 0 ? factory.keywordTypeNodes.unknown : additionalType))
   } else if (node.additionalProperties === true) {
     elements.push(factory.createIndexSignature(factory.keywordTypeNodes.unknown))
@@ -118,9 +167,10 @@ function buildIndexSignatures(
   if (node.patternProperties) {
     const first = Object.values(node.patternProperties)[0]
     if (first) {
-      let patternType = (print(first) ?? factory.keywordTypeNodes.unknown) as ts.TypeNode
+      let patternType = print(first) ?? factory.keywordTypeNodes.unknown
+
       if (first.nullable) {
-        patternType = factory.createUnionDeclaration({ nodes: [patternType, factory.keywordTypeNodes.null] }) as ts.TypeNode
+        patternType = factory.createUnionDeclaration({ nodes: [patternType, factory.keywordTypeNodes.null] })
       }
       elements.push(factory.createIndexSignature(patternType))
     }
@@ -130,115 +180,189 @@ function buildIndexSignatures(
 }
 
 /**
- * Converts a `SchemaNode` AST node into a TypeScript `ts.TypeNode`.
+ * TypeScript type printer built with `definePrinter`.
+ *
+ * Converts a `SchemaNode` AST node into a TypeScript AST node:
+ * - **`printer.print(node)`** — when `options.typeName` is set, returns a full
+ *   `type Name = …` or `interface Name { … }` declaration (`ts.Node`).
+ *   Without `typeName`, returns the raw `ts.TypeNode` for the schema.
+ *
+ * Dispatches on `node.type` to the appropriate handler in `nodes`. Options are closed
+ * over per printer instance, so each call to `printerTs(options)` produces an independent printer.
  *
- * Built on `definePrinter` — dispatches on `node.type`, with options closed over
- * per printer instance. Produces the same `ts.TypeNode` output as the keyword-based
- * `parse` in `parser.ts`.
+ * @example Raw type node (no `typeName`)
+ * ```ts
+ * const printer = printerTs({ optionalType: 'questionToken', arrayType: 'array', enumType: 'inlineLiteral' })
+ * const typeNode = printer.print(schemaNode) // ts.TypeNode
+ * ```
+ *
+ * @example Full declaration (with `typeName`)
+ * ```ts
+ * const printer = printerTs({ optionalType: 'questionToken', arrayType: 'array', enumType: 'inlineLiteral', typeName: 'MyType' })
+ * const declaration = printer.print(schemaNode) // ts.TypeAliasDeclaration | ts.InterfaceDeclaration
+ * ```
  */
-export const printerTs = definePrinter<TsPrinter>((options) => ({
-  name: 'typescript',
-  options,
-  nodes: {
-    any: () => factory.keywordTypeNodes.any,
-    unknown: () => factory.keywordTypeNodes.unknown,
-    void: () => factory.keywordTypeNodes.void,
-    boolean: () => factory.keywordTypeNodes.boolean,
-    null: () => factory.keywordTypeNodes.null,
-    blob: () => factory.createTypeReferenceNode('Blob', []),
-    string: () => factory.keywordTypeNodes.string,
-    uuid: () => factory.keywordTypeNodes.string,
-    email: () => factory.keywordTypeNodes.string,
-    url: () => factory.keywordTypeNodes.string,
-    datetime: () => factory.keywordTypeNodes.string,
-    number: () => factory.keywordTypeNodes.number,
-    integer: () => factory.keywordTypeNodes.number,
-    bigint: () => factory.keywordTypeNodes.bigint,
-    date: (node) => dateOrStringNode(node),
-    time: (node) => dateOrStringNode(node),
-    ref(node) {
-      if (!node.name) {
-        return undefined
-      }
-      return factory.createTypeReferenceNode(node.name, undefined)
-    },
-    enum(node) {
-      const values = node.namedEnumValues?.map((v) => v.value) ?? node.enumValues ?? []
+export const printerTs = definePrinter<TsPrinter>((options) => {
+  const addsUndefined = OPTIONAL_ADDS_UNDEFINED.has(options.optionalType)
+
+  return {
+    name: 'typescript',
+    options,
+    nodes: {
+      any: () => factory.keywordTypeNodes.any,
+      unknown: () => factory.keywordTypeNodes.unknown,
+      void: () => factory.keywordTypeNodes.void,
+      never: () => factory.keywordTypeNodes.never,
+      boolean: () => factory.keywordTypeNodes.boolean,
+      null: () => factory.keywordTypeNodes.null,
+      blob: () => factory.createTypeReferenceNode('Blob', []),
+      string: () => factory.keywordTypeNodes.string,
+      uuid: () => factory.keywordTypeNodes.string,
+      email: () => factory.keywordTypeNodes.string,
+      url: (node) => {
+        if (node.path) {
+          return factory.createUrlTemplateType(node.path)
+        }
+        return factory.keywordTypeNodes.string
+      },
+      datetime: () => factory.keywordTypeNodes.string,
+      number: () => factory.keywordTypeNodes.number,
+      integer: () => factory.keywordTypeNodes.number,
+      bigint: () => factory.keywordTypeNodes.bigint,
+      date: dateOrStringNode,
+      time: dateOrStringNode,
+      ref(node) {
+        if (!node.name) {
+          return undefined
+        }
+        return factory.createTypeReferenceNode(node.name, undefined)
+      },
+      enum(node) {
+        const values = node.namedEnumValues?.map((v) => v.value) ?? node.enumValues ?? []
+
+        if (this.options.enumType === 'inlineLiteral' || !node.name) {
+          const literalNodes = values
+            .filter((v): v is string | number | boolean => v !== null)
+            .map((value) => constToTypeNode(value, typeof value as 'string' | 'number' | 'boolean'))
+            .filter(Boolean)
+
+          return factory.createUnionDeclaration({ withParentheses: true, nodes: literalNodes }) ?? undefined
+        }
+
+        const resolvedName = pascalCase(node.name)
+        const typeName = ENUM_TYPES_WITH_KEY_SUFFIX.has(this.options.enumType) ? `${resolvedName}Key` : resolvedName
+
+        return factory.createTypeReferenceNode(typeName, undefined)
+      },
+      union(node) {
+        const members = node.members ?? []
+
+        const hasStringLiteral = members.some((m) => m.type === 'enum' && m.enumType === 'string')
+        const hasPlainString = members.some((m) => isPlainStringType(m))
+
+        if (hasStringLiteral && hasPlainString) {
+          const memberNodes = members
+            .map((m) => {
+              if (isPlainStringType(m)) {
+                return factory.createIntersectionDeclaration({
+                  nodes: [factory.keywordTypeNodes.string, factory.createTypeLiteralNode([])],
+                  withParentheses: true,
+                })
+              }
+
+              return this.print(m)
+            })
+            .filter(Boolean)
+
+          return factory.createUnionDeclaration({ withParentheses: true, nodes: memberNodes }) ?? undefined
+        }
+
+        return factory.createUnionDeclaration({ withParentheses: true, nodes: buildMemberNodes(members, this.print) }) ?? undefined
+      },
+      intersection(node) {
+        return factory.createIntersectionDeclaration({ withParentheses: true, nodes: buildMemberNodes(node.members, this.print) }) ?? undefined
+      },
+      array(node) {
+        const itemNodes = (node.items ?? []).map((item) => this.print(item)).filter(Boolean)
+
+        return factory.createArrayDeclaration({ nodes: itemNodes, arrayType: this.options.arrayType }) ?? undefined
+      },
+      tuple(node) {
+        return buildTupleNode(node, this.print)
+      },
+      object(node) {
+        const { print, options } = this
+        const addsQuestionToken = OPTIONAL_ADDS_QUESTION_TOKEN.has(options.optionalType)
+
+        const propertyNodes: Array<ts.TypeElement> = node.properties.map((prop) => {
+          const baseType = print(prop.schema) ?? factory.keywordTypeNodes.unknown
+          const type = buildPropertyType(prop.schema, baseType, options.optionalType)
+
+          const propertyNode = factory.createPropertySignature({
+            questionToken: prop.schema.optional || prop.schema.nullish ? addsQuestionToken : false,
+            name: prop.name,
+            type,
+            readOnly: prop.schema.readOnly,
+          })
 
-      if (this.options.enumType === 'inlineLiteral' || !node.name) {
-        const literalNodes = values
-          .filter((v): v is string | number | boolean => v !== null)
-          .map((value) => constToTypeNode(value, typeof value === 'number' ? 'number' : typeof value === 'boolean' ? 'boolean' : 'string'))
-          .filter(Boolean) as Array<ts.TypeNode>
+          return factory.appendJSDocToNode({ node: propertyNode, comments: buildPropertyJSDocComments(prop.schema) })
+        })
 
-        return factory.createUnionDeclaration({ withParentheses: true, nodes: literalNodes }) ?? undefined
-      }
+        const allElements = [...propertyNodes, ...buildIndexSignatures(node, propertyNodes.length, print)]
 
-      const typeName = ['asConst', 'asPascalConst'].includes(this.options.enumType) ? `${node.name}Key` : node.name
+        if (!allElements.length) {
+          return factory.keywordTypeNodes.object
+        }
 
-      return factory.createTypeReferenceNode(typeName, undefined)
+        return factory.createTypeLiteralNode(allElements)
+      },
     },
-    union(node) {
-      const members = node.members ?? []
-
-      const hasStringLiteral = members.some((m) => m.type === 'enum' && m.enumType === 'string')
-      const hasPlainString = members.some((m) => isPlainStringType(m))
-
-      if (hasStringLiteral && hasPlainString) {
-        const nodes = members
-          .map((m) => {
-            if (isPlainStringType(m)) {
-              return factory.createIntersectionDeclaration({
-                nodes: [factory.keywordTypeNodes.string, factory.createTypeLiteralNode([])],
-                withParentheses: true,
-              }) as ts.TypeNode
-            }
-
-            return this.print(m)
-          })
-          .filter(Boolean) as Array<ts.TypeNode>
+    print(node) {
+      let type = this.print(node)
 
-        return factory.createUnionDeclaration({ withParentheses: true, nodes }) ?? undefined
+      if (!type) {
+        return undefined
       }
 
-      return factory.createUnionDeclaration({ withParentheses: true, nodes: buildMemberNodes(members, this.print) }) ?? undefined
-    },
-    intersection(node) {
-      return factory.createIntersectionDeclaration({ withParentheses: true, nodes: buildMemberNodes(node.members, this.print) }) ?? undefined
-    },
-    array(node) {
-      const itemNodes = (node.items ?? []).map((item) => this.print(item)).filter(Boolean) as Array<ts.TypeNode>
-
-      return factory.createArrayDeclaration({ nodes: itemNodes, arrayType: this.options.arrayType }) ?? undefined
-    },
-    tuple(node) {
-      return buildTupleNode(node, this.print)
-    },
-    object(node) {
-      const addsQuestionToken = ['questionToken', 'questionTokenAndUndefined'].includes(this.options.optionalType)
-      const { print } = this
-
-      const propertyNodes: Array<ts.TypeElement> = node.properties.map((prop) => {
-        const baseType = (print(prop.schema) ?? factory.keywordTypeNodes.unknown) as ts.TypeNode
-        const type = buildPropertyType(prop.schema, baseType, this.options.optionalType)
-
-        const propertyNode = factory.createPropertySignature({
-          questionToken: prop.schema.optional || prop.schema.nullish ? addsQuestionToken : false,
-          name: prop.name,
-          type,
-          readOnly: prop.schema.readOnly,
-        })
-
-        return factory.appendJSDocToNode({ node: propertyNode, comments: buildPropertyJSDocComments(prop.schema) })
-      })
+      // Apply top-level nullable / optional union modifiers.
+      if (node.nullable) {
+        type = factory.createUnionDeclaration({ nodes: [type, factory.keywordTypeNodes.null] })
+      }
 
-      const allElements = [...propertyNodes, ...buildIndexSignatures(node, propertyNodes.length, print)]
+      if ((node.nullish || node.optional) && addsUndefined) {
+        type = factory.createUnionDeclaration({ nodes: [type, factory.keywordTypeNodes.undefined] })
+      }
 
-      if (!allElements.length) {
-        return factory.keywordTypeNodes.object
+      // Without typeName, return the type node as-is (no declaration wrapping).
+      const { typeName, syntaxType = 'type', description, keysToOmit } = this.options
+      if (!typeName) {
+        return type
       }
 
-      return factory.createTypeLiteralNode(allElements)
+      const useTypeGeneration = syntaxType === 'type' || type.kind === factory.syntaxKind.union || !!keysToOmit?.length
+
+      return factory.createTypeDeclaration({
+        name: typeName,
+        isExportable: true,
+        type: keysToOmit?.length
+          ? factory.createOmitDeclaration({
+              keys: keysToOmit,
+              type,
+              nonNullable: true,
+            })
+          : type,
+        syntax: useTypeGeneration ? 'type' : 'interface',
+        comments: [
+          node?.title ? jsStringEscape(node.title) : undefined,
+          description ? `@description ${jsStringEscape(description)}` : undefined,
+          node?.deprecated ? '@deprecated' : undefined,
+          node && 'min' in node && node.min !== undefined ? `@minLength ${node.min}` : undefined,
+          node && 'max' in node && node.max !== undefined ? `@maxLength ${node.max}` : undefined,
+          node && 'pattern' in node && node.pattern ? `@pattern ${node.pattern}` : undefined,
+          node?.default ? `@default ${node.default}` : undefined,
+          node?.example ? `@example ${node.example}` : undefined,
+        ],
+      })
     },
-  },
-}))
+  }
+})

package/src/types.ts

@@ -2,7 +2,6 @@ import type { Group, Output, PluginFactoryOptions, ResolveNameParams } from '@ku
 import type { contentType, Oas } from '@kubb/oas'
 import type { Exclude, Include, Override, ResolvePathOptions } from '@kubb/plugin-oas'
 import type { Generator } from '@kubb/plugin-oas/generators'
-import type ts from 'typescript'
 
 export type Options = {
   /**
@@ -63,6 +62,8 @@ export type Options = {
   /**
    * Set a suffix for the generated enums.
    * @default 'enum'
+   * @deprecated Set `enumSuffix` on the adapter (`adapterOas({ enumSuffix })`) instead.
+   * In v5, the adapter owns this decision at parse time; the plugin option is ignored.
    */
   enumSuffix?: string
   /**
@@ -70,6 +71,8 @@ export type Options = {
    * - 'string' represents dates as string values.
    * - 'date' represents dates as JavaScript Date objects.
    * @default 'string'
+   * @deprecated Set `dateType` on the adapter (`adapterOas({ dateType })`) instead.
+   * In v5, the adapter owns this decision at parse time; the plugin option is ignored.
    */
   dateType?: 'string' | 'date'
   /**
@@ -78,6 +81,8 @@ export type Options = {
    * - 'bigint' uses the TypeScript `bigint` type (accurate for values exceeding Number.MAX_SAFE_INTEGER).
    * @note in v5 of Kubb 'bigint' will become the default to better align with OpenAPI's int64 specification.
    * @default 'number'
+   * @deprecated Set `integerType` on the adapter (`adapterOas({ integerType })`) instead.
+   * In v5, the adapter owns this decision at parse time; the plugin option is ignored.
    */
   integerType?: 'number' | 'bigint'
   /**
@@ -86,6 +91,8 @@ export type Options = {
    * - 'unknown' requires type narrowing before use.
    * - 'void' represents no value.
    * @default 'any'
+   * @deprecated Set `unknownType` on the adapter (`adapterOas({ unknownType })`) instead.
+   * In v5, the adapter owns this decision at parse time; the plugin option is ignored.
    */
   unknownType?: 'any' | 'unknown' | 'void'
   /**
@@ -94,6 +101,8 @@ export type Options = {
    * - 'unknown' requires type narrowing before use.
    * - 'void' represents no value.
    * @default `unknownType`
+   * @deprecated Set `emptySchemaType` on the adapter (`adapterOas({ emptySchemaType })`) instead.
+   * In v5, the adapter owns this decision at parse time; the plugin option is ignored.
    */
   emptySchemaType?: 'any' | 'unknown' | 'void'
   /**
@@ -117,17 +126,6 @@ export type Options = {
      */
     name?: (name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string
   }
-  /**
-   * @example
-   * Use https://ts-ast-viewer.com to generate factory code(see createPropertySignature)
-   * category: factory.createPropertySignature(
-   *   undefined,
-   *   factory.createIdentifier("category"),
-   *   factory.createToken(ts.SyntaxKind.QuestionToken),
-   *   factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword)
-   * )
-   */
-  mapper?: Record<string, ts.PropertySignature>
   /**
    * How to style your params, by default no casing is applied
    * - 'camelcase' uses camelCase for pathParams, queryParams and headerParams property names
@@ -160,7 +158,6 @@ type ResolvedOptions = {
   arrayType: NonNullable<Options['arrayType']>
   transformers: NonNullable<Options['transformers']>
   syntaxType: NonNullable<Options['syntaxType']>
-  mapper: Record<string, any>
   paramsCasing: Options['paramsCasing']
 }