@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,115 +1,120 @@
1
1
  # Configure serialization
2
2
 
3
- The generated client encodes parameters by their OpenAPI `style` and `explode`, and encodes and decodes bodies by their media type. Each generated operation carries its parameter styles and content types, so most requests need no extra setup.
3
+ Change how the generated client encodes parameters by their OpenAPI `style` and `explode`, and how it encodes and decodes bodies by media type.
4
+
5
+ Each generated call carries its parameter styles and content types, so most specs need no setup.
4
6
 
5
7
  ## Parameter styles
6
8
 
7
- A parameter without `style` or `explode` in the spec uses the default for its location.
9
+ A parameter without `style` or `explode` in the spec uses its location's default.
10
+
11
+ ::tabs
8
12
 
9
- ### Query
13
+ :::tabs-item{label="Query"}
10
14
 
11
- Query parameters default to the `form` style. Arrays explode into repeated keys unless the spec
12
- says otherwise, and `spaceDelimited`, `pipeDelimited`, and `deepObject` change how arrays and
13
- objects collapse.
15
+ For a query parameter named `id`:
14
16
 
15
- | Style | `explode` | Input | Result |
16
- | ---------------- | --------- | ------------------- | ---------------- |
17
- | `form` (default) | `true` | `{ id: [3, 4, 5] }` | `id=3&id=4&id=5` |
18
- | `form` | `false` | `{ id: [3, 4, 5] }` | `id=3,4,5` |
19
- | `spaceDelimited` | `false` | `{ id: [3, 4, 5] }` | `id=3%204%205` |
20
- | `pipeDelimited` | `false` | `{ id: [3, 4, 5] }` | `id=3\|4\|5` |
21
- | `deepObject` | `n/a` | `{ a: { b: 1 } }` | `a%5Bb%5D=1` |
17
+ | Style | `explode` | Input | Sent |
18
+ | ---------------- | --------- | ---------------- | ---------------- |
19
+ | `form` (default) | `true` | `[3, 4, 5]` | `id=3&id=4&id=5` |
20
+ | `form` | `false` | `[3, 4, 5]` | `id=3,4,5` |
21
+ | `form` (default) | `true` | `{ a: 1, b: 2 }` | `a=1&b=2` |
22
+ | `spaceDelimited` | `false` | `[3, 4, 5]` | `id=3%204%205` |
23
+ | `pipeDelimited` | `false` | `[3, 4, 5]` | `id=3%7C4%7C5` |
24
+ | `deepObject` | n/a | `{ a: 1 }` | `id%5Ba%5D=1` |
22
25
 
23
- With `explode: true`, `spaceDelimited` and `pipeDelimited` fall back to repeated keys like `form`,
24
- so the delimiter only shows with `explode: false`.
26
+ `spaceDelimited` and `pipeDelimited` default `explode` to `false`. A space in a value goes out as `%20`.
25
27
 
26
- ### Path
28
+ :::
27
29
 
28
- Path parameters default to the `simple` style, which emits the bare value. `label` prefixes a
29
- `.` and `matrix` prefixes a `;name=` segment. The results below are the serialized segment for a
30
- parameter named `id`.
30
+ :::tabs-item{label="Path"}
31
31
 
32
- | Style | `explode` | Input | Result |
32
+ For a path parameter named `id`, the segment that replaces `{id}`:
33
+
34
+ | Style | `explode` | Input | Sent |
33
35
  | ------------------ | --------- | ---------------- | ----------------- |
34
36
  | `simple` (default) | `false` | `[3, 4, 5]` | `3,4,5` |
37
+ | `simple` (default) | `false` | `{ x: 1, y: 2 }` | `x,1,y,2` |
35
38
  | `label` | `true` | `[3, 4, 5]` | `.3.4.5` |
36
39
  | `matrix` | `true` | `[3, 4, 5]` | `;id=3;id=4;id=5` |
