@superutils/fetch 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Toufiqur Rahaman Chowdhury
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# @superutils/fetch
+
+A lightweight `fetch` wrapper for browsers and Node.js, designed to simplify data fetching and reduce boilerplate.
+
+This package enhances the native `fetch` API by providing a streamlined interface and integrating practical & useful features from `@superutils/promise`. It offers built-in support for automatic retries, request timeouts, interceptors, and effortless request cancellation, making complex asynchronous flows simple and manageable.
+
+## Table of Contents
+
+- Features
+- Installation
+- Usage
+    - `fetch(url, options)`
+    - `fetchDeferred(deferOptions, url, fetchOptions)`
+
+## Features
+
+- **Simplified API**: Automatically parses JSON responses, eliminating the need for `.then(res => res.json())`.
+- **Built-in Retries**: Automatic request retries with configurable exponential or fixed backoff strategies.
+- **Request Timeouts**: Easily specify a timeout for any request to prevent it from hanging indefinitely.
+- **Cancellable & Debounced Requests**: The `fetchDeferred` utility provides debouncing and throttling capabilities, automatically cancelling stale or intermediate requests. This is ideal for features like live search inputs.
+- **Interceptors**: Hook into the request/response lifecycle to globally modify requests, handle responses, or manage errors.
+- **Strongly Typed**: Written in TypeScript for excellent autocompletion and type safety.
+- **Isomorphic**: Works seamlessly in both Node.js and browser environments.
+
+## Installation
+
+```bash
+npm install @superutils/fetch
+```
+
+## Usage
+
+<div id="fetch"></div>
+
+### `fetch(url, options)`
+
+Make a simple GET request. No need for `response.json()` or `result.data.theActualData` drilling.
+
+```typescript
+import { fetch } from '@superutils/fetch'
+
+const theActualData = await fetch('https://dummyjson.com/products/1')
+console.log(theActualData)
+```
+
+<div id="fetchDeferred"></div>
+
+### `fetchDeferred(deferOptions, url, fetchOptions)`
+
+A practical utility that combines `PromisE.deferred()` from the `@superutils/promise` package with `fetch()`. It's perfect for implementing cancellable, debounced, or throttled search inputs.
+
+```typescript
+import { fetchDeferred, ResolveIgnored } from '@superutils/fetch'
+
+// Create a debounced search function with a 300ms delay.
+const searchProducts = fetchDeferred({
+	delayMs: 300, // Debounce delay
+	resolveIgnored: ResolveIgnored.WITH_UNDEFINED, // Ignored (aborted) promises will resolve with `undefined`
+})
+
+// User types 'iphone'
+searchProducts('https://dummyjson.com/products/search?q=iphone').then(
+	result => {
+		console.log('Result for "iphone":', result)
+	},
+)
+
+// Before 300ms has passed, the user continues typing 'iphone 9'
+setTimeout(() => {
+	searchProducts('https://dummyjson.com/products/search?q=iphone 9').then(
+		result => {
+			console.log('Result for "iphone 9":', result)
+		},
+	)
+}, 200)
+// Outcome:
+// The first request for "iphone" is aborted.
+// The first promise resolves with `undefined`.
+// The second request for "iphone 9" is executed after the 300ms debounce delay.
+```
+
+**Behavior with different `deferOptions` in the example above:**
+
+- **`throttle: true`**: Switches from debounce to throttle mode. The first request for "iphone" would
+  execute immediately. The second request for "iphone 9", made within the 300ms throttle window, would be ignored.
+- **`delayMs: 0`**: Disables debouncing and throttling, enabling sequential/queue mode. Both requests ("iphone"
+  and "iphone 9") would execute, but one after the other, never simultaneously.
+- **`resolveIgnored`**: Controls how the promise for an aborted request (like the first "iphone" call) resolves.
+    1. `ResolveIgnored.WITH_UNDEFINED` (used in the example): The promise for the aborted "iphone"
+       request resolves with `undefined`.
+    2. `ResolveIgnored.WITH_LAST`: The promise for the aborted "iphone" request waits and resolves with the result
+       of the final "iphone 9" request. Both promises resolve to the same value.
+    3. `ResolveIgnored.NEVER`: The promise for the aborted "iphone" request is neither resolved nor rejected.
+       It will remain pending indefinitely.
+    4. `ResolveIgnored.WITH_ERROR`: The promise for the aborted "iphone" request is rejected with a `FetchError`.
+
+#### Using defaults to reduce redundancy
+
+```typescript
+import { fetchDeferred, ResolveIgnored } from '@superutils/fetch'
+
+// Create a throttled function to fetch a random quote.
+// The URL and a 3-second timeout are set as defaults, creating a reusable client.
+const getRandomQuote = fetchDeferred(
+	{
+		delayMs: 300, // Throttle window
+		throttle: true,
+		// Ignored calls will resolve with the result of the last successful call.
+		resolveIgnored: ResolveIgnored.WITH_LAST,
+	},
+	'https://dummyjson.com/quotes/random', // Default URL
+	{ timeout: 3000 }, // Default fetch options
+)
+
+// Call the function multiple times in quick succession.
+getRandomQuote().then(quote => console.log('Call 1 resolved:', quote.id))
+getRandomQuote().then(quote => console.log('Call 2 resolved:', quote.id))
+getRandomQuote().then(quote => console.log('Call 3 resolved:', quote.id))
+
+// Outcome:
+// Due to throttling, only one network request is made.
+// Because `resolveIgnored` is `WITH_LAST`, all three promises resolve with the same quote.
+// The promises for the two ignored calls resolve as soon as the first successful call resolves.
+// Console output will show the same quote ID for all three calls.
+```
+
+<div id="post"></div>
+
+### `post(url, options)`
+
+<div id="postDeferred"></div>
+
+### `postDeferred(deferOptions, url, postOptions)`

