From 25387ae1cedb93b385029e759cac9a22b71ec498 Mon Sep 17 00:00:00 2001
From: Jay <jasonsaayman@gmail.com>
Date: Mon, 27 Apr 2026 14:33:31 +0200
Subject: [PATCH] chore: added clarifying docs for the type change (#10804)

---
 index.d.cts | 25 +++++++++++++++++++++++++
 index.d.ts  | 25 +++++++++++++++++++++++++
 2 files changed, 50 insertions(+)

diff --git a/index.d.cts b/index.d.cts
index be5c214f..55227f8d 100644
--- a/index.d.cts
+++ b/index.d.cts
@@ -320,10 +320,35 @@ declare namespace axios {
 
   type AxiosResponseHeaders = RawAxiosResponseHeaders & AxiosHeaders;
 
+  /**
+   * `transformRequest` is invoked as a left-fold pipeline: each function's return
+   * value becomes the next function's `data` argument (see `lib/core/transformData.js`).
+   *
+   * The `D` generic describes the type of `data` entering the *first* transformer
+   * in the chain. Subsequent transformers in an array — and any user transformer
+   * that runs after axios's default `transformRequest` (which serializes objects
+   * to JSON, FormData, URLSearchParams, etc.) — may receive a serialized form
+   * (`string`, `Buffer`, `ArrayBuffer`, `FormData`, `URLSearchParams`,
+   * `Stream`, ...) rather than `D`. The final transformer in the chain is
+   * expected to return one of those serialized forms.
+   *
+   * For best results, type `D` only when supplying a single transformer that
+   * runs first, or accept that intermediate stages may need a runtime check.
+   */
   interface AxiosRequestTransformer<D = any> {
     (this: InternalAxiosRequestConfig<D>, data: D, headers: AxiosRequestHeaders): any;
   }
 
+  /**
+   * `transformResponse` is invoked as a left-fold pipeline: each function's
+   * return value becomes the next function's `data` argument.
+   *
+   * The `T` generic describes the type of `data` entering the *first* transformer
+   * in the chain — typically the raw response body (`string`, `ArrayBuffer`,
+   * `Buffer`, or `Stream` depending on `responseType`). Later transformers
+   * receive whatever the previous stage returned, so `T` is only accurate for
+   * the first call.
+   */
   interface AxiosResponseTransformer<T = any> {
     (
       this: InternalAxiosRequestConfig,
diff --git a/index.d.ts b/index.d.ts
index 151d8615..e059b32c 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -138,10 +138,35 @@ export type RawAxiosResponseHeaders = Partial<RawAxiosHeaders & RawCommonRespons
 
 export type AxiosResponseHeaders = RawAxiosResponseHeaders & AxiosHeaders;
 
+/**
+ * `transformRequest` is invoked as a left-fold pipeline: each function's return
+ * value becomes the next function's `data` argument (see `lib/core/transformData.js`).
+ *
+ * The `D` generic describes the type of `data` entering the *first* transformer
+ * in the chain. Subsequent transformers in an array — and any user transformer
+ * that runs after axios's default `transformRequest` (which serializes objects
+ * to JSON, FormData, URLSearchParams, etc.) — may receive a serialized form
+ * (`string`, `Buffer`, `ArrayBuffer`, `FormData`, `URLSearchParams`,
+ * `Stream`, ...) rather than `D`. The final transformer in the chain is
+ * expected to return one of those serialized forms.
+ *
+ * For best results, type `D` only when supplying a single transformer that
+ * runs first, or accept that intermediate stages may need a runtime check.
+ */
 export interface AxiosRequestTransformer<D = any> {
   (this: InternalAxiosRequestConfig<D>, data: D, headers: AxiosRequestHeaders): any;
 }
 
+/**
+ * `transformResponse` is invoked as a left-fold pipeline: each function's
+ * return value becomes the next function's `data` argument.
+ *
+ * The `T` generic describes the type of `data` entering the *first* transformer
+ * in the chain — typically the raw response body (`string`, `ArrayBuffer`,
+ * `Buffer`, or `Stream` depending on `responseType`). Later transformers
+ * receive whatever the previous stage returned, so `T` is only accurate for
+ * the first call.
+ */
 export interface AxiosResponseTransformer<T = any> {
   (
     this: InternalAxiosRequestConfig,