@kubb/plugin-ts 4.14.0 → 4.15.0

package/src/factory.ts

@@ -17,6 +17,16 @@ export const syntaxKind = {
   union: SyntaxKind.UnionType as 192,
 } 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
@@ -86,16 +96,29 @@ export function createTupleDeclaration({ nodes, withParentheses }: { nodes: Arra
   return node
 }
 
-export function createArrayDeclaration({ nodes }: { nodes: Array<ts.TypeNode> }): ts.TypeNode | null {
+export function createArrayDeclaration({ nodes, arrayType = 'array' }: { nodes: Array<ts.TypeNode>; arrayType?: 'array' | 'generic' }): ts.TypeNode | null {
   if (!nodes.length) {
     return factory.createTupleTypeNode([])
   }
 
   if (nodes.length === 1) {
-    return factory.createArrayTypeNode(nodes.at(0)!)
+    const node = nodes[0]
+    if (!node) {
+      return null
+    }
+    if (arrayType === 'generic') {
+      return factory.createTypeReferenceNode(factory.createIdentifier('Array'), [node])
+    }
+    return factory.createArrayTypeNode(node)
   }
 
-  return factory.createExpressionWithTypeArguments(factory.createIdentifier('Array'), [factory.createUnionTypeNode(nodes)])
+  // For union types (multiple nodes), respect arrayType preference
+  const unionType = factory.createUnionTypeNode(nodes)
+  if (arrayType === 'generic') {
+    return factory.createTypeReferenceNode(factory.createIdentifier('Array'), [unionType])
+  }
+  // For array syntax with unions, we need parentheses: (string | number)[]
+  return factory.createArrayTypeNode(factory.createParenthesizedType(unionType))
 }
 
 /**
@@ -572,8 +595,56 @@ export const keywordTypeNodes = {
   boolean: factory.createKeywordTypeNode(ts.SyntaxKind.BooleanKeyword),
   undefined: factory.createKeywordTypeNode(ts.SyntaxKind.UndefinedKeyword),
   null: factory.createLiteralTypeNode(factory.createToken(ts.SyntaxKind.NullKeyword)),
+  never: factory.createKeywordTypeNode(ts.SyntaxKind.NeverKeyword),
 } as const
 
+/**
+ * Converts a path like '/pet/{petId}/uploadImage' to a template literal type
+ * like `/pet/${string}/uploadImage`
+ */
+export function createUrlTemplateType(path: string): ts.TypeNode {
+  // If no parameters, return literal string type
+  if (!path.includes('{')) {
+    return factory.createLiteralTypeNode(factory.createStringLiteral(path))
+  }
+
+  // Split path by parameter placeholders, e.g. '/pet/{petId}/upload' -> ['/pet/', 'petId', '/upload']
+  const segments = path.split(/(\{[^}]+\})/)
+
+  // Separate static parts from parameter placeholders
+  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}
+    } 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))
+  })
+
+  return ts.factory.createTemplateLiteralType(head, templateSpans)
+}
+
 export const createTypeLiteralNode = factory.createTypeLiteralNode
 
 export const createTypeReferenceNode = factory.createTypeReferenceNode
@@ -581,6 +652,7 @@ export const createNumericLiteral = factory.createNumericLiteral
 export const createStringLiteral = factory.createStringLiteral
 
 export const createArrayTypeNode = factory.createArrayTypeNode
+export const createParenthesizedType = factory.createParenthesizedType
 
 export const createLiteralTypeNode = factory.createLiteralTypeNode
 export const createNull = factory.createNull
@@ -591,3 +663,5 @@ export const createTupleTypeNode = factory.createTupleTypeNode
 export const createRestTypeNode = factory.createRestTypeNode
 export const createTrue = factory.createTrue
 export const createFalse = factory.createFalse
+export const createIndexedAccessTypeNode = factory.createIndexedAccessTypeNode
+export const createTypeOperatorNode = factory.createTypeOperatorNode

package/src/generators/__snapshots__/createPet.ts

