@kubb/plugin-axios 5.9.0 → 5.9.2

package/dist/templates/axios.d.ts

@@ -6,27 +6,21 @@ import { AxiosError, AxiosInstance, AxiosRequestConfig, AxiosResponse, InternalA
  * HTTP status codes treated as a success, everything else is an error.
  */
 export type SuccessStatusCode = '200' | '201' | '202' | '203' | '204' | '205' | '206' | '207' | '208' | '226';
-/**
- * The success members of a per-status responses record.
- */
 export type SuccessOf<TResponses> = TResponses[Extract<keyof TResponses, SuccessStatusCode>];
-/**
- * The error members of a per-status responses record, every documented status that is not a 2xx.
- */
 export type ErrorOf<TResponses> = TResponses[Exclude<keyof TResponses, SuccessStatusCode>];
 /**
  * Converts a response record's string status key to its numeric literal, leaving non-numeric keys like `default` as `number`.
  */
 export type ToStatusNumber<TStatus> = TStatus extends `${infer TNumber extends number}` ? TNumber : number;
 /**
- * The plain body of a per-status response, unwrapping the `{ contentType; data }` union so an error result keeps the bare body union on `error`.
+ * Unwraps content-type variants to keep the bare body on `error`.
  */
 export type DataOf<T> = T extends {
   contentType: string;
   data: infer TData;
 } ? TData : T;
 /**
- * The success variant for a single status, flattened so the negotiated `contentType` sits next to `data` and `switch (result.contentType)` narrows it.
+ * Keeps `contentType` beside `data` so switching on it narrows the body.
  */
 export type SuccessVariant<TStatus, TEntry, TRequest, TResponse> = TEntry extends {
   contentType: string;
@@ -50,7 +44,7 @@ export type SuccessVariant<TStatus, TEntry, TRequest, TResponse> = TEntry extend
   response: TResponse;
 };
 /**
- * One result variant for a single documented status, keyed by the numeric `status` so a `switch (result.status)` narrows `data` or `error`.
+ * Narrows `data` or `error` when switching on the numeric status.
  */
 export type ResultByStatus<TResponses, TStatus extends keyof TResponses, TRequest, TResponse> = TStatus extends SuccessStatusCode ? SuccessVariant<TStatus, TResponses[TStatus], TRequest, TResponse> : {
   status: ToStatusNumber<TStatus>;
@@ -60,16 +54,13 @@ export type ResultByStatus<TResponses, TStatus extends keyof TResponses, TReques
   request: TRequest;
   response: TResponse;
 };
-/**
- * The union of every documented status' result variant.
- */
 export type ResultUnion<TResponses, TRequest, TResponse> = { [TStatus in keyof TResponses]: ResultByStatus<TResponses, TStatus, TRequest, TResponse>; }[keyof TResponses];
 /**
- * The union of just the success (2xx) status variants, selected by status code so an untyped error payload can never widen `data`.
+ * Selects success statuses without letting untyped error payloads widen `data`.
  */
 export type SuccessResultUnion<TResponses, TRequest, TResponse> = { [TStatus in Extract<keyof TResponses, SuccessStatusCode>]: ResultByStatus<TResponses, TStatus, TRequest, TResponse>; }[Extract<keyof TResponses, SuccessStatusCode>];
 /**
- * The shape every generated function returns, discriminated by the top-level `status`, narrowing to the 2xx variants under `throwOnError` and to every documented status without it.
+ * Narrows `data` and `error` by status. With `throwOnError`, includes only success variants.
  */
 export type RequestResult<TResponses, ThrowOnError extends boolean = true, TRequest = AxiosRequestConfig, TResponse = AxiosResponse> = ThrowOnError extends true ? [SuccessResultUnion<TResponses, TRequest, TResponse>] extends [never] ? {
   status: number;
@@ -100,11 +91,15 @@ export type Unwrappable<T extends {
 /**
  * Attaches `unwrap()` to a result promise, which rejects with `error` when the result carried one.
  *
- * @example Full result
- * `const { data, error } = await getPetById({ path: { petId: 1 } })`
+ * @example
+ * ```ts
+ * const { data, error } = await getPetById({ path: { petId: 1 } })
+ * ```
  *
- * @example Success body only
- * `const pet = await getPetById({ path: { petId: 1 } }).unwrap()`
+ * @example
+ * ```ts
+ * const pet = await getPetById({ path: { petId: 1 } }).unwrap()
+ * ```
  */
 export declare function withUnwrap<T extends {
   data: unknown;
@@ -117,15 +112,11 @@ export declare function withUnwrap<T extends {
 export type UnwrappedResult<TResponses, ThrowOnError extends boolean = true, TRequest = AxiosRequestConfig, TResponse = AxiosResponse> = ThrowOnError extends true ? RequestResult<TResponses, true, TRequest, TResponse>['data'] : RequestResult<TResponses, ThrowOnError, TRequest, TResponse>;
 /**
  * Returns the success body when `throwOnError` is true, or the full result when it is false.
- * Backs generated operations with `returnType: 'data'`.
  */
 export declare function unwrapResult<T extends {
   data: unknown;
   error: unknown;
 }>(promise: Promise<T>, throwOnError: boolean | undefined): Promise<T | T['data']>;
-/**
- * The data-shaped keys of the grouped options object, which `Options` re-adds typed per operation.
- */
 export type DataShape = {
   body?: unknown;
   cookies?: unknown;
@@ -135,41 +126,33 @@ export type DataShape = {
 };
 export type ResponseType = 'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream' | 'formdata';
 /**
- * Turns a raw response body into a parsed value, registered per media type as a codec's `deserialize` to handle formats the runtime does not decode itself.
+ * Decodes a response body for a codec's media type.
  */
 export type Deserializer<T = unknown> = (raw: unknown, contentType: string) => T | Promise<T>;
 /**
- * Serializes a request body for a single media type, registered per content type as a codec's `serialize` to encode formats the default serializer does not handle.
+ * Encodes a request body for a codec's media type.
  */
 export type ContentBodySerializer = (body: unknown, contentType?: string) => unknown;
 /**
- * A per-content-type codec registered on `codecs`, keyed by content type. `serialize` encodes the
- * request body for that media type and `deserialize` decodes the response body. Either half is
- * optional, so a codec can handle one direction.
+ * Encodes requests or decodes responses for a media type. Either direction can be omitted.
  */
 export type Codec = {
   serialize?: ContentBodySerializer;
   deserialize?: Deserializer;
 };
 /**
- * The per-call content type selection, where a bare string sets the request content type and the object form also sets the response format sent as `Accept`.
+ * A string sets the request content type. The object form can also set `Accept`.
  */
 export type ContentType = string | {
   request?: string;
   response?: string;
 };
 /**
- * A Standard Schema validator (zod, valibot, arktype) that parses a value before it is sent or after
- * it is received. `runValidator` runs it through `validateStandardSchema`. Wired through the per-call
- * `validator.request` / `validator.response` / `validator.error` hooks (`error` runs on the error body when a
- * non-2xx call does not throw), and `validator.path` / `validator.query` / `validator.headers` for the
- * request params.
+ * Validates request bodies and params, success bodies, or non-throwing error bodies with Standard Schema.
  */
 export type Validator<T = unknown> = StandardSchemaValidator<T>;
 /**
- * The failing value and the call it came from, handed to `onValidationError` alongside the `ParseError`.
- * `direction` says which side rejected it: the request, the success body, or the error body. `source`
- * says which part of it: the body, or one of the request param groups.
+ * Identifies the value and request that failed validation in `onValidationError`.
  */
 export type ValidationErrorContext = {
   value: unknown;
@@ -180,9 +163,7 @@ export type ValidationErrorContext = {
   status?: number;
 };
 /**
- * Decides what a failed validation does. Returning nothing rethrows the `ParseError`; returning
- * `{ value }` resolves the call with that value instead, so a drifted body can be reported and still
- * delivered. The box keeps an explicit `{ value: undefined }` substitution distinct from declining.
+ * Return `{ value }` to substitute a failed value, including `undefined`. Returning nothing rethrows the `ParseError`.
  */
 export type ValidationErrorHandler = (error: ParseError, context: ValidationErrorContext) => {
   value: unknown;
@@ -200,7 +181,7 @@ export type Auth = {
   scopes?: Array<string>;
 };
 /**
- * The raw token a consumer returns for a scheme (or `user:password` for basic), or `undefined` to skip it.
+ * Return `user:password` for basic auth, or `undefined` to skip a scheme.
  */
 export type AuthToken = string | undefined;
 /**
@@ -211,9 +192,6 @@ export type AuthResolver = AuthToken | ((auth: Auth) => AuthToken | Promise<Auth
  * Extra axios config the runtime spreads onto every request, an escape hatch for per-call fields it does not set itself such as `timeout`, `proxy`, and the progress callbacks.
  */
 export type AxiosOptions = AxiosRequestConfig;
-/**
- * The request a generated function hands to the runtime, with `body` / `headers` / `path` / `query` from the grouped options.
- */
 export type RequestConfig<TBody = unknown, TRequest = AxiosRequestConfig, TResponse = AxiosResponse> = {
   baseURL?: string;
   url?: string;
@@ -248,8 +226,7 @@ export type RequestConfig<TBody = unknown, TRequest = AxiosRequestConfig, TRespo
   auth?: AuthResolver;
 };
 /**
- * The grouped options object passed to every generated function: the request config minus the
- * data-shaped keys and the literal `url`, plus the per-operation `<Name>Request`.
+ * Combines client options with the operation's typed request params and body.
  */
 export type Options<TData extends DataShape, ThrowOnError extends boolean = true, TRequest = AxiosRequestConfig, TResponse = AxiosResponse> = Omit<RequestConfig<unknown, TRequest, TResponse>, keyof DataShape | 'url'> & TData & {
   client?: ClientInstance<TRequest, TResponse>;
@@ -270,9 +247,6 @@ export type ClientConfig = {
   onValidationError?: ValidationErrorHandler;
   auth?: AuthResolver;
 };
-/**
- * The result a resolved call produces before it is cast to `RequestResult` by the generated wrapper.
- */
 export type CallResult<TRequest = AxiosRequestConfig, TResponse = AxiosResponse> = {
   status: number;
   data: unknown;
@@ -283,7 +257,7 @@ export type CallResult<TRequest = AxiosRequestConfig, TResponse = AxiosResponse>
 };
 export type InterceptorFn<T, TRequest = AxiosRequestConfig, TResponse = AxiosResponse> = (value: T, requestConfig?: RequestConfig<unknown, TRequest, TResponse>) => T | Promise<T>;
 /**
- * A single interceptor channel with a transport-agnostic `use` / `eject` / `update` API, backed by axios's native interceptor managers.
+ * Registers, removes, or replaces handlers on axios's native interceptor managers.
  */
 export type InterceptorChannel<T, TRequest = AxiosRequestConfig, TResponse = AxiosResponse> = {
   use: (fn: InterceptorFn<T, TRequest, TResponse>) => number;
@@ -291,7 +265,7 @@ export type InterceptorChannel<T, TRequest = AxiosRequestConfig, TResponse = Axi
   update: (id: number, fn: InterceptorFn<T, TRequest, TResponse>) => void;
 };
 /**
- * The three interceptor channels every client instance exposes, wrapping axios's native managers with `error` mapped onto the response rejection handler.
+ * Maps error interceptors to axios's response rejection handler.
  */
 export type Interceptors<TRequest = AxiosRequestConfig, TResponse = AxiosResponse> = {
   request: InterceptorChannel<InternalAxiosRequestConfig, TRequest, TResponse>;
@@ -347,7 +321,7 @@ export declare function resolveAuth(params: {
   query: Record<string, unknown>;
 }): Promise<void>;
 /**
- * Builds the shared client core bound to an axios instance (defaulting to `defaultTransport`, else `axios.create()`), with `throwOnError` riding axios's `validateStatus`.
+ * Uses the configured axios instance or creates one. `throwOnError` sets axios's default `validateStatus`.
  */
 export declare function createClientCore<TRequest = AxiosRequestConfig, TResponse = AxiosResponse>(options?: {
   defaultTransport?: AxiosInstance;
@@ -370,16 +344,14 @@ export type ServerSentEvent<TData = unknown> = {
  */
 export declare function parseEventStream<TData = unknown>(stream: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>): AsyncGenerator<ServerSentEvent<TData>>;
 /**
- * The resolved shape returned by a generated `text/event-stream` operation: the typed event
- * `stream` plus the native `response`.
+ * Returns parsed events alongside the native response.
  */
 export type EventStreamResult<TData = unknown, TResponse = AxiosResponse> = {
   stream: AsyncGenerator<ServerSentEvent<TData>>;
   response: TResponse;
 };
 /**
- * Wraps a transport result whose `data` is a streaming body into an `EventStreamResult`, exposing
- * the parsed events as a typed async iterator. Generated SSE operations call this.
+ * Exposes a streaming response body as typed Server-Sent Events.
  */
 export declare function toEventStream<TData = unknown>(result: Promise<{
   data: unknown;

package/docs/options.md

@@ -93,7 +93,7 @@ export default defineConfig({
 
 Only the params your OpenAPI spec declares are sent. Path and query keys the spec does not declare are stripped, so a key such as an undocumented filter or a cache-buster never reaches the URL. Declare it in the spec, or leave `params` off. Headers are the exception: client-level `headers` (such as `Authorization` or tracing headers) are merged with the call's headers before validation, so headers the spec does not declare pass through unchanged, and declared header params match in any casing.
 
-Pair `request` and `params` with `pluginZod({ inferred: 'direction' })` when the schemas use codecs, so the request types accept the domain values (such as a `Date`) that the validators encode. See [`inferred`](https://kubb.dev/extensions/kubb-labs/plugin-zod/options#inferred).
+Pair `request` and `params` with `pluginZod({ inferred: 'codec' })` when the schemas use codecs, so the request types accept the domain values (such as a `Date`) that the validators encode. See [`inferred`](https://kubb.dev/extensions/kubb-labs/plugin-zod/options#inferred).
 
 ### sdk
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-axios",
-  "version": "5.9.0",
+  "version": "5.9.2",
   "description": "Generate a slim, type-safe HTTP client with Kubb based on axios.",
   "keywords": [
     "api-client",
@@ -80,19 +80,19 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/plugin-ts": "^5.1.0",
-    "@kubb/plugin-zod": "^5.7.0"
+    "@kubb/plugin-ts": "^5.2.0",
+    "@kubb/plugin-zod": "^5.7.2"
   },
   "devDependencies": {
     "@internals/client": "0.0.0",
     "@internals/shared": "0.0.0",
     "axios": "^1.20.0",
-    "kubb": "^5.13.0",
+    "kubb": "^5.14.0",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
     "axios": "^1.20.0",
-    "kubb": "^5.13.0"
+    "kubb": "^5.14.0"
   },
   "peerDependenciesMeta": {
     "axios": {