@gcmdev/faxios 0.1.0 → 0.2.1

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): string | Array<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,13 @@
+/** 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`);
+    }
+    const val = params[key];
+    if (val == null) {
+      throw new Error(`Path param "${key}" is null or undefined`);
+    }
+    return encodeURIComponent(String(val));
+  });
+}

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: ReturnType<typeof setTimeout> | null = 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,296 @@
+"use strict";
+
+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 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<string | number> | null | undefined, key: string | number, dots: unknown): string {
+  if (!path) return String(key);
+  return path
+    .concat(key)
+    .map(function each(token: string | number, 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();
+  }
+
+  options = utils.toFlatObject(
+    options,
+    {
+      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: string | number, path: null | Array<string | number>, _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<string | number>, 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 string | number,
+          path ?? null,
+          exposedHelpers
+        );
+
+      if (result === true) {
+        build(el, path ? path.concat(key as string | number) : [ key as string | number ], 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 }
+  );
+}

package/src/lib/helpers/trackStream.ts

@@ -0,0 +1,123 @@
+type ReadableStreamController = {
+  enqueue: (chunk: Uint8Array) => void;
+  close: () => void;
+};
+
+type ReadableStreamSource = {
+  pull?: (controller: ReadableStreamController) => Promise<void>;
+  cancel?: (reason?: unknown) => Promise<unknown>;
+};
+
+type ReadableStreamInit = {
+  highWaterMark?: number;
+};
+
+type ReadableStreamCtor = new (source: ReadableStreamSource, init?: ReadableStreamInit) => unknown;
+
+const ReadableStreamGlobal = (globalThis as Record<string, unknown>)["ReadableStream"] as ReadableStreamCtor | undefined;
+
+type ByteChunk = { byteLength: number; slice: (start: number, end?: number) => ByteChunk; };
+
+const streamChunk = function* (chunk: ByteChunk, chunkSize?: number): Generator<ByteChunk> {
+  const len = chunk.byteLength;
+
+  if (!chunkSize || len < chunkSize) {
+    yield chunk;
+    return;
+  }
+
+  let pos = 0;
+  let end: number;
+
+  while (pos < len) {
+    end = pos + chunkSize;
+    yield chunk.slice(pos, end);
+    pos = end;
+  }
+};
+
+const readBytes = async function* (iterable: AsyncIterable<ByteChunk> | unknown, chunkSize?: number): AsyncGenerator<ByteChunk> {
+  for await (const chunk of readStream(iterable)) {
+    yield* streamChunk(chunk, chunkSize);
+  }
+};
+
+type ReaderLike = {
+  read: () => Promise<{ done: boolean; value: ByteChunk; }>;
+  cancel: () => Promise<void>;
+};
+
+type StreamLike = {
+  [Symbol.asyncIterator]?: () => AsyncIterator<ByteChunk>;
+  getReader?: () => ReaderLike;
+};
+
+const readStream = async function* (stream: unknown): AsyncGenerator<ByteChunk> {
+  const s = stream as StreamLike;
+  if (s[Symbol.asyncIterator]) {
+    yield* s as AsyncIterable<ByteChunk>;
+    return;
+  }
+
+  const reader = s.getReader!();
+  try {
+    for (;;) {
+      // eslint-disable-next-line no-await-in-loop
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      yield value;
+    }
+  }
+  finally {
+    await reader.cancel();
+  }
+};
+
+export const trackStream = (stream: unknown, chunkSize: number | undefined, onProgress?: ((bytes: number) => void) | null, onFinish?: ((err?: unknown) => void) | null): unknown => {
+  const iterator = readBytes(stream, chunkSize);
+
+  let bytes = 0;
+  let done = false;
+  const _onFinish = (e?: unknown): void => {
+    if (!done) {
+      done = true;
+      onFinish && onFinish(e);
+    }
+  };
+
+  return new ReadableStreamGlobal!(
+    {
+      async pull(controller: ReadableStreamController) {
+        try {
+          const { done: iterDone, value } = await iterator.next();
+
+          if (iterDone) {
+            _onFinish();
+            controller.close();
+            return;
+          }
+
+          const len = value.byteLength;
+          if (onProgress) {
+            const loadedBytes = (bytes += len);
+            onProgress(loadedBytes);
+          }
+          controller.enqueue(new Uint8Array(value as unknown as ArrayBuffer));
+        }
+        catch (err) {
+          _onFinish(err);
+          throw err;
+        }
+      },
+      async cancel(reason?: unknown) {
+        _onFinish(reason);
+        return iterator.return(undefined);
+      },
+    },
+    {
+      highWaterMark: 2,
+    }
+  );
+};