@gcmdev/faxios 0.2.1 → 0.2.3

package/src/lib/faxios.ts

@@ -15,8 +15,8 @@ import formDataToJSON from "./helpers/formDataToJSON.js";
 import HttpStatusCode from "./helpers/HttpStatusCode.js";
 import isFaxiosError from "./helpers/isFaxiosError.js";
 import toFormData from "./helpers/toFormData.js";
+import type { CreateFaxiosDefaults, FaxiosDefaults, FaxiosHeaderValue, FaxiosMiddleware, FaxiosPluginArgument, FaxiosRequestConfig, FaxiosResponse, HeadersDefaults, Method, SchemaConfig, StringLiteralsOrString } from "./types.js";
 import type { StandardSchemaV1 } from "./types/standard-schema.js";
-import type { Method, StringLiteralsOrString, CreateFaxiosDefaults, FaxiosDefaults, FaxiosHeaderValue, FaxiosMiddleware, FaxiosPluginArgument, FaxiosRequestConfig, HeadersDefaults, FaxiosResponse, SchemaConfig } from "./types.js";
 import utils from "./utils.js";
 
 /**
@@ -91,11 +91,11 @@ type ProvidedCapabilities<TProv> = [TProv] extends [null | undefined] ? {} : TPr
 // use() reads capability names with Object.keys() and skips the keys that could pollute a prototype,
 // so the registry only holds string names. A symbol, number or dangerous key would be typed on
 // ctx.capabilities without matching a registered name, and nothing could satisfy a requirement for one.
-type UnsupportedCapabilityKeys<TCaps> = Extract<keyof TCaps, symbol | number | "__proto__" | "constructor" | "prototype">;
+type UnsupportedCapabilityKeys<TCaps> = Extract<keyof TCaps, "__proto__" | "constructor" | "prototype" | number | symbol>;
 
-type RejectUnsupportedCapabilityKeys<TReq, TProv> = [UnsupportedCapabilityKeys<TReq> | UnsupportedCapabilityKeys<TProv>] extends [never]
+type RejectUnsupportedCapabilityKeys<TReq, TProv> = [UnsupportedCapabilityKeys<TProv> | UnsupportedCapabilityKeys<TReq>] extends [never]
   ? unknown
-  : { "faxios: capability names must be strings other than __proto__, constructor and prototype": UnsupportedCapabilityKeys<TReq> | UnsupportedCapabilityKeys<TProv>; };
+  : { "faxios: capability names must be strings other than __proto__, constructor and prototype": UnsupportedCapabilityKeys<TProv> | UnsupportedCapabilityKeys<TReq>; };
 
 // Nothing sets a plugin option for the caller, so a required one would be typed as present in the
 // plugin's middleware while every request that omits it leaves it undefined.
@@ -130,23 +130,6 @@ type CheckPlugin<THave, TReq, TProv, TOpt> = RequireCapabilities<THave, TReq>
 // without narrowing first.
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- see above
 export type FaxiosInstance<TOpts = {}, TCaps = {}> = {
-  /**
-   * Register middleware or a plugin and return this instance, typed with the plugin's request
-   * options and capabilities added. A plugin whose required capabilities aren't installed yet, or
-   * that provides a capability another installed plugin already provides, is a type error.
-   */
-  use: <TReq = unknown, TProv = unknown, TOpt = unknown>(
-    middleware: FaxiosMiddleware<TOpts, TCaps> | (FaxiosPluginArgument<TReq, TProv, TOpt> & CheckPlugin<TCaps, TReq, TProv, TOpt>)
-  ) => FaxiosInstance<TOpts & TOpt, TCaps & ProvidedCapabilities<TProv>>;
-  /**
-   * Remove middleware or a plugin registered with use(), by reference. In-flight requests are
-   * unaffected. The instance type is not narrowed: request options and capabilities the ejected
-   * plugin added stay in its type.
-   */
-  // A method, so its parameter is checked bivariantly: middleware typed for this instance's
-  // options and capabilities is accepted.
-  // eslint-disable-next-line @typescript-eslint/method-signature-style -- see above
-  eject<TReq = unknown, TProv = unknown, TOpt = unknown>(middleware: FaxiosMiddleware<TOpt> | FaxiosPluginArgument<TReq, TProv, TOpt>): void;
   /**
    * Define a typed endpoint for `method` and `url` (with optional `{key}` placeholders). `config`
    * holds request defaults and the `pathParamsSchema`, `paramsSchema`, `requestSchema` and
@@ -165,6 +148,15 @@ export type FaxiosInstance<TOpts = {}, TCaps = {}> = {
     url: string,
     config?: DefineConfig<PP, P, D, R> & TOpts
   ) => DefinedEndpoint<PP, P, D, R, TOpts>;
+  /**
+   * Remove middleware or a plugin registered with use(), by reference. In-flight requests are
+   * unaffected. The instance type is not narrowed: request options and capabilities the ejected
+   * plugin added stay in its type.
+   */
+  // A method, so its parameter is checked bivariantly: middleware typed for this instance's
+  // options and capabilities is accepted.
+  // eslint-disable-next-line @typescript-eslint/method-signature-style -- see above
+  eject<TReq = unknown, TProv = unknown, TOpt = unknown>(middleware: FaxiosMiddleware<TOpt> | FaxiosPluginArgument<TReq, TProv, TOpt>): void;
   /**
    * Group endpoints that share `url` and `config`. Returns one endpoint factory per method (`get`,
    * `post`, `put`, `patch`, `delete`, `head`, `options`; no `query`), each taking `paramsSchema`,
@@ -176,22 +168,38 @@ export type FaxiosInstance<TOpts = {}, TCaps = {}> = {
     url: string,
     config?: RouteConfig<PP> & TOpts
   ) => RouteBuilder<PP, TOpts>;
+  /**
+   * Register middleware or a plugin and return this instance, typed with the plugin's request
+   * options and capabilities added. A plugin whose required capabilities aren't installed yet, or
+   * that provides a capability another installed plugin already provides, is a type error.
+   */
+  use: <TReq = unknown, TProv = unknown, TOpt = unknown>(
+    middleware: FaxiosMiddleware<TOpts, TCaps> | (FaxiosPluginArgument<TReq, TProv, TOpt> & CheckPlugin<TCaps, TReq, TProv, TOpt>)
+  ) => FaxiosInstance<TOpts & TOpt, TCaps & ProvidedCapabilities<TProv>>;
   <O, D = unknown>(config: SchemaConfig<O, D> & TOpts): Promise<FaxiosResponse<O, D>>;
   <O, D = unknown>(url: string, config: SchemaConfig<O, D> & TOpts): Promise<FaxiosResponse<O, D>>;
   <T = unknown, R = FaxiosResponse<T>, D = unknown>(config: FaxiosRequestConfig<D> & TOpts): Promise<R>;
   <T = unknown, R = FaxiosResponse<T>, D = unknown>(url: string, config?: FaxiosRequestConfig<D> & TOpts): Promise<R>;
