@gcmdev/faxios 0.1.0 → 0.2.1

package/src/lib/helpers/buildURL.ts

@@ -0,0 +1,77 @@
+"use strict";
+
+import type { ParamEncoder } from "../types.js";
+import utils from "../utils.js";
+import FaxiosURLSearchParams from "./FaxiosURLSearchParams.js";
+
+/**
+ * It replaces URL-encoded forms of `:`, `$`, `,`, and spaces with
+ * their plain counterparts (`:`, `$`, `,`, `+`).
+ *
+ * @param {string} val The value to be encoded.
+ *
+ * @returns {string} The encoded value.
+ */
+export function encode(val: string): string {
+  return encodeURIComponent(val)
+    .replace(/%3A/gi, ":")
+    .replace(/%24/g, "$")
+    .replace(/%2C/gi, ",")
+    .replace(/%20/g, "+");
+}
+
+// The request path validates `paramsSerializer.encode` as a function; this
+// guard narrows the untyped option to ParamEncoder without asserting it.
+function isParamEncoder(value: unknown): value is ParamEncoder {
+  return typeof value === "function";
+}
+
+/**
+ * Build a URL by appending params to the end
+ *
+ * @param {string} url The base of the url (e.g., http://www.google.com)
+ * @param {object} [params] The params to be appended
+ * @param {?(object|Function)} options
+ *
+ * @returns {string} The formatted url
+ */
+export default function buildURL(url: string, params?: unknown, options?: unknown): string {
+  if (!params) {
+    return url;
+  }
+
+  const _options = utils.isFunction(options)
+    ? {
+      serialize: options,
+    }
+    : options;
+
+  // Read serializer options pollution-safely: own properties and methods on a
+  // class/template prototype are honored, but values injected onto a polluted
+  // Object.prototype are ignored.
+  const customEncode = utils.getSafeProp(_options, "encode");
+  const _encode: ParamEncoder = isParamEncoder(customEncode) ? customEncode : encode;
+  const serializeFn = utils.getSafeProp(_options, "serialize") as ((params: unknown, options: unknown) => string) | undefined;
+
+  let serializedParams: string | undefined;
+
+  if (serializeFn) {
+    serializedParams = serializeFn(params, _options);
+  }
+  else {
+    serializedParams = utils.isURLSearchParams(params)
+      ? (params as { toString: () => string; }).toString()
+      : new FaxiosURLSearchParams(params, _options).toString(_encode);
+  }
+
+  if (serializedParams) {
+    const hashmarkIndex = url.indexOf("#");
+
+    if (hashmarkIndex !== -1) {
+      url = url.slice(0, hashmarkIndex);
+    }
+    url += (url.indexOf("?") === -1 ? "?" : "&") + serializedParams;
+  }
+
+  return url;
+}

package/src/lib/helpers/cloneConfig.ts

@@ -0,0 +1,23 @@
+import type { FaxiosRequestConfig } from "../types.js";
+
+export const DANGEROUS_KEYS = new Set([ "__proto__", "constructor", "prototype" ]);
+
+// 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:
+// null-proto so fetch.ts destructuring can't inherit Object.prototype gadgets, and
+// dangerous keys filtered to block prototype-pollution write paths.
+export default function cloneConfig<T extends FaxiosRequestConfig>(src: T): T & Record<string, unknown> {
+  const dst = Object.create(null) as T & Record<string, unknown>;
+  Object.defineProperty(dst, "hasOwnProperty", Object.assign(Object.create(null) as PropertyDescriptor, {
+    value: Object.prototype.hasOwnProperty,
+    writable: true,
+    configurable: true,
+    enumerable: false,
+  }));
+  for (const key of Object.keys(src)) {
+    if (!DANGEROUS_KEYS.has(key)) {
+      (dst as Record<string, unknown>)[key] = (src as Record<string, unknown>)[key];
+    }
+  }
+  return dst;
+}

package/src/lib/helpers/combineURLs.ts

