@kubb/plugin-axios 6.0.3 → 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.
- package/dist/index.cjs +2 -2
- package/dist/index.js +2 -2
- package/docs/guides/calling-operations.md +45 -80
- package/docs/guides/configure-requests.md +206 -0
- package/docs/guides/error-handling.md +73 -81
- package/docs/guides/migrate-to-v6.md +147 -202
- package/docs/guides/serialization.md +135 -91
- package/docs/guides/server-sent-events.md +136 -276
- package/docs/guides/transport.md +53 -30
- package/docs/options.md +72 -85
- package/docs/overview.md +33 -15
- package/kubb-extension.json +1 -1
- package/package.json +2 -2
- package/docs/guides/authentication.md +0 -101
- package/docs/guides/base-url.md +0 -102
- package/docs/guides/interceptors.md +0 -109
|
@@ -1,287 +1,232 @@
|
|
|
1
1
|
# Migrate to v6
|
|
2
2
|
|
|
3
|
-
`@kubb/plugin-axios`
|
|
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
|
-
|
|
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
|
-
|
|
10
|
-
npm install --save-dev kubb@latest @kubb/plugin-axios@6
|
|
11
|
-
```
|
|
7
|
+
## Upgrade steps
|
|
12
8
|
|
|
13
|
-
|
|
9
|
+
::steps{level="3"}
|
|
14
10
|
|
|
15
|
-
|
|
16
|
-
npx kubb generate
|
|
17
|
-
```
|
|
11
|
+
### Upgrade the packages
|
|
18
12
|
|
|
19
|
-
|
|
13
|
+
Upgrade `kubb` and `@kubb/plugin-axios` together. v6 needs Kubb 5.19.0 or later:
|
|
20
14
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
15
|
+
```bash
|
|
16
|
+
npm install --save-dev kubb@latest @kubb/plugin-axios@6
|
|
17
|
+
```
|
|
24
18
|
|
|
25
|
-
|
|
19
|
+
### Regenerate
|
|
26
20
|
|
|
27
|
-
|
|
21
|
+
This rewrites `.kubb/` and the operation files:
|
|
28
22
|
|
|
29
|
-
|
|
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
|
-
|
|
27
|
+
### Run the type checker
|
|
60
28
|
|
|
61
|
-
|
|
29
|
+
Most breaking changes show up as compile errors:
|
|
62
30
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
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
|
-
|
|
35
|
+
### Fix each error
|
|
81
36
|
|
|
82
|
-
|
|
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
|
-
|
|
39
|
+
::
|
|
85
40
|
|
|
86
|
-
|
|
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
|
-
|
|
99
|
-
|
|
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
|
-
|
|
103
|
-
|
|
104
|
-
|
|
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
|
-
|
|
113
|
-
|
|
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
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
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
|
-
|
|
123
|
-
|
|
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
|
-
|
|
106
|
+
```diff [Status ranges]
|
|
107
|
+
- import type { ListPetsStatus4XX } from './gen/types/ListPets'
|
|
108
|
+
+ import type { ListPetsStatus4xx } from './gen/types/ListPets'
|
|
109
|
+
```
|
|
127
110
|
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
|
|
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
|
-
|
|
118
|
+
::
|
|
135
119
|
|
|
136
120
|
## Interceptors
|
|
137
121
|
|
|
138
|
-
`client.interceptors` handlers now
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
204
|
-
|
|
205
|
-
## Status ranges
|
|
151
|
+
## Media types
|
|
206
152
|
|
|
207
|
-
|
|
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
|
-
-
|
|
211
|
-
+
|
|
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
|
-
|
|
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
|
-
|
|
162
|
+
## Streams
|
|
217
163
|
|
|
218
|
-
|
|
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
|
-
-
|
|
223
|
-
+
|
|
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
|
-
|
|
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
|
-
-
|
|
232
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
214
|
+
### New in v6
|
|
270
215
|
|
|
271
|
-
|
|
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
|
-
|
|
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
|
|
282
|
-
- A successful stream call with a body
|
|
283
|
-
- An event
|
|
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
|
-
|
|
230
|
+
### SDK root class
|
|
286
231
|
|
|
287
|
-
|
|
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).
|