@gcmdev/faxios 0.2.2 → 0.2.3

package/skills/configure-requests/SKILL.md

@@ -202,6 +202,9 @@ catch (error) {
   schema step and right before `fetch`, so an abort during pre-flight work sends nothing.
 - A timeout always rejects with `ETIMEDOUT`. `ECONNABORTED` is never raised, and
   `transitional.clarifyTimeoutError` has no effect.
+- With `responseType: "stream"`, `timeout` and `signal` stay active until the body is fully
+  read or cancelled. Reading a stalled body rejects with `ETIMEDOUT` or `ERR_CANCELED`.
+  Cancel a body you don't read so the timer and signal listener are released.
 
 ### Handle errors by code
 
@@ -356,9 +359,9 @@ export only. Instances from `create()` do not have them; import them by name ins
    `faxios.plugins` is undefined. Import from `@gcmdev/faxios/plugins/<name>`.
 7. **MEDIUM: Calling statics on an instance.** `api.isCancel(e)` is undefined on a `create()`
    instance. Use the named import.
-8. **MEDIUM: Expecting `onUploadProgress` everywhere.** It fires only where `fetch` can stream a
-   request body (`duplex: "half"`, for example Node). Browsers generally do not report upload
-   progress through fetch; do not promise it there.
+8. **MEDIUM: Expecting `onUploadProgress` everywhere.** It fires only where faxios can stream
+   the request body (Node; not Deno or Bun). In browsers and web workers faxios never streams the
+   body for progress, so the callback is not called; do not promise it there. Source: `src/lib/adapters/fetch.ts` (`isBrowserRuntime`).
 9. **MEDIUM: Retrying POST by accident or by assumption.** The retry plugin skips POST and PATCH
    unless they are listed in `methods`; a custom `retryOn` cannot override that.
 10. **MEDIUM: Downloading a binary body without `responseType`.** The bytes are decoded as UTF-8

package/skills/configure-requests/references/axios-differences.md

@@ -23,7 +23,7 @@ behaviour outside this list as unverified until the installed types and a test p
 | `proxy: {...}` / `httpAgent` / `httpsAgent` | Runtime-level proxy config. In Node the project docs pass an `undici` `ProxyAgent` as `fetchOptions.dispatcher`, using the app's own `undici` dependency | Not faxios options; faxios passes the dispatcher to `fetch` but does not test proxying |
 | `maxRedirects`, `beforeRedirect` | fetch follows redirects; `fetchOptions: { redirect: "manual" }` to stop | `ERR_FR_TOO_MANY_REDIRECTS` is never raised |
 | `maxRate`, `socketPath`, `decompress`, `insecureHTTPParser`, `httpVersion`, HTTP/2 options, `lookup`, `family` | none | Removed; ignored at runtime when untyped |
-| `onUploadProgress` | same option | Fires only where fetch streams request bodies (Node); not a browser guarantee |
+| `onUploadProgress` | same option | Fires only where fetch streams request bodies (Node); never called in browsers or web workers |
 | `responseType: "document"` | none in practice | Falls back to text |
 | retry via `axios-retry` | `retry()` from `@gcmdev/faxios/plugins/retry` | POST/PATCH excluded by default |
 | auth header interceptor | `authBearer()` from `@gcmdev/faxios/plugins/auth-bearer` | Sends only to the baseURL origin by default |

package/src/lib/adapters/fetch.ts

@@ -81,10 +81,12 @@ const rejectUsedStreamBody = (data: unknown, config: InternalFaxiosRequestConfig
   if (isWebStream) sentStreamBodies.add(body);
 };
 
+const isBrowserRuntime = platform.hasStandardBrowserEnv || platform.hasStandardBrowserWebWorkerEnv;
+
 // Server runtimes default User-Agent to their own (e.g. "node"), so name faxios there.
 // Browsers send their own User-Agent; setting one makes every cross-origin request
 // need a CORS preflight that most APIs don't allow.
-const setsUserAgent = !platform.hasStandardBrowserEnv && !platform.hasStandardBrowserWebWorkerEnv;
+const setsUserAgent = !isBrowserRuntime;
 const applyDefaultUserAgent = (headers: FaxiosRequestHeaders): void => {
   if (setsUserAgent) headers.set("User-Agent", "faxios/" + VERSION, false);
 };
@@ -171,8 +173,16 @@ type FetchEnv = {
   Response?: unknown;
 };
 
-// eslint-disable-next-line sonarjs/function-return-type
-const factory = (env: FetchEnv) => {
+type FetchAdapter = (config: InternalFaxiosRequestConfig) => Promise<unknown>;
+
+// Own reads only: a polluted Object.prototype.fetch must never become the transport.
+const readOwn = (obj: unknown, key: string): unknown =>
+  typeof obj === "object" && obj !== null && utils.hasOwnProp(obj, key) ? Reflect.get(obj, key) : undefined;
+const ownEnv = (config: unknown, key: keyof FetchEnv): unknown => readOwn(readOwn(config, "env"), key);
+
+// Feature detection depends only on the Request and Response constructors, so one adapter
+// serves every `env.fetch`. `env.fetch` is read for each request.
+const factory = (env: Omit<FetchEnv, "fetch">): FetchAdapter => {
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
   const globalObject: Record<string, unknown> = utils.global ?? globalThis;
   const ReadableStream = globalObject["ReadableStream"] as
@@ -183,22 +193,11 @@ const factory = (env: FetchEnv) => {
     | undefined;
 
   // `undefined` falls back to the global constructor; `null` disables it.
-  const envFetch = env.fetch as FetchFn | undefined;
   const Request = (env.Request === undefined ? globalObject["Request"] : env.Request) as AnyConstructor | undefined;
   const Response = (env.Response === undefined ? globalObject["Response"] : env.Response) as AnyConstructor | undefined;
-  const _globalFetch = (globalThis as unknown as Record<string, unknown>)[
-    "fetch"
-  ];
-  const isFetchSupported = envFetch
-    ? isFunction(envFetch)
-    : isFunction(_globalFetch);
   const isRequestSupported = isFunction(Request);
   const isResponseSupported = isFunction(Response);
 
-  if (!isFetchSupported) {
-    return false;
-  }
-
   // Only members this runtime's Request exposes, so an engine that rejects members it doesn't
   // implement (Cloudflare Workers) is never sent one.
   const requestInitDefaults = Object.entries(REQUEST_INIT_DEFAULTS).filter(([ key ]) =>
@@ -209,7 +208,7 @@ const factory = (env: FetchEnv) => {
   // .mode or undici .dispatcher apply to every request. Every own enumerable key of fetchOptions
   // is copied, so runtime extensions (Next.js `next`, Workers `cf`, Bun `tls`) still pass through;
   // inherited keys never do. The caller sets signal, method, headers, body, duplex, credentials.
-  const initFromFetchOptions = (fetchOptions: unknown): Record<string, unknown> => {
+  const initFromFetchOptions = (fetchOptions: unknown, envFetch: FetchFn | undefined): Record<string, unknown> => {
     const init: Record<string, unknown> = Object.create(null);
     for (const [ key, value ] of requestInitDefaults) init[key] = value;
     // Node's global fetch reads `dispatcher` the same way; pin it to undici's own global one.
@@ -278,6 +277,13 @@ const factory = (env: FetchEnv) => {
       return duplexAccessed && !hasContentType;
     });
 
+  // Outside browsers a FormData body under maxBodyLength is streamed and counted as fetch reads it;
+  // browsers can't send a stream body (see buildUploadStream).
+  const countsFormDataWhileSent = !isBrowserRuntime && supportsRequestStream;
+  // Bodies counted as fetch reads them when maxBodyLength is set.
+  const isCountedWhileSent = (body: unknown): boolean =>
+    utils.isReadableStream!(body) || utils.isStream(body) || (countsFormDataWhileSent && utils.isSpecCompliantForm(body));
+
   const supportsResponseStream =
     isResponseSupported &&
     isReadableStreamSupported &&
@@ -294,26 +300,22 @@ const factory = (env: FetchEnv) => {
     stream: supportsResponseStream && ((res: AnyResponse) => res.body),
   };
 
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-  isFetchSupported &&
-    (() => {
-      [ "text", "arrayBuffer", "blob", "formData", "stream" ].forEach(type => {
-        !resolvers[type] &&
-          (resolvers[type] = (res: AnyResponse, config?: unknown) => {
-            const method = (res as Record<string, unknown>)[type];
-
-            if (method) {
-              return (method as (this: AnyResponse) => unknown).call(res);
-            }
-
-            throw new FaxiosError(
-              `Response type '${type}' is not supported`,
-              FaxiosError.ERR_NOT_SUPPORT,
-              config as InternalFaxiosRequestConfig
-            );
-          });
+  [ "text", "arrayBuffer", "blob", "formData", "stream" ].forEach(type => {
+    !resolvers[type] &&
+      (resolvers[type] = (res: AnyResponse, config?: unknown) => {
+        const method = (res as Record<string, unknown>)[type];
+
+        if (method) {
+          return (method as (this: AnyResponse) => unknown).call(res);
+        }
+
+        throw new FaxiosError(
+          `Response type '${type}' is not supported`,
+          FaxiosError.ERR_NOT_SUPPORT,
+          config as InternalFaxiosRequestConfig
+        );
       });
-    })();
+  });
 
   const getBodyLength = async (body: unknown): Promise<number | undefined> => {
     if (body == null) {
@@ -324,14 +326,6 @@ const factory = (env: FetchEnv) => {
       return (body as { size: number; }).size;
     }
 
-    if (utils.isSpecCompliantForm(body)) {
-      const _request = new (Request as AnyConstructor)(platform.origin, {
-        method: "POST",
-        body,
-      }) as AnyRequest;
-      return (await _request.arrayBuffer()).byteLength;
-    }
-
     if (utils.isArrayBufferView(body) || utils.isArrayBuffer(body)) {
       return (body as ArrayBuffer | ArrayBufferView).byteLength;
     }
@@ -346,6 +340,23 @@ const factory = (env: FetchEnv) => {
     return undefined;
   };
 
+  // The bytes of a FormData body's field values and files, from their sizes, without reading the
+  // body. A lower bound: the multipart body adds boundaries and part headers. Undefined for any
+  // other body.
+  const getFormDataFieldsLength = async (body: unknown): Promise<number | undefined> => {
+    if (!utils.isSpecCompliantForm(body)) {
+      return undefined;
+    }
+    let length = 0;
+    for (const [ , value ] of body as Iterable<[string, unknown]>) {
+      // A FormData value is a string or a File.
+      const size = utils.isString(value) ? undefined : utils.getSafeProp(value, "size");
+      // eslint-disable-next-line no-await-in-loop
+      length += typeof size === "number" ? size : (await encodeText(String(value))).byteLength;
+    }
+    return length;
+  };
+
   const resolveBodyLength = async (
     headers: FaxiosRequestHeaders,
     body: unknown
@@ -436,10 +447,13 @@ const factory = (env: FetchEnv) => {
     }
     // Enforce maxBodyLength against known-size bodies before dispatch using
     // the body's actual size — never a caller-declared Content-Length.
+    // A FormData body isn't measured, since that buffers it whole: its values alone over the limit
+    // reject it here, and where it's streamed the byte counter covers the multipart framing too.
     if (hasMaxBodyLength && method !== "get" && method !== "head") {
       const outboundLength = await getBodyLength(data);
-      if (typeof outboundLength === "number" && isFinite(outboundLength)) {
-        if (outboundLength > maxBodyLength) {
+      const checkedLength = outboundLength ?? await getFormDataFieldsLength(data);
+      if (typeof checkedLength === "number" && isFinite(checkedLength)) {
+        if (checkedLength > maxBodyLength) {
           throw new FaxiosError(
             "Request body larger than maxBodyLength limit",
             FaxiosError.ERR_BAD_REQUEST,
@@ -501,6 +515,10 @@ const factory = (env: FetchEnv) => {
     request: unknown,
     pendingBodyErrorRef: PendingBodyErrorRef
   ): Promise<{ data: unknown; requestContentLength: number | undefined; }> => {
+    // Browsers can't be given a stream body for upload progress: Chromium sends one only over
+    // HTTP/2 or later and WebKit not at all, so the upload would fail. onUploadProgress isn't
+    // called there (#209).
+    const uploadProgress = isBrowserRuntime ? undefined : onUploadProgress;
     const _makeBodyLengthError = () =>
       new FaxiosError(
         "Request body larger than maxBodyLength limit",
@@ -524,14 +542,21 @@ const factory = (env: FetchEnv) => {
           }
           onProgress && onProgress(loadedBytes);
         },
-        flush
+        (err?: unknown) => {
+          // A chunk trackStream rejected (not bytes) surfaces as the coded error, not ERR_NETWORK.
+          if (err instanceof FaxiosError && !pendingBodyErrorRef.value) {
+            err.config = config;
+            pendingBodyErrorRef.value = err;
+          }
+          flush && flush();
+        }
       );
 
     if (
       supportsRequestStream &&
       method !== "get" &&
       method !== "head" &&
-      (onUploadProgress || mustEnforceStreamBody)
+      (uploadProgress || mustEnforceStreamBody)
     ) {
       requestContentLength =
         requestContentLength == null
@@ -546,7 +571,7 @@ const factory = (env: FetchEnv) => {
           body: data,
           duplex: "half",
         }) as AnyRequest;
-        data = applyUploadProgress(_request, data, headers, requestContentLength, onUploadProgress, _trackStream);
+        data = applyUploadProgress(_request, data, headers, requestContentLength, uploadProgress, _trackStream);
       }
     }
     else if (
@@ -584,11 +609,11 @@ const factory = (env: FetchEnv) => {
     hasMaxContentLength: boolean,
     maxContentLength: number,
     isStreamResponse: boolean,
-    unsubscribe: (() => void) | false | undefined,
+    release: (err?: unknown) => void,
     config: InternalFaxiosRequestConfig,
     request: unknown
   ): AnyResponse => {
-    const needsWrapping = onDownloadProgress || hasMaxContentLength || (isStreamResponse && unsubscribe);
+    const needsWrapping = !!onDownloadProgress || hasMaxContentLength || isStreamResponse;
     if (!supportsResponseStream || !response.body || !needsWrapping) {
       return response;
     }
@@ -598,9 +623,15 @@ const factory = (env: FetchEnv) => {
       options[prop] = response[prop];
     });
 
-    const responseContentLength = utils.toFiniteNumber(
-      (responseHeaders.getContentLength as () => unknown)()
-    );
+    // Content-Length is the encoded size; the stream yields decoded bytes, so
+    // the total is unknown when the body is content-encoded.
+    const contentEncoding = String(responseHeaders.get("content-encoding") ?? "").trim()
+      .toLowerCase();
+    const responseContentLength = contentEncoding && contentEncoding !== "identity"
+      ? undefined
+      : utils.toFiniteNumber(
+        (responseHeaders.getContentLength as () => unknown)()
+      );
 
     const [ onProgress, flush ] = onDownloadProgress
       ? progressEventDecorator(
@@ -635,17 +666,18 @@ const factory = (env: FetchEnv) => {
         response.body,
         DEFAULT_CHUNK_SIZE,
         onChunkProgress,
-        () => {
+        (err?: unknown) => {
           flush && flush();
-          unsubscribe && unsubscribe();
+          release(err);
         }
       ),
       options
     ) as AnyResponse;
   };
 
-  const unsubscribeOnComplete = (isStreamResponse: boolean, unsubscribe: (() => void) | undefined) => {
-    if (!isStreamResponse) unsubscribe?.();
+  // A stream body releases the request when it ends; a response without a body has nothing to wait for.
+  const unsubscribeOnComplete = (isStreamResponse: boolean, response: AnyResponse, unsubscribe: () => void) => {
+    if (!isStreamResponse || response.body == null) unsubscribe();
   };
 
   return async (config: InternalFaxiosRequestConfig) => {
@@ -680,6 +712,7 @@ const factory = (env: FetchEnv) => {
         ? (config as unknown as Record<string, unknown>)[key]
         : undefined;
 
+    const envFetch = ownEnv(config, "fetch") as FetchFn | undefined;
     const _fetch: FetchFn = (envFetch || (globalThis as unknown as Record<string, unknown>)["fetch"]) as FetchFn;
 
     if (timeout != null && !Number.isFinite(Number(timeout))) {
@@ -694,13 +727,16 @@ const factory = (env: FetchEnv) => {
       responseType ? (responseType + "").toLowerCase() : "text"
     ) as typeof responseType;
 
+    // Owns the request's cleanup: aborting it on a failure aborts fetch, which releases the
+    // connection and any body still being sent or received.
+    const requestController = new AbortController();
     const composedSignal = composeSignals(
-      [ signal ],
+      [ signal, requestController.signal ],
       timeout,
       timeoutErrorMessage
-    ) as ComposedSignal | undefined;
+    ) as ComposedSignal;
 
-    const unsubscribe = composedSignal?.unsubscribe?.bind(composedSignal);
+    const unsubscribe = composedSignal.unsubscribe!.bind(composedSignal);
 
     let request: null | Request = null;
     const pendingBodyErrorRef: PendingBodyErrorRef = { value: null };
@@ -724,8 +760,7 @@ const factory = (env: FetchEnv) => {
 
       // A streamed body under maxBodyLength must be counted as fetch consumes
       // it; its size is never trusted from a caller-declared Content-Length.
-      const isStreamLike = utils.isReadableStream!(data) || utils.isStream(data);
-      const mustEnforceStreamBody = hasMaxBodyLength && isStreamLike;
+      const mustEnforceStreamBody = hasMaxBodyLength && isCountedWhileSent(data);
 
       ({ data } = await buildUploadStream(
         data,
@@ -762,7 +797,7 @@ const factory = (env: FetchEnv) => {
       // Case-insensitive check: toByteStringHeaderObject may normalize to lowercase.
       data = toWebStream(await encodeBodyIfNeeded(data, serializedHeaders, encodeText));
 
-      const resolvedOptions = initFromFetchOptions(fetchOptions);
+      const resolvedOptions = initFromFetchOptions(fetchOptions, envFetch);
       resolvedOptions["signal"] = composedSignal;
       resolvedOptions["method"] = (method as string).toUpperCase();
       resolvedOptions["headers"] = serializedHeaders;
@@ -788,6 +823,14 @@ const factory = (env: FetchEnv) => {
         supportsResponseStream &&
         (responseType === "stream" || responseType === "response");
 
+      // A stream body outlives this call, so its end, error or cancel releases the request.
+      // A buffered body is released below, or by the catch on failure.
+      const releaseStreamBody = (bodyErr?: unknown): void => {
+        if (!isStreamResponse) return;
+        if (bodyErr !== undefined) requestController.abort(bodyErr);
+        unsubscribe();
+      };
+
       response = buildDownloadStream(
         response,
         responseHeaders,
@@ -795,7 +838,7 @@ const factory = (env: FetchEnv) => {
         hasMaxContentLength,
         maxContentLength!,
         isStreamResponse,
-        unsubscribe,
+        releaseStreamBody,
         config,
         request
       );
@@ -816,12 +859,12 @@ const factory = (env: FetchEnv) => {
         request
       );
 
-      unsubscribeOnComplete(isStreamResponse, unsubscribe);
+      unsubscribeOnComplete(isStreamResponse, response, unsubscribe);
 
       return await new Promise((resolve, reject) => {
         settle(resolve, reject, {
           data: responseData,
-          headers: FaxiosHeaders.from(response.headers),
+          headers: responseHeaders,
           status: response.status,
           statusText: response.statusText,
           config,
@@ -830,42 +873,57 @@ const factory = (env: FetchEnv) => {
       });
     }
     catch (err) {
-      unsubscribe && unsubscribe();
-      throw handleFetchCaughtError(err, composedSignal, pendingBodyErrorRef, config, request);
+      let error: unknown = err;
+      try {
+        handleFetchCaughtError(err, composedSignal, pendingBodyErrorRef, config, request);
+      }
+      catch (classified) {
+        error = classified;
+      }
+      // Classify first: the abort below sets the composed signal's reason.
+      requestController.abort(error);
+      unsubscribe();
+      throw error;
     }
   };
 };
 
-const seedCache = new Map<unknown, unknown>();
-
-export const getFetch = (config?: { env?: Record<string, unknown>; }) => {
-  // Own reads only: a polluted Object.prototype.fetch must never become the transport.
-  const env = config && utils.hasOwnProp(config, "env") ? config.env : undefined;
-  const own = (key: keyof FetchEnv): unknown => (env && utils.hasOwnProp(env, key) ? env[key] : undefined);
-  const fetch = own("fetch");
-  const Request = own("Request");
-  const Response = own("Response");
-  const seeds: Array<unknown> = [ Request, Response, fetch ];
-
-  const len = seeds.length;
-  let i = len;
-  let seed: unknown;
-  let target: unknown;
-  let map: Map<unknown, unknown> = seedCache;
-
-  while (i--) {
-    seed = seeds[i];
-    target = map.get(seed);
-
-    if (target === undefined) {
-      target = i ? new Map<unknown, unknown>() : factory({ fetch, Request, Response });
-      map.set(seed, target);
-    }
+// One adapter per Request/Response pair. Weak keys let a per-request `env.Request` or
+// `env.Response` be collected. `undefined` (use the global) and any non-function (disabled)
+// get stand-in keys.
+const GLOBAL_CTOR = {};
+const NO_CTOR = {};
+const adapters = new WeakMap<object, WeakMap<object, FetchAdapter>>();
 
-    map = target as Map<unknown, unknown>;
+const ctorKey = (ctor: unknown): object => {
+  if (ctor === undefined) return GLOBAL_CTOR;
+  return isFunction(ctor) ? (ctor as object) : NO_CTOR;
+};
+
+// `false` tells dispatchRequest that this runtime has no fetch.
+// eslint-disable-next-line sonarjs/function-return-type
+export const getFetch = (config?: { env?: Record<string, unknown>; }): false | FetchAdapter => {
+  const fetch = ownEnv(config, "fetch");
+  if (!isFunction(fetch || (globalThis as unknown as Record<string, unknown>)["fetch"])) {
+    return false;
   }
 
-  return target;
+  const Request = ownEnv(config, "Request");
+  const Response = ownEnv(config, "Response");
+  const requestKey = ctorKey(Request);
+  const responseKey = ctorKey(Response);
+
+  let byResponse = adapters.get(requestKey);
+  if (!byResponse) {
+    byResponse = new WeakMap();
+    adapters.set(requestKey, byResponse);
+  }
+  let adapter = byResponse.get(responseKey);
+  if (!adapter) {
+    adapter = factory({ Request, Response });
+    byResponse.set(responseKey, adapter);
+  }
+  return adapter;
 };
 
 getFetch();

package/src/lib/core/FaxiosHeaders.ts

@@ -28,6 +28,25 @@ function normalizeHeader(header: string): string {
     .toLowerCase();
 }
 
+// Per instance: lowercased own key -> own key. Callers may also write and delete headers as plain
+// properties, so an entry is only trusted while its key is still own, and a miss rebuilds the index.
+const keyIndexes = new WeakMap<object, Map<string, string>>();
+
+function indexKeys(headers: object): Map<string, string> {
+  const index = new Map<string, string>();
+  // Later keys overwrite earlier ones, matching utils.findKey, which scans from the end.
+  for (const key of Object.keys(headers)) {
+    index.set(key.toLowerCase(), key);
+  }
+  keyIndexes.set(headers, index);
+  return index;
+}
+
+function findHeaderKey(headers: object, lHeader: string): string | undefined {
+  const key = keyIndexes.get(headers)?.get(lHeader);
+  return key !== undefined && utils.hasOwnProp(headers, key) ? key : indexKeys(headers).get(lHeader);
+}
+
 // eslint-disable-next-line sonarjs/function-return-type
 function normalizeValue(
   value: FaxiosHeaderValue | undefined
@@ -187,6 +206,9 @@ class FaxiosHeaders {
     rewrite?: boolean
   ): this {
     const self = this;
+    // Set once a lookup misses, which rebuilds the index from the own keys. Only setHeader writes
+    // to self until this call returns, so from then on the index is complete and a miss is final.
+    let index: Map<string, string> | undefined;
 
     function setHeader(
       _value: unknown,
@@ -199,7 +221,11 @@ class FaxiosHeaders {
         return;
       }
 
-      const key = utils.findKey(self, lHeader) as string | undefined;
+      const key = index ? index.get(lHeader) : findHeaderKey(self, lHeader);
+      if (key === undefined) {
+        index ??= keyIndexes.get(self)!;
+        index.set(String(_header).toLowerCase(), _header);
+      }
 
       if (
         !key ||
@@ -260,7 +286,7 @@ class FaxiosHeaders {
     header = normalizeHeader(header);
 
     if (header) {
-      const key = utils.findKey(this, header) as string | undefined;
+      const key = findHeaderKey(this, header);
 
       if (key) {
         const value = (this as Record<string, unknown>)[
@@ -299,7 +325,7 @@ class FaxiosHeaders {
     header = normalizeHeader(header);
 
     if (header) {
-      const key = utils.findKey(this, header) as string | undefined;
+      const key = findHeaderKey(this, header);
 
       return !!(
         key &&
@@ -325,7 +351,7 @@ class FaxiosHeaders {
       _header = normalizeHeader(_header);
 
       if (_header) {
-        const key = utils.findKey(self, _header) as string | undefined;
+        const key = findHeaderKey(self, _header);
 
         if (
           key &&
@@ -381,11 +407,12 @@ class FaxiosHeaders {
 
   normalize(format: boolean = false): this {
     const self = this;
-    const headers: Record<string, unknown> = {};
+    // Lowercased normalized name -> normalized name, for names already kept.
+    const kept = new Map<string, string>();
 
     utils.forEach(this, (value: unknown, _header: unknown) => {
       const header = _header as string;
-      const key = utils.findKey(headers, header) as string | undefined;
+      const key = kept.get(header.toLowerCase());
 
       if (key) {
         (self as Record<string, unknown>)[key] = normalizeValue(
@@ -405,7 +432,7 @@ class FaxiosHeaders {
         value as FaxiosHeaderValue
       );
 
-      headers[normalized] = true;
+      kept.set(normalized.toLowerCase(), normalized);
     });
 
     return this;

package/src/lib/core/dispatchRequest.ts

@@ -104,7 +104,12 @@ export default async function dispatchRequest(this: unknown, config: InternalFax
 
   config.data = transformData.call(config, config.transformRequest);
 
-  if (config.data != null && !utils.isFormData(config.data) && [ "post", "put", "patch" ].indexOf(config.method as string) !== -1) {
+  const data: unknown = config.data;
+  // Binary and stream bodies keep their own type: fetch uses `Blob.type` or sends none.
+  const isBinaryOrStream = utils.isBlob(data) || utils.isFile(data) || utils.isArrayBuffer(data) || utils.isArrayBufferView(data) ||
+    utils.isReadableStream?.(data) || utils.isStream(data) ||
+    (typeof data === "object" && data !== null && Symbol.asyncIterator in data);
+  if (data != null && !utils.isFormData(data) && !isBinaryOrStream && [ "post", "put", "patch" ].indexOf(config.method as string) !== -1) {
     (config.headers as unknown as { setContentType: (v: string, r: boolean) => void; }).setContentType("application/x-www-form-urlencoded", false);
   }
 

package/src/lib/env/data.ts

@@ -1 +1 @@
-export const VERSION = "0.2.2";
+export const VERSION = "0.2.3";

package/src/lib/helpers/progressEventReducer.ts

@@ -51,7 +51,20 @@ export const progressEventDecorator = (total: number | undefined, throttled: Ret
   ];
 };
 
+// Progress listeners are caller code: any error they throw (or a promise they
+// reject) is caught and ignored so it can't become an uncaught exception or
+// change how the request settles.
 export const asyncDecorator =
   (fn: (...args: Array<unknown>) => unknown) =>
     (...args: Array<unknown>) =>
-      utils.asap(() => fn(...args));
+      utils.asap(() => {
+        try {
+          const result = fn(...args);
+          if (utils.isThenable(result)) {
+            (result as PromiseLike<unknown>).then(undefined, () => {});
+          }
+        }
+        catch {
+          // Ignored by design: see the onUploadProgress/onDownloadProgress docs.
+        }
+      });