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

package/dist/{types-aotMcdUB.d.ts → types-eWhVEVgF.d.ts}

@@ -65,6 +65,8 @@ 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;
   /**
@@ -72,6 +74,8 @@ 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';
   /**
@@ -80,6 +84,8 @@ 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';
   /**
@@ -88,6 +94,8 @@ 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';
   /**
@@ -96,6 +104,8 @@ 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';
   /**
@@ -167,4 +177,4 @@ type ResolvedOptions = {
 type PluginTs = PluginFactoryOptions<'plugin-ts', Options, ResolvedOptions, never, ResolvePathOptions>;
 //#endregion
 export { PluginTs as n, Options as t };
-//# sourceMappingURL=types-aotMcdUB.d.ts.map
+//# sourceMappingURL=types-eWhVEVgF.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-ts",
-  "version": "5.0.0-alpha.4",
+  "version": "5.0.0-alpha.5",
   "description": "TypeScript code generation plugin for Kubb, transforming OpenAPI schemas into TypeScript interfaces, types, and utility functions.",
   "keywords": [
     "typescript",
@@ -67,17 +67,17 @@
     }
   ],
   "dependencies": {
-    "@kubb/fabric-core": "0.13.3",
-    "@kubb/react-fabric": "0.13.3",
+    "@kubb/fabric-core": "0.14.0",
+    "@kubb/react-fabric": "0.14.0",
     "remeda": "^2.33.6",
     "typescript": "5.9.3",
-    "@kubb/ast": "5.0.0-alpha.4",
-    "@kubb/core": "5.0.0-alpha.4",
-    "@kubb/oas": "5.0.0-alpha.4",
-    "@kubb/plugin-oas": "5.0.0-alpha.4"
+    "@kubb/ast": "5.0.0-alpha.5",
+    "@kubb/core": "5.0.0-alpha.5",
+    "@kubb/plugin-oas": "5.0.0-alpha.5",
+    "@kubb/oas": "5.0.0-alpha.5"
   },
   "peerDependencies": {
-    "@kubb/react-fabric": "0.13.3"
+    "@kubb/react-fabric": "0.14.0"
   },
   "engines": {
     "node": ">=22"

package/src/components/v2/Type.tsx

@@ -18,11 +18,24 @@ type Props = {
   enumType: PluginTs['resolvedOptions']['enumType']
   enumKeyCasing: PluginTs['resolvedOptions']['enumKeyCasing']
   syntaxType: PluginTs['resolvedOptions']['syntaxType']
+  mapper?: PluginTs['resolvedOptions']['mapper']
   description?: string
   keysToOmit?: string[]
 }
 
-export function Type({ name, typedName, node, keysToOmit, optionalType, arrayType, syntaxType, enumType, enumKeyCasing, ...rest }: Props): FabricReactNode {
+export function Type({
+  name,
+  typedName,
+  node,
+  keysToOmit,
+  optionalType,
+  arrayType,
+  syntaxType,
+  enumType,
+  enumKeyCasing,
+  mapper,
+  ...rest
+}: Props): FabricReactNode {
   const typeNodes: ts.Node[] = []
 
   const description = rest.description || node?.description
@@ -32,7 +45,7 @@ export function Type({ name, typedName, node, keysToOmit, optionalType, arrayTyp
     },
   })
 
-  const printer = printerTs({ optionalType, arrayType, enumType })
+  const printer = printerTs({ optionalType, arrayType, enumType, mapper })
   let type = printer.print(node)
 
   if (!type) {

package/src/factory.ts

@@ -662,43 +662,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))
   })
 

package/src/generators/v2/typeGenerator.tsx

@@ -1,45 +1,46 @@
+import { applyParamsCasing } from '@kubb/ast'
 import type { SchemaNode } from '@kubb/ast/types'
 import { defineGenerator } from '@kubb/core'
 import { useKubb } from '@kubb/core/hooks'
 import { File } from '@kubb/react-fabric'
 import { Type } from '../../components/v2/Type.tsx'
 import type { PluginTs } from '../../types'
+import { buildDataSchemaNode, buildResponsesSchemaNode, buildResponseUnionSchemaNode } from './utils.ts'
 
 export const typeGenerator = defineGenerator<PluginTs>({
   name: 'typescript',
   type: 'react',
   Operation({ node, adapter, options }) {
-    const { enumType, enumKeyCasing, optionalType, arrayType, syntaxType } = options
+    const { enumType, enumKeyCasing, optionalType, arrayType, syntaxType, paramsCasing, mapper } = options
+    const { mode, getFile, resolveName } = useKubb<PluginTs>()
 
-    const { plugin, mode, getFile, resolveName } = useKubb<PluginTs>()
+    const file = getFile({ name: node.operationId, extname: '.ts', mode })
+    const params = applyParamsCasing(node.parameters, paramsCasing)
 
-    const file = getFile({
-      name: node.operationId,
-      pluginName: plugin.name,
-      extname: '.ts',
-      mode,
-    })
+    function renderSchemaType({
+      node: schemaNode,
+      name,
+      typedName,
+      description,
+    }: {
+      node: SchemaNode | null
+      name: string
+      typedName: string
+      description?: string
+    }) {
+      if (!schemaNode) {
+        return null
+      }
 
-    function renderSchemaType({ node: schemaNode, name, typedName, description }: { node: SchemaNode; name: string; typedName: string; description?: string }) {
       const imports = adapter.getImports(schemaNode, (schemaName) => ({
-        name: resolveName({
-          name: schemaName,
-          pluginName: plugin.name,
-          type: 'type',
-        }),
-        path: getFile({
-          name: schemaName,
-          pluginName: plugin.name,
-          extname: '.ts',
-          mode,
-        }).path,
+        name: resolveName({ name: schemaName, type: 'type' }),
+        path: getFile({ name: schemaName, extname: '.ts', mode }).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 />)}
-
           <Type
             name={name}
             typedName={typedName}
@@ -50,127 +51,93 @@ export const typeGenerator = defineGenerator<PluginTs>({
             optionalType={optionalType}
             arrayType={arrayType}
             syntaxType={syntaxType}
+            mapper={mapper}
           />
         </>
       )
     }
 
-    // Parameter types — each parameter rendered as its own type
-    const paramTypes = node.parameters.map((param) => {
-      const name = resolveName({
-        name: `${node.operationId} ${param.name}`,
-        pluginName: plugin.name,
-        type: 'function',
-      })
-      const typedName = resolveName({
-        name: `${node.operationId} ${param.name}`,
-        pluginName: plugin.name,
-        type: 'type',
-      })
-
-      return renderSchemaType({ node: param.schema, name, typedName })
-    })
+    const paramTypes = params.map((param) =>
+      renderSchemaType({
+        node: param.schema,
+        name: resolveName({ name: `${node.operationId} ${param.name}`, type: 'function' }),
+        typedName: resolveName({ name: `${node.operationId} ${param.name}`, type: 'type' }),
+      }),
+    )
 
-    // Response types
     const responseTypes = node.responses
       .filter((res) => res.schema)
-      .map((res) => {
-        const schemaNode = res.schema!
-        const responseName = `${node.operationId} ${res.statusCode}`
-        const resolvedName = resolveName({
-          name: responseName,
-          pluginName: plugin.name,
-          type: 'function',
-        })
-        const typedName = resolveName({
-          name: responseName,
-          pluginName: plugin.name,
-          type: 'type',
-        })
-
-        return renderSchemaType({ node: schemaNode, name: resolvedName, typedName, description: res.description })
-      })
+      .map((res) =>
+        renderSchemaType({
+          node: res.schema!,
+          name: resolveName({ name: `${node.operationId} ${res.statusCode}`, type: 'function' }),
+          typedName: resolveName({ name: `${node.operationId} ${res.statusCode}`, type: 'type' }),
+          description: res.description,
+        }),
+      )
 
-    // Request body type
     const requestType = node.requestBody
-      ? (() => {
-          const requestName = `${node.operationId} MutationRequest`
-          const resolvedName = resolveName({
-            name: requestName,
-            pluginName: plugin.name,
-            type: 'function',
-          })
-          const typedName = resolveName({
-            name: requestName,
-            pluginName: plugin.name,
-            type: 'type',
-          })
-
-          return renderSchemaType({ node: node.requestBody, name: resolvedName, typedName, description: node.requestBody.description })
-        })()
+      ? renderSchemaType({
+          node: node.requestBody,
+          name: resolveName({ name: `${node.operationId} MutationRequest`, type: 'function' }),
+          typedName: resolveName({ name: `${node.operationId} MutationRequest`, type: 'type' }),
+          description: node.requestBody.description,
+        })
       : null
 
+    const dataType = renderSchemaType({
+      node: buildDataSchemaNode({ node: { ...node, parameters: params }, resolveName }),
+      name: resolveName({ name: `${node.operationId} Data`, type: 'function' }),
+      typedName: resolveName({ name: `${node.operationId} Data`, type: 'type' }),
+    })
+
+    const responsesType = renderSchemaType({
+      node: buildResponsesSchemaNode({ node, resolveName }),
+      name: resolveName({ name: `${node.operationId} Responses`, type: 'function' }),
+      typedName: resolveName({ name: `${node.operationId} Responses`, type: 'type' }),
+    })
+
+    const responseType = renderSchemaType({
+      node: buildResponseUnionSchemaNode({ node, resolveName }),
+      name: resolveName({ name: `${node.operationId} Response`, type: 'function' }),
+      typedName: resolveName({ name: `${node.operationId} Response`, type: 'type' }),
+    })
+
     return (
       <File baseName={file.baseName} path={file.path} meta={file.meta}>
         {paramTypes}
         {responseTypes}
         {requestType}
+        {dataType}
+        {responsesType}
+        {responseType}
       </File>
     )
   },
   Schema({ node, adapter, options }) {
-    const { enumType, enumKeyCasing, syntaxType, optionalType, arrayType } = options
-    const { plugin, mode, resolveName, getFile } = useKubb<PluginTs>()
+    const { enumType, enumKeyCasing, syntaxType, optionalType, arrayType, mapper } = options
+    const { mode, resolveName, getFile } = useKubb<PluginTs>()
 
     if (!node.name) {
       return
     }
 
     const imports = adapter.getImports(node, (schemaName) => ({
-      name: resolveName({
-        name: schemaName,
-        pluginName: plugin.name,
-        type: 'type',
-      }),
-      path: getFile({
-        name: schemaName,
-        pluginName: plugin.name,
-        extname: '.ts',
-        mode,
-        // options: {
-        //   group
-        // },
-      }).path,
+      name: resolveName({ name: schemaName, type: 'type' }),
+      path: getFile({ name: schemaName, extname: '.ts', mode }).path,
     }))
 
     const isEnumSchema = node.type === 'enum'
 
-    let typedName = resolveName({
-      name: node.name,
-      pluginName: plugin.name,
-      type: 'type',
-    })
-
+    let typedName = resolveName({ name: node.name, type: 'type' })
     if (['asConst', 'asPascalConst'].includes(enumType) && isEnumSchema) {
-      typedName = typedName += 'Key'
+      typedName += 'Key'
     }
 
     const type = {
-      name: resolveName({
-        name: node.name,
-        pluginName: plugin.name,
-        type: 'function',
-      }),
+      name: resolveName({ name: node.name, type: 'function' }),
       typedName,
-      file: getFile({
-        name: node.name,
-        pluginName: plugin.name,
-        extname: '.ts',
-        mode,
-        // options: {
-        //   group
-        // },
-      }),
+      file: getFile({ name: node.name, extname: '.ts', mode }),
     } as const
 
     return (
@@ -179,7 +146,6 @@ export const typeGenerator = defineGenerator<PluginTs>({
           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}
           typedName={type.typedName}
@@ -189,6 +155,7 @@ export const typeGenerator = defineGenerator<PluginTs>({
           optionalType={optionalType}
           arrayType={arrayType}
           syntaxType={syntaxType}
+          mapper={mapper}
         />
       </File>
     )

package/src/generators/v2/utils.ts

@@ -0,0 +1,145 @@
+import { createProperty, createSchema } from '@kubb/ast'
+import type { OperationNode, ParameterNode, SchemaNode } from '@kubb/ast/types'
+
+type ResolveName = (opts: { name: string; type: 'type' | 'function' }) => string
+
+type BuildParamsSchemaOptions = {
+  params: Array<ParameterNode>
+  operationId: string
+  resolveName: ResolveName
+}
+
+/**
+ * Builds an `ObjectSchemaNode` for a group of parameters (path/query/header).
+ * Each property is a `ref` schema pointing to the individually-resolved parameter type.
+ */
+export function buildParamsSchema({ params, operationId, resolveName }: BuildParamsSchemaOptions): SchemaNode {
+  return createSchema({
+    type: 'object',
+    properties: params.map((param) =>
+      createProperty({
+        name: param.name,
+        schema: createSchema({
+          type: 'ref',
+          name: resolveName({ name: `${operationId} ${param.name}`, type: 'function' }),
+          optional: !param.required,
+        }),
+      }),
+    ),
+  })
+}
+
+type BuildOperationSchemaOptions = {
+  node: OperationNode
+  resolveName: ResolveName
+}
+
+/**
+ * Builds an `ObjectSchemaNode` representing the `<OperationId>Data` type:
+ * - `data`         → request body ref (optional) or `never`
+ * - `pathParams`   → inline object of path param refs, or `never`
+ * - `queryParams`  → inline object of query param refs (optional), or `never`
+ * - `headerParams` → inline object of header param refs (optional), or `never`
+ * - `url`          → Express-style template literal (plugin-ts extension, handled by printer)
+ */
+export function buildDataSchemaNode({ node, resolveName }: BuildOperationSchemaOptions): SchemaNode {
+  const pathParams = node.parameters.filter((p) => p.in === 'path')
+  const queryParams = node.parameters.filter((p) => p.in === 'query')
+  const headerParams = node.parameters.filter((p) => p.in === 'header')
+
+  return createSchema({
+    type: 'object',
+    properties: [
+      createProperty({
+        name: 'data',
+        schema: node.requestBody
+          ? createSchema({
+              type: 'ref',
+              name: resolveName({ name: `${node.operationId} MutationRequest`, type: 'function' }),
+              optional: true,
+            })
+          : createSchema({ type: 'never', optional: true }),
+      }),
+      createProperty({
+        name: 'pathParams',
+        schema:
+          pathParams.length > 0
+            ? buildParamsSchema({ params: pathParams, operationId: node.operationId, resolveName })
+            : createSchema({ type: 'never', optional: true }),
+      }),
+      createProperty({
+        name: 'queryParams',
+        schema:
+          queryParams.length > 0
+            ? createSchema({ ...buildParamsSchema({ params: queryParams, operationId: node.operationId, resolveName }), optional: true })
+            : createSchema({ type: 'never', optional: true }),
+      }),
+      createProperty({
+        name: 'headerParams',
+        schema:
+          headerParams.length > 0
+            ? createSchema({ ...buildParamsSchema({ params: headerParams, operationId: node.operationId, resolveName }), optional: true })
+            : createSchema({ type: 'never', optional: true }),
+      }),
+      createProperty({
+        name: 'url',
+        schema: createSchema({ type: 'url', path: node.path }),
+      }),
+    ],
+  })
+}
+
+/**
+ * Builds an `ObjectSchemaNode` representing `<OperationId>Responses` — keyed by HTTP status code.
+ *
+ * Example output:
+ * ```ts
+ * export type PlaceOrderPatchResponses = { 200: PlaceOrderPatch200; 405: PlaceOrderPatch405 }
+ * ```
+ */
+export function buildResponsesSchemaNode({ node, resolveName }: BuildOperationSchemaOptions): SchemaNode | null {
+  const responsesWithSchema = node.responses.filter((res) => res.schema)
+
+  if (responsesWithSchema.length === 0) {
+    return null
+  }
+
+  return createSchema({
+    type: 'object',
+    properties: responsesWithSchema.map((res) =>
+      createProperty({
+        name: String(res.statusCode),
+        schema: createSchema({
+          type: 'ref',
+          name: resolveName({ name: `${node.operationId} ${res.statusCode}`, type: 'function' }),
+        }),
+      }),
+    ),
+  })
+}
+
+/**
+ * Builds a `UnionSchemaNode` representing `<OperationId>Response` — all response types in union format.
+ *
+ * Example output:
+ * ```ts
+ * export type PlaceOrderPatchResponse = PlaceOrderPatch200 | PlaceOrderPatch405
+ * ```
+ */
+export function buildResponseUnionSchemaNode({ node, resolveName }: BuildOperationSchemaOptions): SchemaNode | null {
+  const responsesWithSchema = node.responses.filter((res) => res.schema)
+
+  if (responsesWithSchema.length === 0) {
+    return null
+  }
+
+  return createSchema({
+    type: 'union',
+    members: responsesWithSchema.map((res) =>
+      createSchema({
+        type: 'ref',
+        name: resolveName({ name: `${node.operationId} ${res.statusCode}`, type: 'function' }),
+      }),
+    ),
+  })
+}