@@ -0,0 +1,11 @@
+"use strict";
+
+export default function combineURLs(baseURL: string, relativeURL?: string): string {
+  if (!relativeURL) return baseURL;
+  // Scan indices, slice once — no regex (ReDoS risk on 100k-slash inputs in browser engines)
+  let i = baseURL.length - 1;
+  while (i >= 0 && baseURL.charCodeAt(i) === 47) i--;
+  let j = 0;
+  while (j < relativeURL.length && relativeURL.charCodeAt(j) === 47) j++;
+  return baseURL.slice(0, i + 1) + "/" + relativeURL.slice(j);
+}

package/src/lib/helpers/composeSignals.ts

@@ -0,0 +1,74 @@
+import CanceledError from "../cancel/CanceledError.js";
+import FaxiosError from "../core/FaxiosError.js";
+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;
+  reason?: unknown;
+};
+export type ExtendedAbortSignal = AbortSignal & { unsubscribe?: (() => void) | ((handler: AbortHandler) => void); };
+
+const composeSignals = (signals: Array<unknown> | null | undefined, timeout?: number, timeoutMessage?: string): ExtendedAbortSignal | undefined => {
+  let activeSignals: Array<SignalLike> | null = signals ? (signals.filter(Boolean) as Array<SignalLike>) : [];
+
+  if (!timeout && !activeSignals.length) {
+    return;
+  }
+
+  const controller = new AbortController();
+
+  let aborted = false;
+
+  const onabort: AbortHandler = function (this: AbortSignal & { reason?: unknown; }, reason: unknown) {
+    if (!aborted) {
+      aborted = true;
+      unsubscribe();
+      const err = reason instanceof Error ? reason : this.reason;
+      const errMsg = err instanceof Error ? err.message : (err as string | undefined);
+      const abortErr = err instanceof FaxiosError ? err : new CanceledError(errMsg, undefined, undefined);
+      controller.abort(abortErr);
+    }
+  };
+
+  let timer: ReturnType<typeof setTimeout> | null =
+    timeout
+      ? setTimeout(() => {
+        timer = null;
+        onabort.call(controller.signal, new FaxiosError(timeoutMessage || `timeout of ${timeout}ms exceeded`, FaxiosError.ETIMEDOUT));
+      }, timeout)
+      : null;
+
+  const unsubscribe = () => {
+    if (!activeSignals) { return; }
+    if (timer) { clearTimeout(timer); }
+    timer = null;
+    activeSignals.forEach(signal => {
+      signal.unsubscribe
+        ? (signal.unsubscribe)(onabort)
+        : signal.removeEventListener("abort", onabort);
+    });
+    activeSignals = null;
+  };
+
+  // An already-aborted input never fires "abort" again, so propagate it now.
+  for (const signal of activeSignals) {
+    if (signal.aborted) {
+      onabort.call(signal as unknown as AbortSignal, signal.reason);
+      break;
+    }
+    signal.addEventListener("abort", onabort);
+  }
+
+  const { signal } = controller;
+
+  (signal as ExtendedAbortSignal).unsubscribe = () => utils.asap(unsubscribe);
+
+  return signal;
+};
+
+export default composeSignals;

package/src/lib/helpers/cookies.ts

