`operationTypes` to simplify generated operation types

[alario-tang]

operationTypes — simplify generated operation types

Add an operationTypes?: boolean option (default true) to @kubb/plugin-ts that references base schema types directly instead of the per-operation alias layer.

Behavior

With operationTypes: false, a request body or response backed by a single $ref resolves to the referenced component type (e.g. Pet) instead of the AddPetData / AddPetStatus200 alias. Inline, array, and union schemas keep their per-operation alias because no single base type exists.

• @kubb/plugin-ts stops emitting the redundant $ref-backed aliases and references the base component inside the aggregate XxxResponses / XxxResponse types.
• The option lives on @kubb/plugin-ts only. It makes the TypeScript resolver inline $ref-backed names; consumer plugins (@kubb/plugin-client, @kubb/plugin-react-query, @kubb/plugin-vue-query) read that resolver through the plugin driver, so they inherit the inlining automatically — no per-plugin flag to keep in sync.
• Default (true) keeps existing output unchanged.

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginTs({ operationTypes: false }),
    pluginClient(),
  ],
})

Before (operationTypes: true, default)

import type { AddPetData, AddPetStatus200, AddPetStatus422 } from '../models/AddPet'

export async function addPet(data?: AddPetData, config: Partial<RequestConfig<AddPetData>> = {}) {
  const res = await request<AddPetStatus200, ResponseErrorConfig<AddPetStatus422>, AddPetData>({ /* ... */ })
  return res.data
}

After (operationTypes: false)

import type { Pet } from '../models/Pet'
import type { HttpValidationError } from '../models/HttpValidationError'

export async function addPet(data?: Pet, config: Partial<RequestConfig<Pet>> = {}) {
  const res = await request<Pet, ResponseErrorConfig<HttpValidationError>, Pet>({ /* ... */ })
  return res.data
}

Note on the 2xx discussion

The separate request from the thread — narrowing the success/return type (and TanStack TData) to the 2xx response instead of the union of all status codes — already shipped and is unchanged by this option. operationTypes only controls whether the names are the base component types or the per-operation aliases.

Implemented in #222.

Original request (by @alario-tang)

Feature Request: Option to simplify generated operation types

Problem

When generating TypeScript types for API operations, Kubb creates multiple type aliases that are often redundant:

// Generated in models/orderManagement/OrderManagementGetAllPortfolioTrades.ts

export type OrderManagementGetAllPortfolioTrades200 = PortfolioTradesResponseCO;
export type OrderManagementGetAllPortfolioTrades422 = HTTPValidationError;
export type OrderManagementGetAllPortfolioTradesMutationResponse = OrderManagementGetAllPortfolioTrades200;
export type OrderManagementGetAllPortfolioTradesMutation = {
  Response: OrderManagementGetAllPortfolioTrades200;
  Request: OrderManagementGetAllPortfolioTradesMutationRequest;
  Errors: OrderManagementGetAllPortfolioTrades422;
};

In practice, I only need to import the base business type (PortfolioTradesResponseCO) directly. The operation-level aliases add noise and increase bundle size.

Proposed Solution

Add a configuration option like operationTypes: false to skip generating operation-level type aliases and use the base types directly in generated functions.

Use Case

• Projects that don't need fine-grained error type handling per status code
• Cleaner imports in business code
• Smaller generated output

[brenodanyel]

+1 ! same thing here with @kubb/plugin-vue-query.

On a POST, the mutation success type is a union of every response in the OpenAPI spec (201 | 401 | 409). In the component you mutateAsync() and then naturally try to access response.id, but obviously TS complains because id isn’t on the 401/409 shapes.

Our client throws on !response.ok, so 4xx never actually resolve the mutation; only 2xx does.

operationTypes: false (or success typed as 2xx only) would match how TanStack Query is actually used and save us from as or 'id' in response on every mutation.

Stack: Kubb 5.0.0-beta.22 + plugin-ts / client / vue-query.

[stijnvanhulle]

@brenodanyel Am I correct that you want to have 2xx to be result in your vue-query return type instead of having all possible reponse types?

[stijnvanhulle]

@brenodanyel what about:

Given an OpenAPI operation addPet with responses 200 → Pet, 405 → Error:

Before (current behavior — XxxMutation is the full union):

// generated useAddPet.ts
export function useAddPet<TContext>(
  options: {
    mutation?: MutationObserverOptions<
      AddPetMutationResponse,                          // Pet | Error  ← union
      ResponseErrorConfig<AddPetStatus405>,
      { data: AddPetMutationRequest },
      TContext
    > & { client?: QueryClient }
    client?: Partial<RequestConfig<AddPetMutationRequest>> & { client?: typeof fetch }
  } = {},
) { /* ... */ }

// call site — TS complains because Error has no `id`
const pet = await mutateAsync({ data: { name: 'Rex' } })
pet.id // ❌ Property 'id' does not exist on type 'Pet | Error'
After with default responseType: 'success':

export function useAddPet<TContext>(
  options: {
    mutation?: MutationObserverOptions<
      AddPetStatus200,                                 // Pet only  ← 2xx
      ResponseErrorConfig<AddPetStatus405>,
      { data: AddPetMutationRequest },
      TContext
    > & { client?: QueryClient }
    client?: Partial<RequestConfig<AddPetMutationRequest>> & { client?: typeof fetch }
  } = {},
) { /* ... */ }

const pet = await mutateAsync({ data: { name: 'Rex' } })
pet.id // ✅ Pet.id

[brenodanyel]

exactly!

[brenodanyel]

Currently I have made a workaround script that edits the gen files programatically. I hope we have a official solution in future