@@ -40,7 +40,7 @@ export type CreatePetsMutationRequest = {
 
 export type CreatePetsMutationResponse = createPets201 | createPets202
 
-export type createPetsMutation = {
+export type CreatePetsMutation = {
   Response: createPets201 | createPets202
   Request: createPetsMutationRequest
   Errors: any

package/src/generators/__snapshots__/createPetWithEmptySchemaTypeUnknown.ts

@@ -40,7 +40,7 @@ export type CreatePetsMutationRequest = {
 
 export type CreatePetsMutationResponse = createPets201 | createPets202
 
-export type createPetsMutation = {
+export type CreatePetsMutation = {
   Response: createPets201 | createPets202
   Request: createPetsMutationRequest
   Errors: any

package/src/generators/__snapshots__/createPetWithEmptySchemaTypeVoid.ts

@@ -40,7 +40,7 @@ export type CreatePetsMutationRequest = {
 
 export type CreatePetsMutationResponse = createPets201 | createPets202
 
-export type createPetsMutation = {
+export type CreatePetsMutation = {
   Response: createPets201 | createPets202
   Request: createPetsMutationRequest
   Errors: any

package/src/generators/__snapshots__/createPetWithUnknownTypeUnknown.ts

@@ -40,7 +40,7 @@ export type CreatePetsMutationRequest = {
 
 export type CreatePetsMutationResponse = createPets201 | createPets202
 
-export type createPetsMutation = {
+export type CreatePetsMutation = {
   Response: createPets201 | createPets202
   Request: createPetsMutationRequest
   Errors: any

package/src/generators/__snapshots__/createPetWithUnknownTypeVoid.ts

@@ -40,7 +40,7 @@ export type CreatePetsMutationRequest = {
 
 export type CreatePetsMutationResponse = createPets201 | createPets202
 
-export type createPetsMutation = {
+export type CreatePetsMutation = {
   Response: createPets201 | createPets202
   Request: createPetsMutationRequest
   Errors: any

package/src/generators/__snapshots__/deletePet.ts

@@ -5,7 +5,7 @@
 
 export type DeletePetsPetidMutationResponse = any
 
-export type deletePetsPetidMutation = {
+export type DeletePetsPetidMutation = {
   Response: any
   Errors: any
 }

package/src/generators/__snapshots__/getPets.ts

@@ -23,7 +23,7 @@ export type ListPetsError = error
 
 export type ListPetsQueryResponse = listPets200
 
-export type listPetsQuery = {
+export type ListPetsQuery = {
   Response: listPets200
   QueryParams: listPetsQueryParams
   Errors: any

package/src/generators/__snapshots__/showPetById.ts

@@ -28,7 +28,7 @@ export type ShowPetByIdError = error
 
 export type ShowPetByIdQueryResponse = showPetById200
 
-export type showPetByIdQuery = {
+export type ShowPetByIdQuery = {
   Response: showPetById200
   PathParams: showPetByIdPathParams
   Errors: any

package/src/generators/__snapshots__/systemsWithExplodeForm.ts

@@ -17,7 +17,7 @@ export type Systems200 = object
 
 export type SystemsQueryResponse = systems200
 
-export type systemsQuery = {
+export type SystemsQuery = {
   Response: systems200
   QueryParams: systemsQueryParams
   Errors: any

package/src/generators/typeGenerator.tsx

@@ -2,14 +2,16 @@ import type { PluginManager } from '@kubb/core'
 import { useMode, usePluginManager } from '@kubb/core/hooks'
 import transformers from '@kubb/core/transformers'
 import { safePrint } from '@kubb/fabric-core/parsers/typescript'
+import type { Operation } from '@kubb/oas'
 import { isKeyword, type OperationSchemas, type OperationSchema as OperationSchemaType, SchemaGenerator, schemaKeywords } from '@kubb/plugin-oas'
 import { createReactGenerator } from '@kubb/plugin-oas/generators'
 import { useOas, useOperationManager, useSchemaManager } from '@kubb/plugin-oas/hooks'
 import { getBanner, getFooter } from '@kubb/plugin-oas/utils'
 import { File } from '@kubb/react-fabric'
-import type ts from 'typescript'
+import ts from 'typescript'
 import { Type } from '../components'
 import * as factory from '../factory.ts'
+import { createUrlTemplateType, getUnknownType, keywordTypeNodes } from '../factory.ts'
 import { pluginTsName } from '../plugin.ts'
 import type { PluginTs } from '../types'
 
@@ -103,12 +105,216 @@ function printCombinedSchema({ name, schemas, pluginManager }: { name: string; s
   return safePrint(namespaceNode)
 }
 
+function printRequestSchema({
+  baseName,
+  operation,
+  schemas,
+  pluginManager,
+}: {
+  baseName: string
+  operation: Operation
+  schemas: OperationSchemas
+  pluginManager: PluginManager
+}): string {
+  const name = pluginManager.resolveName({
+    name: `${baseName} Request`,
+    pluginKey: [pluginTsName],
+    type: 'type',
+  })
+
+  const results: string[] = []
+
+  // Generate DataRequest type
+  const dataRequestProperties: ts.PropertySignature[] = []
+
+  if (schemas.request) {
+    const identifier = pluginManager.resolveName({
+      name: schemas.request.name,
+      pluginKey: [pluginTsName],
+      type: 'type',
+    })
+    dataRequestProperties.push(
+      factory.createPropertySignature({
+        name: 'data',
+        questionToken: true,
+        type: factory.createTypeReferenceNode(factory.createIdentifier(identifier), undefined),
+      }),
+    )
+  } else {
+    dataRequestProperties.push(
+      factory.createPropertySignature({
+        name: 'data',
+        questionToken: true,
+        type: keywordTypeNodes.never,
+      }),
+    )
+  }
+
+  // Add pathParams property
+  if (schemas.pathParams) {
+    const identifier = pluginManager.resolveName({
+      name: schemas.pathParams.name,
+      pluginKey: [pluginTsName],
+      type: 'type',
+    })
+    dataRequestProperties.push(
+      factory.createPropertySignature({
+        name: 'pathParams',
+        type: factory.createTypeReferenceNode(factory.createIdentifier(identifier), undefined),
+      }),
+    )
+  } else {
+    dataRequestProperties.push(
+      factory.createPropertySignature({
+        name: 'pathParams',
+        questionToken: true,
+        type: keywordTypeNodes.never,
+      }),
+    )
+  }
+
+  // Add queryParams property
+  if (schemas.queryParams) {
+    const identifier = pluginManager.resolveName({
+      name: schemas.queryParams.name,
+      pluginKey: [pluginTsName],
+      type: 'type',
+    })
+    dataRequestProperties.push(
+      factory.createPropertySignature({
+        name: 'queryParams',
+        questionToken: true,
+        type: factory.createTypeReferenceNode(factory.createIdentifier(identifier), undefined),
+      }),
+    )
+  } else {
+    dataRequestProperties.push(
+      factory.createPropertySignature({
+        name: 'queryParams',
+        questionToken: true,
+        type: keywordTypeNodes.never,
+      }),
+    )
+  }
+
+  // Add headerParams property
+  if (schemas.headerParams) {
+    const identifier = pluginManager.resolveName({
+      name: schemas.headerParams.name,
+      pluginKey: [pluginTsName],
+      type: 'type',
+    })
+    dataRequestProperties.push(
+      factory.createPropertySignature({
+        name: 'headerParams',
+        questionToken: true,
+        type: factory.createTypeReferenceNode(factory.createIdentifier(identifier), undefined),
+      }),
+    )
+  } else {
+    dataRequestProperties.push(
+      factory.createPropertySignature({
+        name: 'headerParams',
+        questionToken: true,
+        type: keywordTypeNodes.never,
+      }),
+    )
+  }
+
+  // Add url property with template literal type
+  dataRequestProperties.push(
+    factory.createPropertySignature({
+      name: 'url',
+      type: createUrlTemplateType(operation.path),
+    }),
+  )
+
+  const dataRequestNode = factory.createTypeAliasDeclaration({
+    name,
+    type: factory.createTypeLiteralNode(dataRequestProperties),
+    modifiers: [factory.modifiers.export],
+  })
+
+  results.push(safePrint(dataRequestNode))
+
+  return results.join('\n\n')
+}
+
+function printResponseSchema({
+  baseName,
+  schemas,
+  pluginManager,
+  unknownType,
+}: {
+  baseName: string
+  schemas: OperationSchemas
+  pluginManager: PluginManager
+  unknownType: PluginTs['resolvedOptions']['unknownType']
+}): string {
+  const results: string[] = []
+
+  const name = pluginManager.resolveName({
+    name: `${baseName} ResponseData`,
+    pluginKey: [pluginTsName],
+    type: 'type',
+  })
+
+  // Generate Responses type (mapping status codes to response types)
+  if (schemas.responses && schemas.responses.length > 0) {
+    const responsesProperties: ts.PropertySignature[] = schemas.responses.map((res) => {
+      const identifier = pluginManager.resolveName({
+        name: res.name,
+        pluginKey: [pluginTsName],
+        type: 'type',
+      })
+
+      return factory.createPropertySignature({
+        name: res.statusCode?.toString() ?? 'default',
+        type: factory.createTypeReferenceNode(factory.createIdentifier(identifier), undefined),
+      })
+    })
+
+    const responsesNode = factory.createTypeAliasDeclaration({
+      name: `${baseName}Responses`,
+      type: factory.createTypeLiteralNode(responsesProperties),
+      modifiers: [factory.modifiers.export],
+    })
+
+    results.push(safePrint(responsesNode))
+
+    // Generate Response type (union via indexed access)
+    const responseNode = factory.createTypeAliasDeclaration({
+      name,
+      type: factory.createIndexedAccessTypeNode(
+        factory.createTypeReferenceNode(factory.createIdentifier(`${baseName}Responses`), undefined),
+        factory.createTypeOperatorNode(
+          ts.SyntaxKind.KeyOfKeyword,
+          factory.createTypeReferenceNode(factory.createIdentifier(`${baseName}Responses`), undefined),
+        ),
+      ),
+      modifiers: [factory.modifiers.export],
+    })
+
+    results.push(safePrint(responseNode))
+  } else {
+    const responseNode = factory.createTypeAliasDeclaration({
+      name,
+      modifiers: [factory.modifiers.export],
+      type: getUnknownType(unknownType),
+    })
+
+    results.push(safePrint(responseNode))
+  }
+
+  return results.join('\n\n')
+}
+
 export const typeGenerator = createReactGenerator<PluginTs>({
   name: 'typescript',
   Operation({ operation, generator, plugin }) {
     const {
       options,
-      options: { mapper, enumType, syntaxType, optionalType },
+      options: { mapper, enumType, syntaxType, optionalType, arrayType, unknownType },
     } = plugin
 
     const mode = useMode()
@@ -118,10 +324,10 @@ export const typeGenerator = createReactGenerator<PluginTs>({
     const { getSchemas, getFile, getName, getGroup } = useOperationManager(generator)
     const schemaManager = useSchemaManager()
 
+    const name = getName(operation, { type: 'type', pluginKey: [pluginTsName] })
+
     const file = getFile(operation)
     const schemas = getSchemas(operation)
-    const type = getName(operation, { type: 'function', pluginKey: [pluginTsName] })
-    const combinedSchemaName = operation.method === 'get' ? `${type}Query` : `${type}Mutation`
     const schemaGenerator = new SchemaGenerator(options, {
       fabric: generator.context.fabric,
       oas,
@@ -162,6 +368,7 @@ export const typeGenerator = createReactGenerator<PluginTs>({
             mapper={mapper}
             enumType={enumType}
             optionalType={optionalType}
+            arrayType={arrayType}
             keysToOmit={keysToOmit}
             syntaxType={syntaxType}
           />
@@ -169,6 +376,11 @@ export const typeGenerator = createReactGenerator<PluginTs>({
       )
     }
 
+    const responseName = schemaManager.getName(schemas.response.name, {
+      type: 'type',
+    })
+    const combinedSchemaName = operation.method === 'get' ? `${name}Query` : `${name}Mutation`
+
     return (
       <File
         baseName={file.baseName}
@@ -179,15 +391,26 @@ export const typeGenerator = createReactGenerator<PluginTs>({
       >
         {operationSchemas.map(mapOperationSchema)}
 
-        <File.Source name={combinedSchemaName} isExportable isIndexable isTypeOnly>
-          {printCombinedSchema({ name: combinedSchemaName, schemas, pluginManager })}
-        </File.Source>
+        {generator.context.UNSTABLE_NAMING ? (
+          <>
+            <File.Source name={`${name}Request`} isExportable isIndexable isTypeOnly>
+              {printRequestSchema({ baseName: name, operation, schemas, pluginManager })}
+            </File.Source>
+            <File.Source name={responseName} isExportable isIndexable isTypeOnly>
+              {printResponseSchema({ baseName: name, schemas, pluginManager, unknownType })}
+            </File.Source>
+          </>
+        ) : (
+          <File.Source name={combinedSchemaName} isExportable isIndexable isTypeOnly>
+            {printCombinedSchema({ name: combinedSchemaName, schemas, pluginManager })}
+          </File.Source>
+        )}
       </File>
     )
   },
   Schema({ schema, plugin }) {
     const {
-      options: { mapper, enumType, syntaxType, optionalType, output },
+      options: { mapper, enumType, syntaxType, optionalType, arrayType, output },
     } = plugin
     const mode = useMode()
 
@@ -231,6 +454,7 @@ export const typeGenerator = createReactGenerator<PluginTs>({
           mapper={mapper}
           enumType={enumType}
           optionalType={optionalType}
+          arrayType={arrayType}
           syntaxType={syntaxType}
         />
       </File>

package/src/parser.ts

@@ -23,12 +23,12 @@ export const typeKeywordMapper = {
   nullable: undefined,
   null: () => factory.keywordTypeNodes.null,
   nullish: undefined,
-  array: (nodes?: ts.TypeNode[]) => {
+  array: (nodes?: ts.TypeNode[], arrayType?: 'array' | 'generic') => {
     if (!nodes) {
       return undefined
     }
 
-    return factory.createArrayDeclaration({ nodes })
+    return factory.createArrayDeclaration({ nodes, arrayType })
   },
   tuple: (nodes?: ts.TypeNode[], rest?: ts.TypeNode, min?: number, max?: number) => {
     if (!nodes) {
@@ -142,6 +142,10 @@ type ParserOptions = {
    * @default `'questionToken'`
    */
   optionalType: 'questionToken' | 'undefined' | 'questionTokenAndUndefined'
+  /**
+   * @default `'array'`
+   */
+  arrayType: 'array' | 'generic'
   /**
    * Choose to use `enum`, `asConst`, `asPascalConst`, `constEnum`, `literal`, or `inlineLiteral` for enums.
    * - `enum`: TypeScript enum
@@ -173,7 +177,6 @@ export const parse = createParser<ts.Node | null, ParserOptions>({
   handlers: {
     union(tree, options) {
       const { current, schema, name } = tree
-      if (!isKeyword(current, schemaKeywords.union)) return undefined
 
       return typeKeywordMapper.union(
         current.args.map((it) => this.parse({ schema, parent: current, name, current: it, siblings: [] }, options)).filter(Boolean) as ts.TypeNode[],
@@ -181,7 +184,6 @@ export const parse = createParser<ts.Node | null, ParserOptions>({
     },
     and(tree, options) {
       const { current, schema, name } = tree
-      if (!isKeyword(current, schemaKeywords.and)) return undefined
 
       return typeKeywordMapper.and(
         current.args.map((it) => this.parse({ schema, parent: current, name, current: it, siblings: [] }, options)).filter(Boolean) as ts.TypeNode[],
@@ -189,15 +191,14 @@ export const parse = createParser<ts.Node | null, ParserOptions>({
     },
     array(tree, options) {
       const { current, schema, name } = tree
-      if (!isKeyword(current, schemaKeywords.array)) return undefined
 
       return typeKeywordMapper.array(
         current.args.items.map((it) => this.parse({ schema, parent: current, name, current: it, siblings: [] }, options)).filter(Boolean) as ts.TypeNode[],
+        options.arrayType,
       )
     },
     enum(tree, options) {
       const { current } = tree
-      if (!isKeyword(current, schemaKeywords.enum)) return undefined
 
       // If enumType is 'inlineLiteral', generate the literal union inline instead of a type reference
       if (options.enumType === 'inlineLiteral') {
@@ -218,19 +219,14 @@ export const parse = createParser<ts.Node | null, ParserOptions>({
     },
     ref(tree, _options) {
       const { current } = tree
-      if (!isKeyword(current, schemaKeywords.ref)) return undefined
 
       return typeKeywordMapper.ref(current.args.name)
     },
-    blob(tree) {
-      const { current } = tree
-      if (!isKeyword(current, schemaKeywords.blob)) return undefined
-
+    blob() {
       return typeKeywordMapper.blob()
     },
     tuple(tree, options) {
       const { current, schema, name } = tree
-      if (!isKeyword(current, schemaKeywords.tuple)) return undefined
 
       return typeKeywordMapper.tuple(
         current.args.items.map((it) => this.parse({ schema, parent: current, name, current: it, siblings: [] }, options)).filter(Boolean) as ts.TypeNode[],
@@ -242,13 +238,11 @@ export const parse = createParser<ts.Node | null, ParserOptions>({
     },
     const(tree, _options) {
       const { current } = tree
-      if (!isKeyword(current, schemaKeywords.const)) return undefined
 
       return typeKeywordMapper.const(current.args.name, current.args.format)
     },
     object(tree, options) {
       const { current, schema, name } = tree
-      if (!isKeyword(current, schemaKeywords.object)) return undefined
 
       const properties = Object.entries(current.args?.properties || {})
         .filter((item) => {
@@ -377,21 +371,16 @@ export const parse = createParser<ts.Node | null, ParserOptions>({
 
       return typeKeywordMapper.object([...properties, additionalProperties, patternProperties].filter(Boolean))
     },
-    datetime(tree) {
-      const { current } = tree
-      if (!isKeyword(current, schemaKeywords.datetime)) return undefined
-
+    datetime() {
       return typeKeywordMapper.datetime()
     },
     date(tree) {
       const { current } = tree
-      if (!isKeyword(current, schemaKeywords.date)) return undefined
 
       return typeKeywordMapper.date(current.args.type)
     },
     time(tree) {
       const { current } = tree
-      if (!isKeyword(current, schemaKeywords.time)) return undefined
 
       return typeKeywordMapper.time(current.args.type)
     },

package/src/plugin.ts

@@ -19,12 +19,14 @@ export const pluginTs = definePlugin<PluginTs>((options) => {
     dateType = 'string',
     unknownType = 'any',
     optionalType = 'questionToken',
+    arrayType = 'array',
     emptySchemaType = unknownType,
     syntaxType = 'type',
     transformers = {},
     mapper = {},
     generators = [typeGenerator].filter(Boolean),
     contentType,
+    UNSTABLE_NAMING,
   } = options
 
   const usedEnumNames = {}
@@ -36,6 +38,7 @@ export const pluginTs = definePlugin<PluginTs>((options) => {
       transformers,
       dateType,
       optionalType,
+      arrayType,
       enumType,
       enumSuffix,
       unknownType,
@@ -122,6 +125,7 @@ export const pluginTs = definePlugin<PluginTs>((options) => {
         include,
         override,
         mode,
+        UNSTABLE_NAMING,
       })
 
       const operationFiles = await operationGenerator.build(...generators)