@kubb/plugin-ts 5.0.0-alpha.3 → 5.0.0-alpha.30

package/src/components/Type.tsx

@@ -1,159 +1,44 @@
-import { camelCase, jsStringEscape, pascalCase, trimQuotes } from '@internals/utils'
-import { safePrint } from '@kubb/fabric-core/parsers/typescript'
-import type { SchemaObject } from '@kubb/oas'
-import { isKeyword, type Schema, SchemaGenerator, schemaKeywords } from '@kubb/plugin-oas'
+import type { Printer } from '@kubb/ast'
+import { collect, narrowSchema, schemaTypes } from '@kubb/ast'
+import type { EnumSchemaNode, SchemaNode } from '@kubb/ast/types'
 import { File } from '@kubb/react-fabric'
 import type { FabricReactNode } from '@kubb/react-fabric/types'
-import type ts from 'typescript'
-import * as factory from '../factory.ts'
-import { parse, typeKeywordMapper } from '../parser.ts'
+import type { PrinterTsFactory } from '../printers/printerTs.ts'
 import type { PluginTs } from '../types.ts'
+import { Enum, getEnumNames } from './Enum.tsx'
 
 type Props = {
   name: string
-  typedName: string
-  schema: SchemaObject
-  tree: Array<Schema>
-  optionalType: PluginTs['resolvedOptions']['optionalType']
-  arrayType: PluginTs['resolvedOptions']['arrayType']
+  node: SchemaNode
+  /**
+   * Pre-configured printer instance created by the generator.
+   * Created with `printerTs({ ..., nodes: options.printer?.nodes })`.
+   */
+  printer: Printer<PrinterTsFactory>
   enumType: PluginTs['resolvedOptions']['enumType']
+  enumTypeSuffix: PluginTs['resolvedOptions']['enumTypeSuffix']
   enumKeyCasing: PluginTs['resolvedOptions']['enumKeyCasing']
-  mapper: PluginTs['resolvedOptions']['mapper']
-  syntaxType: PluginTs['resolvedOptions']['syntaxType']
-  description?: string
-  keysToOmit?: string[]
+  resolver: PluginTs['resolver']
 }
 