-  request: {
-    <O, D = unknown>(config: SchemaConfig<O, D> & TOpts): Promise<FaxiosResponse<O, D>>;
-    <T = unknown, R = FaxiosResponse<T>, D = unknown>(config: FaxiosRequestConfig<D> & TOpts): Promise<R>;
-  };
-  get: {
+  create: (instanceConfig?: CreateFaxiosDefaults) => FaxiosInstance;
+  // `common` plus one header group per method; a key set directly on
+  // `headers` applies to every method.
+  defaults: Omit<FaxiosDefaults, "headers"> & {
+    headers: HeadersDefaults & { [key: string]: FaxiosHeaderValue | undefined; };
+  } & Partial<TOpts>;
+  delete: {
     <O, D = unknown>(url: string, config: SchemaConfig<O, D> & TOpts): Promise<FaxiosResponse<O, D>>;
     <T = unknown, R = FaxiosResponse<T>, D = unknown>(url: string, config?: FaxiosRequestConfig<D> & TOpts): Promise<R>;
   };
-  delete: {
+  get: {
     <O, D = unknown>(url: string, config: SchemaConfig<O, D> & TOpts): Promise<FaxiosResponse<O, D>>;
     <T = unknown, R = FaxiosResponse<T>, D = unknown>(url: string, config?: FaxiosRequestConfig<D> & TOpts): Promise<R>;
   };
+  /**
+   * Build the URL for `config` without sending a request. Applies `baseURL`, `params` and
+   * `paramsSerializer`, but does not substitute `pathParams` or run schemas, so `{key}`
+   * placeholders come back as written.
+   */
+  getUri: (config?: FaxiosRequestConfig & TOpts) => string;
   head: {
     <O, D = unknown>(url: string, config: SchemaConfig<O, D> & TOpts): Promise<FaxiosResponse<O, D>>;
     <T = unknown, R = FaxiosResponse<T>, D = unknown>(url: string, config?: FaxiosRequestConfig<D> & TOpts): Promise<R>;
@@ -200,23 +208,23 @@ export type FaxiosInstance<TOpts = {}, TCaps = {}> = {
     <O, D = unknown>(url: string, config: SchemaConfig<O, D> & TOpts): Promise<FaxiosResponse<O, D>>;
     <T = unknown, R = FaxiosResponse<T>, D = unknown>(url: string, config?: FaxiosRequestConfig<D> & TOpts): Promise<R>;
   };
-  post: {
+  patch: {
     <O, D = unknown>(url: string, data: D | undefined, config: SchemaConfig<O, D> & TOpts): Promise<FaxiosResponse<O, D>>;
     <T = unknown, R = FaxiosResponse<T>, D = unknown>(url: string, data?: D, config?: FaxiosRequestConfig<D> & TOpts): Promise<R>;
   };
-  put: {
+  patchForm: {
     <O, D = unknown>(url: string, data: D | undefined, config: SchemaConfig<O, D> & TOpts): Promise<FaxiosResponse<O, D>>;
     <T = unknown, R = FaxiosResponse<T>, D = unknown>(url: string, data?: D, config?: FaxiosRequestConfig<D> & TOpts): Promise<R>;
   };
-  patch: {
+  post: {
     <O, D = unknown>(url: string, data: D | undefined, config: SchemaConfig<O, D> & TOpts): Promise<FaxiosResponse<O, D>>;
     <T = unknown, R = FaxiosResponse<T>, D = unknown>(url: string, data?: D, config?: FaxiosRequestConfig<D> & TOpts): Promise<R>;
   };
-  query: {
+  postForm: {
     <O, D = unknown>(url: string, data: D | undefined, config: SchemaConfig<O, D> & TOpts): Promise<FaxiosResponse<O, D>>;
     <T = unknown, R = FaxiosResponse<T>, D = unknown>(url: string, data?: D, config?: FaxiosRequestConfig<D> & TOpts): Promise<R>;
   };
-  postForm: {
+  put: {
     <O, D = unknown>(url: string, data: D | undefined, config: SchemaConfig<O, D> & TOpts): Promise<FaxiosResponse<O, D>>;
     <T = unknown, R = FaxiosResponse<T>, D = unknown>(url: string, data?: D, config?: FaxiosRequestConfig<D> & TOpts): Promise<R>;
   };
@@ -224,41 +232,33 @@ export type FaxiosInstance<TOpts = {}, TCaps = {}> = {
     <O, D = unknown>(url: string, data: D | undefined, config: SchemaConfig<O, D> & TOpts): Promise<FaxiosResponse<O, D>>;
     <T = unknown, R = FaxiosResponse<T>, D = unknown>(url: string, data?: D, config?: FaxiosRequestConfig<D> & TOpts): Promise<R>;
   };
-  patchForm: {
+  query: {
     <O, D = unknown>(url: string, data: D | undefined, config: SchemaConfig<O, D> & TOpts): Promise<FaxiosResponse<O, D>>;
     <T = unknown, R = FaxiosResponse<T>, D = unknown>(url: string, data?: D, config?: FaxiosRequestConfig<D> & TOpts): Promise<R>;
   };
-  // `common` plus one header group per method; a key set directly on
-  // `headers` applies to every method.
-  defaults: Omit<FaxiosDefaults, "headers"> & {
-    headers: HeadersDefaults & { [key: string]: FaxiosHeaderValue | undefined; };
-  } & Partial<TOpts>;
-  /**
-   * Build the URL for `config` without sending a request. Applies `baseURL`, `params` and
-   * `paramsSerializer`, but does not substitute `pathParams` or run schemas, so `{key}`
-   * placeholders come back as written.
-   */
-  getUri: (config?: FaxiosRequestConfig & TOpts) => string;
-  create: (instanceConfig?: CreateFaxiosDefaults) => FaxiosInstance;
+  request: {
+    <O, D = unknown>(config: SchemaConfig<O, D> & TOpts): Promise<FaxiosResponse<O, D>>;
+    <T = unknown, R = FaxiosResponse<T>, D = unknown>(config: FaxiosRequestConfig<D> & TOpts): Promise<R>;
+  };
 };
 
 /** The default export: an instance plus the static helpers only it carries. */
 export type FaxiosStatic = FaxiosInstance & {
-  Faxios: typeof Faxios;
+  all: (promises: Array<Promise<unknown>>) => Promise<Array<unknown>>;
+  Cancel: typeof CanceledError;
   CanceledError: typeof CanceledError;
-  isCancel: typeof isCancel;
-  VERSION: typeof VERSION;
-  toFormData: typeof toFormData;
+  default: FaxiosStatic;
+  Faxios: typeof Faxios;
   FaxiosError: typeof FaxiosError;
-  Cancel: typeof CanceledError;
-  all: (promises: Array<Promise<unknown>>) => Promise<Array<unknown>>;
-  spread: (fn: (...args: Array<unknown>) => unknown) => (arr: Array<unknown>) => unknown;
-  isFaxiosError: typeof isFaxiosError;
-  mergeConfig: typeof mergeConfig;
   FaxiosHeaders: typeof FaxiosHeaders;
   formToJSON: (thing: unknown) => unknown;
   HttpStatusCode: typeof HttpStatusCode;
-  default: FaxiosStatic;
+  isCancel: typeof isCancel;
+  isFaxiosError: typeof isFaxiosError;
+  mergeConfig: typeof mergeConfig;
+  spread: (fn: (...args: Array<unknown>) => unknown) => (arr: Array<unknown>) => unknown;
+  toFormData: typeof toFormData;
+  VERSION: typeof VERSION;
 };
 
 // Create the default instance to be exported; the statics are attached below.

package/src/lib/helpers/HttpStatusCode.ts

@@ -71,7 +71,7 @@ const HttpStatusCode = {
 };
 
 Object.entries(HttpStatusCode).forEach(([ key, value ]) => {
-  (HttpStatusCode as Record<string | number, string | number>)[value] = key;
+  (HttpStatusCode as Record<number | string, number | string>)[value] = key;
 });
 
 export default HttpStatusCode;

package/src/lib/helpers/cloneConfig.ts

@@ -1,6 +1,5 @@
 import type { FaxiosRequestConfig } from "../types.js";
-
-export const DANGEROUS_KEYS = new Set([ "__proto__", "constructor", "prototype" ]);
+import utils from "../utils.js";
 
 // ponytail: null-proto shallow clone; replaces mergeConfig({}, config) which ran the full
 // two-config merge machinery just to get a defensive copy. Security invariants preserved:
@@ -15,7 +14,7 @@ export default function cloneConfig<T extends FaxiosRequestConfig>(src: T): T &
     enumerable: false,
   }));
   for (const key of Object.keys(src)) {
-    if (!DANGEROUS_KEYS.has(key)) {
+    if (!utils.isDangerousKey(key)) {
       (dst as Record<string, unknown>)[key] = (src as Record<string, unknown>)[key];
     }
   }

package/src/lib/helpers/composeSignals.ts

@@ -5,11 +5,11 @@ import utils from "../utils.js";
 type AbortHandler = (this: AbortSignal & { reason?: unknown; }, reason: unknown) => void;
 type EventListenerFn = (event: unknown) => void;
 type SignalLike = {
-  unsubscribe?: (() => void) | ((handler: AbortHandler) => void);
-  addEventListener: (type: string, listener: EventListenerFn) => void;
-  removeEventListener: (type: string, listener: EventListenerFn) => void;
   aborted: boolean;
+  addEventListener: (type: string, listener: EventListenerFn) => void;
   reason?: unknown;
+  removeEventListener: (type: string, listener: EventListenerFn) => void;
+  unsubscribe?: (() => void) | ((handler: AbortHandler) => void);
 };
 export type ExtendedAbortSignal = AbortSignal & { unsubscribe?: (() => void) | ((handler: AbortHandler) => void); };
 
@@ -35,7 +35,7 @@ const composeSignals = (signals: Array<unknown> | null | undefined, timeout?: nu
     }
   };
 
-  let timer: ReturnType<typeof setTimeout> | null =
+  let timer: null | ReturnType<typeof setTimeout> =
     timeout
       ? setTimeout(() => {
         timer = null;

package/src/lib/helpers/cookies.ts

@@ -2,9 +2,9 @@ import platform from "../platform.js";
 import utils from "../utils.js";
 
 type CookieManager = {
-  write: (name: string, value: string, expires?: number, path?: string, domain?: string, secure?: boolean, sameSite?: string) => void;
-  read: (name: string) => string | null;
+  read: (name: string) => null | string;
   remove: (name: string) => void;
+  write: (name: string, value: string, expires?: number, path?: string, domain?: string, secure?: boolean, sameSite?: string) => void;
 };
 
 const _globalThis = globalThis as { document?: { cookie?: string; }; };
@@ -36,7 +36,7 @@ export default platform.hasStandardBrowserEnv
       _globalThis.document.cookie = cookie.join("; ");
     },
 
-    read(name: string): string | null {
+    read(name: string): null | string {
       if (!_globalThis.document) return null;
       // Match name=value by splitting on the semicolon separator instead of building a
       // RegExp from `name` — interpolating an unescaped string into a RegExp would let

package/src/lib/helpers/formDataToJSON.ts

@@ -29,7 +29,7 @@ function parsePropPath(name: string): Array<string> {
   // foo x y z
   const path: Array<string> = [];
   const pattern = /\w+|\[(\w*)]/g;
-  let match: RegExpExecArray | null;
+  let match: null | RegExpExecArray;
 
   while ((match = pattern.exec(name)) !== null) {
     throwIfDepthExceeded(path.length);
@@ -66,13 +66,13 @@ function arrayToObject(arr: Array<unknown>): Record<string, unknown> {
  *
  * @returns {Object<string, any> | null} The converted object.
  */
-function formDataToJSON(formData: unknown): Record<string, unknown> | null {
+function formDataToJSON(formData: unknown): null | Record<string, unknown> {
   function buildPath(path: Array<string>, value: unknown, target: Record<string, unknown>, index: number): boolean {
     throwIfDepthExceeded(index);
 
-    let name: string | number = path[index++]!;
+    let name: number | string = path[index++]!;
 
-    if (name === "__proto__") return true;
+    if (utils.isDangerousKey(name)) return true;
 
     const isNumericKey = Number.isFinite(+name);
     const isLast = index >= path.length;

package/src/lib/helpers/parseHeaders.ts

@@ -38,8 +38,8 @@ const ignoreDuplicateOf = utils.toObjectSet([
  *
  * @returns {Object} Headers parsed into an object
  */
-export default (rawHeaders: string): Record<string, string | Array<string>> => {
-  const parsed: Record<string, string | Array<string>> = {};
+export default (rawHeaders: string): Record<string, Array<string> | string> => {
+  const parsed: Record<string, Array<string> | string> = {};
   let key: string;
   let val: string;
   let i: number;

package/src/lib/helpers/progressEventReducer.ts

@@ -11,7 +11,7 @@ export const progressEventReducer = (listener: (data: FaxiosProgressEvent) => vo
     if (!e || typeof (e as Record<string, unknown>).loaded !== "number") {
       return;
     }
-    const ev = e as { loaded: number; total?: number; lengthComputable?: boolean; };
+    const ev = e as { lengthComputable?: boolean; loaded: number; total?: number; };
     const rawLoaded = ev.loaded;
     const total = ev.lengthComputable ? ev.total : undefined;
     const loaded = total != null ? Math.min(rawLoaded, total) : rawLoaded;
@@ -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.
+        }
+      });

package/src/lib/helpers/sanitizeHeaderValue.ts

@@ -36,7 +36,7 @@ const INVALID_UNICODE_HEADER_VALUE_CHARS = new RegExp("[\\u0000-\\u0008\\u000a-\
 const INVALID_BYTE_STRING_HEADER_VALUE_CHARS = new RegExp("[^\\u0009\\u0020-\\u007e\\u0080-\\u00ff]+", "g");
 
 // eslint-disable-next-line sonarjs/function-return-type
-function sanitizeValue(value: unknown, invalidChars: RegExp): string | Array<string> {
+function sanitizeValue(value: unknown, invalidChars: RegExp): Array<string> | string {
   if (utils.isArray(value)) {
     return (value as Array<unknown>).map(item => sanitizeValue(item, invalidChars) as string);
   }

package/src/lib/helpers/substitutePathParams.ts

@@ -1,13 +1,23 @@
+import FaxiosError from "../core/FaxiosError.js";
+
+// `.` and `..` (raw or percent-encoded) would become a dot segment that the URL parser resolves,
+// moving the request to another path.
+const DOT_SEGMENT = /^(?:\.|%2e){1,2}$/i;
+
 /** Expects raw (unencoded) param values — applies encodeURIComponent here. */
 export function substitutePathParams(url: string, params: Record<string, unknown>): string {
   return url.replace(/\{([^{}]+)\}/g, (_match, key: string) => {
     if (!Object.prototype.hasOwnProperty.call(params, key)) {
-      throw new Error(`Path param "${key}" not found in pathParams`);
+      throw new FaxiosError(`Path param "${key}" not found in pathParams`, FaxiosError.ERR_BAD_OPTION_VALUE);
     }
     const val = params[key];
     if (val == null) {
-      throw new Error(`Path param "${key}" is null or undefined`);
+      throw new FaxiosError(`Path param "${key}" is null or undefined`, FaxiosError.ERR_BAD_OPTION_VALUE);
     }
-    return encodeURIComponent(String(val));
+    const str = String(val);
+    if (DOT_SEGMENT.test(str)) {
+      throw new FaxiosError(`Path param "${key}" must not be "." or ".." (or a percent-encoded form)`, FaxiosError.ERR_BAD_OPTION_VALUE);
+    }
+    return encodeURIComponent(str);
   });
 }

package/src/lib/helpers/throttle.ts

@@ -8,7 +8,7 @@ function throttle(fn: (...args: Array<unknown>) => void, freq: number): [(...arg
   let timestamp = 0;
   const threshold = 1000 / freq;
   let lastArgs: Array<unknown> | null = null;
-  let timer: ReturnType<typeof setTimeout> | null = null;
+  let timer: null | ReturnType<typeof setTimeout> = null;
 
   const invoke = (args: Array<unknown>, now: number = Date.now()) => {
     timestamp = now;

package/src/lib/helpers/toFormData.ts

@@ -2,7 +2,7 @@
 
 import FaxiosError from "../core/FaxiosError.js";
 // temporary hotfix to avoid circular references until FaxiosURLSearchParams is refactored
-import type { GenericFormData, SerializerVisitor, FormDataVisitorHelpers } from "../types.js";
+import type { FormDataVisitorHelpers, GenericFormData, SerializerVisitor } from "../types.js";
 import utils from "../utils.js";
 
 // Default nesting limit shared with the inverse transform (formDataToJSON) so
@@ -40,11 +40,11 @@ function removeBrackets(key: string): string {
  *
  * @returns {string} The path to the current key.
  */
-function renderKey(path: Array<string | number> | null | undefined, key: string | number, dots: unknown): string {
+function renderKey(path: Array<number | string> | null | undefined, key: number | string, dots: unknown): string {
   if (!path) return String(key);
   return path
     .concat(key)
-    .map(function each(token: string | number, i: number) {
+    .map(function each(token: number | string, i: number) {
       token = removeBrackets(String(token));
       return !dots && i ? "[" + token + "]" : token;
     })
@@ -91,7 +91,7 @@ const predicates = utils.toFlatObject(utils, {}, null as unknown as false, funct
  */
 function toFormData(obj: unknown, formData?: GenericFormData | null, options?: Record<string, unknown>): GenericFormData {
   if (!utils.isObject(obj)) {
-    throw new TypeError("target must be an object");
+    throw new FaxiosError("target must be an object", FaxiosError.ERR_BAD_REQUEST);
   }
 
   const FormDataCtor = (globalThis as Record<string, unknown>)["FormData"] as (new () => GenericFormData) | undefined;
@@ -100,13 +100,15 @@ function toFormData(obj: unknown, formData?: GenericFormData | null, options?: R
     formData = new FormDataCtor();
   }
 
+  // Null-prototype destination: `visitor`, `maxDepth` and `Blob` are read below, and a polluted
+  // Object.prototype must not supply them.
   options = utils.toFlatObject(
     options,
-    {
+    Object.assign(Object.create(null) as Record<string, unknown>, {
       metaTokens: true,
       dots: false,
       indexes: false,
-    },
+    }),
     false,
     function defined(option: string, source: unknown) {
       return !utils.isUndefined((source as Record<string, unknown>)[option]);
@@ -118,16 +120,16 @@ function toFormData(obj: unknown, formData?: GenericFormData | null, options?: R
   const visitor = (options["visitor"] || defaultVisitor) as SerializerVisitor;
   const dots = options["dots"];
   const indexes = options["indexes"];
-  const _Blob = options["Blob"] || (typeof (globalThis as Record<string, unknown>)["Blob"] !== "undefined" && (globalThis as Record<string, unknown>)["Blob"]);
+  const _Blob = (options["Blob"] || (globalThis as Record<string, unknown>)["Blob"]) as (new (parts: Array<unknown>) => unknown) | undefined;
   const maxDepth =
     options["maxDepth"] === undefined
       ? DEFAULT_FORM_DATA_MAX_DEPTH
       : (options["maxDepth"] as number);
-  const useBlob = _Blob && utils.isSpecCompliantForm(formData);
+  const useBlob = typeof _Blob === "function" && utils.isSpecCompliantForm(formData);
   const stack: Array<unknown> = [];
 
   if (!utils.isFunction(visitor)) {
-    throw new TypeError("visitor must be a function");
+    throw new FaxiosError("visitor must be a function", FaxiosError.ERR_BAD_OPTION_VALUE);
   }
 
   function convertValue(value: unknown): unknown {
@@ -141,16 +143,15 @@ function toFormData(obj: unknown, formData?: GenericFormData | null, options?: R
       return String(value);
     }
 
-    if (!useBlob && utils.isBlob(value)) {
-      throw new FaxiosError("Blob is not supported. Use a Buffer instead.");
+    if (!useBlob && (utils.isBlob(value) || utils.isArrayBuffer(value) || utils.isTypedArray(value))) {
+      throw new FaxiosError(
+        "Binary FormData values need a spec-compliant FormData and a Blob constructor (set the `Blob` option)",
+        FaxiosError.ERR_NOT_SUPPORT
+      );
     }
 
     if (utils.isArrayBuffer(value) || utils.isTypedArray(value)) {
-      const BlobCtor = (globalThis as Record<string, unknown>)["Blob"] as (new (parts: Array<unknown>) => unknown) | undefined;
-      if (useBlob && typeof BlobCtor === "function") {
-        return new BlobCtor([ value ]);
-      }
-      throw new FaxiosError("Blob is required for binary FormData values in this environment", FaxiosError.ERR_NOT_SUPPORT);
+      return new (_Blob as new (parts: Array<unknown>) => unknown)([ value ]);
     }
 
     return value;
@@ -201,7 +202,7 @@ function toFormData(obj: unknown, formData?: GenericFormData | null, options?: R
    *
    * @returns {boolean} return true to visit the each prop of the value recursively
    */
-  function defaultVisitor(this: GenericFormData, value: unknown, key: string | number, path: null | Array<string | number>, _helpers?: FormDataVisitorHelpers): boolean {
+  function defaultVisitor(this: GenericFormData, value: unknown, key: number | string, path: Array<number | string> | null, _helpers?: FormDataVisitorHelpers): boolean {
     let arr: unknown = value;
 
     if (utils.isReactNative(formData) && utils.isReactNativeBlob(value)) {
@@ -248,19 +249,20 @@ function toFormData(obj: unknown, formData?: GenericFormData | null, options?: R
     return false;
   }
 
-  const exposedHelpers: FormDataVisitorHelpers = Object.assign(predicates, {
-    defaultVisitor: defaultVisitor,
+  const exposedHelpers: FormDataVisitorHelpers = {
+    ...predicates,
+    defaultVisitor,
     convertValue,
     isVisitable,
-  });
+  };
 
-  function build(value: unknown, path?: Array<string | number>, depth = 0): void {
+  function build(value: unknown, path?: Array<number | string>, depth = 0): void {
     if (utils.isUndefined(value)) return;
 
     throwIfMaxDepthExceeded(depth);
 
     if (stack.indexOf(value) !== -1) {
-      throw new Error("Circular reference detected in " + (path ?? []).join("."));
+      throw new FaxiosError("Circular reference detected in " + (path ?? []).join("."), FaxiosError.ERR_BAD_REQUEST);
     }
 
     stack.push(value);
@@ -271,23 +273,19 @@ function toFormData(obj: unknown, formData?: GenericFormData | null, options?: R
         visitor.call(
           formData as GenericFormData,
           el,
-          utils.isString(key) ? (key as string).trim() : key as string | number,
+          utils.isString(key) ? (key as string).trim() : key as number | string,
           path ?? null,
           exposedHelpers
         );
 
       if (result === true) {
-        build(el, path ? path.concat(key as string | number) : [ key as string | number ], depth + 1);
+        build(el, path ? path.concat(key as number | string) : [ key as number | string ], depth + 1);
       }
     });
 
     stack.pop();
   }
 
-  if (!utils.isObject(obj)) {
-    throw new TypeError("data must be an object");
-  }
-
   build(obj);
 
   return formData;

package/src/lib/helpers/trackStream.ts

@@ -1,11 +1,14 @@
+import FaxiosError from "../core/FaxiosError.js";
+import utils from "../utils.js";
+
 type ReadableStreamController = {
-  enqueue: (chunk: Uint8Array) => void;
   close: () => void;
+  enqueue: (chunk: Uint8Array) => void;
 };
 
 type ReadableStreamSource = {
-  pull?: (controller: ReadableStreamController) => Promise<void>;
   cancel?: (reason?: unknown) => Promise<unknown>;
+  pull?: (controller: ReadableStreamController) => Promise<void>;
 };
 
 type ReadableStreamInit = {
@@ -16,9 +19,31 @@ type ReadableStreamCtor = new (source: ReadableStreamSource, init?: ReadableStre
 
 const ReadableStreamGlobal = (globalThis as Record<string, unknown>)["ReadableStream"] as ReadableStreamCtor | undefined;
 
-type ByteChunk = { byteLength: number; slice: (start: number, end?: number) => ByteChunk; };
+const textEncoder = typeof TextEncoder === "function" ? new TextEncoder() : undefined;
+
+// View the chunk's bytes without copying them. Strings are UTF-8 encoded; anything else is not
+// a byte chunk and is rejected rather than silently converted.
+const toBytes = (chunk: unknown): Uint8Array => {
+  if (chunk instanceof Uint8Array) {
+    return chunk;
+  }
+  if (utils.isArrayBufferView(chunk)) {
+    const view = chunk as ArrayBufferView;
+    return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+  }
+  if (utils.isArrayBuffer(chunk)) {
+    return new Uint8Array(chunk as ArrayBuffer);
+  }
+  if (utils.isString(chunk) && textEncoder) {
+    return textEncoder.encode(chunk as string);
+  }
+  throw new FaxiosError(
+    "Stream chunk must be a Uint8Array, another ArrayBufferView, an ArrayBuffer or a string, got " + utils.kindOf(chunk),
+    FaxiosError.ERR_BAD_REQUEST
+  );
+};
 
-const streamChunk = function* (chunk: ByteChunk, chunkSize?: number): Generator<ByteChunk> {
+const streamChunk = function* (chunk: Uint8Array, chunkSize?: number): Generator<Uint8Array> {
   const len = chunk.byteLength;
 
   if (!chunkSize || len < chunkSize) {
@@ -31,31 +56,31 @@ const streamChunk = function* (chunk: ByteChunk, chunkSize?: number): Generator<
 
   while (pos < len) {
     end = pos + chunkSize;
-    yield chunk.slice(pos, end);
+    yield chunk.subarray(pos, end);
     pos = end;
   }
 };
 
-const readBytes = async function* (iterable: AsyncIterable<ByteChunk> | unknown, chunkSize?: number): AsyncGenerator<ByteChunk> {
+const readBytes = async function* (iterable: unknown, chunkSize?: number): AsyncGenerator<Uint8Array> {
   for await (const chunk of readStream(iterable)) {
-    yield* streamChunk(chunk, chunkSize);
+    yield* streamChunk(toBytes(chunk), chunkSize);
   }
 };
 
 type ReaderLike = {
-  read: () => Promise<{ done: boolean; value: ByteChunk; }>;
   cancel: () => Promise<void>;
+  read: () => Promise<{ done: boolean; value: unknown; }>;
 };
 
 type StreamLike = {
-  [Symbol.asyncIterator]?: () => AsyncIterator<ByteChunk>;
+  [Symbol.asyncIterator]?: () => AsyncIterator<unknown>;
   getReader?: () => ReaderLike;
 };
 
-const readStream = async function* (stream: unknown): AsyncGenerator<ByteChunk> {
+const readStream = async function* (stream: unknown): AsyncGenerator<unknown> {
   const s = stream as StreamLike;
   if (s[Symbol.asyncIterator]) {
-    yield* s as AsyncIterable<ByteChunk>;
+    yield* s as AsyncIterable<unknown>;
     return;
   }
 
@@ -104,9 +129,12 @@ export const trackStream = (stream: unknown, chunkSize: number | undefined, onPr
             const loadedBytes = (bytes += len);
             onProgress(loadedBytes);
           }
-          controller.enqueue(new Uint8Array(value as unknown as ArrayBuffer));
+          controller.enqueue(value);
         }
         catch (err) {
+          // Cancel the source so its lock and connection are released. The original error wins
+          // over a failure to cancel.
+          await iterator.return(undefined).catch(() => {});
           _onFinish(err);
           throw err;
         }