@@ -0,0 +1,68 @@
+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;
+  remove: (name: string) => void;
+};
+
+const _globalThis = globalThis as { document?: { cookie?: string; }; };
+
+export default platform.hasStandardBrowserEnv
+  ? // Standard browser envs support document.cookie
+  {
+    write(name: string, value: string, expires?: number, path?: string, domain?: string, secure?: boolean, sameSite?: string) {
+      if (!_globalThis.document) return;
+
+      const cookie = [ `${name}=${encodeURIComponent(value)}` ];
+
+      if (utils.isNumber(expires)) {
+        cookie.push(`expires=${new Date(expires!).toUTCString()}`);
+      }
+      if (utils.isString(path)) {
+        cookie.push(`path=${path}`);
+      }
+      if (utils.isString(domain)) {
+        cookie.push(`domain=${domain}`);
+      }
+      if (secure === true) {
+        cookie.push("secure");
+      }
+      if (utils.isString(sameSite)) {
+        cookie.push(`SameSite=${sameSite}`);
+      }
+
+      _globalThis.document.cookie = cookie.join("; ");
+    },
+
+    read(name: string): string | null {
+      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
+      // metacharacters (e.g. `.+?` in an attacker-influenced cookie name) cause ReDoS or
+      // match the wrong cookie. Browsers may serialize cookie pairs as either ";" or
+      // "; ", so ignore optional whitespace before each cookie name.
+      const cookies = (_globalThis.document.cookie ?? "").split(";");
+      for (let i = 0; i < cookies.length; i++) {
+        const cookie = cookies[i]!.replace(/^\s+/, "");
+        const eq = cookie.indexOf("=");
+        if (eq !== -1 && cookie.slice(0, eq) === name) {
+          return decodeURIComponent(cookie.slice(eq + 1));
+        }
+      }
+      return null;
+    },
+
+    remove(name: string) {
+      this.write(name, "", Date.now() - 86400000, "/");
+    },
+  } satisfies CookieManager
+  : // Non-standard browser env (web workers, react-native) lack needed support.
+  {
+    write() {},
+    read(): null {
+      return null;
+    },
+    remove() {},
+  } satisfies CookieManager;

package/src/lib/helpers/deprecatedMethod.ts

@@ -0,0 +1,32 @@
+"use strict";
+
+/*eslint no-console:0*/
+
+/**
+ * Supply a warning to the developer that a method they are using
+ * has been deprecated.
+ *
+ * @param {string} method The name of the deprecated method
+ * @param {string} [instead] The alternate method to use if applicable
+ * @param {string} [docs] The documentation URL to get further details
+ *
+ * @returns {void}
+ */
+export default function deprecatedMethod(method: string, instead?: string, docs?: string) {
+  try {
+    console.warn(
+      "DEPRECATED method `" +
+        method +
+        "`." +
+        (instead ? " Use `" + instead + "` instead." : "") +
+        " This method will be removed in a future release."
+    );
+
+    if (docs) {
+      console.warn("For more information about usage see " + docs);
+    }
+  }
+  catch {
+    /* Ignore */
+  }
+}

package/src/lib/helpers/estimateDataURLDecodedBytes.ts

