@kubb/plugin-ts 5.0.0-alpha.23 → 5.0.0-alpha.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-ts",
-  "version": "5.0.0-alpha.23",
+  "version": "5.0.0-alpha.25",
   "description": "TypeScript code generation plugin for Kubb, transforming OpenAPI schemas into TypeScript interfaces, types, and utility functions.",
   "keywords": [
     "typescript",
@@ -51,10 +51,10 @@
   "dependencies": {
     "@kubb/fabric-core": "0.15.1",
     "@kubb/react-fabric": "0.15.1",
-    "remeda": "^2.33.6",
+    "remeda": "^2.33.7",
     "typescript": "5.9.3",
-    "@kubb/ast": "5.0.0-alpha.23",
-    "@kubb/core": "5.0.0-alpha.23"
+    "@kubb/ast": "5.0.0-alpha.25",
+    "@kubb/core": "5.0.0-alpha.25"
   },
   "peerDependencies": {
     "@kubb/react-fabric": "0.15.1"

package/src/components/Enum.tsx

@@ -35,17 +35,12 @@ export function getEnumNames({
 }): {
   enumName: string
   typeName: string
-  /**
-   * The PascalCase name that `$ref` importers will use to reference this enum type.
-   * For `asConst`/`asPascalConst` this differs from `typeName` (which has a `Key` suffix).
-   */
-  refName: string
 } {
   const resolved = resolver.default(node.name!, 'type')
   const enumName = enumType === 'asPascalConst' ? resolved : camelCase(node.name!)
   const typeName = ENUM_TYPES_WITH_KEY_SUFFIX.has(enumType) ? resolver.resolveEnumKeyName(node, enumTypeSuffix) : resolved
 
-  return { enumName, typeName, refName: resolved }
+  return { enumName, typeName }
 }
 
 /**
@@ -67,7 +62,7 @@ export function Enum({ node, enumType, enumTypeSuffix, enumKeyCasing, resolver }
     typeName,
     enums: (node.namedEnumValues?.map((v) => [trimQuotes(v.name.toString()), v.value]) ??
       node.enumValues?.filter((v): v is NonNullable<typeof v> => v !== null && v !== undefined).map((v) => [trimQuotes(v.toString()), v]) ??
-      []) as unknown as Array<[string, string]>,
+      []) as Array<[string | number, string | number | boolean]>,
     type: enumType,
     enumKeyCasing,
   })

package/src/components/Type.tsx

@@ -18,6 +18,12 @@ type Props = {
   resolver: PluginTs['resolver']
   description?: string
   keysToOmit?: string[]
+  /**
+   * Names of top-level schemas that are enums.
+   * Used so the printer's `ref` handler can use the suffixed type name (e.g. `StatusKey`)
+   * instead of the plain PascalCase name (e.g. `Status`) when resolving `$ref` enum targets.
+   */
+  enumSchemaNames?: Set<string>
 }
 
 export function Type({
@@ -32,6 +38,7 @@ export function Type({
   enumKeyCasing,
   description,
   resolver,
+  enumSchemaNames,
 }: Props): FabricReactNode {
   const resolvedDescription = description || node?.description
   const enumSchemaNodes = collect<EnumSchemaNode>(node, {
@@ -51,6 +58,7 @@ export function Type({
     description: resolvedDescription,
     keysToOmit,
     resolver,
+    enumSchemaNames,
   })
   const output = printer.print(node)
 

package/src/constants.ts

@@ -27,3 +27,13 @@ export const ENUM_TYPES_WITH_RUNTIME_VALUE = new Set<EnumType | undefined>(['enu
  * `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
 
@@ -249,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,
@@ -692,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
+}

package/src/generators/typeGenerator.tsx

@@ -11,46 +11,115 @@ import { buildData, buildResponses, buildResponseUnion } from '../utils.ts'
 export const typeGenerator = defineGenerator<PluginTs>({
   name: 'typescript',
   type: 'react',
+  Schema({ node, adapter, options, config, resolver }) {
+    const { enumType, enumTypeSuffix, enumKeyCasing, syntaxType, optionalType, arrayType, output, group, transformers = [] } = options
+
+    const transformedNode = transform(node, composeTransformers(...transformers))
+
+    if (!transformedNode.name) {
+      return
+    }
+
+    const root = path.resolve(config.root, config.output.path)
+    const mode = getMode(path.resolve(root, output.path))
+    // Build a set of schema names that are enums so the ref handler and getImports
+    // callback can use the suffixed type name (e.g. `StatusKey`) for those refs.
+    const enumSchemaNames = new Set((adapter.rootNode?.schemas ?? []).filter((s) => narrowSchema(s, schemaTypes.enum) && s.name).map((s) => s.name!))
+
+    function resolveImportName(schemaName: string): string {
+      if (ENUM_TYPES_WITH_KEY_SUFFIX.has(enumType) && enumTypeSuffix && enumSchemaNames.has(schemaName)) {
+        return resolver.resolveEnumKeyName({ name: schemaName }, enumTypeSuffix)
+      }
+      return resolver.default(schemaName, 'type')
+    }
+
+    const imports = adapter.getImports(transformedNode, (schemaName) => ({
+      name: resolveImportName(schemaName),
+      path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group }).path,
+    }))
+
+    const isEnumSchema = !!narrowSchema(transformedNode, schemaTypes.enum)
+
+    const meta = {
+      name:
+        ENUM_TYPES_WITH_KEY_SUFFIX.has(enumType) && isEnumSchema
+          ? resolver.resolveEnumKeyName(transformedNode, enumTypeSuffix)
+          : resolver.resolveName(transformedNode.name),
+      file: resolver.resolveFile({ name: transformedNode.name, extname: '.ts' }, { root, output, group }),
+    } as const
+
+    return (
+      <File
+        baseName={meta.file.baseName}
+        path={meta.file.path}
+        meta={meta.file.meta}
+        banner={resolver.resolveBanner(adapter.rootNode, { output, config })}
+        footer={resolver.resolveFooter(adapter.rootNode, { output, config })}
+      >
+        {mode === 'split' &&
+          imports.map((imp) => (
+            <File.Import key={[transformedNode.name, imp.path, imp.isTypeOnly].join('-')} root={meta.file.path} path={imp.path} name={imp.name} isTypeOnly />
+          ))}
+        <Type
+          name={meta.name}
+          node={transformedNode}
+          enumType={enumType}
+          enumTypeSuffix={enumTypeSuffix}
+          enumKeyCasing={enumKeyCasing}
+          optionalType={optionalType}
+          arrayType={arrayType}
+          syntaxType={syntaxType}
+          resolver={resolver}
+          enumSchemaNames={enumSchemaNames}
+        />
+      </File>
+    )
+  },
   Operation({ node, adapter, options, config, resolver }) {
     const { enumType, enumTypeSuffix, enumKeyCasing, optionalType, arrayType, syntaxType, paramsCasing, group, output, transformers = [] } = options
 
+    const transformedNode = transform(node, composeTransformers(...transformers))
+
     const root = path.resolve(config.root, config.output.path)
     const mode = getMode(path.resolve(root, output.path))
 
-    const file = resolver.resolveFile({ name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path }, { root, output, group })
-
-    const params = caseParams(node.parameters, paramsCasing)
-
-    function renderSchemaType({
-      node: schemaNode,
-      name,
-      description,
-      keysToOmit,
-    }: {
-      node: SchemaNode | null
-      name: string
-      description?: string
-      keysToOmit?: Array<string>
-    }) {
-      if (!schemaNode) {
-        return null
+    const params = caseParams(transformedNode.parameters, paramsCasing)
+
+    const meta = {
+      file: resolver.resolveFile(
+        { name: transformedNode.operationId, extname: '.ts', tag: transformedNode.tags[0] ?? 'default', path: transformedNode.path },
+        { root, output, group },
+      ),
+    } as const
+
+    // Build a set of schema names that are enums so the ref handler and getImports
+    // callback can use the suffixed type name (e.g. `StatusKey`) for those refs.
+    const enumSchemaNames = new Set((adapter.rootNode?.schemas ?? []).filter((s) => narrowSchema(s, schemaTypes.enum) && s.name).map((s) => s.name!))
+
+    function resolveImportName(schemaName: string): string {
+      if (ENUM_TYPES_WITH_KEY_SUFFIX.has(enumType) && enumTypeSuffix && enumSchemaNames.has(schemaName)) {
+        return resolver.resolveEnumKeyName({ name: schemaName }, enumTypeSuffix)
       }
+      return resolver.default(schemaName, 'type')
+    }
 
-      const transformedNode = transform(schemaNode, composeTransformers(...transformers))
+    function renderSchemaType({ schema, name, keysToOmit }: { schema: SchemaNode | null; name: string; keysToOmit?: Array<string> }) {
+      if (!schema) return null
 
-      const imports = adapter.getImports(transformedNode, (schemaName) => ({
-        name: resolver.default(schemaName, 'type'),
+      const imports = adapter.getImports(schema, (schemaName) => ({
+        name: resolveImportName(schemaName),
         path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group }).path,
       }))
 
       return (
         <>
           {mode === 'split' &&
-            imports.map((imp) => <File.Import key={[name, imp.path, imp.isTypeOnly].join('-')} root={file.path} path={imp.path} name={imp.name} isTypeOnly />)}
+            imports.map((imp) => (
+              <File.Import key={[name, imp.path, imp.isTypeOnly].join('-')} root={meta.file.path} path={imp.path} name={imp.name} isTypeOnly />
+            ))}
           <Type
             name={name}
-            node={transformedNode}
-            description={description}
+            node={schema}
             enumType={enumType}
             enumTypeSuffix={enumTypeSuffix}
             enumKeyCasing={enumKeyCasing}
@@ -59,6 +128,7 @@ export const typeGenerator = defineGenerator<PluginTs>({
             syntaxType={syntaxType}
             resolver={resolver}
             keysToOmit={keysToOmit}
+            enumSchemaNames={enumSchemaNames}
           />
         </>
       )
@@ -66,50 +136,55 @@ export const typeGenerator = defineGenerator<PluginTs>({
 
     const paramTypes = params.map((param) =>
       renderSchemaType({
-        node: param.schema,
-        name: resolver.resolveParamName(node, param),
+        schema: param.schema,
+        name: resolver.resolveParamName(transformedNode, param),
       }),
     )
 
-    const requestType = node.requestBody?.schema
+    const requestType = transformedNode.requestBody?.schema
       ? renderSchemaType({
-          node: node.requestBody.schema,
-          name: resolver.resolveDataName(node),
-          description: node.requestBody.description ?? node.requestBody.schema.description,
-          keysToOmit: node.requestBody.keysToOmit,
+          schema: {
+            ...transformedNode.requestBody.schema,
+            description: transformedNode.requestBody.description ?? transformedNode.requestBody.schema.description,
+          },
+          name: resolver.resolveDataName(transformedNode),
+          keysToOmit: transformedNode.requestBody.keysToOmit,
         })
       : null
 
-    const responseTypes = node.responses.map((res) =>
+    const responseTypes = transformedNode.responses.map((res) =>
       renderSchemaType({
-        node: res.schema,
-        name: resolver.resolveResponseStatusName(node, res.statusCode),
-        description: res.description,
+        schema: res.schema,
+        name: resolver.resolveResponseStatusName(transformedNode, res.statusCode),
         keysToOmit: res.keysToOmit,
       }),
     )
 
     const dataType = renderSchemaType({
-      node: buildData({ node: { ...node, parameters: params }, resolver }),
-      name: resolver.resolveRequestConfigName(node),
+      schema: buildData({ ...transformedNode, parameters: params }, { resolver }),
+      name: resolver.resolveRequestConfigName(transformedNode),
     })
 
     const responsesType = renderSchemaType({
-      node: buildResponses({ node, resolver }),
-      name: resolver.resolveResponsesName(node),
+      schema: buildResponses(transformedNode, { resolver }),
+      name: resolver.resolveResponsesName(transformedNode),
     })
 
     const responseType = renderSchemaType({
-      node: buildResponseUnion({ node, resolver }),
-      name: resolver.resolveResponseName(node),
-      description: 'Union of all possible responses',
+      schema: transformedNode.responses.some((res) => res.schema)
+        ? {
+            ...buildResponseUnion(transformedNode, { resolver })!,
+            description: 'Union of all possible responses',
+          }
+        : null,
+      name: resolver.resolveResponseName(transformedNode),
     })
 
     return (
       <File
-        baseName={file.baseName}
-        path={file.path}
-        meta={file.meta}
+        baseName={meta.file.baseName}
+        path={meta.file.path}
+        meta={meta.file.meta}
         banner={resolver.resolveBanner(adapter.rootNode, { output, config })}
         footer={resolver.resolveFooter(adapter.rootNode, { output, config })}
       >
@@ -122,56 +197,4 @@ export const typeGenerator = defineGenerator<PluginTs>({
       </File>
     )
   },
-  Schema({ node, adapter, options, config, resolver }) {
-    const { enumType, enumTypeSuffix, enumKeyCasing, syntaxType, optionalType, arrayType, output, group, transformers = [] } = options
-
-    const root = path.resolve(config.root, config.output.path)
-    const mode = getMode(path.resolve(root, output.path))
-
-    if (!node.name) {
-      return
-    }
-
-    const transformedNode = transform(node, composeTransformers(...transformers))
-
-    const imports = adapter.getImports(transformedNode, (schemaName) => ({
-      name: resolver.default(schemaName, 'type'),
-      path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group }).path,
-    }))
-
-    const isEnumSchema = !!narrowSchema(node, schemaTypes.enum)
-
-    const name = ENUM_TYPES_WITH_KEY_SUFFIX.has(enumType) && isEnumSchema ? resolver.resolveEnumKeyName(node, enumTypeSuffix) : resolver.resolveName(node.name)
-
-    const type = {
-      name,
-      file: resolver.resolveFile({ name: node.name, extname: '.ts' }, { root, output, group }),
-    } as const
-
-    return (
-      <File
-        baseName={type.file.baseName}
-        path={type.file.path}
-        meta={type.file.meta}
-        banner={resolver.resolveBanner(adapter.rootNode, { output, config })}
-        footer={resolver.resolveFooter(adapter.rootNode, { output, config })}
-      >
-        {mode === 'split' &&
-          imports.map((imp) => (
-            <File.Import key={[node.name, imp.path, imp.isTypeOnly].join('-')} root={type.file.path} path={imp.path} name={imp.name} isTypeOnly />
-          ))}
-        <Type
-          name={type.name}
-          node={transformedNode}
-          enumType={enumType}
-          enumTypeSuffix={enumTypeSuffix}
-          enumKeyCasing={enumKeyCasing}
-          optionalType={optionalType}
-          arrayType={arrayType}
-          syntaxType={syntaxType}
-          resolver={resolver}
-        />
-      </File>
-    )
-  },
 })