37
- | `simple` | `false` | `{ x: 1, y: 2 }` | `x,1,y,2` |
38
40
 
39
- ### Header and cookie
41
+ :::
42
+
43
+ :::tabs-item{label="Header"}
44
+
45
+ Headers always use the `simple` style. Only `explode` varies, and values are sent as they are.
46
+
47
+ | `explode` | Input | Sent |
48
+ | ----------------- | ------------------------------- | ---------------------- |
49
+ | `false` (default) | `'X-Ids': [3, 4]` | `X-Ids: 3,4` |
50
+ | `false` (default) | `'X-Filter': { role: 'admin' }` | `X-Filter: role,admin` |
51
+ | `true` | `'X-Filter': { role: 'admin' }` | `X-Filter: role=admin` |
52
+
53
+ :::
40
54
 
41
- Header parameters use the `simple` style and cookie parameters use the `form` style. Both fix the
42
- style and only let `explode` vary, so the metadata for these locations carries `explode` alone.
43
- Header values are sent as-is, and cookie values are URL-encoded into a single `Cookie` header.
55
+ :::tabs-item{label="Cookie"}
44
56
 
45
- | Location | `explode` | Input | Result |
46
- | -------- | --------- | --------------------------------- | ---------------------- |
47
- | header | `false` | `[3, 4]` | `X-Ids: 3,4` |
48
- | header | `true` | `{ role: 'admin' }` | `X-Filter: role=admin` |
49
- | cookie | `false` | `{ session: 'abc', ids: [1, 2] }` | `session=abc; ids=1,2` |
50
- | cookie | `true` | `{ ids: [1, 2] }` | `ids=1; ids=2` |
57
+ Cookies use the `form` style, or the OpenAPI 3.2 `cookie` style, joined into one `Cookie` header.
58
+
59
+ | Style | `explode` | Input | Sent |
60
+ | ---------------- | --------- | --------------------------------- | ---------------------- |
61
+ | `form` (default) | `false` | `{ session: 'abc', ids: [1, 2] }` | `session=abc; ids=1,2` |
62
+ | `form` | `true` | `{ ids: [1, 2] }` | `ids=1; ids=2` |
63
+ | `cookie` | `true` | `{ ids: [1, 2] }` | `ids=1; ids=2` |
64
+
65
+ `form` percent-encodes values. `cookie` sends them as they are, and a value it cannot send, such as one with `;`, throws a `TypeError`.
66
+
67
+ :::
68
+
69
+ ::
70
+
71
+ For `allowReserved` and `explode: true` on delimited styles, see [Delimited styles and allowReserved](#delimited-styles-and-allowreserved).
51
72
 
52
73
  ## Override parameter serialization
53
74
 
54
- To replace these defaults, override `serializer.query` or `serializer.path` on the client. Omitted functions keep their defaults:
75
+ Set a `serializer` key on the client to replace that serializer for every call, or on one call. The keys are `query`, `path`, `header`, and `cookie`, and the other keys keep theirs:
55
76
 
56
77
  ```typescript
57
- import { client } from './gen/.kubb/client'
58
78
  import qs from 'qs'
79
+ import { client } from './gen/.kubb/client'
59
80
 
60
81
  client.setConfig({
61
- serializer: {
62
- query: (params) => qs.stringify(params, { arrayFormat: 'brackets' }),
63
- },
82
+ serializer: { query: (params) => qs.stringify(params, { arrayFormat: 'brackets' }) },
64
83
  })
65
84
  ```
66
85
 
67
- A serializer set this way runs for every call. Pass `serializer` on a single call to override only that request.
68
-
69
- Kubb writes each serializer a spec needs into `.kubb/serializers/` and lists it in `.kubb/config.ts`, which `.kubb/client.ts` passes to `setConfig`. The core has no serializer of its own.
70
-
71
- | Key in `serializer` | File | Written for |
72
- | ------------------- | ------------------------------------------------------------------------------------ | ------------------------------ |
73
- | `query` | `query.ts`, or `queryStyles.ts` for a spec with a styled query parameter | every spec |
74
- | `path` | `path.ts`, plus `pathStyles.ts` for a spec with a `label` or `matrix` path parameter | every spec |
75
- | `header` | `headers.ts` | a spec with a header parameter |
76
- | `cookie` | `cookies.ts` | a spec with a cookie parameter |
77
-
78
- A call that needs a serializer the spec did not register throws a `TypeError` that names the key, such as `serializer.cookie`. Set it on the client to send such a call. Without `serializer.header`, an array or object header value is sent as JSON.
86
+ Kubb writes only the serializers a spec needs. See [Serializer files](#serializer-files) for which files it writes.
79
87
 
80
88
  ## Built-in media types
81
89
 
82
90
  | Keys | Encodes | Decodes |
83
91
  | ---------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------ |
84
92
  | `application/json`, `application/*+json`, `text/json` | JSON | JSON |
85
- | `text/*` | a string | text |
93
+ | `text/*` | a string as is | text |
86
94
  | `multipart/form-data`, `application/x-www-form-urlencoded` | `FormData` or `URLSearchParams` from an object | `FormData` |
87
95
  | `application/octet-stream`, `application/pdf`, `image/*`, `audio/*`, `video/*` | a `Blob` as is | `Blob` |
88
96
  | `text/event-stream`, `application/jsonl`, `application/x-ndjson`, `application/json-seq` | | text, or item by item with `client.stream` |
89
97
  | `*/*` | JSON for objects, strings and binary bodies as is | JSON, or text when the body is not JSON |
90
98
 
91
- `.kubb/client.ts` registers a form media type only when the document has a body of that type, and the stream media types only when it streams. `multipartFormData` is in `.kubb/mediaTypes/formData.ts` and `urlencoded` in `.kubb/mediaTypes/urlencoded.ts`. The stream media types are `streamMediaTypes` in `.kubb/sse.ts`.
92
-
93
- A key can be a pattern. The runtime lower-cases the type, drops its parameters, and tries the exact type, then a suffix such as `application/*+json`, then a wildcard such as `text/*`, then `*/*`. Write your own keys in lower case.
99
+ The runtime matches the lower-cased type without its parameters: the exact type, then a suffix such as `application/*+json`, then a wildcard such as `text/*`, then `*/*`. Write your own keys in lower case.
94
100
 
95
101
  ## Encode request bodies
96
102
 
97
- When an operation declares one request content type, Kubb sets it on the generated function, so you pass only the body. For an operation that accepts more than one, set `contentType` on the call. A body without a content type is sent as `application/json`, unless it is already encoded.
98
-
99
- Bodies that are already encoded (`FormData`, `URLSearchParams`, `Blob`, `ArrayBuffer`, typed arrays, streams, and strings) pass through every built-in media type as they are. A string under a JSON media type is JSON-encoded.
103
+ For an operation with several request content types, set `contentType` on the call. A body without a content type goes out as `application/json`, unless it is already encoded.
100
104
 
101
- > [!NOTE]
102
- > When the body is `FormData`, the runtime removes any `Content-Type` header so the transport sets it with the multipart boundary.
105
+ - An encoded body passes every built-in media type as is: `FormData`, `URLSearchParams`, `Blob`, `ArrayBuffer`, typed arrays, streams, and strings. Under a JSON media type, a string is JSON-encoded.
106
+ - For a `FormData` body, the runtime removes `Content-Type`, so the transport sets it with the multipart boundary.
107
+ - XML, YAML, and CSV have no built-in encoder, so an object under one throws a `TypeError`. Pass the encoded string, cast to the body type (`body: xml as unknown as AddPetBodyXml`), or add a media type.
103
108
 
104
- An XML, YAML, or CSV media type has no built-in handler, so an object sent under one throws a `TypeError`. Pass the encoded body as a string, or register a media type. The generated body type is the schema, such as `Pet`, so a string body needs a cast: `body: xml as unknown as AddPetBodyXml`.
109
+ For `bigint` bodies, see [`bigint` request bodies](#bigint-request-bodies).
105
110
 
106
111
  ## Add a media type
107
112
 
108
- Register a handler under its media type with `mediaTypes`. `encode` gets the body and a context with the full `contentType`, and returns a body axios can send. `decode` gets the `Response`, so a binary format can read bytes:
113
+ Register a handler under its media type in `mediaTypes`. `encode` gets the body and a context with the full `contentType`, and returns a body axios can send. `decode` gets the `Response`, so a binary format can read bytes:
109
114
 
110
115
  ```typescript
111
- import { client } from './gen/.kubb/client'
112
116
  import { XMLBuilder, XMLParser } from 'fast-xml-parser'
117
+ import { client } from './gen/.kubb/client'
113
118
 
114
119
  client.setConfig({
115
120
  mediaTypes: {
@@ -121,33 +126,27 @@ client.setConfig({
121
126
  })
122
127
  ```
123
128
 
124
- Handlers merge per key over the built-ins, over earlier `setConfig` calls, and, when passed on a single call, over the client ones. An entry with only `decode` still encodes through the next match, such as `*/*`.
125
-
126
- A streaming format adds `stream`, which reads the 2xx body item by item. The runtime validates each item:
129
+ Handlers merge per key over the built-ins. For the merge order, see [Media type merge order](#media-type-merge-order). A streaming format adds `stream`, which reads a 2xx body item by item, and the runtime validates each item:
127
130
 
128
131
  ```typescript
129
132
  client.setConfig({
130
- mediaTypes: {
131
- 'multipart/mixed': { stream: (body, { contentType }) => readParts(body, boundaryOf(contentType)) },
132
- },
133
+ mediaTypes: { 'multipart/mixed': { stream: (body, { contentType }) => readParts(body, boundaryOf(contentType)) } },
133
134
  })
134
135
  ```
135
136
 
136
137
  ## Decode responses
137
138
 
138
- The runtime decodes each body by the response `Content-Type`, after axios reads it as bytes. Native axios response interceptors on `getAxiosInstance()` see those bytes, so use `client.interceptors.response` to see the decoded body. The media type is on the result as `contentType`, so a `switch (result.contentType)` narrows `data` for an operation that returns more than one.
139
-
140
- - A 2xx response without a `Content-Type` is decoded as the media type the call asked for in `contentType.response`, then as `*/*`.
141
- - A 204, 205, or 304 response, a `HEAD` request, and an empty body give `data: undefined`.
142
- - Invalid JSON under a JSON media type throws a `ParseError`. Catch it, or register a lenient `application/json` handler.
139
+ Axios reads every body as bytes, then the runtime decodes it by the response `Content-Type`. Native axios response interceptors see those bytes, so use `client.interceptors.response` to see the decoded body. A `switch (result.contentType)` narrows `data` for an operation that returns several media types.
143
140
 
144
- To skip the lookup for one call, set `parseAs` to `'json'`, `'text'`, `'blob'`, `'arrayBuffer'`, or `'stream'`. It applies to a 2xx body only. Kubb sets `parseAs: 'blob'` on an operation with only binary success content:
141
+ | Response | `data` |
142
+ | ---------------------------------------------------- | ---------------------------------------------------------------------------------- |
143
+ | 204, 205, or 304, a `HEAD` request, or an empty body | `undefined` |
144
+ | Invalid JSON under a JSON media type | Throws a `ParseError`. Catch it, or register a lenient `application/json` handler. |
145
+ | 2xx with `parseAs` set on the call | Read as `'json'`, `'text'`, `'blob'`, `'arrayBuffer'`, or `'stream'`. |
145
146
 
146
- ```typescript
147
- const { data } = await getReport({ path: { id: '123' }, parseAs: 'text' })
148
- ```
147
+ For a 2xx without a `Content-Type`, see [Default content types](#default-content-types). For binary downloads and vendor types, see [Binary and vendor responses](#binary-and-vendor-responses).
149
148
 
150
- The generated types follow what the built-in media types return. A response read as text, such as `application/xml`, `application/yaml`, or `text/csv`, is typed `string`, even when the document gives it an object schema. A vendor type such as `application/vnd.github.object` keeps its schema type, because the client parses its JSON body. A media type you register changes the value but not that type, so narrow or cast `data` to what it returns:
149
+ XML, YAML, and CSV responses are typed `string`, even with an object schema. A media type you register changes the value but not the type, so cast `data`:
151
150
 
152
151
  ```typescript
153
152
  const result = await getPetById({ path: { petId: 1 }, contentType: { response: 'application/xml' } })
@@ -156,27 +155,72 @@ if (result.contentType === 'application/xml') {
156
155
  }
157
156
  ```
158
157
 
159
- The examples set [`integerType: 'number'`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#integertype) on the adapter, so an `int64` id such as `petId` is a `number`. With the default it is a `bigint` and the call takes `1n`.
158
+ > [!NOTE]
159
+ > With the adapter's default [`integerType: 'bigint'`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#integertype), an `int64` field is typed `bigint`, but `JSON.parse` returns a `number`. Set `integerType: 'number'`, or turn on [`validator: 'zod'`](https://kubb.dev/extensions/kubb-labs/plugin-axios/options#validator), which converts the field. `JSON.parse` loses precision above `Number.MAX_SAFE_INTEGER` either way, so declare an exact 64-bit ID as a string.
160
160
 
161
- [Server-sent events](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/server-sent-events) covers stream media types and `client.stream`.
161
+ Next, [Server-sent events](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/server-sent-events) covers the stream media types and `client.stream`.
162
162
 
163
- > [!NOTE]
164
- > With the adapter's default [`integerType: 'bigint'`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#integertype), a `format: int64` field is typed `bigint`, but `JSON.parse` returns a `number`. Set `integerType: 'number'` on `adapterOas`, or turn on [`validator: 'zod'`](#validate-responses), which converts the field to `bigint`. Either way, `JSON.parse` loses precision above `Number.MAX_SAFE_INTEGER`, so declare an exact 64-bit ID as a string in the document.
163
+ ## Less common cases
165
164
 
166
- ## Validate responses
165
+ ### Delimited styles and allowReserved
167
166
 
168
- Enable `validator` on the client plugin and register `pluginZod` in the same configuration. Validation is disabled by default.
167
+ When a [query parameter](#parameter-styles) uses `spaceDelimited` or `pipeDelimited`, or sets `allowReserved`:
169
168
 
170
- ```typescript
171
- import { pluginAxios } from '@kubb/plugin-axios'
169
+ - `spaceDelimited` and `pipeDelimited` default `explode` to `false`. With `explode: true`, they repeat the key, like `form`.
170
+ - With `allowReserved`, reserved characters stay as they are, except `#`, `&`, and `+`.
172
171
 
173
- pluginAxios({ validator: 'zod' })
174
- ```
172
+ ### Serializer files
175
173
 
176
- `'zod'` validates the success response body and the error body. Use the object form to opt in per direction, where `request` validates the request body before the call goes out:
174
+ When you look for a serializer in `.kubb/serializers/`, Kubb writes only the ones the spec needs and registers them in `.kubb/config.ts`. Set a key from the table to replace one, as [Override parameter serialization](#override-parameter-serialization) shows.
177
175
 
178
- ```typescript
179
- pluginAxios({ validator: { request: 'zod', response: 'zod' } })
180
- ```
176
+ | Key in `serializer` | File | Written for |
177
+ | ------------------- | -------------------------------------------------------------- | ------------------------------ |
178
+ | `query` | `query.ts`, or `queryStyles.ts` with a styled query parameter | every spec |
179
+ | `path` | `path.ts`, plus `pathStyles.ts` with a `label` or `matrix` one | every spec |
180
+ | `header` | `headers.ts` | a spec with a header parameter |
181
+ | `cookie` | `cookies.ts` | a spec with a cookie parameter |
182
+
183
+ A call that needs a serializer the spec did not register throws a `TypeError` that names it, such as `serializer.cookie`. Without `serializer.header`, an array or object header value goes out as JSON.
184
+
185
+ ### Form and stream media types
186
+
187
+ When a form or stream type from [Built-in media types](#built-in-media-types) has no handler, the spec does not use it:
188
+
189
+ - `.kubb/config.ts` registers each form type only when the spec has a body of that type, from `.kubb/mediaTypes/formData.ts` and `.kubb/mediaTypes/urlencoded.ts`.
190
+ - It registers the stream types, `streamMediaTypes` from `.kubb/sse.ts`, only when the spec streams.
191
+ - `.kubb/client.ts` passes that config to `setConfig`.
192
+
193
+ To send a type the spec does not declare, register a handler, as [Add a media type](#add-a-media-type) shows.
194
+
195
+ ### Default content types
196
+
197
+ When a call sets no `contentType`:
198
+
199
+ - An operation with one request content type has it built in. For one with several, set `contentType` on the call.
200
+ - A 2xx response without a `Content-Type` decodes as the call's `contentType.response`, then as `*/*`.
201
+
202
+ ### `bigint` request bodies
203
+
204
+ When a request body holds a `bigint`, it goes out as a JSON number. A value outside the safe-integer range throws a `TypeError` instead of losing precision, so register a media type to send it another way.
205
+
206
+ ### Media type merge order
207
+
208
+ When you register a handler for a type that already has one, handlers merge per key over the built-ins and over earlier `setConfig` calls. A handler passed on one call merges over the client's. An entry with only `decode` still encodes through the next match, such as `*/*`.
209
+
210
+ ### Binary and vendor responses
211
+
212
+ When an operation's success content is only binary, Kubb sets `parseAs: 'blob'` on it, so `data` is a `Blob` whatever its media type. The generated types follow what the built-in media types return. A vendor type such as `application/vnd.github.object` keeps its schema type.
213
+
214
+ ### Parameter validation
215
+
216
+ When [`validator`](https://kubb.dev/extensions/kubb-labs/plugin-axios/options#validator) checks `params`, the call sends what each `<operation>PathSchema`, `QuerySchema`, `HeadersSchema`, or `CookiesSchema` returns:
217
+
218
+ - A codec param such as a `Date` goes out in its wire form.
219
+ - Path and query keys the spec does not declare are stripped, such as a cache-buster.
220
+ - Undeclared headers pass through, and declared ones match in any casing. Client-level `headers` are checked too, and `auth` values are not.
221
+
222
+ With codecs, pair `request` and `params` with [`pluginZod({ inferred: 'codec' })`](https://kubb.dev/extensions/kubb-labs/plugin-zod/options#inferred), so the request types accept domain values such as a `Date`. To skip the checks, [turn validation off at runtime](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/error-handling#turn-validation-off-at-runtime).
223
+
224
+ ### Error body validation
181
225
 
182
- With a validator set, Kubb passes the matching schema to each generated call, and the runtime parses the decoded body through it. A body that does not match throws a `ParseError` with the schema's `issues`.
226
+ When `validator` is on and a non-2xx response has a body, the runtime checks it against the schema of its status, then its range such as `5xx`, then `default`. A status the document leaves out keeps its body unchecked. An error body that fails its schema throws a `ParseError` instead of the `ResponseError`, also with `throwOnError: false`. To recover, see [Validation failures](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/error-handling#validation-failures).