@@ -0,0 +1,95 @@
+/**
+ * Estimate decoded byte length of a data:// URL *without* allocating large buffers.
+ * - For base64: compute exact decoded size using length and padding;
+ *               handle %XX at the character-count level (no string allocation).
+ * - For non-base64: compute the exact percent-decoded UTF-8 byte length.
+ *
+ * @param {string} url
+ * @returns {number}
+ */
+const isHexDigit = (charCode: number) =>
+  (charCode >= 48 && charCode <= 57) ||
+  (charCode >= 65 && charCode <= 70) ||
+  (charCode >= 97 && charCode <= 102);
+
+const isPercentEncodedByte = (str: string, i: number, len: number) =>
+  i + 2 < len &&
+  isHexDigit(str.charCodeAt(i + 1)) &&
+  isHexDigit(str.charCodeAt(i + 2));
+
+function countBase64Padding(body: string, len: number): number {
+  let pad = 0;
+  let i = len;
+  while (pad < 2 && i > 0) {
+    if (body.charCodeAt(i - 1) === 61 /* '=' */) {
+      pad++;
+      i--;
+    }
+    else if (i >= 3 && body.charCodeAt(i - 3) === 37 /* '%' */ && body.charCodeAt(i - 2) === 51 /* '3' */ &&
+               (body.charCodeAt(i - 1) === 68 || body.charCodeAt(i - 1) === 100) /* 'D'|'d' */) {
+      pad++;
+      i -= 3;
+    }
+    else {
+      break;
+    }
+  }
+  return pad;
+}
+
+function estimateBase64DecodedBytes(body: string): number {
+  let effectiveLen = body.length;
+  const len = body.length;
+
+  for (let i = 0; i < len; i++) {
+    if (body.charCodeAt(i) === 37 /* '%' */ && i + 2 < len) {
+      const a = body.charCodeAt(i + 1);
+      const b = body.charCodeAt(i + 2);
+      if (isHexDigit(a) && isHexDigit(b)) {
+        effectiveLen -= 2;
+        i += 2;
+      }
+    }
+  }
+
+  const pad = countBase64Padding(body, len);
+  const bytes = Math.floor(effectiveLen / 4) * 3 - pad;
+  return bytes > 0 ? bytes : 0;
+}
+
+// Returns [utf8Bytes, extraCharsToSkip]
+function utf8CharBytes(body: string, i: number, len: number): [number, number] {
+  const c = body.charCodeAt(i);
+  if (c === 37 /* '%' */ && isPercentEncodedByte(body, i, len)) return [ 1, 2 ];
+  if (c < 0x80) return [ 1, 0 ];
+  if (c < 0x800) return [ 2, 0 ];
+  if (c >= 0xd800 && c <= 0xdbff && i + 1 < len) {
+    const next = body.charCodeAt(i + 1);
+    if (next >= 0xdc00 && next <= 0xdfff) return [ 4, 1 ];
+  }
+  return [ 3, 0 ];
+}
+
+// Compute UTF-8 byte length directly from UTF-16 code units without allocating
+// a byte buffer (TextEncoder.encode would defeat the DoS guard on large bodies).
+function estimateUtf8BodyBytes(body: string): number {
+  let bytes = 0;
+  for (let i = 0, len = body.length; i < len; i++) {
+    const [ b, skip ] = utf8CharBytes(body, i, len);
+    bytes += b;
+    i += skip;
+  }
+  return bytes;
+}
+
+export default function estimateDataURLDecodedBytes(url: string): number {
+  if (!url || typeof url !== "string") return 0;
+  if (!url.startsWith("data:")) return 0;
+
+  const comma = url.indexOf(",");
+  if (comma < 0) return 0;
+
+  const meta = url.slice(5, comma);
+  const body = url.slice(comma + 1);
+  return /;base64/i.test(meta) ? estimateBase64DecodedBytes(body) : estimateUtf8BodyBytes(body);
+}

package/src/lib/helpers/formDataToJSON.ts

@@ -0,0 +1,122 @@
+"use strict";
+
+import FaxiosError from "../core/FaxiosError.js";
+import utils from "../utils.js";
+import { DEFAULT_FORM_DATA_MAX_DEPTH } from "./toFormData.js";
+
+const MAX_DEPTH = DEFAULT_FORM_DATA_MAX_DEPTH;
+
+function throwIfDepthExceeded(index: number): void {
+  if (index > MAX_DEPTH) {
+    throw new FaxiosError(
+      "FormData field is too deeply nested (" + index + " levels). Max depth: " + MAX_DEPTH,
+      FaxiosError.ERR_FORM_DATA_DEPTH_EXCEEDED
+    );
+  }
+}
+
+/**
+ * It takes a string like `foo[x][y][z]` and returns an array like `['foo', 'x', 'y', 'z']
+ *
+ * @param {string} name - The name of the property to get.
+ *
+ * @returns An array of strings.
+ */
+function parsePropPath(name: string): Array<string> {
+  // foo[x][y][z]
+  // foo.x.y.z
+  // foo-x-y-z
+  // foo x y z
+  const path: Array<string> = [];
+  const pattern = /\w+|\[(\w*)]/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = pattern.exec(name)) !== null) {
+    throwIfDepthExceeded(path.length);
+    path.push(match[0] === "[]" ? "" : (match[1] ?? match[0]));
+  }
+
+  return path;
+}
+
+/**
+ * Convert an array to an object.
+ *
+ * @param {Array<any>} arr - The array to convert to an object.
+ *
+ * @returns An object with the same keys and values as the array.
+ */
+function arrayToObject(arr: Array<unknown>): Record<string, unknown> {
+  const obj: Record<string, unknown> = {};
+  const keys = Object.keys(arr);
+  let i: number;
+  const len = keys.length;
+  let key: string;
+  for (i = 0; i < len; i++) {
+    key = keys[i]!;
+    obj[key] = (arr as unknown as Record<string, unknown>)[key];
+  }
+  return obj;
+}
+
+/**
+ * It takes a FormData object and returns a JavaScript object
+ *
+ * @param {string} formData The FormData object to convert to JSON.
+ *
+ * @returns {Object<string, any> | null} The converted object.
+ */
+function formDataToJSON(formData: unknown): Record<string, unknown> | null {
+  function buildPath(path: Array<string>, value: unknown, target: Record<string, unknown>, index: number): boolean {
+    throwIfDepthExceeded(index);
+
+    let name: string | number = path[index++]!;
+
+    if (name === "__proto__") return true;
+
+    const isNumericKey = Number.isFinite(+name);
+    const isLast = index >= path.length;
+    name = !name && utils.isArray(target) ? (target as Array<unknown>).length : name;
+
+    const key = String(name);
+
+    if (isLast) {
+      if (utils.hasOwnProp(target, key)) {
+        target[key] = utils.isArray(target[key])
+          ? (target[key] as Array<unknown>).concat(value)
+          : [ target[key], value ];
+      }
+      else {
+        target[key] = value;
+      }
+
+      return !isNumericKey;
+    }
+
+    if (!utils.hasOwnProp(target, key) || !utils.isObject(target[key])) {
+      target[key] = [];
+    }
+
+    const result = buildPath(path, value, target[key] as Record<string, unknown>, index);
+
+    if (result && utils.isArray(target[key])) {
+      target[key] = arrayToObject(target[key] as Array<unknown>);
+    }
+
+    return !isNumericKey;
+  }
+
+  if (utils.isFormData(formData) && utils.isFunction((formData as { entries?: unknown; }).entries)) {
+    const obj: Record<string, unknown> = {};
+
+    utils.forEachEntry(formData, (name: unknown, value: unknown) => {
+      buildPath(parsePropPath(name as string), value, obj, 0);
+    });
+
+    return obj;
+  }
+
+  return null;
+}
+
+export default formDataToJSON;

