@gcmdev/faxios 0.2.0 → 0.2.2

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, Array<string> | string> => {
+  const parsed: Record<string, Array<string> | 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 { 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;
+    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));

package/src/lib/helpers/sanitizeHeaderValue.ts

@@ -0,0 +1,61 @@
+"use strict";
+
+import utils from "../utils.js";
+
+function trimSPorHTAB(str: string): string {
+  let start = 0;
+  let end = str.length;
+
+  while (start < end) {
+    const code = str.charCodeAt(start);
+
+    if (code !== 0x09 && code !== 0x20) {
+      break;
+    }
+
+    start += 1;
+  }
+
+  while (end > start) {
+    const code = str.charCodeAt(end - 1);
+
+    if (code !== 0x09 && code !== 0x20) {
+      break;
+    }
+
+    end -= 1;
+  }
+
+  return start === 0 && end === str.length ? str : str.slice(start, end);
+}
+
+// The control-code ranges are intentional: header sanitization strips C0/DEL bytes.
+// eslint-disable-next-line no-control-regex
+const INVALID_UNICODE_HEADER_VALUE_CHARS = new RegExp("[\\u0000-\\u0008\\u000a-\\u001f\\u007f]+", "g");
+// eslint-disable-next-line no-control-regex, sonarjs/no-control-regex
+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): Array<string> | string {
+  if (utils.isArray(value)) {
+    return (value as Array<unknown>).map(item => sanitizeValue(item, invalidChars) as string);
+  }
+
+  return trimSPorHTAB(String(value).replace(invalidChars, ""));
+}
+
+export const sanitizeHeaderValue = (value: unknown) =>
+  sanitizeValue(value, INVALID_UNICODE_HEADER_VALUE_CHARS);
+
+const sanitizeByteStringHeaderValue = (value: unknown) =>
+  sanitizeValue(value, INVALID_BYTE_STRING_HEADER_VALUE_CHARS);
+
+export function toByteStringHeaderObject(headers: { toJSON: () => Record<string, unknown>; }) {
+  const byteStringHeaders: Record<string, unknown> = Object.create(null);
+
+  utils.forEach(headers.toJSON(), (value: unknown, header: unknown) => {
+    byteStringHeaders[String(header)] = sanitizeByteStringHeaderValue(value);
+  });
+
+  return byteStringHeaders;
+}

package/src/lib/helpers/speedometer.ts

@@ -0,0 +1,55 @@
+"use strict";
+
+/**
+ * Calculate data maxRate
+ * @param {Number} [samplesCount= 10]
+ * @param {Number} [min= 1000]
+ * @returns {Function}
+ */
+function speedometer(samplesCount?: number, min?: number): (chunkLength: number) => number | undefined {
+  samplesCount = samplesCount || 10;
+  const bytes: Array<number> = new Array(samplesCount);
+  const timestamps: Array<number> = new Array(samplesCount);
+  let head = 0;
+  let tail = 0;
+  let firstSampleTS: number | undefined;
+
+  min = min !== undefined ? min : 1000;
+
+  return function push(chunkLength: number): number | undefined {
+    const now = Date.now();
+
+    const startedAt = timestamps[tail];
+
+    if (!firstSampleTS) {
+      firstSampleTS = now;
+    }
+
+    bytes[head] = chunkLength;
+    timestamps[head] = now;
+
+    let i = tail;
+    let bytesCount = 0;
+
+    while (i !== head) {
+      bytesCount += bytes[i++]!;
+      i = i % samplesCount;
+    }
+
+    head = (head + 1) % samplesCount;
+
+    if (head === tail) {
+      tail = (tail + 1) % samplesCount;
+    }
+
+    if (now - firstSampleTS < min) {
+      return;
+    }
+
+    const passed = startedAt && now - startedAt;
+
+    return passed ? Math.round((bytesCount * 1000) / passed) : undefined;
+  };
+}
+
+export default speedometer;

package/src/lib/helpers/substitutePathParams.ts

@@ -0,0 +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 FaxiosError(`Path param "${key}" not found in pathParams`, FaxiosError.ERR_BAD_OPTION_VALUE);
+    }
+    const val = params[key];
+    if (val == null) {
+      throw new FaxiosError(`Path param "${key}" is null or undefined`, FaxiosError.ERR_BAD_OPTION_VALUE);
+    }
+    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

