@kubb/plugin-axios 5.14.0-canary.20261109T125041 → 6.0.0
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 +11 -1771
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +3 -238
- package/dist/index.d.ts +3 -238
- package/dist/index.js +12 -1749
- package/dist/index.js.map +1 -1
- package/dist/templates/client.d.ts +54 -2
- package/docs/guides/authentication.md +29 -2
- package/docs/guides/base-url.md +44 -2
- package/docs/guides/error-handling.md +31 -8
- package/docs/guides/interceptors.md +54 -19
- package/docs/guides/migrate-to-v6.md +287 -0
- package/docs/guides/serialization.md +117 -63
- package/docs/guides/server-sent-events.md +130 -29
- package/docs/guides/transport.md +17 -21
- package/docs/options.md +14 -4
- package/docs/overview.md +1 -1
- package/kubb-extension.json +1 -1
- package/package.json +8 -10
- package/src/index.ts +0 -1
- package/src/plugin.ts +7 -74
- package/src/types.ts +2 -2
- package/templates/client.ts +133 -244
- package/dist/client-B1OgL91n.d.ts +0 -81
- package/dist/core-D6FAGTsL.d.ts +0 -2
- package/dist/templates/axios.d.ts +0 -6
- package/dist/templates/core.d.ts +0 -2
- package/dist/templates/serializers.d.ts +0 -1
- package/dist/templates/standardSchema.d.ts +0 -1
- package/src/generators/clientGenerator.tsx +0 -10
- package/src/templates.ts +0 -16
- package/templates/axios.ts +0 -2
- package/templates/core.ts +0 -2
- package/templates/serializers.ts +0 -2
- package/templates/standardSchema.ts +0 -2
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Add interceptors
|
|
2
2
|
|
|
3
|
-
Register handlers on `client.interceptors.request`, `.response`, or `.error` to apply behavior across calls. Handlers receive
|
|
3
|
+
Register handlers on `client.interceptors.request`, `.response`, or `.error` to apply behavior across calls. Handlers receive the resolved request, the decoded result, or the error a call ends with.
|
|
4
4
|
|
|
5
5
|
## Run before the send
|
|
6
6
|
|
|
@@ -10,40 +10,53 @@ Request handlers run after URL construction, serialization, and authentication.
|
|
|
10
10
|
import { client } from './gen/.kubb/client'
|
|
11
11
|
|
|
12
12
|
client.interceptors.request.use((request) => {
|
|
13
|
-
request.headers
|
|
13
|
+
request.headers['X-Request-ID'] = crypto.randomUUID()
|
|
14
14
|
return request
|
|
15
15
|
})
|
|
16
16
|
```
|
|
17
17
|
|
|
18
|
-
The handler receives
|
|
19
|
-
|
|
18
|
+
The handler receives a `ResolvedRequest` (`url`, `method`, `headers`, `body`, `signal`,
|
|
19
|
+
`credentials`, `options`, `stream`).
|
|
20
20
|
|
|
21
21
|
## Run after the send
|
|
22
22
|
|
|
23
|
-
Response handlers run before
|
|
23
|
+
Response handlers run after the body is decoded and before the status check and the validator, so a JSON body is
|
|
24
|
+
already parsed. On a `client.stream` call, `data` is the raw body stream. The handler receives a `DecodedResponse`
|
|
25
|
+
(`data`, `status`, `statusText`, `headers`, `contentType`, `request`, `response`):
|
|
24
26
|
|
|
25
27
|
```typescript
|
|
26
|
-
client.interceptors.response.use((
|
|
27
|
-
console.info(`${
|
|
28
|
-
return
|
|
28
|
+
client.interceptors.response.use((result) => {
|
|
29
|
+
console.info(`${result.status} ${result.contentType}`)
|
|
30
|
+
return result
|
|
29
31
|
})
|
|
30
32
|
```
|
|
31
33
|
|
|
32
34
|
## React to an error
|
|
33
35
|
|
|
34
|
-
|
|
35
|
-
`
|
|
36
|
+
Error handlers get every failure: a `ResponseError` for a non-2xx status, a network error, an abort, or a
|
|
37
|
+
`ParseError`. Narrow with `ResponseError.is`:
|
|
36
38
|
|
|
37
39
|
```typescript
|
|
40
|
+
import { client, ResponseError } from './gen/.kubb/client'
|
|
41
|
+
|
|
38
42
|
client.interceptors.error.use((error) => {
|
|
39
|
-
if (error.
|
|
43
|
+
if (ResponseError.is(error) && error.status === 401) scheduleTokenRefresh()
|
|
44
|
+
if (error.name === 'AbortError') console.info('canceled')
|
|
40
45
|
return error
|
|
41
46
|
})
|
|
42
47
|
```
|
|
43
48
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
49
|
+
Return another error, such as a domain error, and the call throws it instead. Each handler receives the error the one
|
|
50
|
+
before it returned. A handler that returns nothing keeps the error:
|
|
51
|
+
|
|
52
|
+
```typescript
|
|
53
|
+
class NotFoundError extends Error {}
|
|
54
|
+
|
|
55
|
+
client.interceptors.error.use((error) => (ResponseError.is(error) && error.status === 404 ? new NotFoundError(error.message) : error))
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
With `throwOnError: false`, a documented non-2xx response resolves and no error handler runs for it, so inspect the
|
|
59
|
+
returned `error` on the result. An error inside a stream loop throws from the loop and skips the error handlers.
|
|
47
60
|
|
|
48
61
|
## Add, replace, and remove handlers
|
|
49
62
|
|
|
@@ -51,14 +64,13 @@ result instead. A transport failure (no response) still throws, and the error ha
|
|
|
51
64
|
to swap its function in place.
|
|
52
65
|
|
|
53
66
|
> [!NOTE]
|
|
54
|
-
>
|
|
55
|
-
> reverse order.
|
|
67
|
+
> Handlers run in the order you register them.
|
|
56
68
|
|
|
57
69
|
```typescript
|
|
58
70
|
const id = client.interceptors.request.use((request) => request)
|
|
59
71
|
|
|
60
72
|
client.interceptors.request.update(id, (request) => {
|
|
61
|
-
request.headers
|
|
73
|
+
request.headers['X-Trace'] = 'on'
|
|
62
74
|
return request
|
|
63
75
|
})
|
|
64
76
|
|
|
@@ -67,6 +79,29 @@ client.interceptors.request.eject(id)
|
|
|
67
79
|
|
|
68
80
|
## Where to set them
|
|
69
81
|
|
|
70
|
-
Register handlers on the shared `client` for all operations
|
|
82
|
+
Register handlers on the shared `client` for all operations. `client.createClient(config)` returns an instance with the
|
|
83
|
+
same config and no handlers. `client.extend(config)` returns one that runs the parent's handlers, even those added
|
|
84
|
+
later, before its own:
|
|
85
|
+
|
|
86
|
+
```typescript
|
|
87
|
+
import { client } from './gen/.kubb/client'
|
|
88
|
+
|
|
89
|
+
const admin = client.extend({ headers: { 'X-Role': 'admin' } })
|
|
90
|
+
admin.interceptors.request.use((request) => request) // runs after the handlers on client
|
|
91
|
+
await getPetById({ path: { petId: 1 }, client: admin })
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## Native axios interceptors
|
|
95
|
+
|
|
96
|
+
To get the native `InternalAxiosRequestConfig`, `AxiosResponse`, or `AxiosError`, register an axios interceptor on `getAxiosInstance()`:
|
|
97
|
+
|
|
98
|
+
```typescript
|
|
99
|
+
import { getAxiosInstance } from './gen/.kubb/client'
|
|
100
|
+
|
|
101
|
+
getAxiosInstance().interceptors.request.use((config) => {
|
|
102
|
+
config.headers.set('traceparent', currentTraceparent())
|
|
103
|
+
return config
|
|
104
|
+
})
|
|
105
|
+
```
|
|
71
106
|
|
|
72
|
-
`client.interceptors`
|
|
107
|
+
They run after the `client.interceptors` request handlers, in reverse order of registration, and response interceptors see the raw bytes. An instance you wrap with `createAxiosTransport` keeps its own interceptors. See [Use a custom transport](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/transport).
|
|
@@ -0,0 +1,287 @@
|
|
|
1
|
+
# Migrate to v6
|
|
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.
|
|
4
|
+
|
|
5
|
+
## Upgrade steps
|
|
6
|
+
|
|
7
|
+
1. Upgrade `kubb` and `@kubb/plugin-axios` together. v6 needs Kubb 5.18.4 or later:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install --save-dev kubb@latest @kubb/plugin-axios@6
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
2. Regenerate. This rewrites `.kubb/` and the operation files:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npx kubb generate
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
3. Run the type checker. Most breaking changes show up as compile errors in your own code:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npx tsc --noEmit
|
|
23
|
+
```
|
|
24
|
+
|
|
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.
|
|
26
|
+
|
|
27
|
+
## What to change
|
|
28
|
+
|
|
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'
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
The package exports `templates/client.ts` for its types only. Runtime values such as `client` still come from the generated `.kubb/client.ts`.
|
|
60
|
+
|
|
61
|
+
## Renamed and removed exports
|
|
62
|
+
|
|
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.
|
|
79
|
+
|
|
80
|
+
`ServerSentEvent`, `TypedEvent`, and `StreamResult` moved from `.kubb/sse.ts` to `.kubb/client.ts`.
|
|
81
|
+
|
|
82
|
+
## Media types
|
|
83
|
+
|
|
84
|
+
`codecs` is now `mediaTypes`, and its methods are renamed:
|
|
85
|
+
|
|
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) } } })
|
|
97
|
+
|
|
98
|
+
// after
|
|
99
|
+
client.setConfig({ mediaTypes: { 'application/xml': { decode: async (response) => parseXml(await response.text()) } } })
|
|
100
|
+
```
|
|
101
|
+
|
|
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' })
|
|
111
|
+
|
|
112
|
+
// after
|
|
113
|
+
const { stream } = await client.stream({ method: 'GET', url: '/events', eventShape: 'data' })
|
|
114
|
+
```
|
|
115
|
+
|
|
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>
|
|
121
|
+
|
|
122
|
+
// after
|
|
123
|
+
let result: StreamResult<StreamPetsResponses, true, ServerSentEvent<PetEvent>>
|
|
124
|
+
```
|
|
125
|
+
|
|
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:
|
|
127
|
+
|
|
128
|
+
```typescript
|
|
129
|
+
for await (const entry of await streamLogs()) {
|
|
130
|
+
console.info(entry.message) // LogEntry
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
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).
|
|
135
|
+
|
|
136
|
+
## Interceptors
|
|
137
|
+
|
|
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:
|
|
139
|
+
|
|
140
|
+
```typescript
|
|
141
|
+
// before
|
|
142
|
+
client.interceptors.request.use((config) => {
|
|
143
|
+
config.headers.set('X-Request-ID', crypto.randomUUID())
|
|
144
|
+
return config
|
|
145
|
+
})
|
|
146
|
+
|
|
147
|
+
// after: keep the native axios handler
|
|
148
|
+
getAxiosInstance().interceptors.request.use((config) => {
|
|
149
|
+
config.headers.set('X-Request-ID', crypto.randomUUID())
|
|
150
|
+
return config
|
|
151
|
+
})
|
|
152
|
+
|
|
153
|
+
// or: rewrite it for the resolved request, to share it with @kubb/plugin-fetch
|
|
154
|
+
client.interceptors.request.use((request) => {
|
|
155
|
+
request.headers['X-Request-ID'] = crypto.randomUUID()
|
|
156
|
+
return request
|
|
157
|
+
})
|
|
158
|
+
```
|
|
159
|
+
|
|
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:
|
|
195
|
+
|
|
196
|
+
```typescript
|
|
197
|
+
client.interceptors.error.use((error) => {
|
|
198
|
+
if (ResponseError.is(error) && error.status === 401) refreshToken()
|
|
199
|
+
return error
|
|
200
|
+
})
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
See [Handle errors](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/error-handling).
|
|
204
|
+
|
|
205
|
+
## Status ranges
|
|
206
|
+
|
|
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:
|
|
208
|
+
|
|
209
|
+
```diff
|
|
210
|
+
- import type { ListPetsStatus4XX } from './gen/types/ListPets'
|
|
211
|
+
+ import type { ListPetsStatus4xx } from './gen/types/ListPets'
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
## Generated file paths
|
|
215
|
+
|
|
216
|
+
Two changes move generated files. The exported names stay the same:
|
|
217
|
+
|
|
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`.
|
|
220
|
+
|
|
221
|
+
```diff
|
|
222
|
+
- import { listPayments } from './gen/clients/payment/listPayments'
|
|
223
|
+
+ import { listPayments } from './gen/clients/store/payment/listPayments'
|
|
224
|
+
```
|
|
225
|
+
|
|
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:
|
|
229
|
+
|
|
230
|
+
```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 })
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
The root class shares one client with every tag. Add interceptors on `api.client`.
|
|
238
|
+
|
|
239
|
+
## Behavior changes
|
|
240
|
+
|
|
241
|
+
These compile without errors, so check them by hand.
|
|
242
|
+
|
|
243
|
+
Client:
|
|
244
|
+
|
|
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()`.
|
|
247
|
+
|
|
248
|
+
Requests:
|
|
249
|
+
|
|
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.
|
|
259
|
+
|
|
260
|
+
Responses:
|
|
261
|
+
|
|
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`.
|
|
268
|
+
|
|
269
|
+
Types:
|
|
270
|
+
|
|
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 })`.
|
|
276
|
+
|
|
277
|
+
## From 5.12 or earlier
|
|
278
|
+
|
|
279
|
+
These changed in 5.13 and compile without errors:
|
|
280
|
+
|
|
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.
|
|
284
|
+
|
|
285
|
+
## Query plugins
|
|
286
|
+
|
|
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.
|