@kubb/plugin-ts 5.0.0-alpha.8 → 5.0.0-beta.3

package/src/factory.ts

@@ -1,11 +1,16 @@
 import { camelCase, pascalCase, screamingSnakeCase, snakeCase } from '@internals/utils'
+import { ast } from '@kubb/core'
 import { isNumber, sortBy } from 'remeda'
 import ts from 'typescript'
+import { OPTIONAL_ADDS_UNDEFINED } from './constants.ts'
 
 const { SyntaxKind, factory } = ts
 
 // https://ts-ast-viewer.com/
 
+/**
+ * TypeScript AST modifiers for common keywords (async, export, const, static).
+ */
 export const modifiers = {
   async: factory.createModifier(ts.SyntaxKind.AsyncKeyword),
   export: factory.createModifier(ts.SyntaxKind.ExportKeyword),
@@ -13,22 +18,15 @@ export const modifiers = {
   static: factory.createModifier(ts.SyntaxKind.StaticKeyword),
 } as const
 
+/**
+ * TypeScript syntax kind constants for union, literal, and string types.
+ */
 export const syntaxKind = {
   union: SyntaxKind.UnionType as 192,
   literalType: SyntaxKind.LiteralType,
   stringLiteral: SyntaxKind.StringLiteral,
 } as const
 
-export function getUnknownType(unknownType: 'any' | 'unknown' | 'void' | undefined) {
-  if (unknownType === 'any') {
-    return keywordTypeNodes.any
-  }
-  if (unknownType === 'void') {
-    return keywordTypeNodes.void
-  }
-
-  return keywordTypeNodes.unknown
-}
 function isValidIdentifier(str: string): boolean {
   if (!str.length || str.trim() !== str) {
     return false
@@ -48,6 +46,10 @@ function propertyName(name: string | ts.PropertyName): ts.PropertyName {
 
 const questionToken = factory.createToken(ts.SyntaxKind.QuestionToken)
 
+/**
+ * Creates a question token for optional type annotations.
+ * Pass `true` to use the cached token, or provide a pre-created token.
+ */
 export function createQuestionToken(token?: boolean | ts.QuestionToken) {
   if (!token) {
     return undefined
@@ -58,6 +60,10 @@ export function createQuestionToken(token?: boolean | ts.QuestionToken) {
   return token
 }
 
+/**
+ * Creates a TypeScript intersection type node from multiple type nodes.
+ * Returns the single node if only one is provided, or wraps in parentheses if requested.
+ */
 export function createIntersectionDeclaration({ nodes, withParentheses }: { nodes: Array<ts.TypeNode>; withParentheses?: boolean }): ts.TypeNode | null {
   if (!nodes.length) {
     return null
@@ -77,27 +83,15 @@ export function createIntersectionDeclaration({ nodes, withParentheses }: { node
 }
 
 /**
- * Minimum nodes length of 2
- * @example `string & number`
+ * Creates a TypeScript array type node.
+ * Use `arrayType: 'array'` for bracket syntax (`T[]`), or `'generic'` for `Array<T>`.
+ *
+ * @example Array bracket syntax
+ * `createArrayDeclaration({ nodes: [stringType], arrayType: 'array' }) // → string[]`
+ *
+ * @example Generic Array syntax
+ * `createArrayDeclaration({ nodes: [stringType], arrayType: 'generic' }) // → Array<string>`
  */
-export function createTupleDeclaration({ nodes, withParentheses }: { nodes: Array<ts.TypeNode>; withParentheses?: boolean }): ts.TypeNode | null {
-  if (!nodes.length) {
-    return null
-  }
-
-  if (nodes.length === 1) {
-    return nodes[0] || null
-  }
-
-  const node = factory.createTupleTypeNode(nodes)
-
-  if (withParentheses) {
-    return factory.createParenthesizedType(node)
-  }
-
-  return node
-}
-
 export function createArrayDeclaration({ nodes, arrayType = 'array' }: { nodes: Array<ts.TypeNode>; arrayType?: 'array' | 'generic' }): ts.TypeNode | null {
   if (!nodes.length) {
     return factory.createTupleTypeNode([])
@@ -125,7 +119,8 @@ export function createArrayDeclaration({ nodes, arrayType = 'array' }: { nodes:
 
 /**
  * Minimum nodes length of 2
- * @example `string | number`
+ * @example Union type example
+ * `string | number`
  */
 export function createUnionDeclaration({ nodes, withParentheses }: { nodes: Array<ts.TypeNode>; withParentheses?: boolean }): ts.TypeNode {
   if (!nodes.length) {
@@ -145,6 +140,10 @@ export function createUnionDeclaration({ nodes, withParentheses }: { nodes: Arra
   return node
 }
 
+/**
+ * Creates a TypeScript property signature for object/interface members.
+ * Supports optional markers, readonly modifiers, and type annotations.
+ */
 export function createPropertySignature({
   readOnly,
   modifiers = [],
@@ -166,6 +165,9 @@ export function createPropertySignature({
   )
 }
 
+/**
+ * Creates a function parameter declaration with optional markers, rest parameters, and type annotations.
+ */
 export function createParameterSignature(
   name: string | ts.BindingName,
   {
@@ -186,6 +188,10 @@ export function createParameterSignature(
   return factory.createParameterDeclaration(modifiers, dotDotDotToken, name, createQuestionToken(questionToken), type, initializer)
 }
 
+/**
+ * Creates a JSDoc comment node from an array of comment strings.
+ * Returns null if no comments are provided.
+ */
 export function createJSDoc({ comments }: { comments: string[] }) {
   if (!comments.length) {
     return null
@@ -204,7 +210,10 @@ export function createJSDoc({ comments }: { comments: string[] }) {
 }
 
 /**
- * @link https://github.com/microsoft/TypeScript/issues/44151
+ * Attaches JSDoc comments to an AST node as synthetic leading comments.
+ * Filters out undefined comments before attaching.
+ *
+ * @see https://github.com/microsoft/TypeScript/issues/44151
  */
 export function appendJSDocToNode<TNode extends ts.Node>({ node, comments }: { node: TNode; comments: Array<string | undefined> }) {
   const filteredComments = comments.filter(Boolean)
@@ -222,6 +231,10 @@ export function appendJSDocToNode<TNode extends ts.Node>({ node, comments }: { n
   return ts.addSyntheticLeadingComment(node, ts.SyntaxKind.MultiLineCommentTrivia, `${text || '*'}\n`, true)
 }
 
+/**
+ * Creates a TypeScript index signature for dynamic property access.
+ * Defines the key type (default: `string`) and value type on an object.
+ */
 export function createIndexSignature(
   type: ts.TypeNode,
   {
@@ -238,6 +251,9 @@ export function createIndexSignature(
   return factory.createIndexSignature(modifiers, [createParameterSignature(indexName, { type: indexType })], type)
 }
 
+/**
+ * Creates a TypeScript type alias declaration with optional modifiers and type parameters.
+ */
 export function createTypeAliasDeclaration({
   modifiers,
   name,
@@ -252,6 +268,9 @@ export function createTypeAliasDeclaration({
   return factory.createTypeAliasDeclaration(modifiers, name, typeParameters, type)
 }
 
+/**
+ * Creates a TypeScript interface declaration with optional modifiers, type parameters, and members.
+ */
 export function createInterfaceDeclaration({
   modifiers,
   name,
@@ -266,6 +285,10 @@ export function createInterfaceDeclaration({
   return factory.createInterfaceDeclaration(modifiers, name, typeParameters, undefined, members)
 }
 
+/**
+ * Creates a TypeScript type declaration as either a type alias or interface.
+ * Intelligently selects the syntax based on the type structure and attaches JSDoc comments.
+ */
 export function createTypeDeclaration({
   syntax,
   isExportable,
@@ -281,7 +304,7 @@ export function createTypeDeclaration({
 }) {
   if (syntax === 'interface' && 'members' in type) {
     const node = createInterfaceDeclaration({
-      members: type.members as Array<ts.TypeElement>,
+      members: [...(type as ts.TypeLiteralNode).members],
       modifiers: isExportable ? [modifiers.export] : [],
       name,
       typeParameters: undefined,
@@ -306,6 +329,9 @@ export function createTypeDeclaration({
   })
 }
 
+/**
+ * Creates a TypeScript namespace declaration (exported module).
+ */
 export function createNamespaceDeclaration({ statements, name }: { name: string; statements: ts.Statement[] }) {
   return factory.createModuleDeclaration(
     [factory.createToken(ts.SyntaxKind.ExportKeyword)],
@@ -316,8 +342,17 @@ export function createNamespaceDeclaration({ statements, name }: { name: string;
 }
 
 /**
- * In { propertyName: string; name?: string } is `name` being used to make the type more unique when multiple same names are used.
- * @example `import { Pet as Cat } from './Pet'`
+ * Creates an import declaration with support for default imports, named imports, namespace imports, and type-only imports.
+ * Optionally rename imported members with `propertyName` and `name` pairs.
+ *
+ * @example Default import
+ * `import Pet from './Pet'`
+ *
+ * @example Named imports with rename
+ * `import { Pet as Cat } from './Pet'`
+ *
+ * @example Namespace import
+ * `import * as Pet from './Pet'`
  */
 export function createImportDeclaration({
   name,
@@ -375,6 +410,10 @@ export function createImportDeclaration({
   )
 }
 
+/**
+ * Creates an export declaration with support for named exports, namespace exports, and type-only exports.
+ * Sorts export names alphabetically for consistent output across platforms.
+ */
 export function createExportDeclaration({
   path,
   asAlias,
@@ -440,6 +479,20 @@ function applyEnumKeyCasing(key: string, casing: 'screamingSnakeCase' | 'snakeCa
   return key
 }
 
+/**
+ * Creates a TypeScript enum declaration or equivalent construct in various formats.
+ * Returns a tuple of [name node, type node] - name node may be undefined for certain types.
+ *
+ * @example
+ * ```ts
+ * const [name, type] = createEnumDeclaration({
+ *   type: 'enum',
+ *   name: 'petType',
+ *   typeName: 'PetType',
+ *   enums: [['cat', 'cat'], ['dog', 'dog']],
+ * })
+ * ```
+ */
 export function createEnumDeclaration({
   type = 'enum',
   name,
@@ -626,6 +679,10 @@ export function createEnumDeclaration({
   ]
 }
 
+/**
+ * Creates a TypeScript `Omit<T, Keys>` type reference node.
+ * Optionally wraps the type in `NonNullable<T>` if `nonNullable` is true.
+ */
 export function createOmitDeclaration({ keys, type, nonNullable }: { keys: Array<string> | string; type: ts.TypeNode; nonNullable?: boolean }) {
   const node = nonNullable ? factory.createTypeReferenceNode(factory.createIdentifier('NonNullable'), [type]) : type
 
@@ -643,6 +700,10 @@ export function createOmitDeclaration({ keys, type, nonNullable }: { keys: Array
   return factory.createTypeReferenceNode(factory.createIdentifier('Omit'), [node, factory.createLiteralTypeNode(factory.createStringLiteral(keys))])
 }
 
+/**
+ * Pre-built TypeScript keyword type nodes for common primitive types.
+ * Use these to avoid repeatedly creating the same type nodes.
+ */
 export const keywordTypeNodes = {
   any: factory.createKeywordTypeNode(ts.SyntaxKind.AnyKeyword),
   unknown: factory.createKeywordTypeNode(ts.SyntaxKind.UnknownKeyword),
@@ -701,26 +762,213 @@ export function createUrlTemplateType(path: string): ts.TypeNode {
   return ts.factory.createTemplateLiteralType(head, templateSpans)
 }
 
+/**
+ * Creates a TypeScript type literal node (anonymous object type).
+ */
 export const createTypeLiteralNode = factory.createTypeLiteralNode
 
+/**
+ * Creates a TypeScript type reference node (e.g., `Array<string>`, `Record<K, V>`).
+ */
 export const createTypeReferenceNode = factory.createTypeReferenceNode
+
+/**
+ * Creates a numeric literal type node.
+ */
 export const createNumericLiteral = factory.createNumericLiteral
+
+/**
+ * Creates a string literal type node.
+ */
 export const createStringLiteral = factory.createStringLiteral
 
+/**
+ * Creates an array type node (e.g., `T[]`).
+ */
 export const createArrayTypeNode = factory.createArrayTypeNode
+
+/**
+ * Creates a parenthesized type node to control operator precedence.
+ */
 export const createParenthesizedType = factory.createParenthesizedType
 
+/**
+ * Creates a literal type node (e.g., `'hello'`, `42`, `true`).
+ */
 export const createLiteralTypeNode = factory.createLiteralTypeNode
+
+/**
+ * Creates a null literal type node.
+ */
 export const createNull = factory.createNull
+
+/**
+ * Creates an identifier node.
+ */
 export const createIdentifier = factory.createIdentifier
 
+/**
+ * Creates an optional type node (e.g., `T | undefined`).
+ */
 export const createOptionalTypeNode = factory.createOptionalTypeNode
+
+/**
+ * Creates a tuple type node (e.g., `[string, number]`).
+ */
 export const createTupleTypeNode = factory.createTupleTypeNode
+
+/**
+ * Creates a rest type node for variadic tuple elements (e.g., `...T[]`).
+ */
 export const createRestTypeNode = factory.createRestTypeNode
+
+/**
+ * Creates a boolean true literal type node.
+ */
 export const createTrue = factory.createTrue
+
+/**
+ * Creates a boolean false literal type node.
+ */
 export const createFalse = factory.createFalse
+
+/**
+ * Creates an indexed access type node (e.g., `T[K]`).
+ */
 export const createIndexedAccessTypeNode = factory.createIndexedAccessTypeNode
+
+/**
+ * Creates a type operator node (e.g., `keyof T`, `readonly T[]`).
+ */
 export const createTypeOperatorNode = factory.createTypeOperatorNode
+
+/**
+ * Creates a prefix unary expression (e.g., negative numbers, logical not).
+ */
 export const createPrefixUnaryExpression = factory.createPrefixUnaryExpression
 
+/**
+ * Exports TypeScript SyntaxKind enum for AST node type checking.
+ */
 export { SyntaxKind }
+
+// ─── Printer helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Converts a primitive const value to a TypeScript literal type node.
+ * Handles negative numbers via a prefix unary expression.
+ */
+export function constToTypeNode(value: string | number | boolean, format: 'string' | 'number' | 'boolean'): ts.TypeNode | undefined {
+  if (format === 'boolean') {
+    return createLiteralTypeNode(value === true ? createTrue() : createFalse())
+  }
+  if (format === 'number' && typeof value === 'number') {
+    if (value < 0) {
+      return createLiteralTypeNode(createPrefixUnaryExpression(SyntaxKind.MinusToken, createNumericLiteral(Math.abs(value))))
+    }
+    return createLiteralTypeNode(createNumericLiteral(value))
+  }
+  return createLiteralTypeNode(createStringLiteral(String(value)))
+}
+
+/**
+ * Returns a `Date` reference type node when `representation` is `'date'`, otherwise falls back to `string`.
+ */
+export function dateOrStringNode(node: { representation?: string }): ts.TypeNode {
+  return node.representation === 'date' ? createTypeReferenceNode(createIdentifier('Date')) : keywordTypeNodes.string
+}
+
+/**
+ * Maps an array of `SchemaNode`s through the printer, filtering out `null` and `undefined` results.
+ */
+export function buildMemberNodes(
+  members: Array<ast.SchemaNode> | undefined,
+  print: (node: ast.SchemaNode) => ts.TypeNode | null | undefined,
+): 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.
+ */
+export function buildTupleNode(node: ast.ArraySchemaNode, print: (node: ast.SchemaNode) => ts.TypeNode | null | undefined): ts.TypeNode | undefined {
+  let items = (node.items ?? []).map(print).filter(Boolean)
+
+  const restNode = node.rest ? (print(node.rest) ?? undefined) : undefined
+  const { min, max } = node
+
+  if (max !== undefined) {
+    items = items.slice(0, max)
+    if (items.length < max && restNode) {
+      items = [...items, ...Array(max - items.length).fill(restNode)]
+    }
+  }
+
+  if (min !== undefined) {
+    items = items.map((item, i) => (i >= min ? createOptionalTypeNode(item) : item))
+  }
+
+  if (max === undefined && restNode) {
+    items.push(createRestTypeNode(createArrayTypeNode(restNode)))
+  }
+
+  return createTupleTypeNode(items)
+}
+
+/**
+ * Applies `nullable` and optional/nullish `| undefined` union modifiers to a property's resolved base type.
+ */
+export function buildPropertyType(
+  schema: ast.SchemaNode,
+  baseType: ts.TypeNode,
+  optionalType: 'questionToken' | 'undefined' | 'questionTokenAndUndefined',
+): ts.TypeNode {
+  const addsUndefined = OPTIONAL_ADDS_UNDEFINED.has(optionalType)
+  const meta = ast.syncSchemaRef(schema)
+
+  let type = baseType
+
+  if (meta.nullable) {
+    type = createUnionDeclaration({ nodes: [type, keywordTypeNodes.null] })
+  }
+
+  if ((meta.nullish || meta.optional) && addsUndefined) {
+    type = createUnionDeclaration({ nodes: [type, keywordTypeNodes.undefined] })
+  }
+
+  return type
+}
+
+/**
+ * Creates TypeScript index signatures for `additionalProperties` and `patternProperties` on an object schema node.
+ */
+export function buildIndexSignatures(
+  node: { additionalProperties?: ast.SchemaNode | boolean; patternProperties?: Record<string, ast.SchemaNode> },
+  propertyCount: number,
+  print: (node: ast.SchemaNode) => ts.TypeNode | null | undefined,
+): Array<ts.TypeElement> {
+  const elements: Array<ts.TypeElement> = []
+
+  if (node.additionalProperties && node.additionalProperties !== true) {
+    const additionalType = print(node.additionalProperties) ?? keywordTypeNodes.unknown
+
+    elements.push(createIndexSignature(propertyCount > 0 ? keywordTypeNodes.unknown : additionalType))
+  } else if (node.additionalProperties === true) {
+    elements.push(createIndexSignature(keywordTypeNodes.unknown))
+  }
+
+  if (node.patternProperties) {
+    const first = Object.values(node.patternProperties)[0]
+    if (first) {
+      let patternType = print(first) ?? keywordTypeNodes.unknown
+
+      if (first.nullable) {
+        patternType = createUnionDeclaration({ nodes: [patternType, keywordTypeNodes.null] })
+      }
+      elements.push(createIndexSignature(patternType))
+    }
+  }
+
+  return elements
+}