-export function Type({
-  name,
-  typedName,
-  tree,
-  keysToOmit,
-  schema,
-  optionalType,
-  arrayType,
-  syntaxType,
-  enumType,
-  enumKeyCasing,
-  mapper,
-  description,
-}: Props): FabricReactNode {
-  const typeNodes: ts.Node[] = []
-
-  if (!tree.length) {
-    return ''
-  }
-
-  const schemaFromTree = tree.find((item) => item.keyword === schemaKeywords.schema)
-  const enumSchemas = SchemaGenerator.deepSearch(tree, schemaKeywords.enum)
-
-  let type =
-    (tree
-      .map((current, _index, siblings) =>
-        parse(
-          { name, schema, parent: undefined, current, siblings },
-          {
-            optionalType,
-            arrayType,
-            enumType,
-            mapper,
-          },
-        ),
-      )
-      .filter(Boolean)
-      .at(0) as ts.TypeNode) || typeKeywordMapper.undefined()
-
-  // Add a "Key" suffix to avoid collisions where necessary
-  if (['asConst', 'asPascalConst'].includes(enumType) && enumSchemas.length > 0) {
-    const isDirectEnum = schema.type === 'array' && schema.items !== undefined
-    const isEnumOnly = 'enum' in schema && schema.enum
-
-    if (isDirectEnum || isEnumOnly) {
-      const enumSchema = enumSchemas[0]!
-      const typeNameWithKey = `${enumSchema.args.typeName}Key`
-
-      type = factory.createTypeReferenceNode(typeNameWithKey)
-
-      if (schema.type === 'array') {
-        if (arrayType === 'generic') {
-          type = factory.createTypeReferenceNode(factory.createIdentifier('Array'), [type])
-        } else {
-          type = factory.createArrayTypeNode(type)
-        }
-      }
-    }
-  }
-
-  if (schemaFromTree && isKeyword(schemaFromTree, schemaKeywords.schema)) {
-    const isNullish = tree.some((item) => item.keyword === schemaKeywords.nullish)
-    const isNullable = tree.some((item) => item.keyword === schemaKeywords.nullable)
-    const isOptional = tree.some((item) => item.keyword === schemaKeywords.optional)
+export function Type({ name, node, printer, enumType, enumTypeSuffix, enumKeyCasing, resolver }: Props): FabricReactNode {
+  const enumSchemaNodes = collect<EnumSchemaNode>(node, {
+    schema(n): EnumSchemaNode | undefined {
+      const enumNode = narrowSchema(n, schemaTypes.enum)
+      if (enumNode?.name) return enumNode
+    },
+  })
 
-    if (isNullable) {
-      type = factory.createUnionDeclaration({
-        nodes: [type, factory.keywordTypeNodes.null],
-      }) as ts.TypeNode
-    }
+  const output = printer.print(node)
 
-    if (isNullish && ['undefined', 'questionTokenAndUndefined'].includes(optionalType as string)) {
-      type = factory.createUnionDeclaration({
-        nodes: [type, factory.keywordTypeNodes.undefined],
-      }) as ts.TypeNode
-    }
-
-    if (isOptional && ['undefined', 'questionTokenAndUndefined'].includes(optionalType as string)) {
-      type = factory.createUnionDeclaration({
-        nodes: [type, factory.keywordTypeNodes.undefined],
-      }) as ts.TypeNode
-    }
+  if (!output) {
+    return
   }
 
-  const useTypeGeneration = syntaxType === 'type' || [factory.syntaxKind.union].includes(type.kind as typeof factory.syntaxKind.union) || !!keysToOmit?.length
-
-  typeNodes.push(
-    factory.createTypeDeclaration({
-      name,
-      isExportable: true,
-      type: keysToOmit?.length
-        ? factory.createOmitDeclaration({
-            keys: keysToOmit,
-            type,
-            nonNullable: true,
-          })
-        : type,
-      syntax: useTypeGeneration ? 'type' : 'interface',
-      comments: [
-        schema.title ? `${jsStringEscape(schema.title)}` : undefined,
-        description ? `@description ${jsStringEscape(description)}` : undefined,
-        schema.deprecated ? '@deprecated' : undefined,
-        schema.minLength ? `@minLength ${schema.minLength}` : undefined,
-        schema.maxLength ? `@maxLength ${schema.maxLength}` : undefined,
-        schema.pattern ? `@pattern ${schema.pattern}` : undefined,
-        schema.default ? `@default ${schema.default}` : undefined,
-        schema.example ? `@example ${schema.example}` : undefined,
-      ],
-    }),
-  )
-
-  const enums = [...new Set(enumSchemas)].map((enumSchema) => {
-    const name = enumType === 'asPascalConst' ? pascalCase(enumSchema.args.name) : camelCase(enumSchema.args.name)
-    const typeName = ['asConst', 'asPascalConst'].includes(enumType) ? `${enumSchema.args.typeName}Key` : enumSchema.args.typeName
-
-    const [nameNode, typeNode] = factory.createEnumDeclaration({
-      name,
-      typeName,
-      enums: enumSchema.args.items
-        .map((item) => (item.value === undefined ? undefined : [trimQuotes(item.name?.toString()), item.value]))
-        .filter(Boolean) as unknown as Array<[string, string]>,
-      type: enumType,
-      enumKeyCasing,
-    })
-
+  const enums = [...new Map(enumSchemaNodes.map((n) => [n.name, n])).values()].map((node) => {
     return {
-      nameNode,
-      typeNode,
-      name,
-      typeName,
+      node,
+      ...getEnumNames({ node, enumType, enumTypeSuffix, resolver }),
     }
   })
 
@@ -164,28 +49,10 @@ export function Type({
   return (
     <>
       {shouldExportEnums &&
-        enums.map(({ name, nameNode, typeName, typeNode }) => (
-          <>
-            {nameNode && (
-              <File.Source name={name} isExportable isIndexable isTypeOnly={false}>
-                {safePrint(nameNode)}
-              </File.Source>
-            )}
-            {
-              <File.Source
-                name={typeName}
-                isIndexable
-                isExportable={['enum', 'asConst', 'asPascalConst', 'constEnum', 'literal', undefined].includes(enumType)}
-                isTypeOnly={['asConst', 'asPascalConst', 'literal', undefined].includes(enumType)}
-              >
-                {safePrint(typeNode)}
-              </File.Source>
-            }
-          </>
-        ))}
+        enums.map(({ node }) => <Enum node={node} enumType={enumType} enumTypeSuffix={enumTypeSuffix} enumKeyCasing={enumKeyCasing} resolver={resolver} />)}
       {shouldExportType && (
-        <File.Source name={typedName} isTypeOnly isExportable isIndexable>
-          {safePrint(...typeNodes)}
+        <File.Source name={name} isTypeOnly isExportable isIndexable>
+          {output}
         </File.Source>
       )}
     </>

package/src/constants.ts

@@ -0,0 +1,39 @@
+import type { PluginTs } from './types.ts'
+
+type OptionalType = PluginTs['resolvedOptions']['optionalType']
+type EnumType = PluginTs['resolvedOptions']['enumType']
+
+/**
+ * `optionalType` values that cause a property's type to include `| undefined`.
+ */
+export const OPTIONAL_ADDS_UNDEFINED = new Set<OptionalType>(['undefined', 'questionTokenAndUndefined'] as const)
+
+/**
+ * `optionalType` values that render the property key with a `?` token.
+ */
+export const OPTIONAL_ADDS_QUESTION_TOKEN = new Set<OptionalType>(['questionToken', 'questionTokenAndUndefined'] as const)
+
+/**
+ * `enumType` values that append a `Key` suffix to the generated enum type alias.
+ */
+export const ENUM_TYPES_WITH_KEY_SUFFIX = new Set<EnumType>(['asConst', 'asPascalConst'] as const)
+
+/**
+ * `enumType` values that require a runtime value declaration (object, enum, or literal).
+ */
+export const ENUM_TYPES_WITH_RUNTIME_VALUE = new Set<EnumType | undefined>(['enum', 'asConst', 'asPascalConst', 'constEnum', 'literal', undefined] as const)
+
+/**
+ * `enumType` values whose type declaration is type-only (no runtime value emitted for the type alias).
+ */
+export const ENUM_TYPES_WITH_TYPE_ONLY = new Set<EnumType | undefined>(['asConst', 'asPascalConst', 'literal', undefined] as const)
+
+/**
+ * Ordering priority for function parameters: lower = sorted earlier.
+ */
+export const PARAM_RANK = {
+  required: 0,
+  optional: 1,
+  withDefault: 2,
+  rest: 3,
+} as const

package/src/factory.ts

@@ -1,6 +1,9 @@
 import { camelCase, pascalCase, screamingSnakeCase, snakeCase } from '@internals/utils'
+import { syncSchemaRef } from '@kubb/ast'
+import type { ArraySchemaNode, SchemaNode } from '@kubb/ast/types'
 import { isNumber, sortBy } from 'remeda'
 import ts from 'typescript'
+import { OPTIONAL_ADDS_UNDEFINED } from './constants.ts'
 
 const { SyntaxKind, factory } = ts
 
@@ -19,16 +22,6 @@ export const syntaxKind = {
   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
@@ -76,28 +69,6 @@ export function createIntersectionDeclaration({ nodes, withParentheses }: { node
   return node
 }
 
-/**
- * Minimum nodes length of 2
- * @example `string & number`
- */
-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([])
@@ -281,7 +252,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,
@@ -662,43 +633,39 @@ export const keywordTypeNodes = {
  * Converts a path like '/pet/{petId}/uploadImage' to a template literal type
  * like `/pet/${string}/uploadImage`
  */
+/**
+ * Converts an OAS-style path (e.g. `/pets/{petId}`) or an Express-style path
+ * (e.g. `/pets/:petId`) to a TypeScript template literal type
+ * like `` `/pets/${string}` ``.
+ */
 export function createUrlTemplateType(path: string): ts.TypeNode {
-  // If no parameters, return literal string type
-  if (!path.includes('{')) {
-    return factory.createLiteralTypeNode(factory.createStringLiteral(path))
-  }
+  // normalized Express `:param` → OAS `{param}` so a single regex handles both.
+  const normalized = path.replace(/:([^/]+)/g, '{$1}')
 
-  // Split path by parameter placeholders, e.g. '/pet/{petId}/upload' -> ['/pet/', 'petId', '/upload']
-  const segments = path.split(/(\{[^}]+\})/)
+  if (!normalized.includes('{')) {
+    return factory.createLiteralTypeNode(factory.createStringLiteral(normalized))
+  }
 
-  // Separate static parts from parameter placeholders
+  const segments = normalized.split(/(\{[^}]+\})/)
   const parts: string[] = []
   const parameterIndices: number[] = []
 
   segments.forEach((segment) => {
     if (segment.startsWith('{') && segment.endsWith('}')) {
-      // This is a parameter placeholder
       parameterIndices.push(parts.length)
-      parts.push(segment) // Will be replaced with ${string}
+      parts.push(segment)
     } else if (segment) {
-      // This is a static part
       parts.push(segment)
     }
   })
 
-  // Build template literal type
-  // Template literal structure: head + templateSpans[]
-  // For '/pet/{petId}/upload': head = '/pet/', spans = [{ type: string, literal: '/upload' }]
-
   const head = ts.factory.createTemplateHead(parts[0] || '')
   const templateSpans: ts.TemplateLiteralTypeSpan[] = []
 
   parameterIndices.forEach((paramIndex, i) => {
     const isLast = i === parameterIndices.length - 1
     const nextPart = parts[paramIndex + 1] || ''
-
     const literal = isLast ? ts.factory.createTemplateTail(nextPart) : ts.factory.createTemplateMiddle(nextPart)
-
     templateSpans.push(ts.factory.createTemplateLiteralTypeSpan(keywordTypeNodes.string, literal))
   })
 
@@ -728,3 +695,121 @@ export const createTypeOperatorNode = factory.createTypeOperatorNode
 export const createPrefixUnaryExpression = factory.createPrefixUnaryExpression
 
 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<SchemaNode> | undefined, print: (node: 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: ArraySchemaNode, print: (node: 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: SchemaNode,
+  baseType: ts.TypeNode,
+  optionalType: 'questionToken' | 'undefined' | 'questionTokenAndUndefined',
+): ts.TypeNode {
+  const addsUndefined = OPTIONAL_ADDS_UNDEFINED.has(optionalType)
+  const meta = 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?: SchemaNode | boolean; patternProperties?: Record<string, SchemaNode> },
+  propertyCount: number,
+  print: (node: 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
+}