package/src/lib/helpers/isAbsoluteURL.ts

@@ -0,0 +1,13 @@
+"use strict";
+
+// ponytail: protocol-relative URLs (//) intentionally not supported — HTTPS-era fork
+export default function isAbsoluteURL(url: unknown): boolean {
+  if (typeof url !== "string") return false;
+  try {
+    new URL(url);
+    return true;
+  }
+  catch {
+    return false;
+  }
+}

package/src/lib/helpers/isFaxiosError.ts

@@ -0,0 +1,19 @@
+"use strict";
+
+import type FaxiosError from "../core/FaxiosError.js";
+import utils from "../utils.js";
+
+/**
+ * Determines whether the payload is an error thrown by Faxios.
+ *
+ * Checks the `isFaxiosError` brand, not `instanceof`, so errors from another
+ * copy of faxios still match. `T` and `D` type `response.data` and
+ * `config.data`; they are not checked at runtime.
+ *
+ * @param {*} payload The value to test
+ *
+ * @returns {boolean} True if the payload is an error thrown by Faxios, otherwise false
+ */
+export default function isFaxiosError<T = unknown, D = unknown>(payload: unknown): payload is FaxiosError<T, D> {
+  return utils.isObject(payload) && (payload as Record<string, unknown>).isFaxiosError === true;
+}

package/src/lib/helpers/isURLSameOrigin.ts

@@ -0,0 +1,16 @@
+import platform from "../platform.js";
+
+export default platform.hasStandardBrowserEnv
+  ? ((origin, isMSIE) => (url: string) => {
+    const _url = new URL(url, platform.origin);
+
+    return (
+      origin.protocol === _url.protocol &&
+        origin.host === _url.host &&
+        (isMSIE || origin.port === _url.port)
+    );
+  })(
+    new URL(platform.origin),
+    !!(/(msie|trident)/i.test(platform.navigator?.userAgent ?? ""))
+  )
+  : () => true;

package/src/lib/helpers/parseHeaders.ts

