@kubb/plugin-client 5.12.0 → 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.
Files changed (72) hide show
  1. package/README.md +1 -1
  2. package/dist/client-Dq0z61hu.d.ts +554 -0
  3. package/dist/index.cjs +1378 -784
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.d.cts +114 -74
  6. package/dist/index.d.ts +114 -74
  7. package/dist/index.js +1376 -786
  8. package/dist/index.js.map +1 -1
  9. package/dist/serializers-BRgfPGr1.d.ts +119 -0
  10. package/dist/{standardSchema-BShJWz2i.d.ts → standardSchema-CGuiSK7F.d.ts} +15 -37
  11. package/dist/templates/client.d.ts +3 -2
  12. package/dist/templates/core.d.ts +3 -3
  13. package/dist/templates/mediaTypes/formData.d.ts +5 -0
  14. package/dist/templates/mediaTypes/urlencoded.d.ts +5 -0
  15. package/dist/templates/mediaTypes.d.ts +2 -0
  16. package/dist/templates/serializers/cookies.d.ts +5 -0
  17. package/dist/templates/serializers/headers.d.ts +5 -0
  18. package/dist/templates/serializers/path.d.ts +5 -0
  19. package/dist/templates/serializers/pathStyles.d.ts +5 -0
  20. package/dist/templates/serializers/query.d.ts +5 -0
  21. package/dist/templates/serializers/queryStyles.d.ts +14 -0
  22. package/dist/templates/serializers.d.ts +2 -2
  23. package/dist/templates/sse.d.ts +20 -113
  24. package/dist/templates/standardSchema.d.ts +1 -1
  25. package/docs/guides/authentication.md +9 -1
  26. package/docs/guides/migrate-to-v6.md +139 -0
  27. package/docs/guides/validate-requests-and-responses.md +8 -3
  28. package/docs/guides/write-your-client.md +117 -11
  29. package/docs/options.md +2 -2
  30. package/docs/overview.md +1 -1
  31. package/kubb-extension.json +1 -1
  32. package/package.json +6 -5
  33. package/src/builders/callConfig.ts +80 -0
  34. package/src/builders/contentType.ts +35 -0
  35. package/src/builders/generics.ts +29 -0
  36. package/src/builders/operationBody.ts +43 -0
  37. package/src/builders/operationData.ts +64 -0
  38. package/src/builders/returnStatement.ts +103 -0
  39. package/src/builders/security.ts +125 -0
  40. package/src/builders/signature.ts +71 -0
  41. package/src/builders/styles.ts +94 -0
  42. package/src/builders/validator.ts +84 -0
  43. package/src/builders/validatorOptions.ts +53 -0
  44. package/src/clientTypes.ts +195 -0
  45. package/src/components/ClientRuntime.tsx +97 -0
  46. package/src/components/Operation.tsx +72 -0
  47. package/src/components/SdkClient.tsx +100 -0
  48. package/src/components/SdkFacade.tsx +35 -0
  49. package/src/generators/clientGenerator.tsx +91 -6
  50. package/src/generators/sdkGenerator.tsx +209 -0
  51. package/src/index.ts +3 -1
  52. package/src/macros.ts +9 -0
  53. package/src/plugin.ts +7 -8
  54. package/src/resolver.ts +28 -0
  55. package/src/setup.ts +90 -0
  56. package/src/types.ts +4 -2
  57. package/templates/client.ts +2 -1
  58. package/templates/core.ts +735 -286
  59. package/templates/mediaTypes/formData.ts +59 -0
  60. package/templates/mediaTypes/urlencoded.ts +33 -0
  61. package/templates/mediaTypes.ts +147 -0
  62. package/templates/serializers/cookies.ts +58 -0
  63. package/templates/serializers/headers.ts +35 -0
  64. package/templates/serializers/path.ts +19 -0
  65. package/templates/serializers/pathStyles.ts +27 -0
  66. package/templates/serializers/query.ts +21 -0
  67. package/templates/serializers/queryStyles.ts +107 -0
  68. package/templates/serializers.ts +48 -364
  69. package/templates/sse.ts +87 -178
  70. package/templates/standardSchema.ts +16 -37
  71. package/dist/client-BxO6Dygu.d.ts +0 -355
  72. package/dist/serializers-Ds8zZwOO.d.ts +0 -190
