@kubb/plugin-axios 6.0.2 → 6.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,287 +1,232 @@
1
1
  # Migrate to v6
2
2
 
3
- `@kubb/plugin-axios` 6 runs on the shared client core from `@kubb/plugin-client`, the same core as `@kubb/plugin-fetch`, with axios as the transport. Code that only calls the generated functions, SDK classes, or hooks needs a regenerate and nothing else. Most other edits land in the file that configures `client`: its interceptors, its axios instance, its media types, and its streams.
3
+ Upgrade `@kubb/plugin-axios` from v5 to v6, which runs on the shared client core from `@kubb/plugin-client` with axios as the transport.
4
4
 
5
- ## Upgrade steps
6
-
7
- 1. Upgrade `kubb` and `@kubb/plugin-axios` together. v6 needs Kubb 5.18.4 or later:
5
+ Code that only calls the generated functions, SDK classes, or hooks needs a regenerate. Most other edits land in the file that configures `client`.
8
6
 
9
- ```bash
10
- npm install --save-dev kubb@latest @kubb/plugin-axios@6
11
- ```
7
+ ## Upgrade steps
12
8
 
13
- 2. Regenerate. This rewrites `.kubb/` and the operation files:
9
+ ::steps{level="3"}
14
10
 
15
- ```bash
16
- npx kubb generate
17
- ```
11
+ ### Upgrade the packages
18
12
 
19
- 3. Run the type checker. Most breaking changes show up as compile errors in your own code:
13
+ Upgrade `kubb` and `@kubb/plugin-axios` together. v6 needs Kubb 5.19.0 or later:
20
14
 
21
- ```bash
22
- npx tsc --noEmit
23
- ```
15
+ ```bash
16
+ npm install --save-dev kubb@latest @kubb/plugin-axios@6
17
+ ```
24
18
 
