@superutils/fetch 1.5.9 → 1.5.11

package/dist/index.cjs

@@ -42,7 +42,7 @@ var import_promise5 = require("@superutils/promise");
 var import_promise3 = require("@superutils/promise");
 
 // src/fetch.ts
-var import_core4 = require("@superutils/core");
+var import_core5 = require("@superutils/core");
 var import_promise2 = require("@superutils/promise");
 
 // src/executeInterceptors.ts
@@ -98,46 +98,8 @@ var getResponse = (url, options = {}) => {
 getResponse.fetch = globalThis.fetch;
 var getResponse_default = getResponse;
 
-// src/mergeOptions.ts
+// src/getResult.ts
 var import_core3 = require("@superutils/core");
-var mergeOptions = (...allOptions) => allOptions.reduce(
-  (merged, options) => {
-    var _a;
-    options = (0, import_core3.isObj)(options) ? options : {};
-    const { headers, interceptors: ints1 = {} } = merged;
-    const { interceptors: ints2 = {} } = options;
-    options.headers && new Headers(options.headers).forEach(
-      (value, key) => headers.set(key, value)
-    );
-    return {
-      ...merged,
-      ...options,
-      errMsgs: (0, import_core3.objCopy)(
-        options.errMsgs,
-        merged.errMsgs,
-        [],
-        "empty"
-      ),
-      headers,
-      interceptors: {
-        error: [...toArr(ints1 == null ? void 0 : ints1.error), ...toArr(ints2 == null ? void 0 : ints2.error)],
-        request: [
-          ...toArr(ints1 == null ? void 0 : ints1.request),
-          ...toArr(ints2 == null ? void 0 : ints2.request)
-        ],
-        response: [
-          ...toArr(ints1 == null ? void 0 : ints1.response),
-          ...toArr(ints2 == null ? void 0 : ints2.response)
-        ],
-        result: [...toArr(ints1 == null ? void 0 : ints1.result), ...toArr(ints2 == null ? void 0 : ints2.result)]
-      },
-      timeout: (_a = options.timeout) != null ? _a : merged.timeout
-    };
-  },
-  { headers: new Headers() }
-);
-var mergeOptions_default = mergeOptions;
-var toArr = (x) => (0, import_core3.isArr)(x) ? x : (0, import_core3.isFn)(x) ? [x] : [];
 
 // src/types/constants.ts
 var ContentType = {
@@ -201,6 +163,170 @@ var FetchError = class _FetchError extends Error {
   }
 };
 
+// src/getResult.ts
+var getResult = async (response, as = "json" /* json */, onDownloadProgress) => {
+  var _a;
+  if (!(0, import_core3.isFn)(onDownloadProgress) || as === "response" /* response */) {
+    const parseFunc = response[as];
+    const result = !(0, import_core3.isFn)(parseFunc) ? response : parseFunc.bind(response)();
+    return result;
+  }
+  const reader = (_a = response == null ? void 0 : response.body) == null ? void 0 : _a.getReader();
+  const contentLength = response.headers.get("Content-Length");
+  const total = contentLength ? parseInt(contentLength, 10) : null;
+  const chunks = new Chunks(
+    [],
+    response.headers.get("content-type")
+  );
+  let received = 0;
+  while (reader) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.value.push(value);
+    received += value.length;
+    (0, import_core3.fallbackIfFails)(
+      onDownloadProgress,
+      total ? [100 * received / total, received, total] : [null, received, null],
+      null
+    );
+  }
+  switch (as) {
+    case "arrayBuffer" /* arrayBuffer */:
+      return chunks.toArrayBuffer();
+    case "blob" /* blob */:
+      return chunks.toBlob();
+    case "bytes" /* bytes */:
+      return chunks.toBytes();
+    case "formData" /* formData */:
+      return chunks.toFormData();
+    case "text" /* text */:
+      return chunks.toText();
+    case "json" /* json */:
+      break;
+  }
+  return chunks.toJSON();
+};
+var getResult_default = getResult;
+var Chunks = class {
+  /**
+   * @param value The initial array of chunks.
+   * @param contentType The MIME type of the content for Blob/FormData conversion.
+   * @param encoding The character encoding for text decoding. Defaults to 'utf-8'.
+   */
+  constructor(value, contentType = "", encoding = "utf-8") {
+    this.value = value;
+    this.contentType = contentType;
+    this.encoding = encoding;
+    /**
+     * Converts the accumulated data to an ArrayBuffer.
+     */
+    this.toArrayBuffer = () => this.concatChunks().buffer;
+    /**
+     * Converts the accumulated data to a Blob
+     *
+     * @param type content type. Default: `this.contentType`
+     */
+    this.toBlob = (type = this.contentType) => new Blob(this.value, { type });
+    /**
+     * Converts the accumulated data to a single Uint8Array.
+     */
+    this.toBytes = () => this.concatChunks();
+    /**
+     * Decodes the data as text and parses it as JSON.
+     *
+     * @template T The expected type of the JSON result.
+     * @param encoding Optional encoding override.
+     * @returns The parsed JSON object.
+     */
+    this.toJSON = (encoding = this.encoding) => JSON.parse(this.toText(encoding));
+    /**
+     * Decodes the accumulated chunks into a string.
+     *
+     * @param encoding The character encoding to use. Defaults to the instance's `encoding`.
+     */
+    this.toText = (encoding = this.encoding) => new TextDecoder(encoding).decode(this.concatChunks());
+  }
+  /**
+   * Concatenates all accumulated chunks into a single Uint8Array.
+   *
+   * @returns A single Uint8Array containing the merged data.
+   */
+  concatChunks() {
+    const total = this.value.reduce((s, c) => s + c.byteLength, 0);
+    const out = new Uint8Array(total);
+    let off = 0;
+    for (const u of this.value) {
+      out.set(u, off);
+      off += u.byteLength;
+    }
+    return out;
+  }
+  /**
+   * Attempts to convert the accumulated data to FormData.
+   *
+   * If the `contentType` is `application/x-www-form-urlencoded` or the content appears to be
+   * query parameters, it parses them into FormData. Otherwise, it appends the entire
+   * content as a Blob under the key 'file'.
+   *
+   * @param encoding Optional encoding override for text decoding.
+   * @returns A FormData instance containing the data.
+   */
+  toFormData(encoding = this.encoding) {
+    const text = this.toText(encoding);
+    const formData = new FormData();
+    if (this.contentType.includes(
+      ContentType.APPLICATION_X_WWW_FORM_URLENCODED
+    ) || text.includes("=")) {
+      const params = new URLSearchParams(text);
+      for (const [k, v] of params) formData.append(k, v);
+      return formData;
+    }
+    formData.append("file", new Blob([text]));
+    return formData;
+  }
+};
+
+// src/mergeOptions.ts
+var import_core4 = require("@superutils/core");
+var mergeOptions = (...allOptions) => allOptions.reduce(
+  (merged, options) => {
+    var _a;
+    options = (0, import_core4.isObj)(options) ? options : {};
+    const { headers, interceptors: ints1 = {} } = merged;
+    const { interceptors: ints2 = {} } = options;
+    options.headers && new Headers(options.headers).forEach(
+      (value, key) => headers.set(key, value)
+    );
+    return {
+      ...merged,
+      ...options,
+      errMsgs: (0, import_core4.objCopy)(
+        options.errMsgs,
+        merged.errMsgs,
+        [],
+        "empty"
+      ),
+      headers,
+      interceptors: {
+        error: [...toArr(ints1 == null ? void 0 : ints1.error), ...toArr(ints2 == null ? void 0 : ints2.error)],
+        request: [
+          ...toArr(ints1 == null ? void 0 : ints1.request),
+          ...toArr(ints2 == null ? void 0 : ints2.request)
+        ],
+        response: [
+          ...toArr(ints1 == null ? void 0 : ints1.response),
+          ...toArr(ints2 == null ? void 0 : ints2.response)
+        ],
+        result: [...toArr(ints1 == null ? void 0 : ints1.result), ...toArr(ints2 == null ? void 0 : ints2.result)]
+      },
+      timeout: (_a = options.timeout) != null ? _a : merged.timeout
+    };
+  },
+  { headers: new Headers() }
+);
+var mergeOptions_default = mergeOptions;
+var toArr = (x) => (0, import_core4.isArr)(x) ? x : (0, import_core4.isFn)(x) ? [x] : [];
+
 // src/fetch.ts
 var defaultErrorMsgs = Object.freeze({
   aborted: "Request aborted",
@@ -211,7 +337,7 @@ var defaultErrorMsgs = Object.freeze({
 });
 var fetch = (url, options = {}) => {
   var _a, _b, _c;
-  if (!(0, import_core4.isObj)(options)) options = {};
+  if (!(0, import_core5.isObj)(options)) options = {};
   let response;
   const opts = mergeOptions_default(
     { errMsgs: defaultErrorMsgs },
@@ -224,16 +350,16 @@ var fetch = (url, options = {}) => {
   (_c = opts.signal) != null ? _c : opts.signal = opts.abortCtrl.signal;
   const { abortCtrl, as: parseAs, headers, onAbort, onTimeout } = opts;
   opts.onAbort = async () => {
-    const err = await (0, import_core4.fallbackIfFails)(onAbort, [], void 0);
+    const err = await (0, import_core5.fallbackIfFails)(onAbort, [], void 0);
     return await interceptErr(
-      (0, import_core4.isError)(err) ? err : new Error(err),
+      (0, import_core5.isError)(err) ? err : new Error(err),
       url,
       opts,
       response
     );
   };
   opts.onTimeout = async () => {
-    const err = await (0, import_core4.fallbackIfFails)(onTimeout, [], void 0);
+    const err = await (0, import_core5.fallbackIfFails)(onTimeout, [], void 0);
     return await interceptErr(
       err != null ? err : new Error(opts.errMsgs.timedout),
       url,
@@ -244,7 +370,7 @@ var fetch = (url, options = {}) => {
   return (0, import_promise2.timeout)(opts, async () => {
     var _a2, _b2, _c2, _d;
     try {
-      opts.body = await (0, import_core4.fallbackIfFails)(
+      opts.body = await (0, import_core5.fallbackIfFails)(
         opts.body,
         [],
         (err) => Promise.reject(err)
@@ -257,11 +383,11 @@ var fetch = (url, options = {}) => {
       );
       const { body, errMsgs, validateUrl = false } = opts;
       (_b2 = opts.signal) != null ? _b2 : opts.signal = abortCtrl.signal;
-      if (validateUrl && !(0, import_core4.isUrlValid)(url, false))
+      if (validateUrl && !(0, import_core5.isUrlValid)(url, false))
         throw new Error(errMsgs.invalidUrl);
       const stringify = ["delete", "patch", "post", "put"].includes(
         `${opts.method}`.toLowerCase()
-      ) && !["undefined", "string"].includes(typeof body) && (0, import_core4.isObj)(body, true) && headers.get("content-type") === ContentType.APPLICATION_JSON;
+      ) && !["undefined", "string"].includes(typeof body) && (0, import_core5.isObj)(body, true) && headers.get("content-type") === ContentType.APPLICATION_JSON;
       if (stringify) opts.body = JSON.stringify(opts.body);
       response = await getResponse_default(url, opts);
       response = await executeInterceptors_default(
@@ -274,7 +400,7 @@ var fetch = (url, options = {}) => {
       const status = response == null ? void 0 : response.status;
       const isSuccess = status >= 200 && status < 300;
       if (!isSuccess) {
-        const jsonError = await (0, import_core4.fallbackIfFails)(
+        const jsonError = await (0, import_core5.fallbackIfFails)(
           // try to parse error response as json first
           () => {
             var _a3;
@@ -285,9 +411,12 @@ var fetch = (url, options = {}) => {
         );
         throw new Error(jsonError, { cause: jsonError });
       }
-      const parseFunc = response[parseAs];
-      let result = !(0, import_core4.isFn)(parseFunc) ? response : parseFunc.bind(response)();
-      if ((0, import_core4.isPromise)(result))
+      let result = getResult_default(
+        response,
+        parseAs,
+        opts.onDownloadProgress
+      );
+      if ((0, import_core5.isPromise)(result)) {
         result = await result.catch(
           (err) => Promise.reject(
             new Error(
@@ -296,6 +425,7 @@ var fetch = (url, options = {}) => {
             )
           )
         );
+      }
       result = await executeInterceptors_default(
         result,
         abortCtrl.signal,

package/dist/index.d.cts

@@ -285,6 +285,7 @@ type FetchCustomOptions = {
      */
     abortCtrl?: AbortController;
     body?: PostArgs[1];
+    errMsgs?: FetchErrMsgs;
     /**
      * Custom fetch function to use instead of the global `fetch`.
      * Useful for testing or using a different fetch implementation (e.g. `node-fetch` in older Node versions).
@@ -292,12 +293,12 @@ type FetchCustomOptions = {
      * Default: `globalThis.fetch`
      */
     fetchFunc?: FetchFunc;
-    errMsgs?: FetchErrMsgs;
     /**
      * Interceptor/transformer callback executed at different stages of the request.
      * See {@link FetchInterceptors} for more details.
      */
     interceptors?: FetchInterceptors;
+    onDownloadProgress?: OnDownloadProgress;
     /** Whether to validate URL before making the request. Default: `false` */
     validateUrl?: boolean;
 } & FetchRetryOptions & TimeoutOptions<[]>;
@@ -378,6 +379,37 @@ type FetchRetryOptions = Omit<Partial<RetryOptions>, 'retry' | 'retryIf'> & {
     retry?: number;
     retryIf?: RetryIfFunc<Response>;
 };
+/**
+ * Callback function for monitoring download progress.
+ *
+ * @param percent The progress percentage (0-100), or `null` if Content-Length is unknown.
+ * @param received The total number of bytes received so far.
+ * @param total The total number of bytes expected, or `null` if Content-Length is unknown.
+ *
+ * @example
+ * #### Download a file as Blob
+ * ```javascript
+ * import fetch from '@superutils/fetch'
+ *
+ * fetch.get(
+ *   'https://dummyjson.com/image/4000x4000/008080/ffffff?text=Hello+@superutils', // dynamic image file
+ *   {
+ *     as: FetchAs.blob,
+ *     onDownloadProgress: (parcent, received, total) =>
+ *     	 console.log({
+ *         percent: `${(parcent ?? 0).toFixed(2)}%`,
+ *         received,
+ *         total,
+ *       }),
+ *   },
+ * ).then(r => console.log('result', r), console.log)
+ * ```
+ */
+type OnDownloadProgress = (percent: number | null, received: number, total: number | null) => ValueOrPromise<void>;
+/**
+ * Possible types for the request body.
+ * Can be a plain object (which will be stringified if JSON), standard BodyInit, or null.
+ */
 type PostBody = Record<string, unknown> | BodyInit | null;
 type PostArgs = [
     url: FetchArgs[0],
@@ -899,4 +931,4 @@ declare const methods: {
  */
 declare const fetch: typeof fetch$1 & typeof methods;
 
-export { type ClientData, ContentType, type ExcludeOptions, type ExcludePostOptions, type ExtractAs, type FetchArgs, type FetchArgsInterceptor, FetchAs, type FetchCustomOptions, type FetchErrMsgs, FetchError, type FetchFunc, type FetchInterceptorError, type FetchInterceptorRequest, type FetchInterceptorResponse, type FetchInterceptorResult, type FetchInterceptors, type FetchInterceptorsMerged, type FetchOptions, type FetchOptionsDefault, type FetchOptionsInterceptor, type FetchResult, type FetchRetryOptions, type GetFetchResult, type IPromise_Fetch, type Interceptor, type PostArgs, type PostBody, type PostDeferredCbArgs, type PostOptions, createClient, createPostClient, fetch as default, executeInterceptors, fetch, mergeOptions };
+export { type ClientData, ContentType, type ExcludeOptions, type ExcludePostOptions, type ExtractAs, type FetchArgs, type FetchArgsInterceptor, FetchAs, type FetchCustomOptions, type FetchErrMsgs, FetchError, type FetchFunc, type FetchInterceptorError, type FetchInterceptorRequest, type FetchInterceptorResponse, type FetchInterceptorResult, type FetchInterceptors, type FetchInterceptorsMerged, type FetchOptions, type FetchOptionsDefault, type FetchOptionsInterceptor, type FetchResult, type FetchRetryOptions, type GetFetchResult, type IPromise_Fetch, type Interceptor, type OnDownloadProgress, type PostArgs, type PostBody, type PostDeferredCbArgs, type PostOptions, createClient, createPostClient, fetch as default, executeInterceptors, fetch, mergeOptions };

package/dist/index.d.ts

@@ -285,6 +285,7 @@ type FetchCustomOptions = {
      */
     abortCtrl?: AbortController;
     body?: PostArgs[1];
+    errMsgs?: FetchErrMsgs;
     /**
      * Custom fetch function to use instead of the global `fetch`.
      * Useful for testing or using a different fetch implementation (e.g. `node-fetch` in older Node versions).
@@ -292,12 +293,12 @@ type FetchCustomOptions = {
      * Default: `globalThis.fetch`
      */
     fetchFunc?: FetchFunc;
-    errMsgs?: FetchErrMsgs;
     /**
      * Interceptor/transformer callback executed at different stages of the request.
      * See {@link FetchInterceptors} for more details.
      */
     interceptors?: FetchInterceptors;
+    onDownloadProgress?: OnDownloadProgress;
     /** Whether to validate URL before making the request. Default: `false` */
     validateUrl?: boolean;
 } & FetchRetryOptions & TimeoutOptions<[]>;
@@ -378,6 +379,37 @@ type FetchRetryOptions = Omit<Partial<RetryOptions>, 'retry' | 'retryIf'> & {
     retry?: number;
     retryIf?: RetryIfFunc<Response>;
 };
+/**
+ * Callback function for monitoring download progress.
+ *
+ * @param percent The progress percentage (0-100), or `null` if Content-Length is unknown.
+ * @param received The total number of bytes received so far.
+ * @param total The total number of bytes expected, or `null` if Content-Length is unknown.
+ *
+ * @example
+ * #### Download a file as Blob
+ * ```javascript
+ * import fetch from '@superutils/fetch'
+ *
+ * fetch.get(
+ *   'https://dummyjson.com/image/4000x4000/008080/ffffff?text=Hello+@superutils', // dynamic image file
+ *   {
+ *     as: FetchAs.blob,
+ *     onDownloadProgress: (parcent, received, total) =>
+ *     	 console.log({
+ *         percent: `${(parcent ?? 0).toFixed(2)}%`,
+ *         received,
+ *         total,
+ *       }),
+ *   },
+ * ).then(r => console.log('result', r), console.log)
+ * ```
+ */
+type OnDownloadProgress = (percent: number | null, received: number, total: number | null) => ValueOrPromise<void>;
+/**
+ * Possible types for the request body.
+ * Can be a plain object (which will be stringified if JSON), standard BodyInit, or null.
+ */
 type PostBody = Record<string, unknown> | BodyInit | null;
 type PostArgs = [
     url: FetchArgs[0],
@@ -899,4 +931,4 @@ declare const methods: {
  */
 declare const fetch: typeof fetch$1 & typeof methods;
 
-export { type ClientData, ContentType, type ExcludeOptions, type ExcludePostOptions, type ExtractAs, type FetchArgs, type FetchArgsInterceptor, FetchAs, type FetchCustomOptions, type FetchErrMsgs, FetchError, type FetchFunc, type FetchInterceptorError, type FetchInterceptorRequest, type FetchInterceptorResponse, type FetchInterceptorResult, type FetchInterceptors, type FetchInterceptorsMerged, type FetchOptions, type FetchOptionsDefault, type FetchOptionsInterceptor, type FetchResult, type FetchRetryOptions, type GetFetchResult, type IPromise_Fetch, type Interceptor, type PostArgs, type PostBody, type PostDeferredCbArgs, type PostOptions, createClient, createPostClient, fetch as default, executeInterceptors, fetch, mergeOptions };
+export { type ClientData, ContentType, type ExcludeOptions, type ExcludePostOptions, type ExtractAs, type FetchArgs, type FetchArgsInterceptor, FetchAs, type FetchCustomOptions, type FetchErrMsgs, FetchError, type FetchFunc, type FetchInterceptorError, type FetchInterceptorRequest, type FetchInterceptorResponse, type FetchInterceptorResult, type FetchInterceptors, type FetchInterceptorsMerged, type FetchOptions, type FetchOptionsDefault, type FetchOptionsInterceptor, type FetchResult, type FetchRetryOptions, type GetFetchResult, type IPromise_Fetch, type Interceptor, type OnDownloadProgress, type PostArgs, type PostBody, type PostDeferredCbArgs, type PostOptions, createClient, createPostClient, fetch as default, executeInterceptors, fetch, mergeOptions };