package/dist/index.d.ts

@@ -0,0 +1,520 @@
+import * as _superutils_promise from '@superutils/promise';
+import { RetryOptions, Config as Config$1, IPromisE, DeferredOptions } from '@superutils/promise';
+export { DeferredOptions, ResolveError, ResolveIgnored } from '@superutils/promise';
+import { ValueOrPromise } from '@superutils/core';
+
+type FetchArgs = [url: string | URL, options?: FetchOptions];
+type FetchArgsInterceptor = [
+    url: string | URL,
+    options: FetchOptionsInterceptor
+];
+declare enum FetchAs {
+    arrayBuffer = "arrayBuffer",
+    blob = "blob",
+    bytes = "bytes",
+    formData = "formData",
+    json = "json",
+    response = "response",
+    text = "text"
+}
+type FetchConf = {
+    /**
+     * Specify how the parse the result. To get raw response use {@link FetchAs.response}.
+     * Default: 'json'
+     */
+    as?: FetchAs;
+    abortCtrl?: AbortController;
+    errMsgs?: FetchErrMsgs;
+    interceptors?: FetchInterceptors;
+    /** Request timeout in milliseconds. */
+    timeout?: number;
+};
+/** Default args */
+type FetchDeferredArgs = [
+    url?: string | URL,
+    options?: Omit<FetchOptions, 'abortCtrl'>
+];
+type FetchErrMsgs = {
+    invalidUrl?: string;
+    parseFailed?: string;
+    reqTimedout?: string;
+    requestFailed?: string;
+};
+/** Custom error message for fetch requests with more detailed info about the request URL, fetch options and response */
+declare class FetchError extends Error {
+    options?: FetchOptions;
+    response?: Response;
+    url: string | URL;
+    constructor(message: string, options: {
+        cause?: unknown;
+        options: FetchOptions;
+        response?: Response;
+        url: string | URL;
+    });
+}
+/**
+ * Fetch error interceptor to be invoked whenever an exception occurs.
+ * This interceptor can also be used as the error transformer by returning {@link FetchError}.
+ *
+ * @param	{FetchError}	fetchError custom error that also contain URL, options & response
+ *
+ * @returns returning undefined or not returning anything will not override the error
+ *
+ * @example	intercept fetch errors to log errors
+ * ```typescript
+ * import PromisE from '@superutils/promise'
+ *
+ * // not returning anything or returning undefined will avoid transforming the error.
+ * const logError = fetchErr => console.log(fetchErr)
+ * const result = await PromisE.fetch('https://my.domain.com/api/that/fails', {
+ *     interceptors: {
+ *         error: [logError]
+ *     }
+ * })
+ * ```
+ *
+ * @example	intercept & transform fetch errors
+ * ```typescript
+ * import PromisE from '@superutils/promise'
+ *
+ * // Interceptors can be async functions or just return a promise that resolves to the error.
+ * // If the execution of the interceptor fails or promise rejects, it will be ignored.
+ * // To transform the error it must directly return an error or a Promise that `resolves` with an error.
+ * const transformError = async fetchErr => {
+ *     fetchErr.message = 'Custom errormessage'
+ * 	   return Promise.resolve(fetchErr)
+ * }
+ * const result = await PromisE.fetch('https://my.domain.com/api/that/fails', {
+ *     interceptors: {
+ *         error: [transformError]
+ *     }
+ * })
+ * ```
+ */
+type FetchInterceptorError = Interceptor<FetchError, []>;
+/**
+ *
+ * Fetch request interceptor to be invoked before making a fetch request.
+ * This interceptor can also be used as a transformer:
+ * 1. by returning an API URL (string/URL)
+ * 2. by modifying the properties of the options object to be used before making the fetch request
+ *
+ * @example intercept and transform fetch request
+ * ```typescript
+ * import PromisE from '@superutils/promise'
+ *
+ * // update API version number
+ * const apiV1ToV2 = url => `${url}`.replace('api/v1', 'api/v2')
+ * const includeAuthToken = (url, options) => {
+ *     options.headers.set('x-auth-token', 'my-auth-token')
+ * }
+ * const data = await PromisE.fetch('https://my.domain.com/api', {
+ *     interceptors: {
+ *         result: [apiV1ToV2, includeAuthToken]
+ *     }
+ * })
+ * ```
+ */
+type FetchInterceptorRequest = Interceptor<FetchArgs[0], FetchArgsInterceptor>;
+/**
+ * Fetch response interceptor to be invoked before making a fetch request.
+ *
+ * This interceptor can also be used as a transformer by return a different/modified {@link Response}.
+ *
+ * @example intercept and transform response:
+ * ```typescript
+ * import PromisE from '@superutils/promise'
+ *
+ * // After successful login, retrieve user balance.
+ * // This is probably better suited as a result transformer but play along as this is
+ * // just a hypothetical scenario ;)
+ * const includeBalance = async response => {
+ *     const balance = await PromisE.fetch('https://my.domain.com/api/user/12325345/balance')
+ * 	   const user = await response.json()
+ *     user.balance = balance
+ *     return new Response(JSON.stringify(user))
+ * }
+ * const user = await PromisE.fetch('https://my.domain.com/api/login', {
+ *     interceptors: {
+ *         response: [includeBalance]
+ *     }
+ * })
+ * ```
+ */
+type FetchInterceptorResponse = Interceptor<Response, FetchArgsInterceptor>;
+/**
+ *
+ * Fetch result interceptor to be invoked before returning parsed fetch result.
+ *
+ * Result interceptors are executed ONLY when a result is successfully parsed (as ArrayBuffer, Blob, JSON, Text...).
+ * Result interceptors WILL NOT be executed if:
+ * - return type is set to `Response` by using {@link FetchAs.response} in the {@link FetchOptions.as}
+ * - exceptions is thrown even before attempting to parse
+ * - parse fails
+ *
+ * This interceptor can also be used as a transformer by returns a different/modified result.
+ *
+ *
+ * @example intercept and transform fetch result
+ * ```typescript
+ * import PromisE from '@superutils/promise'
+ *
+ * // first transform result by extracting result.data
+ * const extractData = result => result?.data ?? result
+ * // then check convert hexadecimal number to BigInt
+ * const hexToBigInt = data => {
+ *     if (data.hasOwnProperty('balance') && `${data.balance}`.startsWith('0x')) {
+ *          data.balance = BigInt(data.balance)
+ *     }
+ *     return data
+ * }
+ * // then log balance (no transformation)
+ * const logBalance = data => {
+ *     data?.hasOwnProperty('balance') && console.log(data.balance)
+ * }
+ * const data = await PromisE.fetch('https://my.domain.com/api', {
+ *     interceptors: {
+ *         result: [
+ * 	           extractData,
+ * 	           hexToBigInt,
+ * 	           logBalance
+ * 	       ]
+ *     }
+ * })
+ * ```
+ */
+type FetchInterceptorResult = Interceptor<unknown, FetchArgsInterceptor>;
+/**
+ * All valid interceptors for fetch requests are:
+ * ---
+ * 1. error,
+ * 2. request
+ * 3. response
+ * 4. result.
+ *
+ * An interceptor can be any of the following:
+ * ---
+ * 1. synchronous function
+ * 2. synchronous function that returns a promise (or sometimes returns a promise)
+ * 3. asynchronous functions
+ *
+ * An interceptor can return:
+ * ---
+ * 1. undefined (void/no return): plain interceptor that does other stuff but does not transform
+ * 2. value: act as a transformer. Returned value depends on the type of interceptor.
+ * 3. promise resolves with (1) value or (2) undefined
+ *
+ * PS:
+ * ---
+ * 1. Any exception thrown by interceptors will gracefully ignored.
+ * 2. Interceptors will be executed in the sequence they're given.
+ * 3. Execution priority: global interceprors will always be executed before local interceptors.
+ *
+ *
+ *
+ * More info & examples:
+ * ---
+ * See the following for more details and examples:
+ *
+ * - `error`: {@link FetchInterceptorError}
+ * - `request`: {@link FetchInterceptorRequest}
+ * - `response`: {@link FetchInterceptorResponse}
+ * - `result`: {@link FetchInterceptorResult}
+ */
+type FetchInterceptors = {
+    error?: FetchInterceptorError[];
+    request?: FetchInterceptorRequest[];
+    response?: FetchInterceptorResponse[];
+    result?: FetchInterceptorResult[];
+};
+/**
+ * Fetch request options
+ */
+type FetchOptions = RequestInit & FetchConf & FetchRetryOptions;
+/**
+ * Fetch options available to interceptors
+ */
+type FetchOptionsInterceptor = Omit<FetchOptions, 'as' | 'errMsgs' | 'interceptors' | 'headers' | keyof FetchRetryOptions> & {
+    as: FetchAs;
+    errMsgs: Required<FetchErrMsgs>;
+    headers: Headers;
+    interceptors: Required<FetchInterceptors>;
+} & Required<FetchRetryOptions>;
+/**
+ * Result types for specific parsers ("as": FetchAs)
+ */
+interface FetchResult<T> {
+    arrayBuffer: ArrayBuffer;
+    blob: Blob;
+    bytes: Uint8Array<ArrayBuffer>;
+    formData: FormData;
+    json: T;
+    text: string;
+    response: Response;
+}
+/**
+ * Fetch retry options
+ */
+type FetchRetryOptions = Partial<RetryOptions> & {
+    /**
+     * Maximum number of retries.
+     *
+     * The total number of attempts will be `retry + 1`.
+     *
+     * Default: `0`
+     */
+    retry?: number;
+};
+/**
+ * Generic fetch interceptor type
+ */
+type Interceptor<T, TArgs extends unknown[], TArgsCb extends unknown[] = [value: T, ...TArgs]> = (...args: TArgsCb) => ValueOrPromise<void> | ValueOrPromise<T>;
+type PostBody = Record<string, unknown> | BodyInit | null;
+type PostArgs = [
+    url: string | URL,
+    data?: PostBody,
+    options?: Omit<FetchOptions, 'method'> & {
+        /** Default: `'post'` */
+        method?: 'post' | 'put' | 'patch' | 'delete';
+    }
+];
+
+type Config = Config$1 & {
+    fetchOptions: FetchOptionsInterceptor;
+};
+declare const config: Config;
+
+/**
+ * A `fetch()` replacement that simplifies data fetching with automatic JSON parsing, request timeouts, retries,
+ * and powerful interceptors. It also includes deferred and throttled request capabilities for complex asynchronous
+ * control flows.
+ *
+ * Will reject promise if response status code is not 2xx (200 <= status < 300).
+ *
+ * @param	url
+ * @param options (optional) all built-in `fetch()` options such as "method", "headers" and the additionals below.
+ * @param options.abortCtrl (optional) if not provided `AbortController` will be instantiated when `timeout` used.
+ * @param options.headers (optional) request headers. Default: `{ 'content-type' : 'application/json'}`
+ * @param options.interceptors (optional) request interceptor callbacks.  See {@link FetchInterceptors} for details.
+ * @param options.method  (optional) Default: `"get"`
+ * @param options.timeout (optional) duration in milliseconds to abort the request if it takes longer.
+ * @param options.parse   (optional) specify how to parse the result.
+ * Default: {@link FetchAs.json}
+ * For raw `Response` use {@link FetchAs.response}
+ *
+ * @example Make a simple HTTP requests
+ * ```typescript
+ * import { fetch } from '@superutils/fetch'
+ *
+ * // no need for `response.json()` or `result.data.theActualData` drilling
+ * fetch('https://dummyjson.com/products/1').then(theActualData => console.log(theActualData))
+ * ```
+ */
+declare function fetch$1<TJSON, TOptions extends FetchOptions = FetchOptions, TReturn = TOptions['as'] extends FetchAs ? FetchResult<TJSON>[TOptions['as']] : TJSON>(url: string | URL, options?: TOptions): IPromisE<TReturn>;
+
+/**
+ * Creates a deferred/throttled version of {@link fetch}, powered by {@link PromisE.deferred}.
+ * This is ideal for scenarios requiring advanced control over HTTP requests, such as debouncing search inputs,
+ * throttling API calls, or ensuring sequential request execution.
+ *
+ * It leverages the robust capabilities of the underlying {@link fetch} function, which includes features like request timeouts and manual abortion.
+ * `fetchDeferred` uses this to automatically abort pending requests when a new one is initiated, preventing race conditions and redundant network traffic.
+ *
+ * @param deferOptions Configuration for the deferred execution behavior (e.g., `delayMs`, `throttle`).
+ * See {@link DeferredOptions} for details.
+ * @param defaultFetchArgs (optional) Default `url` and `fetchOptions` to be used for every call made by the
+ * returned function. This is useful for creating a reusable client for a specific endpoint.
+ *
+ *
+ * @example Debounce/Throttle requests for an auto-complete search input
+ * ```typescript
+ * import { fetchDeferred, ResolveIgnored } from '@superutils/fetch'
+ *
+ * // Create a debounced search function with a 300ms delay.
+ * const searchProducts = fetchDeferred({
+ * 	delayMs: 300, // Debounce delay
+ * 	resolveIgnored: ResolveIgnored.WITH_UNDEFINED, // Ignored (aborted) promises will resolve with `undefined`
+ * })
+ *
+ * // User types 'iphone'
+ * searchProducts('https://dummyjson.com/products/search?q=iphone').then(result => {
+ *   console.log('Result for "iphone":', result);
+ * });
+ *
+ * // Before 300ms has passed, the user continues typing 'iphone 9'
+ * setTimeout(() => {
+ *   searchProducts('https://dummyjson.com/products/search?q=iphone 9').then(result => {
+ *     console.log('Result for "iphone 9":', result);
+ *   });
+ * }, 200);
+ *
+ * // Outcome:
+ * // The first request for "iphone" is aborted.
+ * // The first promise resolves with `undefined`.
+ * // The second request for "iphone 9" is executed after the 300ms debounce delay.
+ * ```
+ *
+ * **Behavior with different `deferOptions` in the example above:**
+ * - **`throttle: true`**: Switches from debounce to throttle mode. The first request for "iphone" would
+ * execute immediately. The second request for "iphone 9", made within the 300ms throttle window, would be ignored.
+ * - **`delayMs: 0`**: Disables debouncing and throttling, enabling sequential/queue mode. Both requests ("iphone"
+ * and "iphone 9") would execute, but one after the other, never simultaneously.
+ * - **`resolveIgnored`**: Controls how the promise for an aborted request (like the first "iphone" call) resolves.
+ *    1. `ResolveIgnored.WITH_UNDEFINED` (used in the example): The promise for the aborted "iphone"
+ * request resolves with `undefined`.
+ *    2. `ResolveIgnored.WITH_LAST`: The promise for the aborted "iphone" request waits and resolves with the result
+ * of the final "iphone 9" request. Both promises resolve to the same value.
+ *    3. `ResolveIgnored.NEVER`: The promise for the aborted "iphone" request is neither resolved nor rejected.
+ * It will remain pending indefinitely.
+ *    4. `ResolveIgnored.WITH_ERROR`: The promise for the aborted "iphone" request is rejected with a `FetchError`.
+ *
+ * @example Creating a reusable, pre-configured client
+ * ```typescript
+ * import { fetchDeferred, ResolveIgnored } from '@superutils/fetch'
+ *
+ * // Create a throttled function to fetch a random quote.
+ * // The URL and a 3-second timeout are set as defaults, creating a reusable client.
+ * const getRandomQuote = fetchDeferred(
+ * 	{
+ * 		delayMs: 300, // Throttle window
+ * 		throttle: true,
+ *      // Ignored calls will resolve with the result of the last successful call.
+ * 		resolveIgnored: ResolveIgnored.WITH_LAST,
+ * 	},
+ * 	'https://dummyjson.com/quotes/random', // Default URL
+ * 	{ timeout: 3000 }, // Default fetch options
+ * )
+ *
+ * // Call the function multiple times in quick succession.
+ * getRandomQuote().then(quote => console.log('Call 1 resolved:', quote.id));
+ * getRandomQuote().then(quote => console.log('Call 2 resolved:', quote.id));
+ * getRandomQuote().then(quote => console.log('Call 3 resolved:', quote.id));
+ *
+ * // Outcome:
+ * // Due to throttling, only one network request is made.
+ * // Because `resolveIgnored` is `WITH_LAST`, all three promises resolve with the same quote.
+ * // The promises for the two ignored calls resolve as soon as the first successful call resolves.
+ * // Console output will show the same quote ID for all three calls.
+ * ```
+ */
+declare function fetchDeferred<ThisArg, DefaultUrl extends string | URL>(deferOptions?: DeferredOptions<ThisArg>, defaultUrl?: DefaultUrl, defaultOptions?: FetchDeferredArgs[1]): <TResult = unknown>(...args: DefaultUrl extends undefined ? FetchArgs : [url?: string | URL | undefined, options?: FetchOptions | undefined]) => _superutils_promise.IPromisE<TResult>;
+
+/**
+ * Creates a deferred/throttled function for making `POST`, `PUT`, or `PATCH` requests, powered by
+ * {@link PromisE.deferred}.
+ * This is ideal for scenarios like auto-saving form data, preventing duplicate submissions on button clicks,
+ * or throttling API updates.
+ *
+ * Like `fetchDeferred`, it automatically aborts pending requests when a new one is initiated, ensuring only
+ * the most recent or relevant action is executed.
+ *
+ * @example Debouncing an authentication token refresh
+ * ```typescript
+ * import { postDeferred } from '@superutils/fetch'
+ * import PromisE from '@superutils/promise'
+ *
+ * // Mock a simple token store
+ * let currentRefreshToken = 'initial-refresh-token'
+ *
+ * // Create a debounced function to refresh the auth token.
+ * // It waits 300ms after the last call before executing.
+ * const refreshAuthToken = postDeferred(
+ * 	{
+ * 		delayMs: 300, // debounce delay
+ * 		onResult: (result: { token: string }) => {
+ * 			console.log(`Auth token successfully refreshed at ${new Date().toISOString()}`)
+ *          currentRefreshToken = result.token
+ *      },
+ * 	},
+ * 	'https://dummyjson.com/auth/refresh', // Default URL
+ * )
+ *
+ * // This function would be called from various parts of an app,
+ * // for example, in response to multiple failed API calls.
+ * function requestNewToken() {
+ *   const body = {
+ * 	   refreshToken: currentRefreshToken,
+ * 	   expiresInMins: 30,
+ *   }
+ *   refreshAuthToken(body)
+ * }
+ *
+ * requestNewToken() // Called at 0ms
+ * PromisE.delay(50, requestNewToken) // Called at 50ms
+ * PromisE.delay(100, requestNewToken) // Called at 100ms
+ *
+ * // Outcome:
+ * // The first two calls are aborted by the debounce mechanism.
+ * // Only the final call executes, 300ms after it was made (at the 400ms mark).
+ * // The token is refreshed only once, preventing redundant network requests.
+ * ```
+ *
+ * @example Auto-saving form data with throttling
+ * ```typescript
+ * import { postDeferred } from '@superutils/fetch'
+ * import PromisE from '@superutils/promise'
+ *
+ * // Create a throttled function to auto-save product updates.
+ * const saveProductThrottled = postDeferred(
+ *     {
+ *         delayMs: 1000, // Throttle window of 1 second
+ *         throttle: true,
+ *         trailing: true, // Ensures the very last update is always saved
+ *         onResult: (product) => console.log(`[Saved] Product: ${product.title}`),
+ *     },
+ * 	   'https://dummyjson.com/products/1', // Default URL
+ * 	   undefined, // No default data
+ * 	   { method: 'put' }, // Default method
+ * )
+ *
+ * // Simulate a user typing quickly, triggering multiple saves.
+ * console.log('User starts typing...');
+ * saveProductThrottled({ title: 'iPhone' }); // Executed immediately (leading edge)
+ * await PromisE.delay(200);
+ * saveProductThrottled({ title: 'iPhone 15' }); // Ignored (within 1000ms throttle window)
+ * await PromisE.delay(300);
+ * saveProductThrottled({ title: 'iPhone 15 Pro' }); // Ignored
+ * await PromisE.delay(400);
+ * saveProductThrottled({ title: 'iPhone 15 Pro Max' }); // Queued to execute on the trailing edge
+ *
+ * // Outcome:
+ * // The first call ('iPhone') is executed immediately.
+ * // The next two calls are ignored by the throttle.
+ * // The final call ('iPhone 15 Pro Max') is executed after the 1000ms throttle window closes,
+ * // thanks to `trailing: true`.
+ * // This results in only two network requests instead of four.
+ * ```
+ */
+declare function postDeferred<ThisArg, DefaultUrl extends string | URL>(deferOptions?: DeferredOptions<ThisArg>, defaultUrl?: DefaultUrl, defaultData?: PostArgs[1], defaultOptions?: PostArgs[2]): <TResult = unknown>(...args: DefaultUrl extends undefined ? PostArgs : [url?: string | URL | undefined, data?: PostBody | undefined, options?: (Omit<FetchOptions, "method"> & {
+    method?: "post" | "put" | "patch" | "delete";
+}) | undefined]) => _superutils_promise.IPromisE<TResult>;
+
+/**
+ * Merge one or more {@link FetchOptions} with global fetch options ({@link config.fetchOptions}).
+ *
+ * Notes:
+ * - {@link config.fetchOptions} will be added as the base and not necessary to be included
+ * - item properties will be prioritized in the order of sequence they were passed in
+ * - the following properties will be merged
+ *     * `errMsgs`
+ *     * `headers`
+ *     * `interceptors`
+ * - all other properties will simply override previous values
+ *
+ * @returns combined
+ */
+declare const mergeFetchOptions: (...allOptions: FetchOptions[]) => FetchOptionsInterceptor;
+
+type Func = <T, Options extends Omit<FetchOptions, 'method'>>(url: string | URL, options?: Options) => ReturnType<typeof fetch$1<T, Options>>;
+type MethodFunc = Func & ({
+    deferred: typeof fetchDeferred;
+} | {
+    deferred: typeof postDeferred;
+});
+type FetchDeferred = typeof fetchDeferred | typeof postDeferred;
+interface DefaultFetch extends Record<string, MethodFunc> {
+    <T, O extends FetchOptions>(...params: Parameters<typeof fetch$1<T, O>>): ReturnType<typeof fetch$1<T, O>>;
+}
+declare const fetch: DefaultFetch;
+
+export { type Config, type DefaultFetch, type FetchArgs, type FetchArgsInterceptor, FetchAs, type FetchConf, type FetchDeferred, type FetchDeferredArgs, type FetchErrMsgs, FetchError, type FetchInterceptorError, type FetchInterceptorRequest, type FetchInterceptorResponse, type FetchInterceptorResult, type FetchInterceptors, type FetchOptions, type FetchOptionsInterceptor, type FetchResult, type FetchRetryOptions, type Func, type Interceptor, type MethodFunc, type PostArgs, type PostBody, config, fetch as default, fetch, fetchDeferred, mergeFetchOptions, postDeferred };