@@ -1,355 +0,0 @@
1
- import { _ as Serializers, h as RequestBody, o as HeadersInit, s as HttpMethod, v as Styles } from "./serializers-Ds8zZwOO.js";
2
- import { a as ValidateOption, i as StandardSchemaValidator, s as ValidationErrorHandler } from "./standardSchema-BShJWz2i.js";
3
- /**
4
- * HTTP status codes treated as a success, everything else is an error.
5
- */
6
- type SuccessStatusCode = '200' | '201' | '202' | '203' | '204' | '205' | '206' | '207' | '208' | '226';
7
- type SuccessOf<TResponses> = TResponses[Extract<keyof TResponses, SuccessStatusCode>];
8
- type ErrorOf<TResponses> = TResponses[Exclude<keyof TResponses, SuccessStatusCode>];
9
- /**
10
- * Converts a response record's string status key to its numeric literal, leaving non-numeric keys like `default` as `number`.
11
- */
12
- type ToStatusNumber<TStatus> = TStatus extends `${infer TNumber extends number}` ? TNumber : number;
13
- /**
14
- * Unwraps content-type variants to keep the bare body on `error`.
15
- */
16
- type DataOf<T> = T extends {
17
- contentType: string;
18
- data: infer TData;
19
- } ? TData : T;
20
- /**
21
- * Keeps `contentType` beside `data` so switching on it narrows the body.
22
- */
23
- type SuccessVariant<TStatus, TEntry, TRequest, TResponse> = TEntry extends {
24
- contentType: string;
25
- data: unknown;
26
- } ? TEntry extends {
27
- contentType: infer TContentType;
28
- data: infer TData;
29
- } ? {
30
- status: ToStatusNumber<TStatus>;
31
- data: TData;
32
- error: undefined;
33
- contentType: TContentType;
34
- request: TRequest;
35
- response: TResponse;
36
- } : never : {
37
- status: ToStatusNumber<TStatus>;
38
- data: TEntry;
39
- error: undefined;
40
- contentType: string | undefined;
41
- request: TRequest;
42
- response: TResponse;
43
- };
44
- /**
45
- * Narrows `data` or `error` when switching on the numeric status.
46
- */
47
- type ResultByStatus<TResponses, TStatus extends keyof TResponses, TRequest, TResponse> = TStatus extends SuccessStatusCode ? SuccessVariant<TStatus, TResponses[TStatus], TRequest, TResponse> : {
48
- status: ToStatusNumber<TStatus>;
49
- data: undefined;
50
- error: DataOf<TResponses[TStatus]>;
51
- contentType: string | undefined;
52
- request: TRequest;
53
- response: TResponse;
54
- };
55
- type ResultUnion<TResponses, TRequest, TResponse> = { [TStatus in keyof TResponses]: ResultByStatus<TResponses, TStatus, TRequest, TResponse>; }[keyof TResponses];
56
- /**
57
- * Selects success statuses without letting untyped error payloads widen `data`.
58
- */
59
- type SuccessResultUnion<TResponses, TRequest, TResponse> = { [TStatus in Extract<keyof TResponses, SuccessStatusCode>]: ResultByStatus<TResponses, TStatus, TRequest, TResponse>; }[Extract<keyof TResponses, SuccessStatusCode>];
60
- /**
61
- * Narrows `data` and `error` by status. With `throwOnError`, includes only success variants.
62
- */
63
- type RequestResult<TResponses, ThrowOnError extends boolean = true, TRequest = NativeRequest, TResponse = NativeResponse> = ThrowOnError extends true ? [SuccessResultUnion<TResponses, TRequest, TResponse>] extends [never] ? {
64
- status: number;
65
- data: SuccessOf<TResponses>;
66
- error: undefined;
67
- contentType: string | undefined;
68
- request: TRequest;
69
- response: TResponse;
70
- } : SuccessResultUnion<TResponses, TRequest, TResponse> : [ResultUnion<TResponses, TRequest, TResponse>] extends [never] ? {
71
- status: number;
72
- data: undefined;
73
- error: undefined;
74
- contentType: string | undefined;
75
- request: TRequest;
76
- response: TResponse;
77
- } : ResultUnion<TResponses, TRequest, TResponse>;
78
- /**
79
- * A `RequestResult` promise with an extra `unwrap()` method that resolves to the success body.
80
- */
81
- type Unwrappable<T extends {
82
- data: unknown;
83
- error: unknown;
84
- }> = Promise<T> & {
85
- unwrap: () => Promise<Extract<T, {
86
- error: undefined;
87
- }>['data']>;
88
- };
89
- /**
90
- * Attaches `unwrap()` to a result promise, which rejects with `error` when the result carried one.
91
- *
92
- * @example
93
- * ```ts
94
- * const { data, error } = await getPetById({ path: { petId: 1 } })
95
- * ```
96
- *
97
- * @example
98
- * ```ts
99
- * const pet = await getPetById({ path: { petId: 1 } }).unwrap()
100
- * ```
101
- */
102
- declare function withUnwrap<T extends {
103
- data: unknown;
104
- error: unknown;
105
- }>(promise: Promise<T>): Unwrappable<T>;
106
- /**
107
- * The shape a generated operation returns with `returnType: 'data'`: the success body when
108
- * `throwOnError` is true, or the full `RequestResult` when it is false.
109
- */
110
- type UnwrappedResult<TResponses, ThrowOnError extends boolean = true, TRequest = NativeRequest, TResponse = NativeResponse> = ThrowOnError extends true ? RequestResult<TResponses, true, TRequest, TResponse>['data'] : RequestResult<TResponses, ThrowOnError, TRequest, TResponse>;
111
- /**
112
- * Returns the success body when `throwOnError` is true, or the full result when it is false.
113
- */
114
- declare function unwrapResult<T extends {
115
- data: unknown;
116
- error: unknown;
117
- }>(promise: Promise<T>, throwOnError: boolean | undefined): Promise<T | T['data']>;
118
- type DataShape = {
119
- body?: unknown;
120
- cookies?: unknown;
121
- headers?: unknown;
122
- path?: unknown;
123
- query?: unknown;
124
- };
125
- type RequestCredentials = 'omit' | 'same-origin' | 'include';
126
- type ResponseType = 'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream' | 'formdata';
127
- /**
128
- * Parser per response content type. Generated when one success response declares several content
129
- * types that do not share a single parser. Keys are base media types, such as `audio/mpeg` or `audio/*`.
130
- */
131
- type ResponseTypeMap = Record<string, ResponseType>;
132
- /**
133
- * Decodes a response body for a codec's media type.
134
- */
135
- type Deserializer<T = unknown> = (raw: unknown, contentType: string) => T | Promise<T>;
136
- /**
137
- * Encodes a request body for a codec's media type.
138
- */
139
- type ContentBodySerializer = (body: unknown, contentType?: string) => RequestBody | undefined;
140
- /**
141
- * Encodes requests or decodes responses for a media type. Either direction can be omitted.
142
- */
143
- type Codec = {
144
- serialize?: ContentBodySerializer;
145
- deserialize?: Deserializer;
146
- };
147
- /**
148
- * A string sets the request content type. The object form can also set `Accept`.
149
- */
150
- type ContentType = string | {
151
- request?: string;
152
- response?: string;
153
- };
154
- /**
155
- * Validates request bodies and params, success bodies, or non-throwing error bodies with Standard Schema.
156
- */
157
- type Validator<T = unknown> = StandardSchemaValidator<T>;
158
- /**
159
- * A resolved security scheme carried on each generated call's `security` array and passed to the `auth` resolver.
160
- */
161
- type Auth = {
162
- type: 'http' | 'apiKey' | 'oauth2' | 'openIdConnect';
163
- scheme?: 'bearer' | 'basic';
164
- name?: string;
165
- in?: 'header' | 'query' | 'cookie';
166
- scopes?: Array<string>;
167
- };
168
- /**
169
- * Return `user:password` for basic auth, or `undefined` to skip a scheme.
170
- */
171
- type AuthToken = string | undefined;
172
- /**
173
- * Resolves the token for a security scheme, either a static token or a callback called per scheme until one returns a token.
174
- */
175
- type AuthResolver = AuthToken | ((auth: Auth) => AuthToken | Promise<AuthToken>);
176
- type RequestConfig<TBody = unknown, TRequest = NativeRequest, TResponse = NativeResponse> = {
177
- baseURL?: string;
178
- url?: string;
179
- method?: HttpMethod;
180
- path?: unknown;
181
- query?: unknown;
182
- /** Alias of `query`, kept for callers that pass the query under this name. */
183
- params?: unknown;
184
- cookies?: unknown;
185
- body?: TBody;
186
- headers?: unknown;
187
- styles?: Styles;
188
- signal?: AbortSignal;
189
- credentials?: RequestCredentials;
190
- options?: Record<string, unknown>;
191
- contentType?: ContentType;
192
- responseType?: ResponseType | ResponseTypeMap;
193
- throwOnError?: boolean;
194
- client?: ClientInstance<TRequest, TResponse>;
195
- transport?: Transport<TRequest, TResponse>;
196
- serializer?: Serializers;
197
- codecs?: Record<string, Codec>;
198
- validator?: {
199
- request?: Validator;
200
- path?: Validator;
201
- query?: Validator;
202
- headers?: Validator;
203
- response?: Validator;
204
- error?: Validator;
205
- };
206
- onValidationError?: ValidationErrorHandler;
207
- validate?: ValidateOption;
208
- security?: Array<Auth>;
209
- auth?: AuthResolver;
210
- };
211
- /**
212
- * Combines client options with the operation's typed request params and body.
213
- */
214
- type Options<TData extends DataShape, ThrowOnError extends boolean = true, TRequest = NativeRequest, TResponse = NativeResponse> = Omit<RequestConfig<unknown, TRequest, TResponse>, keyof DataShape | 'url'> & TData & {
215
- client?: ClientInstance<TRequest, TResponse>;
216
- throwOnError?: ThrowOnError;
217
- };
218
- /**
219
- * Client-level configuration shared by every call an instance makes, overridden by the per-call `RequestConfig`.
220
- */
221
- type ClientConfig<TRequest = NativeRequest, TResponse = NativeResponse> = {
222
- baseURL?: string;
223
- headers?: HeadersInit;
224
- credentials?: RequestCredentials;
225
- options?: Record<string, unknown>;
226
- throwOnError?: boolean;
227
- transport?: Transport<TRequest, TResponse>;
228
- serializer?: Serializers;
229
- codecs?: Record<string, Codec>;
230
- onValidationError?: ValidationErrorHandler;
231
- validate?: ValidateOption;
232
- auth?: AuthResolver;
233
- };
234
- /**
235
- * The normalized request the transport receives, with all serialization, auth, and header work already done.
236
- */
237
- type ResolvedRequest = {
238
- url: string;
239
- method: string;
240
- headers: Record<string, string>;
241
- body?: RequestBody;
242
- signal?: AbortSignal;
243
- credentials?: RequestCredentials;
244
- options?: Record<string, unknown>;
245
- responseType?: ResponseType | ResponseTypeMap;
246
- };
247
- /**
248
- * What a transport returns: the parsed body plus the native request and response objects.
249
- */
250
- type TransportResult<TData = unknown, TRequest = NativeRequest, TResponse = NativeResponse> = {
251
- data: TData;
252
- status: number;
253
- statusText: string;
254
- headers: Headers;
255
- contentType?: string;
256
- request: TRequest;
257
- response: TResponse;
258
- };
259
- /**
260
- * The per-plugin send, supplied to `createClientCore` as `defaultTransport`.
261
- */
262
- type Transport<TRequest = NativeRequest, TResponse = NativeResponse> = (request: ResolvedRequest) => Promise<TransportResult<unknown, TRequest, TResponse>>;
263
- type CallResult<TRequest = NativeRequest, TResponse = NativeResponse> = {
264
- status: number;
265
- data: unknown;
266
- error: unknown;
267
- contentType: string | undefined;
268
- request: TRequest;
269
- response: TResponse;
270
- };
271
- type InterceptorFn<T, TContext = never> = (value: T, context?: TContext) => T | Promise<T>;
272
- /**
273
- * A single interceptor channel with a transport-agnostic `use` / `eject` / `update` API.
274
- */
275
- type InterceptorStack<T, TContext = never> = {
276
- use: (fn: InterceptorFn<T, TContext>) => number;
277
- eject: (id: number) => void;
278
- update: (id: number, fn: InterceptorFn<T, TContext>) => void;
279
- run: (value: T, context?: TContext) => Promise<T>;
280
- };
281
- type Interceptors<TRequest = NativeRequest, TResponse = NativeResponse> = {
282
- request: InterceptorStack<ResolvedRequest, RequestConfig<unknown, TRequest, TResponse>>;
283
- response: InterceptorStack<TransportResult<unknown, TRequest, TResponse>, RequestConfig<unknown, TRequest, TResponse>>;
284
- error: InterceptorStack<ResponseError<unknown, TRequest, TResponse>, RequestConfig<unknown, TRequest, TResponse>>;
285
- };
286
- type UrlConfig = Pick<RequestConfig, 'baseURL' | 'url' | 'path' | 'query' | 'params' | 'serializer' | 'styles'>;
287
- /**
288
- * A client instance: the callable send plus configuration, interceptors, and an isolated
289
- * `createClient` factory bound to the same transport.
290
- */
291
- type ClientInstance<TRequest = NativeRequest, TResponse = NativeResponse> = {
292
- <TBody = unknown>(config: RequestConfig<TBody, TRequest, TResponse>): Promise<CallResult<TRequest, TResponse>>;
293
- getConfig: () => ClientConfig<TRequest, TResponse>;
294
- setConfig: (config: ClientConfig<TRequest, TResponse>) => ClientConfig<TRequest, TResponse>;
295
- getUrl: (config: UrlConfig) => string;
296
- interceptors: Interceptors<TRequest, TResponse>;
297
- createClient: (config?: ClientConfig<TRequest, TResponse>) => ClientInstance<TRequest, TResponse>;
298
- };
299
- /**
300
- * Thrown for a non-2xx response, so a resolved call always means success.
301
- */
302
- declare class ResponseError<TError = unknown, TRequest = NativeRequest, TResponse = NativeResponse> extends Error {
303
- data: TError;
304
- status: number;
305
- statusText: string;
306
- contentType: string | undefined;
307
- request: TRequest;
308
- response: TResponse;
309
- constructor(config: {
310
- data: TError;
311
- status: number;
312
- statusText: string;
313
- contentType?: string;
314
- request: TRequest;
315
- response: TResponse;
316
- method?: string;
317
- url?: string;
318
- });
319
- /**
320
- * Matches on `name`, not `instanceof`: every generated client bundles its own `ResponseError` class.
321
- */
322
- static is(error: unknown): error is ResponseError<unknown, unknown, unknown>;
323
- }
324
- type ResponseErrorConfig<TError = unknown> = ResponseError<TError>;
325
- /**
326
- * Creates a transport-agnostic interceptor channel that runs interceptors in registration order.
327
- */
328
- declare function createInterceptorStack<T, TContext = never>(): InterceptorStack<T, TContext>;
329
- /**
330
- * Walks the per-operation security in order and places the first resolved token on the request, mutating `headers` / `query` in place.
331
- */
332
- declare function resolveAuth(params: {
333
- security: Array<Auth> | undefined;
334
- auth: AuthResolver | undefined;
335
- headers: Record<string, string>;
336
- query: Record<string, unknown>;
337
- }): Promise<void>;
338
- /** A body a transport left as a stream: a web `ReadableStream` or an async iterable such as a Node readable. */
339
- declare function isStreamed(data: unknown): data is ReadableStream<Uint8Array> | AsyncIterable<Uint8Array | string>;
340
- /**
341
- * Picks the parser for a response. A string `responseType` wins. A map is matched against the media type: the exact
342
- * type, then a wildcard such as `audio/*`, then a catch-all entry. Otherwise the parser is guessed from the media type.
343
- */
344
- declare function resolveResponseType(responseType: ResponseType | ResponseTypeMap | undefined, contentType: string | null | undefined): ResponseType | undefined;
345
- /** The media type of the `Content-Type` response header, without its parameters. */
346
- declare function getResponseContentType(headers: Headers | Record<string, string> | undefined): string | undefined;
347
- /**
348
- * Creates an isolated client using the supplied default transport.
349
- */
350
- declare function createClientCore<TRequest = NativeRequest, TResponse = NativeResponse>(options: {
351
- defaultTransport: Transport<TRequest, TResponse>;
352
- } & ClientConfig<TRequest, TResponse>): ClientInstance<TRequest, TResponse>;
353
- type NativeRequest = unknown;
354
- type NativeResponse = unknown;
355
- export { SuccessOf as A, Validator as B, ResolvedRequest as C, ResponseTypeMap as D, ResponseType as E, Transport as F, resolveAuth as G, createInterceptorStack as H, TransportResult as I, withUnwrap as J, resolveResponseType as K, Unwrappable as L, SuccessStatusCode as M, SuccessVariant as N, ResultByStatus as O, ToStatusNumber as P, UnwrappedResult as R, RequestResult as S, ResponseErrorConfig as T, getResponseContentType as U, createClientCore as V, isStreamed as W, InterceptorStack as _, AuthToken as a, RequestConfig as b, ClientInstance as c, ContentType as d, DataOf as f, InterceptorFn as g, ErrorOf as h, AuthResolver as i, SuccessResultUnion as j, ResultUnion as k, Codec as l, Deserializer as m, NativeResponse as n, CallResult as o, DataShape as p, unwrapResult as q, Auth as r, ClientConfig as s, NativeRequest as t, ContentBodySerializer as u, Interceptors as v, ResponseError as w, RequestCredentials as x, Options as y, UrlConfig as z };
@@ -1,190 +0,0 @@
1
- type HeaderValue = string | number | boolean | null | undefined | object;
2
- type HeadersInit = Array<[string, HeaderValue]> | Record<string, HeaderValue>;
3
- /**
4
- * The request body type `fetch` accepts, derived from `RequestInit` instead of the global `BodyInit`
5
- * name, which a Node-only project (`@types/node` without the `dom` lib) does not declare.
6
- */
7
- type RequestBody = NonNullable<RequestInit['body']>;
8
- type HttpMethod = 'GET' | 'PUT' | 'PATCH' | 'POST' | 'DELETE' | 'OPTIONS' | 'HEAD' | 'QUERY';
9
- /**
10
- * The OpenAPI query-parameter serialization style. `form` is the default; `spaceDelimited` and
11
- * `pipeDelimited` join arrays with a space or pipe, and `deepObject` renders objects as
12
- * `key[prop]=value`.
13
- */
14
- type QueryStyle = 'form' | 'spaceDelimited' | 'pipeDelimited' | 'deepObject';
15
- /**
16
- * The serialization metadata shared by the styled parameter locations: the OpenAPI `style` (typed per
17
- * location through `TStyle`), `explode`, and `allowReserved` (keeps RFC 3986 reserved characters
18
- * unencoded, used by query and request bodies).
19
- */
20
- type SerializationStyle<TStyle = string> = {
21
- style?: TStyle;
22
- explode?: boolean;
23
- allowReserved?: boolean;
24
- };
25
- /** The media type of a parameter described with `content`; JSON sends one JSON-encoded value. */
26
- type ParamContentType = {
27
- contentType?: string;
28
- };
29
- /**
30
- * The per-parameter query serialization metadata carried by the generated request. `querystring` marks an OpenAPI 3.2
31
- * `in: querystring` parameter, whose JSON value is the whole query string, sent without its name.
32
- */
33
- type QueryParamStyle = SerializationStyle<QueryStyle> & ParamContentType & {
34
- querystring?: boolean;
35
- };
36
- /**
37
- * Serializes the query object into a search string. The optional second argument carries the
38
- * per-parameter OpenAPI `style` / `explode` / `allowReserved` metadata; without it arrays explode
39
- * into repeated keys and nested objects use the `deepObject` style.
40
- */
41
- type QuerySerializer = (params: Record<string, unknown>, options?: Record<string, QueryParamStyle>) => string;
42
- /**
43
- * The per-parameter cookie serialization metadata carried by the generated request. Cookies use the
44
- * OpenAPI `form` style, so only `explode` is configurable.
45
- */
46
- type CookieParamStyle = ParamContentType & {
47
- explode?: boolean;
48
- };
49
- /**
50
- * The per-parameter header serialization metadata carried by the generated request. Headers use the
51
- * OpenAPI `simple` style, so only `explode` is configurable.
52
- *
53
- * @example
54
- * ```ts
55
- * // styles.header: { 'X-Ids': { explode: false } }, header [3, 4] -> 'X-Ids: 3,4'
56
- * // styles.header: { 'X-Filter': { explode: true } }, header { role: 'admin' } -> 'X-Filter: role=admin'
57
- * ```
58
- */
59
- type HeaderParamStyle = ParamContentType & {
60
- explode?: boolean;
61
- };
62
- /**
63
- * The per-property `encoding` metadata for an `application/x-www-form-urlencoded` or
64
- * `multipart/form-data` request body. `contentType` overrides the part's media type; `style` /
65
- * `explode` / `allowReserved` follow the OpenAPI query rules for urlencoded bodies.
66
- */
67
- type BodyEncoding = SerializationStyle<QueryStyle> & {
68
- contentType?: string;
69
- };
70
- /**
71
- * Serializes the request body. JSON by default; `FormData`, `URLSearchParams`, `Blob`,
72
- * `ArrayBuffer`, and string bodies pass through untouched. The optional `encoding` argument carries
73
- * the per-property OpenAPI `encoding` metadata for form bodies.
74
- */
75
- type BodySerializer = (args: {
76
- body: unknown;
77
- contentType?: string;
78
- encoding?: Record<string, BodyEncoding>;
79
- }) => RequestBody | undefined;
80
- /**
81
- * The OpenAPI path-parameter serialization style. `simple` is the default and emits the bare value;
82
- * `label` prefixes a `.` and `matrix` prefixes a `;name=` segment.
83
- */
84
- type PathStyle = 'simple' | 'label' | 'matrix';
85
- /**
86
- * The per-parameter serialization metadata carried by the generated request. `style` selects the
87
- * OpenAPI style and `explode` controls how arrays and objects expand.
88
- */
89
- type PathParamStyle = SerializationStyle<PathStyle>;
90
- /**
91
- * Serializes a single path parameter for interpolation into the URL, honoring the OpenAPI `style` /
92
- * `explode` passed as `options`. Defaults to `simple` style with `explode: false`: primitives are
93
- * URL-encoded, arrays join their members with commas, and objects flatten to `key,value` pairs.
94
- */
95
- type PathSerializer = (args: {
96
- name: string;
97
- value: unknown;
98
- options?: PathParamStyle;
99
- }) => string;
100
- /**
101
- * The per-concern serializers, grouped so they can be set in one place and overridden per client or
102
- * per call. Each field falls back to the matching `default*Serializer` when omitted.
103
- */
104
- type Serializers = {
105
- query?: QuerySerializer;
106
- body?: BodySerializer;
107
- path?: PathSerializer;
108
- };
109
- /**
110
- * The per-parameter OpenAPI `style` / `explode` metadata a generated request carries, grouped by
111
- * location and keyed by parameter name. Mirrors the `serializer` grouping and feeds the default
112
- * serializers; `body` carries the form `encoding` for a urlencoded or multipart body.
113
- */
114
- type Styles = {
115
- path?: Record<string, PathParamStyle>;
116
- query?: Record<string, QueryParamStyle>;
117
- header?: Record<string, HeaderParamStyle>;
118
- cookie?: Record<string, CookieParamStyle>;
119
- body?: Record<string, BodyEncoding>;
120
- };
121
- declare function isDefaultJsonBody(body: unknown): boolean;
122
- /**
123
- * Default body serializer: passes binary/form bodies through and JSON-serializes everything else.
124
- * For `multipart/form-data` plain objects become `FormData` and for
125
- * `application/x-www-form-urlencoded` they become `URLSearchParams`. When `encoding` is supplied each
126
- * urlencoded property follows its OpenAPI `style` / `explode` / `allowReserved`.
127
- *
128
- * @example
129
- * ```ts
130
- * defaultBodySerializer({ body: { name: 'odie' } }) // '{"name":"odie"}'
131
- * defaultBodySerializer({ body: { field: 'x' }, contentType: 'multipart/form-data' }) // FormData
132
- * defaultBodySerializer({ body: { tags: ['a', 'b'] }, contentType: 'application/x-www-form-urlencoded', encoding: { tags: { explode: false } } }) // 'tags=a,b'
133
- * defaultBodySerializer({ body: { meta: { a: 1 } }, contentType: 'multipart/form-data', encoding: { meta: { contentType: 'application/json' } } }) // FormData with a typed Blob part
134
- * ```
135
- */
136
- declare const defaultBodySerializer: BodySerializer;
137
- /**
138
- * The media type of a `Content-Type` value without its parameters, in lower case: `application/json; charset=utf-8` gives `application/json`.
139
- */
140
- declare function baseContentType(value: string | null | undefined): string | undefined;
141
- /** Whether a content type carries JSON: `application/json`, `text/json`, or a `+json` suffix. */
142
- declare function isJsonMediaType(contentType: string | null | undefined): boolean;
143
- /**
144
- * Serializes cookie parameters into a `Cookie` header value using the OpenAPI `form` style, joined
145
- * with `; `. Values are URL-encoded and `explode` is honored per parameter.
146
- *
147
- * @example
148
- * ```ts
149
- * serializeCookies({ session: 'abc', ids: [1, 2] }) // 'session=abc; ids=1,2'
150
- * serializeCookies({ ids: [1, 2] }, { ids: { explode: true } }) // 'ids=1; ids=2'
151
- * ```
152
- */
153
- declare function serializeCookies(cookies: Record<string, unknown>, styles?: Record<string, CookieParamStyle>): string;
154
- /**
155
- * Default query serializer. Members with `options` metadata follow their OpenAPI `style` / `explode`
156
- * / `allowReserved`. Members without it keep the defaults: arrays explode into repeated keys and
157
- * nested objects use the `deepObject` style (`key[prop]=value`).
158
- *
159
- * @example
160
- * ```ts
161
- * defaultQuerySerializer({ id: [3, 4, 5] }) // 'id=3&id=4&id=5'
162
- * defaultQuerySerializer({ id: [3, 4, 5] }, { id: { style: 'form', explode: false } }) // 'id=3,4,5'
163
- * defaultQuerySerializer({ id: [3, 4, 5] }, { id: { style: 'spaceDelimited', explode: false } }) // 'id=3%204%205'
164
- * defaultQuerySerializer({ id: [3, 4, 5] }, { id: { style: 'pipeDelimited', explode: false } }) // 'id=3|4|5'
165
- * defaultQuerySerializer({ a: { b: 1 } }, { a: { style: 'deepObject' } }) // 'a%5Bb%5D=1'
166
- * defaultQuerySerializer({ a: { b: { c: 1 } } }, { a: { style: 'deepObject' } }) // 'a%5Bb%5D%5Bc%5D=1'
167
- * ```
168
- */
169
- declare const defaultQuerySerializer: QuerySerializer;
170
- /**
171
- * Default path serializer honoring the OpenAPI `style` / `explode` metadata. Without metadata it
172
- * falls back to `simple` style with `explode: false`. Replaces the previous `String(value)`
173
- * interpolation, which emitted `[object Object]` for object path params.
174
- *
175
- * @example
176
- * ```ts
177
- * defaultPathSerializer({ name: 'id', value: [3, 4, 5] }) // '3,4,5'
178
- * defaultPathSerializer({ name: 'id', value: [3, 4, 5], options: { style: 'label', explode: true } }) // '.3.4.5'
179
- * defaultPathSerializer({ name: 'id', value: [3, 4, 5], options: { style: 'matrix', explode: true } }) // ';id=3;id=4;id=5'
180
- * defaultPathSerializer({ name: 'pt', value: { x: 1, y: 2 } }) // 'x,1,y,2'
181
- * ```
182
- */
183
- declare const defaultPathSerializer: PathSerializer;
184
- /**
185
- * Serializes array and object header parameters with the OpenAPI `simple` style before they are
186
- * merged. Header values are not URL-encoded. Primitive values and headers without metadata pass
187
- * through untouched.
188
- */
189
- declare function applyHeaderStyles(headers: HeadersInit | undefined, styles: Record<string, HeaderParamStyle> | undefined): HeadersInit | undefined;
190
- export { defaultQuerySerializer as C, serializeCookies as E, defaultPathSerializer as S, isJsonMediaType as T, Serializers as _, HeaderValue as a, baseContentType as b, ParamContentType as c, PathStyle as d, QueryParamStyle as f, SerializationStyle as g, RequestBody as h, HeaderParamStyle as i, PathParamStyle as l, QueryStyle as m, BodySerializer as n, HeadersInit as o, QuerySerializer as p, CookieParamStyle as r, HttpMethod as s, BodyEncoding as t, PathSerializer as u, Styles as v, isDefaultJsonBody as w, defaultBodySerializer as x, applyHeaderStyles as y };