25
- 4. Fix each error with its row in [What to change](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/migrate-to-v6#what-to-change). Then read [Behavior changes](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/migrate-to-v6#behavior-changes), which the type checker does not catch.
19
+ ### Regenerate
26
20
 
27
- ## What to change
21
+ This rewrites `.kubb/` and the operation files:
28
22
 
29
- | Your code | What to do |
30
- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
31
- | Calls generated functions, SDK methods, or hooks | Regenerate. Then check [Behavior changes](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/migrate-to-v6#behavior-changes). |
32
- | Registers handlers on `client.interceptors` | Move them to `getAxiosInstance()`, or rewrite them. See [Interceptors](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/migrate-to-v6#interceptors). |
33
- | Passes an axios instance as `transport`, or sets `defaultTransport.defaults` | Use `createAxiosTransport` and `getAxiosInstance()`. See [Axios instance](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/migrate-to-v6#axios-instance). |
34
- | Imports from `@kubb/plugin-axios/templates/axios.ts` or `templates/core.ts` | Change the import path. See [Template imports](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/migrate-to-v6#template-imports). |
35
- | Uses `AxiosOptions`, `defaultQuerySerializer`, `toEventStream`, or another removed export | Use the replacement. See [Renamed and removed exports](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/migrate-to-v6#renamed-and-removed-exports). |
36
- | Sets `codecs`, `serializer.body`, or `responseType` | Use `mediaTypes` and `parseAs`. See [Media types](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/migrate-to-v6#media-types). |
37
- | Streams Server-Sent Events, or names `EventStreamResult` | Use `client.stream` and `StreamResult`. See [Streams](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/migrate-to-v6#streams). |
38
- | Writes a `transport` | Return a web `Response`. See [Transports](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/migrate-to-v6#transports). |
39
- | Registers `client.interceptors.error` handlers | Narrow the error first. See [Error interceptors](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/migrate-to-v6#error-interceptors). |
40
- | Imports a `…Status2XX` type, or writes a `'2XX'` key | Write the range in lower case. See [Status ranges](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/migrate-to-v6#status-ranges). |
41
- | Imports generated files by path, and groups by tag or has a schema and an operation of one name | Update the import paths. See [Generated file paths](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/migrate-to-v6#generated-file-paths). |
42
- | Uses SDK classes with `group: { type: 'tag' }`, such as `new pet(config)` | Use the new names, such as `new PetClient(config)`. See [SDK class names](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/migrate-to-v6#sdk-class-names). |
43
- | Comes from 5.12 or earlier and uses streams | Check [From 5.12 or earlier](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/migrate-to-v6#from-5-12-or-earlier). |
44
-
45
- ## Template imports
46
-
47
- `templates/axios.ts` is gone, and the package no longer publishes its own `templates/core.ts`, `templates/serializers.ts`, or `templates/standardSchema.ts`. Import the client types from `@kubb/plugin-axios/templates/client.ts`, and the shared runtime from `@kubb/plugin-client/templates/*`:
48
-
49
- ```typescript
50
- // before
51
- import type { RequestConfig } from '@kubb/plugin-axios/templates/axios.ts'
52
- import type { ResolvedRequest } from '@kubb/plugin-axios/templates/core.ts'
53
-
54
- // after
55
- import type { RequestConfig } from '@kubb/plugin-axios/templates/client.ts'
56
- import type { ResolvedRequest } from '@kubb/plugin-client/templates/core.ts'
23
+ ```bash
24
+ npx kubb generate
57
25
  ```
58
26
 
59
- The package exports `templates/client.ts` for its types only. Runtime values such as `client` still come from the generated `.kubb/client.ts`.
27
+ ### Run the type checker
60
28
 
61
- ## Renamed and removed exports
29
+ Most breaking changes show up as compile errors:
62
30
 
63
- | Before | After |
64
- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
65
- | `AxiosOptions` | `NativeOptions`, the same type: `AxiosRequestConfig`. |
66
- | `validateStatus` | Removed. It had no effect, since the client splits success from error by status. |
67
- | `AxiosTransport`, `InterceptorFn`, `InterceptorChannel` | Removed. `createClientCore`, `ClientInstance`, and `Interceptors` come from the shared core. |
68
- | `defaultQuerySerializer` | `serializeQuery`, or `serializeStyledQuery` for a styled query parameter or a urlencoded body |
69
- | `defaultPathSerializer` | `serializePath`, plus `serializeStyledPath` for a `label` or `matrix` parameter |
70
- | `applyHeaderStyles` | `serializeHeaders` |
71
- | `toEventStream`, `EventStreamCall`, `EventStreamResult` | `client.stream` and `StreamResult`. See [Streams](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/migrate-to-v6#streams). |
72
- | `Codec`, `Deserializer`, `ContentBodySerializer`, `BodySerializer` | `MediaType`. See [Media types](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/migrate-to-v6#media-types). |
73
- | `defaultBodySerializer`, `isDefaultJsonBody` | A `mediaTypes` entry, or `defaultMediaTypes`. |
74
- | `ResponseType`, `ResponseTypeMap`, `resolveResponseType` | `ParseAs` and `parseAs`. |
75
- | `CallResult`, `isStreamed`, `getResponseContentType` | Removed. Read `result.contentType`. |
76
- | `clientGenerator` from `@kubb/plugin-axios` | Removed. Build on `setupClient` and `clientDependencies` from `@kubb/plugin-client`. |
77
-
78
- The serializers now live in one file each under `.kubb/serializers/`, and Kubb writes a file only when the document needs it. `.kubb/config.ts` registers them, and `setConfig({ serializer })` merges per key, so setting `serializer.query` keeps the others. A client you build with `createClientCore` gets none, so pass them in its `serializer` config. `serializer.header` and `serializer.cookie` are new keys.
31
+ ```bash
32
+ npx tsc --noEmit
33
+ ```
79
34
 
80
- `ServerSentEvent`, `TypedEvent`, and `StreamResult` moved from `.kubb/sse.ts` to `.kubb/client.ts`.
35
+ ### Fix each error
81
36
 
82
- ## Media types
37
+ Find its row in [What to change](#what-to-change). Then check the [behavior changes](#behavior-changes), which compile without errors.
83
38
 
84
- `codecs` is now `mediaTypes`, and its methods are renamed:
39
+ ::
85
40
 
86
- | Before | After | Migration |
87
- | --------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------ |
88
- | `codecs` | `mediaTypes` | Rename the key. |
89
- | `codecs[type].serialize(body, contentType)` | `mediaTypes[type].encode(body, context)` | Read `context.contentType`. |
90
- | `codecs[type].deserialize(raw, contentType)` with a parsed body | `mediaTypes[type].decode(response, context)` | Read the body yourself: `await response.text()`. |
91
- | `serializer.body` | removed | Move a custom body serializer into a `mediaTypes` entry. |
92
- | `responseType` on a call, a string or a map | removed | Use `parseAs`, such as `parseAs: 'blob'`, or a media type entry for that call. |
93
-
94
- ```typescript
95
- // before
96
- client.setConfig({ codecs: { 'application/xml': { deserialize: (raw) => parseXml(raw as string) } } })
41
+ ## What to change
97
42
 
98
- // after
99
- client.setConfig({ mediaTypes: { 'application/xml': { decode: async (response) => parseXml(await response.text()) } } })
43
+ | You used | Now |
44
+ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
45
+ | `@kubb/plugin-axios/templates/axios.ts` | `@kubb/plugin-axios/templates/client.ts`. Types only. |
46
+ | `@kubb/plugin-axios/templates/core.ts`, `serializers.ts`, or `standardSchema.ts` | `@kubb/plugin-client/templates/*`. Types only. |
47
+ | `client.interceptors` handlers that read axios objects | Move them to `getAxiosInstance()`, or rewrite them. See [Interceptors](#interceptors). |
48
+ | An axios instance as `transport` | `createAxiosTransport(instance)` |
49
+ | `defaultTransport.defaults` | `getAxiosInstance().defaults`. `defaultTransport` is now a function. |
50
+ | A `transport` that returns `{ data, status, ... }` | Return a web `Response`, or `{ webResponse, request, response }`. Response interceptors get a `DecodedResponse`, the shape `TransportResult` had. |
51
+ | `client.interceptors.error` handlers that read `status` | Narrow with `ResponseError.is` first. They also get network errors (`AxiosError`), aborts, and validation errors. |
52
+ | `AxiosOptions` | `NativeOptions`, the same type: `AxiosRequestConfig`. |
53
+ | `validateStatus` | Removed. The client splits success from error by status. |
54
+ | `AxiosTransport`, `InterceptorChannel` | Removed. `createClientCore`, `ClientInstance`, and `Interceptors` come from the core. |
55
+ | `InterceptorFn` | The core's `InterceptorFn<T>`, which gets the core objects. |
56
+ | `defaultQuerySerializer` | `serializeQuery`, or `serializeStyledQuery` for a styled query parameter. |
57
+ | `defaultPathSerializer` | `serializePath`, plus `serializeStyledPath` for a `label` or `matrix` parameter. |
58
+ | `applyHeaderStyles` | `serializeHeaders` |
59
+ | `codecs` | `mediaTypes`. See [Media types](#media-types). |
60
+ | `Codec`, `Deserializer`, `ContentBodySerializer`, `BodySerializer` | `MediaType` |
61
+ | `serializer.body`, `defaultBodySerializer`, `isDefaultJsonBody` | A `mediaTypes` entry, or `defaultMediaTypes`. |
62
+ | `responseType`, `ResponseType`, `ResponseTypeMap`, `resolveResponseType` | `parseAs` and `ParseAs`, such as `parseAs: 'blob'`, or a media type. |
63
+ | `formMediaTypes` | `multipartFormData` and `urlencoded`, written to `.kubb/mediaTypes/` when the spec has a form body. |
64
+ | `CallResult`, `isStreamed`, `getResponseContentType` | Removed. Read `result.contentType`. |
65
+ | `toEventStream`, `EventStreamCall`, `EventStreamResult` | `client.stream` and `StreamResult`. See [Streams](#streams). |
66
+ | `ServerSentEvent`, `TypedEvent`, or `StreamResult` from `.kubb/sse.ts` | Import them from `.kubb/client.ts`. |
67
+ | A `…Status2XX` type, or a `'2XX'` key in a responses record or `validator.error` | Lower case: `…Status2xx` and `'2xx'`. Upper-case keys are ignored. |
68
+ | `clients/payment/` for tag `payment` with `parent: store` | `clients/store/payment/`. To keep one folder per tag, pass `group: { type: 'tag', name: ({ group }) => group }`. |
69
+ | `types/Point.ts` for operation `point` next to schema `Point` | `types/PointOperation.ts`, whenever a schema file has the same name, in any case. |
70
+ | `new pet(config)` with `sdk` and `group: { type: 'tag' }` | `new PetClient(config)`. Files and root class fields, such as `pet`, stay the same. |
71
+ | `clientGenerator` from `@kubb/plugin-axios` | Removed. Build on `setupClient` and `clientDependencies` from `@kubb/plugin-client`. |
72
+
73
+ Runtime values such as `client` still come from the generated `.kubb/client.ts`. The common rewrites:
74
+
75
+ ::code-group
76
+
77
+ ```diff [Imports]
78
+ - import type { RequestConfig } from '@kubb/plugin-axios/templates/axios.ts'
79
+ - import type { ResolvedRequest } from '@kubb/plugin-axios/templates/core.ts'
80
+ + import type { RequestConfig } from '@kubb/plugin-axios/templates/client.ts'
81
+ + import type { ResolvedRequest } from '@kubb/plugin-client/templates/core.ts'
100
82
  ```
101
83
 
102
- A key can be a pattern, such as `application/*+json` or `text/*`. The form media types are written to `.kubb/mediaTypes/` as `multipartFormData` and `urlencoded`, only when the document has a form body. See [Configure serialization](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/serialization).
103
-
104
- ## Streams
105
-
106
- Send a stream request with `client.stream`. Its result is already the stream:
107
-
108
- ```typescript
109
- // before
110
- const { stream } = await toEventStream(client({ method: 'GET', url: '/events', responseType: 'stream' }), { shape: 'data' })
84
+ ```diff [Axios instance]
85
+ - import { client, defaultTransport } from './gen/.kubb/client'
86
+ + import { client, createAxiosTransport, getAxiosInstance } from './gen/.kubb/client'
111
87
 
112
- // after
113
- const { stream } = await client.stream({ method: 'GET', url: '/events', eventShape: 'data' })
88
+ - defaultTransport.defaults.timeout = 10_000
89
+ - client.setConfig({ transport: axios.create({ baseURL }) })
90
+ + getAxiosInstance().defaults.timeout = 10_000
91
+ + client.setConfig({ transport: createAxiosTransport(axios.create({ baseURL })) })
114
92
  ```
115
93
 
116
- `StreamResult` and `UnwrappedStreamResult` take the responses record and the full event type. Wrap a payload in `ServerSentEvent`. A stream typed with `TypedEvent<…>` stays the same:
117
-
118
- ```typescript
119
- // before
120
- let result: EventStreamResult<PetEvent>
94
+ ```diff [Transport]
95
+ - transport: async () => ({ data: { id: 1 }, status: 200, statusText: 'OK', headers: new Headers(), request, response })
96
+ + transport: async () => Response.json({ id: 1 })
97
+ ```
121
98
 
122
- // after
123
- let result: StreamResult<StreamPetsResponses, true, ServerSentEvent<PetEvent>>
99
+ ```typescript [Error interceptors]
100
+ client.interceptors.error.use((error) => {
101
+ if (ResponseError.is(error) && error.status === 401) refreshToken()
102
+ return error
103
+ })
124
104
  ```
125
105
 
126
- An operation whose only success content type is JSON Lines, such as `application/jsonl` or `application/x-ndjson`, now returns a `StreamResult` with one parsed item per line. It used to return the whole body as one string:
106
+ ```diff [Status ranges]
107
+ - import type { ListPetsStatus4XX } from './gen/types/ListPets'
108
+ + import type { ListPetsStatus4xx } from './gen/types/ListPets'
109
+ ```
127
110
 
128
- ```typescript
129
- for await (const entry of await streamLogs()) {
130
- console.info(entry.message) // LogEntry
131
- }
111
+ ```diff [SDK classes]
112
+ - import { pet } from './gen/sdk/pet/pet'
113
+ - const api = new pet({ baseURL })
114
+ + import { PetClient } from './gen/sdk/pet/pet'
115
+ + const api = new PetClient({ baseURL })
132
116
  ```
133
117
 
134
- A stream response that declares headers returns `StreamResultWithHeaders`, or `UnwrappedStreamResultWithHeaders` with `returnType: 'data'`. See [Stream Server-Sent Events](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/server-sent-events).
118
+ ::
135
119
 
136
120
  ## Interceptors
137
121
 
138
- `client.interceptors` handlers now receive the core objects, as on the fetch client: the `ResolvedRequest`, the `DecodedResponse`, and the error a call ends with. The quickest fix moves each handler to `getAxiosInstance().interceptors` and keeps its body. `getAxiosInstance()` is the instance v5 called `defaultTransport`, so the handlers get the same axios objects:
122
+ `client.interceptors` handlers now get the core objects: `ResolvedRequest`, `DecodedResponse`, and the error. The quickest fix moves each handler, unchanged, to `getAxiosInstance()`, the instance v5 called `defaultTransport`:
123
+
124
+ ::code-group
139
125
 
140
- ```typescript
141
- // before
126
+ ```typescript [v5]
142
127
  client.interceptors.request.use((config) => {
143
128
  config.headers.set('X-Request-ID', crypto.randomUUID())
144
129
  return config
145
130
  })
131
+ ```
146
132
 
147
- // after: keep the native axios handler
133
+ ```typescript [v6, native axios]
148
134
  getAxiosInstance().interceptors.request.use((config) => {
149
135
  config.headers.set('X-Request-ID', crypto.randomUUID())
150
136
  return config
151
137
  })
138
+ ```
152
139
 
153
- // or: rewrite it for the resolved request, to share it with @kubb/plugin-fetch
140
+ ```typescript [v6, core objects]
154
141
  client.interceptors.request.use((request) => {
155
142
  request.headers['X-Request-ID'] = crypto.randomUUID()
156
143
  return request
157
144
  })
158
145
  ```
159
146
 
160
- Native axios response interceptors see the raw bytes, not the decoded body. See [Add interceptors](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/interceptors).
161
-
162
- ## Axios instance
163
-
164
- `transport` takes a transport function. Wrap an axios instance with `createAxiosTransport`, and set defaults on `getAxiosInstance()`:
165
-
166
- ```diff
167
- - import { client, defaultTransport } from './gen/.kubb/client'
168
- + import { client, createAxiosTransport, getAxiosInstance } from './gen/.kubb/client'
169
-
170
- - defaultTransport.defaults.timeout = 10_000
171
- - client.setConfig({ transport: axios.create({ baseURL }) })
172
- + getAxiosInstance().defaults.timeout = 10_000
173
- + client.setConfig({ transport: createAxiosTransport(axios.create({ baseURL })) })
174
- ```
175
-
176
- `defaultTransport` is now a function that sends through `getAxiosInstance()`. Native interceptors for a custom transport go on the instance you pass to `createAxiosTransport`.
177
-
178
- ## Transports
179
-
180
- A transport function returns a web `Response`, or `{ webResponse, request, response }` to also set the native objects. The core decodes the body, and response interceptors receive a `DecodedResponse`, the shape `TransportResult` had:
181
-
182
- ```typescript
183
- // before
184
- transport: async () => ({ data: { id: 1 }, status: 200, statusText: 'OK', headers: new Headers(), request, response })
185
-
186
- // after
187
- transport: async () => Response.json({ id: 1 })
188
- ```
189
-
190
- See [Use a custom transport](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/transport).
191
-
192
- ## Error interceptors
193
-
194
- `client.interceptors.error` handlers now also get network errors, aborts, and validation errors. Narrow with `ResponseError.is` before you read `status`. A network error arrives as the native `AxiosError`. Each handler gets the error the previous one returned:
147
+ ::
195
148
 
196
- ```typescript
197
- client.interceptors.error.use((error) => {
198
- if (ResponseError.is(error) && error.status === 401) refreshToken()
199
- return error
200
- })
201
- ```
149
+ Native response interceptors see the raw bytes, not the decoded body. The core form also works with `@kubb/plugin-fetch`.
202
150
 
203
- See [Handle errors](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/error-handling).
204
-
205
- ## Status ranges
151
+ ## Media types
206
152
 
207
- A status range is written in lower case in generated names and keys. Rename the imports, and the range keys in a responses record or `validator.error` map you wrote by hand. An upper-case key such as `'2XX'` is no longer read:
153
+ `serialize(body, contentType)` becomes `encode(body, context)`, with the type in `context.contentType`. `decode(response, context)` gets the `Response`, not a parsed body, so read the body yourself:
208
154
 
209
155
  ```diff
210
- - import type { ListPetsStatus4XX } from './gen/types/ListPets'
211
- + import type { ListPetsStatus4xx } from './gen/types/ListPets'
156
+ - client.setConfig({ codecs: { 'application/xml': { deserialize: (raw) => parseXml(raw as string) } } })
157
+ + client.setConfig({ mediaTypes: { 'application/xml': { decode: async (response) => parseXml(await response.text()) } } })
212
158
  ```
213
159
 
214
- ## Generated file paths
160
+ A key can be a pattern, such as `text/*`. See [Built-in media types](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/serialization#built-in-media-types).
215
161
 
216
- Two changes move generated files. The exported names stay the same:
162
+ ## Streams
217
163
 
218
- - With `group: { type: 'tag' }`, a tag whose OpenAPI 3.2 `parent` is `store` writes to `store/payment/` instead of `payment/`. Pass `group.name` to keep one folder per tag: `pluginAxios({ group: { type: 'tag', name: ({ group }) => group } })`.
219
- - An operation file gets an `Operation` suffix when a schema file has the same name, ignoring case. Operation `point` goes to `types/PointOperation.ts`, next to schema `Point`.
164
+ `client.stream` returns the stream directly:
220
165
 
221
166
  ```diff
222
- - import { listPayments } from './gen/clients/payment/listPayments'
223
- + import { listPayments } from './gen/clients/store/payment/listPayments'
167
+ - const { stream } = await toEventStream(client({ method: 'GET', url: '/events', responseType: 'stream' }), { shape: 'data' })
168
+ + const { stream } = await client.stream({ method: 'GET', url: '/events', eventShape: 'data' })
224
169
  ```
225
170
 
226
- ## SDK class names
227
-
228
- With `sdk` and `group: { type: 'tag' }`, tag classes are named like `PetClient` instead of `pet`. The files and the root class's `pet` and `store` fields stay the same:
171
+ `StreamResult` and `UnwrappedStreamResult` take the responses record and the full event type, so wrap a payload in `ServerSentEvent`. A `TypedEvent<…>` stays as is:
229
172
 
230
173
  ```diff
231
- - import { pet } from './gen/sdk/pet/pet'
232
- - const api = new pet({ baseURL })
233
- + import { PetClient } from './gen/sdk/pet/pet'
234
- + const api = new PetClient({ baseURL })
174
+ - let result: EventStreamResult<PetEvent>
175
+ + let result: StreamResult<StreamPetsResponses, true, ServerSentEvent<PetEvent>>
235
176
  ```
236
177
 
237
- The root class shares one client with every tag. Add interceptors on `api.client`.
178
+ An operation whose only success type is JSON Lines returns a `StreamResult` with one parsed item per line, not a string. For stream responses with headers, see [Stream result types](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/server-sent-events#stream-result-types).
238
179
 
239
180
  ## Behavior changes
240
181
 
241
- These compile without errors, so check them by hand.
182
+ These compile without errors, so check them by hand:
242
183
 
243
- Client:
184
+ | Area | v5 | v6 |
185
+ | --------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
186
+ | Client | `client.interceptors.request` handlers ran in reverse, as in axios. | They run in registration order. |
187
+ | Client | A child from `createClient()` got its own `axios.create()`. | It inherits the `transport` of `client`. |
188
+ | Requests | A path or operation with its own `servers` used the client's `baseURL`. | It calls its own server, unless the call sets `baseURL`. See [Set the base URL](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/configure-requests#set-the-base-url). |
189
+ | Requests | An object query parameter without `style`: `filter[name]=odie`. | `name=odie&age=3`. Set `style: deepObject` in the spec to keep the brackets. |
190
+ | Requests | An array or object header without `style` went out as JSON. | `X-Ids: 3,4` |
191
+ | Requests | A space in a query value: `+`. | `%20` |
192
+ | Requests | `spaceDelimited` and `pipeDelimited` repeated the key. | `explode` defaults to `false`, so an array goes out as `ids=1%7C2`. |
193
+ | Requests | A `style: cookie` parameter was percent-encoded. | Sent as is. A value it cannot send, such as one with `;`, throws a `TypeError`. |
194
+ | Responses | Invalid JSON under a JSON media type became a string. | Throws a `ParseError`. Catch it, or register a lenient `application/json` entry. |
195
+ | Responses | An aborted call or stream rejected with axios's `CanceledError`. | It rejects with the signal's reason. |
244
196
 
245
- - `client.interceptors.request` handlers run in the order you register them. axios ran its request handlers in reverse.
246
- - A child from `createClient()` inherits the `transport` of `client`. It used to get its own `axios.create()`.
197
+ Also new in v6:
247
198
 
248
- Requests:
199
+ - Requests: `body: null` is sent as JSON `null`. A stream call sends `Accept: text/event-stream`, or its JSON Lines media type. An auth requirement with several schemes sends all of them.
200
+ - Responses: an empty body is `undefined` for every media type, text included. A failed call without a body has `{ status, statusText }` as `error`. Every result and thrown `ResponseError` has the response `Headers` as `headers`.
201
+ - Validation: `ResponseError.data` holds the validated body.
202
+ - Types: a `2xx` key is a success, a range key such as `4xx` types `status` as the codes it covers, and an exact code such as `200` wins over a range. XML, YAML, and CSV responses are `string`, so JSON and XML together give `data: Pet | string`. Image, audio, video, PDF, and `application/octet-stream` responses are `Blob`, even with `type: string`. `result.contentType` is the bare media type, such as `'text/html'`.
203
+ - Serializers: each has its own file in `.kubb/serializers/`, and `setConfig({ serializer })` merges per key. A `createClientCore` client gets no serializers, so pass them in its `serializer` config.
204
+ - Servers: `server.index` no longer counts a server without a `url`.
249
205
 
250
- - A path or operation with its own `servers` sends its calls there instead of to the client's `baseURL`. Pass `baseURL` on the call to override it. See [Set the base URL](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/base-url).
251
- - An object query parameter without a `style` goes out as `name=odie&age=3`, not `filter[name]=odie`. Set `style: deepObject` in the document to keep the brackets.
252
- - An array or object header without a `style` goes out as `X-Ids: 3,4`, not as JSON.
253
- - A space in a query value goes out as `%20`, not `+`.
254
- - `spaceDelimited` and `pipeDelimited` default `explode` to `false`, so an array goes out as `ids=1%7C2`.
255
- - A `style: cookie` parameter goes out without percent-encoding. A value it cannot send, such as one with `;`, throws a `TypeError`.
256
- - `body: null` goes out as the JSON document `null`.
257
- - A stream call sends `Accept: text/event-stream`, or the JSON Lines media type.
258
- - An auth requirement that needs several schemes sends all of them.
206
+ If you upgrade from 5.12 or earlier, also check [these changes](#from-512-or-earlier).
259
207
 
260
- Responses:
208
+ ## Query plugins
209
+
210
+ `@kubb/plugin-react-query`, `@kubb/plugin-vue-query`, `@kubb/plugin-swr`, and `@kubb/plugin-mcp` work with v5 and v6, so you can upgrade them separately. They skip hooks for JSON Lines and event stream operations.
261
211
 
262
- - Invalid JSON under a JSON media type throws a `ParseError` instead of becoming a string. Catch it, or register a lenient `application/json` entry.
263
- - An empty body is `undefined` for every media type, text included.
264
- - A failed call without a body reports `{ status, statusText }` as `error`.
265
- - `ResponseError.data` holds the validated body. Set `validator.error` to a map keyed by status, such as `{ 404: getPetStatus404Schema }`, to check an error body against the schema of its status.
266
- - An aborted call or stream rejects with the signal's reason.
267
- - Every result, and a thrown `ResponseError`, has the response's `Headers` as `headers`.
212
+ ## Less common cases
268
213
 
269
- Types:
214
+ ### New in v6
270
215
 
271
- - A `2xx` response key is a success, and range keys such as `4xx` type `status` as the numbers they cover. An exact code such as `200` wins over a range listed before it.
272
- - An XML, YAML, or CSV response is typed `string`. An operation that returns JSON and XML has `data: Pet | string`, so narrow on `result.contentType`.
273
- - An image, audio, video, PDF, or `application/octet-stream` response is typed `Blob`, even when its schema says `type: string`.
274
- - `result.contentType` is the bare media type, such as `'text/html'`.
275
- - `server.index` no longer counts a server without a `url`. Servers with a `name` are exported as `servers` from `.kubb/client.ts`, for `client.setConfig({ baseURL: servers.staging })`.
216
+ These v6 features need no code change:
276
217
 
277
- ## From 5.12 or earlier
218
+ - Validation: `validator.error` takes a map by status, such as `{ 404: getPetStatus404Schema }`, to check an error body against the schema of its status.
219
+ - Serializers: `serializer.header` and `serializer.cookie` are new. See [Override parameter serialization](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/serialization#override-parameter-serialization).
220
+ - Servers: named servers are exported as `servers` from `.kubb/client.ts`. See [Named servers](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/configure-requests#named-servers).
221
+
222
+ ### From 5.12 or earlier
278
223
 
279
224
  These changed in 5.13 and compile without errors:
280
225
 
281
- - A stream call keeps the adapter set on the call or on the instance, such as a mock adapter in tests. Only a browser call with the default adapters switches to the fetch adapter.
282
- - A successful stream call with a body that is not a stream, such as a JSON body, throws a `TypeError` with the body as its `cause`. A successful answer with no body still ends as an empty stream.
283
- - An event the server ends without a blank line is dropped, as browser `EventSource` does, so end every event with one.
226
+ - A stream call keeps the adapter set on the call or instance, such as a test mock. Only a browser call with the default adapters switches to the fetch adapter.
227
+ - A successful stream call with a non-stream body, such as JSON, throws a `TypeError` with the body as its `cause`. A successful answer with no body still ends as an empty stream.
228
+ - An event that does not end with a blank line is dropped, as in browser `EventSource`, so end every event with one.
284
229
 
285
- ## Query plugins
230
+ ### SDK root class
286
231
 
287
- `@kubb/plugin-react-query`, `@kubb/plugin-vue-query`, `@kubb/plugin-swr`, and `@kubb/plugin-mcp` work with v5 and v6, so you can upgrade them separately. They skip hooks for JSON Lines operations, as they do for event streams.
232
+ With an SDK root class, add interceptors on `api.client`, because the root class shares one client with every tag. See [`sdk`](https://kubb.dev/extensions/kubb-labs/plugin-axios/options#sdk).