@@ -0,0 +1,76 @@
+"use strict";
+
+import utils from "../utils.js";
+
+// RawFaxiosHeaders whose duplicates are ignored by node
+// c.f. https://nodejs.org/api/http.html#http_message_headers
+const ignoreDuplicateOf = utils.toObjectSet([
+  "age",
+  "authorization",
+  "content-length",
+  "content-type",
+  "etag",
+  "expires",
+  "from",
+  "host",
+  "if-modified-since",
+  "if-unmodified-since",
+  "last-modified",
+  "location",
+  "max-forwards",
+  "proxy-authorization",
+  "referer",
+  "retry-after",
+  "user-agent",
+], "");
+
+/**
+ * Parse headers into an object
+ *
+ * ```
+ * Date: Wed, 27 Aug 2014 08:58:49 GMT
+ * Content-Type: application/json
+ * Connection: keep-alive
+ * Transfer-Encoding: chunked
+ * ```
+ *
+ * @param {String} rawHeaders Headers needing to be parsed
+ *
+ * @returns {Object} Headers parsed into an object
+ */
+export default (rawHeaders: string): Record<string, string | Array<string>> => {
+  const parsed: Record<string, string | Array<string>> = {};
+  let key: string;
+  let val: string;
+  let i: number;
+
+  rawHeaders &&
+    rawHeaders.split("\n")
+      .forEach(function parser(line) {
+        // eslint-disable-next-line big-o/no-array-lookup-in-loop
+        i = line.indexOf(":");
+        key = line.substring(0, i).trim()
+          .toLowerCase();
+        val = line.substring(i + 1).trim();
+
+        if (!key || (parsed[key] !== undefined && ignoreDuplicateOf[key] !== undefined)) {
+          return;
+        }
+
+        if (key === "set-cookie") {
+          const existing = parsed[key];
+          if (existing) {
+            (existing as Array<string>).push(val);
+          }
+          else {
+            parsed[key] = [ val ];
+          }
+        }
+        else {
+          const existing = parsed[key] as string | undefined;
+          parsed[key] = existing ? existing + ", " + val : val;
+        }
+      });
+
+  return parsed;
+};

package/src/lib/helpers/progressEventReducer.ts

@@ -0,0 +1,57 @@
+import type { FaxiosProgressEvent } from "../types.js";
+import utils from "../utils.js";
+import speedometer from "./speedometer.js";
+import throttle from "./throttle.js";
+
+export const progressEventReducer = (listener: (data: FaxiosProgressEvent) => void, isDownloadStream: boolean, freq = 3) => {
+  let bytesNotified = 0;
+  const _speedometer = speedometer(50, 250);
+
+  return throttle((e: unknown) => {
+    if (!e || typeof (e as Record<string, unknown>).loaded !== "number") {
+      return;
+    }
+    const ev = e as { loaded: number; total?: number; lengthComputable?: boolean; };
+    const rawLoaded = ev.loaded;
+    const total = ev.lengthComputable ? ev.total : undefined;
+    const loaded = total != null ? Math.min(rawLoaded, total) : rawLoaded;
+    const progressBytes = Math.max(0, loaded - bytesNotified);
+    const rate = _speedometer(progressBytes);
+
+    bytesNotified = Math.max(bytesNotified, loaded);
+
+    const data: FaxiosProgressEvent = {
+      loaded,
+      total,
+      progress: total ? loaded / total : undefined,
+      bytes: progressBytes,
+      rate: rate ? rate : undefined,
+      estimated: rate && total ? (total - loaded) / rate : undefined,
+      event: e,
+      lengthComputable: total != null,
+      download: isDownloadStream ? true : undefined,
+      upload: isDownloadStream ? undefined : true,
+    };
+
+    listener(data);
+  }, freq);
+};
+
+export const progressEventDecorator = (total: number | undefined, throttled: ReturnType<typeof throttle>): [(loaded: number) => void, () => void] => {
+  const lengthComputable = total != null;
+
+  return [
+    (loaded: number) =>
+      throttled[0]({
+        lengthComputable,
+        total,
+        loaded,
+      }),
+    throttled[1],
+  ];
+};
+
+export const asyncDecorator =
+  (fn: (...args: Array<unknown>) => unknown) =>
+    (...args: Array<unknown>) =>
+      utils.asap(() => fn(...args));