package/dist/index.js

@@ -0,0 +1,347 @@
+// src/config.ts
+import {
+  config as promiseConfig
+} from "@superutils/promise";
+
+// src/types.ts
+var FetchAs = /* @__PURE__ */ ((FetchAs3) => {
+  FetchAs3["arrayBuffer"] = "arrayBuffer";
+  FetchAs3["blob"] = "blob";
+  FetchAs3["bytes"] = "bytes";
+  FetchAs3["formData"] = "formData";
+  FetchAs3["json"] = "json";
+  FetchAs3["response"] = "response";
+  FetchAs3["text"] = "text";
+  return FetchAs3;
+})(FetchAs || {});
+var FetchError = class extends Error {
+  constructor(message, options) {
+    super(message, { cause: options.cause });
+    this.name = "FetchError";
+    this.options = options.options;
+    this.response = options.response;
+    this.url = options.url;
+  }
+};
+
+// src/config.ts
+var fetchOptions = {
+  as: "json" /* json */,
+  errMsgs: {
+    invalidUrl: "Invalid URL",
+    parseFailed: "Failed to parse response as",
+    reqTimedout: "Request timed out",
+    requestFailed: "Request failed with status code:"
+  },
+  // all error messages must be defined here
+  headers: new Headers([["content-type", "application/json"]]),
+  /** Global interceptors for fetch requests */
+  interceptors: {
+    /**
+     * Global error interceptors to be invoked whenever an exception occurs
+     * Returning an
+     */
+    error: [],
+    /** Interceptors to be invoked before making fetch requests */
+    request: [],
+    response: [],
+    result: []
+  },
+  ...promiseConfig.retryOptions,
+  retryIf: null,
+  timeout: 0
+};
+var config = promiseConfig;
+config.fetchOptions = fetchOptions;
+var config_default = config;
+
+// src/fetch.ts
+import {
+  isFn as isFn2,
+  isPositiveNumber,
+  isPromise,
+  isUrlValid
+} from "@superutils/core";
+import PromisE2 from "@superutils/promise";
+
+// src/mergeFetchOptions.ts
+import { isEmpty, objKeys } from "@superutils/core";
+var mergeFetchOptions = (...allOptions) => allOptions.reduce((o1, o2) => {
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n;
+  const { errMsgs = {}, headers, interceptors: ints1 = {} } = o1;
+  const { errMsgs: msgs2 = {}, interceptors: ints2 = {} } = o2;
+  o2.headers && new Headers(o2.headers).forEach(
+    (value, key) => headers.set(key, value)
+  );
+  for (const key of objKeys(msgs2)) {
+    if (!isEmpty(msgs2[key])) continue;
+    errMsgs[key] = msgs2[key];
+  }
+  return {
+    ...o1,
+    ...o2,
+    errMsgs,
+    headers,
+    interceptors: {
+      error: (_c = (_b = ints1 == null ? void 0 : ints1.error) == null ? void 0 : _b.concat((_a = ints2 == null ? void 0 : ints2.error) != null ? _a : [])) != null ? _c : [],
+      request: (_f = (_e = ints1 == null ? void 0 : ints1.request) == null ? void 0 : _e.concat((_d = ints2 == null ? void 0 : ints2.request) != null ? _d : [])) != null ? _f : [],
+      response: (_i = (_h = ints1 == null ? void 0 : ints1.response) == null ? void 0 : _h.concat((_g = ints2 == null ? void 0 : ints2.response) != null ? _g : [])) != null ? _i : [],
+      result: (_l = (_k = ints1 == null ? void 0 : ints1.result) == null ? void 0 : _k.concat((_j = ints2 == null ? void 0 : ints2.result) != null ? _j : [])) != null ? _l : []
+    },
+    timeout: (_n = (_m = o2.timeout) != null ? _m : o1.timeout) != null ? _n : 0
+  };
+}, config_default.fetchOptions);
+var mergeFetchOptions_default = mergeFetchOptions;
+
+// src/executeInterceptors.ts
+import { fallbackIfFails, isFn } from "@superutils/core";
+var executeInterceptors = async (value, interceptors, ...args) => {
+  var _a;
+  for (const interceptor of interceptors.filter(isFn)) {
+    value = (_a = await fallbackIfFails(
+      interceptor,
+      [value, args],
+      void 0
+    )) != null ? _a : value;
+  }
+  return value;
+};
+var executeInterceptors_default = executeInterceptors;
+
+// src/getResponse.ts
+import PromisE from "@superutils/promise";
+var getResponse = async (...[url, options]) => {
+  const doFetch = () => globalThis.fetch(url, options).catch(
+    (err) => err.message === "Failed to fetch" ? (
+      // catch network errors to allow retries
+      new Response(null, {
+        status: 0,
+        statusText: "Network Error"
+      })
+    ) : globalThis.Promise.reject(err)
+  );
+  const response = await PromisE.retry(doFetch, {
+    ...options,
+    retryIf: (res, count) => {
+      var _a;
+      return !(res == null ? void 0 : res.ok) && ((_a = options == null ? void 0 : options.retryIf) == null ? void 0 : _a.call(options, res, count)) !== false;
+    }
+  }).catch((err) => {
+    if (!(options == null ? void 0 : options.retry)) return Promise.reject(err);
+    const msg = `Request failed after attempt #${(options.retry || 0) + 1}`;
+    return Promise.reject(new Error(msg, { cause: err }));
+  });
+  return response;
+};
+var getResponse_default = getResponse;
+
+// src/fetch.ts
+function fetch(url, options = {}) {
+  var _a;
+  let abortCtrl;
+  let timeoutId;
+  (_a = options.method) != null ? _a : options.method = "get";
+  const promise = new PromisE2(async (resolve, reject) => {
+    var _a2, _b;
+    const _options = mergeFetchOptions_default(options);
+    const errorInterceptors = [..._options.interceptors.error];
+    const requestInterceptors = [..._options.interceptors.request];
+    const responseInterceptors = [..._options.interceptors.response];
+    const resultInterceptors = [..._options.interceptors.result];
+    url = await executeInterceptors_default(url, requestInterceptors, url, _options);
+    const { as: parseAs, errMsgs, timeout } = _options;
+    if (isPositiveNumber(timeout)) {
+      (_a2 = _options.abortCtrl) != null ? _a2 : _options.abortCtrl = new AbortController();
+      timeoutId = setTimeout(() => {
+        var _a3;
+        return (_a3 = _options.abortCtrl) == null ? void 0 : _a3.abort();
+      }, timeout);
+    }
+    abortCtrl = _options.abortCtrl;
+    if (_options.abortCtrl) _options.signal = _options.abortCtrl.signal;
+    let errResponse;
+    try {
+      if (!isUrlValid(url, false)) throw errMsgs.invalidUrl;
+      let response = await getResponse_default(url, _options);
+      response = await executeInterceptors_default(
+        response,
+        responseInterceptors,
+        url,
+        _options
+      );
+      errResponse = response;
+      const { status = 0 } = response;
+      const isSuccess = status >= 200 && status < 300;
+      if (!isSuccess) {
+        const jsonError = await response.json();
+        const message = (jsonError == null ? void 0 : jsonError.message) || `${errMsgs.requestFailed} ${status}.`;
+        throw new Error(`${message}`.replace("Error: ", ""), {
+          cause: jsonError
+        });
+      }
+      let result = response;
+      const parseFunc = response[parseAs];
+      if (isFn2(parseFunc)) {
+        const handleErr = (err) => {
+          var _a3, _b2;
+          err = new Error(
+            [
+              errMsgs.parseFailed,
+              parseAs + ".",
+              (_b2 = `${(_a3 = err == null ? void 0 : err.message) != null ? _a3 : err}`) == null ? void 0 : _b2.replace("Error: ", "")
+            ].join(" "),
+            { cause: err }
+          );
+          return globalThis.Promise.reject(err);
+        };
+        result = parseFunc();
+        if (isPromise(result)) result = result.catch(handleErr);
+        result = await executeInterceptors_default(
+          result,
+          resultInterceptors,
+          url,
+          _options
+        );
+      }
+      resolve(await result);
+    } catch (err) {
+      const errX = err;
+      let error = new FetchError(
+        (errX == null ? void 0 : errX.name) === "AbortError" ? errMsgs.reqTimedout : err instanceof Error ? err.message : String(err),
+        {
+          cause: (_b = errX == null ? void 0 : errX.cause) != null ? _b : err,
+          response: errResponse,
+          options: _options,
+          url
+        }
+      );
+      error = await executeInterceptors_default(
+        error,
+        errorInterceptors,
+        url,
+        _options
+      );
+      reject(error);
+    }
+    timeoutId && clearTimeout(timeoutId);
+  });
+  promise.onEarlyFinalize.push(() => abortCtrl == null ? void 0 : abortCtrl.abort());
+  return promise;
+}
+var fetch_default = fetch;
+
+// src/fetchDeferred.ts
+import { forceCast } from "@superutils/core";
+import PromisE3 from "@superutils/promise";
+import {
+  ResolveError,
+  ResolveIgnored
+} from "@superutils/promise";
+function fetchDeferred(deferOptions = {}, defaultUrl, defaultOptions) {
+  let _abortCtrl;
+  const fetchCallback = (...args) => {
+    var _a, _b;
+    const [url, options = {}] = args;
+    (_a = options.abortCtrl) != null ? _a : options.abortCtrl = new AbortController();
+    (_b = options.timeout) != null ? _b : options.timeout = defaultOptions == null ? void 0 : defaultOptions.timeout;
+    options.errMsgs = { ...defaultOptions == null ? void 0 : defaultOptions.errMsgs, ...options.errMsgs };
+    const { abortCtrl } = options;
+    _abortCtrl == null ? void 0 : _abortCtrl.abort();
+    _abortCtrl = abortCtrl;
+    const promise = fetch_default(
+      ...forceCast([
+        url != null ? url : defaultUrl,
+        mergeFetchOptions_default(defaultOptions != null ? defaultOptions : {}, options)
+      ])
+    );
+    promise.onEarlyFinalize.push(() => _abortCtrl == null ? void 0 : _abortCtrl.abort());
+    return promise;
+  };
+  return PromisE3.deferredCallback(fetchCallback, deferOptions);
+}
+var fetchDeferred_default = fetchDeferred;
+
+// src/postDeferred.ts
+import { forceCast as forceCast2 } from "@superutils/core";
+import PromisE4 from "@superutils/promise";
+
+// src/post.ts
+import { isStr } from "@superutils/core";
+function post(...[url = "", data, options = {}]) {
+  return fetch_default(
+    url,
+    mergeFetchOptions_default(
+      {
+        method: "post",
+        body: isStr(data) ? data : JSON.stringify(data)
+      },
+      options
+    )
+  );
+}
+
+// src/postDeferred.ts
+import {
+  ResolveError as ResolveError2,
+  ResolveIgnored as ResolveIgnored2
+} from "@superutils/promise";
+function postDeferred(deferOptions = {}, defaultUrl, defaultData, defaultOptions) {
+  let _abortCtrl;
+  const doPost = (...[url, data, options = {}]) => {
+    var _a;
+    (_a = options.abortCtrl) != null ? _a : options.abortCtrl = new AbortController();
+    _abortCtrl == null ? void 0 : _abortCtrl.abort();
+    _abortCtrl = options.abortCtrl;
+    const mergedOptions = mergeFetchOptions_default(options, defaultOptions != null ? defaultOptions : {});
+    const promise = post(
+      ...forceCast2([
+        url != null ? url : defaultUrl,
+        data != null ? data : defaultData,
+        mergedOptions
+      ])
+    );
+    promise.onEarlyFinalize.push(() => _abortCtrl == null ? void 0 : _abortCtrl.abort());
+    return promise;
+  };
+  return PromisE4.deferredCallback(doPost, deferOptions);
+}
+var postDeferred_default = postDeferred;
+
+// src/index.ts
+var fetchGet = (method = "get") => {
+  const methodFunc = ((url, options = {}) => {
+    ;
+    options.method = method;
+    return fetch_default(url, options);
+  });
+  methodFunc.deferred = (...args) => fetchDeferred_default(...args);
+  return methodFunc;
+};
+var fetchPost = (method = "post") => {
+  const methodFunc = ((url, options = {}) => {
+    ;
+    options.method = method;
+    return post(url, options);
+  });
+  methodFunc.deferred = (...args) => postDeferred_default(...args);
+  return methodFunc;
+};
+var fetch2 = fetch_default;
+fetch2.get = fetchGet("get");
+fetch2.head = fetchGet("head");
+fetch2.delete = fetchGet("options");
+fetch2.delete = fetchPost("delete");
+fetch2.patch = fetchPost("patch");
+fetch2.post = fetchPost("post");
+fetch2.put = fetchPost("put");
+var index_default = fetch2;
+export {
+  FetchAs,
+  FetchError,
+  config,
+  index_default as default,
+  fetch2 as fetch,
+  fetchDeferred,
+  mergeFetchOptions,
+  postDeferred
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+	"author": "Toufiqur Rahaman Chowdhury",
+	"description": "Fetch utilities",
+	"dependencies": {
+		"@superutils/core": "^1.0.1",
+		"@superutils/promise": "^1.0.2"
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"keywords": [
+		"promise",
+		"async",
+		"util",
+		"typescript"
+	],
+	"license": "MIT",
+	"main": "dist/index.js",
+	"name": "@superutils/fetch",
+	"peerDependencies": {
+		"@superutils/core": "^1.0.1",
+		"@superutils/promise": "^1.0.2"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"_build": "tsc -p tsconfig.json",
+		"_watch": "tsc -p tsconfig.json --watch",
+		"build": "tsup src/index.ts --format esm --dts --clean --config ../../tsup.config.js",
+		"dev": "npm run build -- --watch",
+		"test": "cd ../../ && npm run test promise"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"types": "dist/index.d.ts",
+	"version": "0.1.0"
+}