package/src/plugin.ts

@@ -167,6 +167,17 @@ export const pluginTs = definePlugin<PluginTs>((options) => {
           { depth: 'shallow' },
         )
 
+        const barrelFiles = await getBarrelFiles(this.fabric.files, {
+          type: output.barrelType ?? 'named',
+          root,
+          output,
+          meta: {
+            pluginName: this.plugin.name,
+          },
+        })
+
+        await this.upsertFile(...barrelFiles)
+
         return
       }
 

package/src/printer.ts

@@ -19,6 +19,10 @@ type TsOptions = {
    * @default `'inlineLiteral'`
    */
   enumType: 'enum' | 'asConst' | 'asPascalConst' | 'constEnum' | 'literal' | 'inlineLiteral'
+  /**
+   * Custom property signatures that override specific object properties by name.
+   */
+  mapper?: Record<string, ts.PropertySignature>
 }
 
 type TsPrinter = PrinterFactoryOptions<'typescript', TsOptions, ts.TypeNode>
@@ -143,13 +147,19 @@ export const printerTs = definePrinter<TsPrinter>((options) => ({
     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: () => 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,
@@ -219,6 +229,10 @@ export const printerTs = definePrinter<TsPrinter>((options) => ({
       const { print } = this
 
       const propertyNodes: Array<ts.TypeElement> = node.properties.map((prop) => {
+        if (this.options.mapper && Object.hasOwn(this.options.mapper, prop.name)) {
+          return this.options.mapper[prop.name]!
+        }
+
         const baseType = (print(prop.schema) ?? factory.keywordTypeNodes.unknown) as ts.TypeNode
         const type = buildPropertyType(prop.schema, baseType, this.options.optionalType)