@@ -0,0 +1,45 @@
+/**
+ * Throttle decorator
+ * @param {Function} fn
+ * @param {Number} freq
+ * @return {Function}
+ */
+function throttle(fn: (...args: Array<unknown>) => void, freq: number): [(...args: Array<unknown>) => void, () => void] {
+  let timestamp = 0;
+  const threshold = 1000 / freq;
+  let lastArgs: Array<unknown> | null = null;
+  let timer: null | ReturnType<typeof setTimeout> = null;
+
+  const invoke = (args: Array<unknown>, now: number = Date.now()) => {
+    timestamp = now;
+    lastArgs = null;
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    fn(...args);
+  };
+
+  const throttled = (...args: Array<unknown>) => {
+    const now = Date.now();
+    const passed = now - timestamp;
+    if (passed >= threshold) {
+      invoke(args, now);
+    }
+    else {
+      lastArgs = args;
+      if (!timer) {
+        timer = setTimeout(() => {
+          timer = null;
+          invoke(lastArgs!);
+        }, threshold - passed);
+      }
+    }
+  };
+
+  const flush = () => { if (lastArgs) invoke(lastArgs); };
+
+  return [ throttled, flush ];
+}
+
+export default throttle;

package/src/lib/helpers/toFormData.ts

@@ -0,0 +1,298 @@
+"use strict";
+
+import FaxiosError from "../core/FaxiosError.js";
+// temporary hotfix to avoid circular references until FaxiosURLSearchParams is refactored
+import type { FormDataVisitorHelpers, GenericFormData, SerializerVisitor } from "../types.js";
+import utils from "../utils.js";
+
+// Default nesting limit shared with the inverse transform (formDataToJSON) so
+// the FormData <-> JSON round-trip stays symmetric.
+export const DEFAULT_FORM_DATA_MAX_DEPTH = 100;
+
+/**
+ * Determines if the given thing is a array or js object.
+ *
+ * @param {string} thing - The object or array to be visited.
+ *
+ * @returns {boolean}
+ */
+function isVisitable(thing: unknown): boolean {
+  return utils.isPlainObject(thing) || utils.isArray(thing);
+}
+
+/**
+ * It removes the brackets from the end of a string
+ *
+ * @param {string} key - The key of the parameter.
+ *
+ * @returns {string} the key without the brackets.
+ */
+function removeBrackets(key: string): string {
+  return key.endsWith("[]") ? key.slice(0, -2) : key;
+}
+
+/**
+ * It takes a path, a key, and a boolean, and returns a string
+ *
+ * @param {string} path - The path to the current key.
+ * @param {string} key - The key of the current object being iterated over.
+ * @param {string} dots - If true, the key will be rendered with dots instead of brackets.
+ *
+ * @returns {string} The path to the current key.
+ */
+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: number | string, i: number) {
+      token = removeBrackets(String(token));
+      return !dots && i ? "[" + token + "]" : token;
+    })
+    .join(dots ? "." : "");
+}
+
+/**
+ * If the array is an array and none of its elements are visitable, then it's a flat array.
+ *
+ * @param {Array<any>} arr - The array to check
+ *
+ * @returns {boolean}
+ */
+function isFlatArray(arr: unknown): boolean {
+  return utils.isArray(arr) && !(arr as Array<unknown>).some(isVisitable);
+}
+
+const predicates = utils.toFlatObject(utils, {}, null as unknown as false, function filter(prop: string) {
+  return /^is[A-Z]/.test(prop);
+});
+
+/**
+ * Convert a data object to FormData
+ *
+ * @param {Object} obj
+ * @param {?Object} [formData]
+ * @param {?Object} [options]
+ * @param {Function} [options.visitor]
+ * @param {Boolean} [options.metaTokens = true]
+ * @param {Boolean} [options.dots = false]
+ * @param {?Boolean} [options.indexes = false]
+ *
+ * @returns {Object}
+ **/
+
+/**
+ * It converts an object into a FormData object
+ *
+ * @param {Object<any, any>} obj - The object to convert to form data.
+ * @param {string} formData - The FormData object to append to.
+ * @param {Object<string, any>} options
+ *
+ * @returns
+ */
+function toFormData(obj: unknown, formData?: GenericFormData | null, options?: Record<string, unknown>): GenericFormData {
+  if (!utils.isObject(obj)) {
+    throw new TypeError("target must be an object");
+  }
+
+  const FormDataCtor = (globalThis as Record<string, unknown>)["FormData"] as (new () => GenericFormData) | undefined;
+  if (!formData) {
+    if (!FormDataCtor) throw new FaxiosError("FormData is not available in this environment", FaxiosError.ERR_NOT_SUPPORT);
+    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]);
+    }
+  );
+
+  const metaTokens = options["metaTokens"];
+
+  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 maxDepth =
+    options["maxDepth"] === undefined
+      ? DEFAULT_FORM_DATA_MAX_DEPTH
+      : (options["maxDepth"] as number);
+  const useBlob = _Blob && utils.isSpecCompliantForm(formData);
+  const stack: Array<unknown> = [];
+
+  if (!utils.isFunction(visitor)) {
+    throw new TypeError("visitor must be a function");
+  }
+
+  function convertValue(value: unknown): unknown {
+    if (value === null) return "";
+
+    if (utils.isDate(value)) {
+      return (value as Date).toISOString();
+    }
+
+    if (utils.isBoolean(value)) {
+      return String(value);
+    }
+
+    if (!useBlob && utils.isBlob(value)) {
+      throw new FaxiosError("Blob is not supported. Use a Buffer instead.");
+    }
+
+    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 value;
+  }
+
+  function throwIfMaxDepthExceeded(depth: number): void {
+    if (depth > (maxDepth)) {
+      throw new FaxiosError(
+        "Object is too deeply nested (" +
+          depth +
+          " levels). Max depth: " +
+          maxDepth,
+        FaxiosError.ERR_FORM_DATA_DEPTH_EXCEEDED
+      );
+    }
+  }
+
+  function stringifyWithDepthLimit(value: unknown, depth: number): string {
+    if (maxDepth === Infinity) {
+      return JSON.stringify(value);
+    }
+
+    const ancestors: Array<unknown> = [];
+
+    return JSON.stringify(value, function limitDepth(this: unknown, _key: string, currentValue: unknown): unknown {
+      if (!utils.isObject(currentValue)) {
+        return currentValue;
+      }
+
+      while (ancestors.length && ancestors[ancestors.length - 1] !== this) {
+        ancestors.pop();
+      }
+
+      ancestors.push(currentValue);
+      throwIfMaxDepthExceeded(depth + ancestors.length - 1);
+
+      return currentValue;
+    });
+  }
+
+  /**
+   * Default visitor.
+   *
+   * @param {*} value
+   * @param {String|Number} key
+   * @param {Array<String|Number>} path
+   * @this {FormData}
+   *
+   * @returns {boolean} return true to visit the each prop of the value recursively
+   */
+  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)) {
+      (formData as GenericFormData).append(renderKey(path, key, dots), convertValue(value));
+      return false;
+    }
+
+    if (value && !path && typeof value === "object") {
+      if (String(key).endsWith("{}")) {
+        key = metaTokens ? key : String(key).slice(0, -2);
+
+        value = stringifyWithDepthLimit(value, 1);
+      }
+      else if (
+        (utils.isArray(value) && isFlatArray(value)) ||
+        ((utils.isFileList(value) || String(key).endsWith("[]")) &&
+          (arr = utils.toArray(value)))
+      ) {
+        key = removeBrackets(String(key));
+
+        (arr as Array<unknown>).forEach(function each(el: unknown, index: number) {
+          !utils.isUndefined(el) && el !== null &&
+            (formData as GenericFormData).append(
+              /* eslint-disable sonarjs/no-nested-conditional */
+              indexes === true
+                ? renderKey([ String(key) ], index, dots)
+                : indexes === null
+                  ? String(key)
+                  : String(key) + "[]",
+              /* eslint-enable sonarjs/no-nested-conditional */
+              convertValue(el)
+            );
+        });
+        return false;
+      }
+    }
+
+    if (isVisitable(value)) {
+      return true;
+    }
+
+    (formData as GenericFormData).append(renderKey(path, key, dots), convertValue(value));
+
+    return false;
+  }
+
+  const exposedHelpers: FormDataVisitorHelpers = Object.assign(predicates, {
+    defaultVisitor: defaultVisitor,
+    convertValue,
+    isVisitable,
+  });
+
+  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("."));
+    }
+
+    stack.push(value);
+
+    utils.forEach(value, function each(el: unknown, key: unknown) {
+      const result =
+        !utils.isUndefined(el) && el !== null &&
+        visitor.call(
+          formData as GenericFormData,
+          el,
+          utils.isString(key) ? (key as string).trim() : key as number | string,
+          path ?? null,
+          exposedHelpers
+        );
+
+      if (result === true) {
+        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;
+}
+
+export default toFormData;

package/src/lib/helpers/toURLEncodedForm.ts

@@ -0,0 +1,14 @@
+"use strict";
+
+import platform from "../platform.js";
+import type { GenericFormData } from "../types.js";
+import toFormData from "./toFormData.js";
+
+export default function toURLEncodedForm(data: unknown, options?: Record<string, unknown>) {
+  // ponytail: web-standard platform always provides global URLSearchParams
+  return toFormData(
+    data,
+    new (platform.classes.URLSearchParams as new () => object)() as unknown as GenericFormData,
+    { ...options }
+  );
+}