@superutils/fetch 1.2.3 → 1.3.0

package/README.md

@@ -67,39 +67,39 @@ All fetch calls return a `PromisE` (`@superutils/promise`) instance which means
 
 1. Status tracking: all instances come with `.pending`, `.resolved` and `.rejected` attributes that indicate the current state of the promise.
 
-    ```javascript
-    import fetch from '@superutils/fetch'
+```javascript
+import fetch from '@superutils/fetch'
 
-    const request = fetch('https://dummyjson.com/products/1')
+const request = fetch('https://dummyjson.com/products/1')
 
-    console.log(request.pending) // true
+console.log(request.pending) // true
 
-    request.then(() => {
-    	console.log(request.resolved) // true
-    	console.log(request.pending) // false
-    	console.log(request.rejected) // false
-    })
-    ```
+request.then(() => {
+	console.log(request.resolved) // true
+	console.log(request.pending) // false
+	console.log(request.rejected) // false
+})
+```
 
 2. Early finalization: all `PromisE` instances expose `.resolve()` and `.reject()` methods that allow early finalization and `.onEarlyFinalize` array that allows adding callbacks to be executed when the promise is finalized externally using these methods. Fetch promises utilize this to abort the request when appropriate.
 
-    ```javascript
-    import fetch from '@superutils/fetch'
+```javascript
+import fetch from '@superutils/fetch'
 
-    // Request that will take 5 seconds to resolve
-    const request = fetch('https://dummyjson.com/products?delay=5000')
+// Request that will take 5 seconds to resolve
+const request = fetch('https://dummyjson.com/products?delay=5000')
 
-    request.then(result => console.log(result), console.warn)
+request.then(result => console.log(result), console.warn)
 
-    // Add a callback to do stuff whenever request is aborted externally.
-    // This will not be invoked if fetch fails or resolves (promise finalized naturally) using the Promise executor.
-    request.onEarlyFinalize.push((resolved, valueOrReason) =>
-    	console.log('Aborted externally:', { resolved, valueOrReason }),
-    )
+// Add a callback to do stuff whenever request is aborted externally.
+// This will not be invoked if fetch fails or resolves (promise finalized naturally) using the Promise executor.
+request.onEarlyFinalize.push((resolved, valueOrReason) =>
+	console.log('Aborted externally:', { resolved, valueOrReason }),
+)
 
-    // resolve/reject before the promise is finalized
-    request.reject(new Error('No longer needed'))
-    ```
+// resolve/reject before the promise is finalized
+request.reject(new Error('No longer needed'))
+```
 
 <div id="methods"></div>
 
@@ -362,86 +362,82 @@ The following interceptor callbacks allow intercepting and/or transforming at di
 - Value returned (transformed) by an interceptor will be carried over to the subsequent interceptor of the same type.
 - There are 2 category of interceptors:
     - Local: interceptors provided when making a request.
+    - Global: interceptors that are executed application-wide on every request. Global interceptors can be added/accessed at `fetch.defaults.interceptors`. Global interceptors are always executed before local interceptors.
 
-    **Example: Interceptor usage**
-
-    ```javascript
-    import fetch, { FetchError } from '@superutils/fetch'
-
-    const interceptors = {
-    	error: [
-    		(err, url, options) => {
-    			console.log('Request failed', err, url, options)
-    			// return nothing/undefined to keep the error unchanged
-    			// or return modified/new error
-    			err.message = 'My custom error message!'
-    			// or create a new FetchError by cloning it (make sure all the required properties are set correctly)
-    			return err.clone('My custom error message!')
-    		},
-    	],
-    	request: [
-    		(url, options) => {
-    			// add extra headers or modify request options here
-    			options.headers.append('x-custom-header', 'some value')
-
-    			// transform the URL by returning a modified URL
-    			return url + '?param=value'
-    		},
-    	],
-    	response: [
-    		(response, url, options) => {
-    			if (response.ok) return
-    			console.log('request was successful', { url, options })
-
-    			// You can transform the response by returning different `Response` object or even make a completely new HTTP reuqest.
-    			// You can transform the response by returning different `Response` object or even make a completely new HTTP request.
-    			// The subsequent response interceptors will receive the returned response
-    			return fetch('https://dummyjson.com/products/1') // promise will be resolved automatically
-    		},
-    	],
-    	result: [
-    		(result, url, options) => {
-    			const productId = Number(
-    				new URL(url).pathname.split('/products/')[1],
-    			)
-    			if (options.method === 'get' && !Number.isNaN(productId)) {
-    				result.title ??= 'Unknown title'
-    			}
-    			return result
-    		},
-    	],
-    }
-    fetch
-    	.get('https://dummyjson.com/products/1', { interceptors })
-    	.then(product => console.log({ product }))
-    ```
+**Example: Interceptor usage**
 
-    - Global: interceptors that are executed application-wide on every request. Global interceptors can be added/accessed at `fetch.defaults.interceptors`. Global interceptors are always executed before local interceptors.
+```javascript
+import fetch, { FetchError } from '@superutils/fetch'
+
+const interceptors = {
+	error: [
+		(err, url, options) => {
+			console.log('Request failed', err, url, options)
+			// return nothing/undefined to keep the error unchanged
+			// or return modified/new error
+			err.message = 'My custom error message!'
+			// or create a new FetchError by cloning it (make sure all the required properties are set correctly)
+			return err.clone('My custom error message!')
+		},
+	],
+	request: [
+		(url, options) => {
+			// add extra headers or modify request options here
+			options.headers.append('x-custom-header', 'some value')
+
+			// transform the URL by returning a modified URL
+			return url + '?param=value'
+		},
+	],
+	response: [
+		(response, url, options) => {
+			if (response.ok) return
+			console.log('request was successful', { url, options })
+
+			// You can transform the response by returning different `Response` object or even make a completely new HTTP reuqest.
+			// You can transform the response by returning different `Response` object or even make a completely new HTTP request.
+			// The subsequent response interceptors will receive the returned response
+			return fetch('https://dummyjson.com/products/1') // promise will be resolved automatically
+		},
+	],
+	result: [
+		(result, url, options) => {
+			const productId = Number(
+				new URL(url).pathname.split('/products/')[1],
+			)
+			if (options.method === 'get' && !Number.isNaN(productId)) {
+				result.title ??= 'Unknown title'
+			}
+			return result
+		},
+	],
+}
+fetch
+	.get('https://dummyjson.com/products/1', { interceptors })
+	.then(product => console.log({ product }))
+```
 
-        **Example: Add global request and error interceptors**
+**Example: Add global request and error interceptors**
 
-        ```javascript
-        import fetch from '@superutils/fetch'
+```javascript
+import fetch from '@superutils/fetch'
 
-        const { interceptors } = fetch.defaults
+const { interceptors } = fetch.defaults
 
-        interceptors.request.push((url, options) => {
-        	// a headers to all requests make by the application
-        	// add headers to all requests made by the application
-        	options.headers.append('x-auth', 'token')
-        })
+interceptors.request.push((url, options) => {
+	// a headers to all requests make by the application
+	// add headers to all requests made by the application
+	options.headers.append('x-auth', 'token')
+})
 
-        interceptors.error.push((err, url, options) => {
-        	// log whenever a request fails
-        	console.log('Error interceptor', err)
-        })
+interceptors.error.push((err, url, options) => {
+	// log whenever a request fails
+	console.log('Error interceptor', err)
+})
 
-        // Each time a requst is made using @superutils/fetch, the above interceptors will be executed when appropriate
-        fetch('https://dummyjson.com/products/1').then(
-        	console.log,
-        	console.warn,
-        )
-        ```
+// Each time a requst is made using @superutils/fetch, the above interceptors will be executed when appropriate
+fetch('https://dummyjson.com/products/1').then(console.log, console.warn)
+```
 
 <div id="retry"></div>
 
@@ -569,7 +565,7 @@ While `createClient()` is versatile enough for any HTTP method, `createPostClien
 Similar to `createClient`, the returned function comes equipped with a `.deferred()` method, enabling debounced, throttled, or sequential execution.
 
 ```javascript
-import { createPostClient, FetchAs } from '@superutils/fetch'
+import { createPostClient } from '@superutils/fetch'
 
 // Create a POST client with 10-second as the default timeout
 const postClient = createPostClient(
@@ -591,8 +587,9 @@ postClient(
 const updateProduct = postClient.deferred(
 	{
 		delayMs: 300, // debounce duration
+		onResult: console.log, // prints only successful results
 	},
-	'https://dummyjson.com/products/1',
+	'https://dummyjson.com/products/add',
 	{
 		method: 'patch',
 		timeout: 3000,

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _superutils_promise from '@superutils/promise';
-import { RetryOptions, RetryIfFunc, DeferredAsyncOptions, IPromisE } from '@superutils/promise';
+import { RetryOptions, RetryIfFunc, DeferredAsyncOptions, IPromisE_Timeout } from '@superutils/promise';
 export { DeferredAsyncOptions, ResolveError, ResolveIgnored } from '@superutils/promise';
 import { ValueOrPromise } from '@superutils/core';
 
@@ -19,16 +19,6 @@ declare const ContentType: {
     readonly TEXT_PLAIN: "text/plain";
     readonly VIDEO_MP4: "video/mp4";
 };
-type ExcludeOptions<Target, // options to exclude
-Options extends FetchOptions = FetchOptions> = Target extends FetchOptions ? {
-    headers?: Options['headers'];
-} & Omit<Options, 'headers' | keyof Target> & Partial<Record<Exclude<keyof Target, 'headers'>, never>> : Options;
-type ExcludePostOptions<Target> = ExcludeOptions<Target, PostOptions>;
-type FetchArgs = [url: string | URL, options?: FetchOptions];
-type FetchArgsInterceptor = [
-    url: string | URL,
-    options: FetchOptionsInterceptor
-];
 declare enum FetchAs {
     arrayBuffer = "arrayBuffer",
     blob = "blob",
@@ -38,53 +28,18 @@ declare enum FetchAs {
     response = "response",
     text = "text"
 }
-/** Extract `FetchAs` from `FetchOptions` */
-type FetchAsFromOptions<TOptions, TFallback = FetchAs.json> = TOptions extends {
-    as: infer As;
-} ? As extends FetchAs ? As : TFallback : TFallback;
-/** Custom fetch options (not used by built-in `fetch()`*/
-type FetchCustomOptions = {
-    /**
-     * Specify how the parse the result. To get raw response use {@link FetchAs.response}.
-     * Default: 'json'
-     */
-    as?: FetchAs;
-    abortCtrl?: AbortController;
-    body?: PostBody | (() => PostBody);
-    errMsgs?: FetchErrMsgs;
-    interceptors?: FetchInterceptors;
-    /** Request timeout in milliseconds. */
-    timeout?: number;
-    validateUrl?: boolean;
-} & FetchRetryOptions;
-/** Default args */
-type FetchDeferredArgs<OmitMethod extends boolean = false> = [
-    url?: string | URL,
-    options?: Omit<FetchOptions, 'abortCtrl' | (OmitMethod extends true ? 'method' : never)>
-];
-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;
-    });
-    clone: (newMessage: string) => FetchError;
-}
+
+/**
+ * Generic definition for interceptor and transformer callbacks used throughout the fetch lifecycle.
+ */
+type Interceptor<T, TArgs extends unknown[]> = (...args: [value: T, ...TArgs]) => ValueOrPromise<void> | ValueOrPromise<T>;
 /**
  * Fetch error interceptor to be invoked whenever an exception occurs.
  * This interceptor can also be used as the error transformer by returning {@link FetchError}.
  *
+ * Note: The error interceptor is only triggered if the request ultimately fails. If retries are enabled (`retry > 0`)
+ * and a subsequent attempt succeeds, this interceptor will not be invoked for the intermediate failures.
+ *
  * @param	{FetchError}	fetchError custom error that also contain URL, options & response
  *
  * @returns returning undefined or not returning anything will not override the error
@@ -217,10 +172,10 @@ type FetchInterceptorResult<Args extends unknown[] = FetchArgsInterceptor> = Int
 /**
  * All valid interceptors for fetch requests are:
  * ---
- * 1. error,
+ * 1. error
  * 2. request
  * 3. response
- * 4. result.
+ * 4. result
  *
  * An interceptor can be any of the following:
  * ---
@@ -239,10 +194,9 @@ type FetchInterceptorResult<Args extends unknown[] = FetchArgsInterceptor> = Int
  * 1. Any exception thrown by interceptors will gracefully ignored.
  * 2. Interceptors will be executed in the sequence they're given.
  * 3. Execution priority: global interceptors will always be executed before local interceptors.
+ * 4. The following options cannot be modified using interceptors: abortCtrl, as, signal, timeout
  *
- *
- *
- * More info & examples:
+ * More info about specific interceptor types & examples:
  * ---
  * See the following for more details and examples:
  *
@@ -252,24 +206,108 @@ type FetchInterceptorResult<Args extends unknown[] = FetchArgsInterceptor> = Int
  * - `result`: {@link FetchInterceptorResult}
  */
 type FetchInterceptors = {
+    /** Request error interceptors/transformers. See {@link FetchInterceptorError} for more details. */
     error?: FetchInterceptorError[];
+    /** Request request interceptors/transformers. See {@link FetchInterceptorRequest} for more details. */
     request?: FetchInterceptorRequest[];
+    /** Request response interceptors/transformers. See {@link FetchInterceptorResponse} for more details. */
     response?: FetchInterceptorResponse[];
+    /** Request result interceptors/transformers. See {@link FetchInterceptorResult} for more details. */
     result?: FetchInterceptorResult[];
 };
+
+type ExcludeOptions<Target, // options to exclude
+Options extends FetchOptions = FetchOptions> = Target extends FetchOptions ? {
+    headers?: Options['headers'];
+} & Omit<Options, 'headers' | keyof Target> & Partial<Record<Exclude<keyof Target, 'headers'>, never>> : Options;
+type ExcludePostOptions<Target> = ExcludeOptions<Target, PostOptions>;
+type FetchArgs = [url: string | URL, options?: FetchOptions];
+type FetchArgsInterceptor = [
+    url: string | URL,
+    options: FetchOptionsInterceptor
+];
+/** Extract `FetchAs` from `FetchOptions` */
+type FetchAsFromOptions<TOptions, TFallback = FetchAs.json> = TOptions extends {
+    as: infer As;
+} ? As extends FetchAs ? As : TFallback : TFallback;
+/** Custom fetch options (not used by built-in `fetch()`*/
+type FetchCustomOptions = {
+    /**
+     * Specify how the parse the result. To get raw response use {@link FetchAs.response}.
+     * Default: 'json'
+     */
+    as?: FetchAs;
+    /**
+     * An `AbortController` instance to control the request.
+     *
+     * If not provided, a new instance is automatically created internally.
+     *
+     * It is supported in addition to the standard `signal`. If both are provided, `abortCtrl` will be aborted
+     * when the `signal` aborts or when the request times out.
+     *
+     * Recommendation:
+     * - For request timeout purposes, setting a timeout duration will be sufficient.
+     * Abort controller/signal is not needed.
+     * - Use `abortCtrl` instead of `signal` to prevent creating internal `AbortController` instance.
+     */
+    abortCtrl?: AbortController;
+    body?: PostBody | (() => PostBody);
+    /**
+     * 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).
+     *
+     * Default: `globalThis.fetch`
+     */
+    fetchFunc?: (...args: FetchArgs) => Promise<Response>;
+    errMsgs?: FetchErrMsgs;
+    /**
+     * Interceptor/transformer callback executed at different stages of the request.
+     * See {@link FetchInterceptors} for more details.
+     */
+    interceptors?: FetchInterceptors;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Whether to validate URL before making the request. Default: `true` */
+    validateUrl?: boolean;
+} & FetchRetryOptions;
+/** Default args */
+type FetchDeferredArgs<OmitMethod extends boolean = false> = [
+    url?: string | URL,
+    options?: Omit<FetchOptions, 'abortCtrl' | (OmitMethod extends true ? 'method' : never)>
+];
+type FetchErrMsgs = {
+    /** Error message to be used when request is aborted without specifying a message */
+    aborted?: string;
+    /** Error message to be use when URL validation fails */
+    invalidUrl?: string;
+    /** Error message to be used when request parse failes */
+    parseFailed?: string;
+    /** Error message to be used when request times out */
+    timedout?: string;
+    /** Error message to be used when request fails */
+    requestFailed?: string;
+};
 /**
  * Fetch request options
  */
 type FetchOptions = Omit<RequestInit, 'body'> & FetchCustomOptions;
-type FetchOptionsDefaults = Omit<FetchOptionsInterceptor, 'as' | 'method'>;
+/** Default fetch options */
+type FetchOptionsDefault = Omit<FetchOptionsInterceptor, 'abortCtrl' | 'as' | 'method' | 'signal' | 'timeout'> & {
+    /** Request timeout duration in milliseconds. Default: `30_000` (30 seconds) */
+    timeout: number;
+};
 /**
- * Fetch options available to interceptors
+ * Fetch options available to interceptors.
+ *
  */
-type FetchOptionsInterceptor = Omit<FetchOptions, 'as' | 'errMsgs' | 'interceptors' | 'headers' | keyof FetchRetryOptions> & {
+type FetchOptionsInterceptor = Omit<FetchOptions, 'as' | 'errMsgs' | 'interceptors' | 'headers' | 'timeout' | keyof FetchRetryOptions> & {
     as: FetchAs;
+    /** Error messages */
     errMsgs: Required<FetchErrMsgs>;
     headers: Headers;
+    /** Interceptors/transformers for fetch requests. See {@link FetchInterceptors} for more details. */
     interceptors: Required<FetchInterceptors>;
+    timeout: number;
 } & FetchRetryOptions;
 /**
  * Result types for specific parsers ("as": FetchAs)
@@ -297,10 +335,6 @@ type FetchRetryOptions = Omit<Partial<RetryOptions>, 'retry' | 'retryIf'> & {
     retry?: number;
     retryIf?: RetryIfFunc<Response>;
 };
-/**
- * Generic fetch interceptor type
- */
-type Interceptor<T, TArgs extends unknown[]> = (...args: [value: T, ...TArgs]) => ValueOrPromise<void> | ValueOrPromise<T>;
 type PostBody = Record<string, unknown> | BodyInit | null;
 type PostArgs<OmitMethod = false> = [
     url: string | URL,
@@ -356,6 +390,21 @@ type PostOptions = {
     method?: 'post' | 'put' | 'patch' | 'delete' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 } & Omit<FetchOptions, 'method'>;
 
+/** Custom error message for fetch requests with more detailed info about the request URL, fetch options and response */
+declare class FetchError extends Error {
+    /** Create a new `FetchError` with a new `message` while preserving all metadata */
+    clone: (newMessage: string) => FetchError;
+    options: FetchOptions;
+    response: Response | undefined;
+    url: string | URL;
+    constructor(message: string, options: {
+        cause?: unknown;
+        options: FetchOptions;
+        response?: Response;
+        url: string | URL;
+    });
+}
+
 /**
  * Create a reusable fetch client with shared options. The returned function comes attached with a
  * `.deferred()` function for debounce and throttle behavior.
@@ -417,8 +466,8 @@ declare const createClient: <FixedOpts extends FetchOptions | undefined, CommonO
 fixedOptions?: FixedOpts, 
 /** Common fetch options that can be overriden by individual request */
 commonOptions?: FetchOptions & CommonOpts, commonDeferOptions?: DeferredAsyncOptions<unknown, unknown>) => {
-    <T, TOptions extends ExcludeOptions<FixedOpts> | undefined = ExcludeOptions<FixedOpts> | undefined, TAs extends FetchAs = FixedAs extends FetchAs ? FixedAs : FetchAsFromOptions<TOptions, FetchAsFromOptions<CommonOpts>>, TReturn = FetchResult<T>[TAs]>(url: FetchArgs[0], options?: TOptions): IPromisE<TReturn>;
-    deferred<ThisArg = unknown, Delay extends number = number, DefaultUrl extends FetchArgs[0] | undefined = string | URL | undefined, DefaultOptions extends ExcludeOptions<FixedOpts> | undefined = ExcludeOptions<FixedOpts> | undefined>(deferOptions?: DeferredAsyncOptions<ThisArg, Delay>, defaultUrl?: DefaultUrl, defaultOptions?: DefaultOptions): <TResult = unknown, TOptions_1 extends ExcludeOptions<FixedOpts> | undefined = ExcludeOptions<FixedOpts> | undefined, TAs_1 extends FetchAs = FixedAs extends FetchAs ? FixedAs : FetchAsFromOptions<TOptions_1, FetchAsFromOptions<CommonOpts>>, TReturn_1 = FetchResult<TResult>[TAs_1]>(...args: DefaultUrl extends undefined ? [url: FetchArgs[0], options?: TOptions_1] : [options?: TOptions_1]) => IPromisE<TReturn_1>;
+    <T, TOptions extends ExcludeOptions<FixedOpts> | undefined = ExcludeOptions<FixedOpts> | undefined, TAs extends FetchAs = FixedAs extends FetchAs ? FixedAs : FetchAsFromOptions<TOptions, FetchAsFromOptions<CommonOpts>>, TReturn = FetchResult<T>[TAs]>(url: FetchArgs[0], options?: TOptions): _superutils_promise.IPromisE_Timeout<TReturn>;
+    deferred<ThisArg = unknown, Delay extends number = number, DefaultUrl extends FetchArgs[0] | undefined = string | URL | undefined, DefaultOptions extends ExcludeOptions<FixedOpts> | undefined = ExcludeOptions<FixedOpts> | undefined>(deferOptions?: DeferredAsyncOptions<ThisArg, Delay>, defaultUrl?: DefaultUrl, defaultOptions?: DefaultOptions): <TResult = unknown, TOptions_1 extends ExcludeOptions<FixedOpts> | undefined = ExcludeOptions<FixedOpts> | undefined, TAs_1 extends FetchAs = FixedAs extends FetchAs ? FixedAs : FetchAsFromOptions<TOptions_1, FetchAsFromOptions<CommonOpts>>, TReturn_1 = FetchResult<TResult>[TAs_1]>(...args: DefaultUrl extends undefined ? [url: FetchArgs[0], options?: TOptions_1] : [options?: TOptions_1]) => _superutils_promise.IPromisE_Timeout<TReturn_1>;
 };
 
 /**
@@ -455,8 +504,9 @@ commonOptions?: FetchOptions & CommonOpts, commonDeferOptions?: DeferredAsyncOpt
  * const updateProduct = postClient.deferred(
  * 	{
  * 		delayMs: 300, // debounce duration
+ * 		onResult: console.log, // prints only successful results
  * 	},
- * 	'https://dummyjson.com/products/1',
+ * 	'https://dummyjson.com/products/add',
  * 	{
  * 		method: 'patch',
  * 		timeout: 3000,
@@ -471,24 +521,12 @@ declare const createPostClient: <FixedOpts extends PostOptions | undefined, Comm
 fixedOptions?: FixedOpts, 
 /** Common fetch options that can be overriden by individual request */
 commonOptions?: PostOptions & CommonOpts, commonDeferOptions?: DeferredAsyncOptions<unknown, unknown>) => {
-    <T = unknown, TOptions extends ExcludePostOptions<FixedOpts> | undefined = ExcludePostOptions<FixedOpts> | undefined, TAs extends FetchAs = FixedAs extends FetchAs ? FixedAs : FetchAsFromOptions<TOptions, FetchAsFromOptions<CommonOpts>>, TReturn = FetchResult<T>[TAs]>(url: PostArgs[0], data?: PostArgs[1], options?: TOptions): IPromisE<TReturn>;
-    deferred<ThisArg, Delay extends number, DefaultUrl extends PostArgs[0] | undefined, DefaultData extends PostArgs[1] = undefined, DefaultOptions extends ExcludePostOptions<FixedOpts> | undefined = undefined>(deferOptions?: DeferredAsyncOptions<ThisArg, Delay>, defaultUrl?: DefaultUrl, defaultData?: DefaultData, defaultOptions?: DefaultOptions): <TResult = unknown, TOptions_1 extends ExcludePostOptions<FixedOpts> | undefined = ExcludePostOptions<FixedOpts>, TAs_1 extends FetchAs = FixedAs extends FetchAs ? FixedAs : FetchAsFromOptions<TOptions_1, FetchAsFromOptions<CommonOpts>>, TReturn_1 = FetchResult<TResult>[TAs_1]>(...args: PostDeferredCbArgs<DefaultUrl, DefaultData, TOptions_1>) => IPromisE<TReturn_1>;
+    <T = unknown, TOptions extends ExcludePostOptions<FixedOpts> | undefined = ExcludePostOptions<FixedOpts> | undefined, TAs extends FetchAs = FixedAs extends FetchAs ? FixedAs : FetchAsFromOptions<TOptions, FetchAsFromOptions<CommonOpts>>, TReturn = FetchResult<T>[TAs]>(url: PostArgs[0], data?: PostArgs[1], options?: TOptions): IPromisE_Timeout<TReturn>;
+    deferred<ThisArg, Delay extends number, DefaultUrl extends PostArgs[0] | undefined, DefaultData extends PostArgs[1] = undefined, DefaultOptions extends ExcludePostOptions<FixedOpts> | undefined = undefined>(deferOptions?: DeferredAsyncOptions<ThisArg, Delay>, defaultUrl?: DefaultUrl, defaultData?: DefaultData, defaultOptions?: DefaultOptions): <TResult = unknown, TOptions_1 extends ExcludePostOptions<FixedOpts> | undefined = ExcludePostOptions<FixedOpts>, TAs_1 extends FetchAs = FixedAs extends FetchAs ? FixedAs : FetchAsFromOptions<TOptions_1, FetchAsFromOptions<CommonOpts>>, TReturn_1 = FetchResult<TResult>[TAs_1]>(...args: PostDeferredCbArgs<DefaultUrl, DefaultData, TOptions_1>) => IPromisE_Timeout<TReturn_1>;
 };
 
-/**
- * Gracefully executes interceptors and returns the processed value.
- * If the value is not transformed (by returning a new value) by the interceptors,
- * the original value is returned.
- *
- * @param	value value to be passed to the interceptors
- * @param	interceptors interceptor callbacks
- * @param	args (optional) common arguments to be supplied to all the interceptors in addition to
- * the `value' which will always be the first argument.
- *
- * Interceptor arguments: `[value, ...args]`
- */
-declare const executeInterceptors: <T, TArgs extends unknown[]>(value: T, interceptors?: Interceptor<T, TArgs>[], ...args: TArgs) => Promise<T>;
-
+/** Node.js setTimeout limit is 2147483647 (2^31-1). Larger values fire immediately. */
+declare const MAX_TIMEOUT = 2147483647;
 /**
  * Extended `fetch` with timeout, retry, and other options. Automatically parses as JSON by default on success.
  *
@@ -508,9 +546,9 @@ declare const executeInterceptors: <T, TArgs extends unknown[]>(value: T, interc
  * ```
  */
 declare const fetch: {
-    <T, TOptions extends FetchOptions = FetchOptions, TAs extends FetchAs = TOptions["as"] extends FetchAs ? TOptions["as"] : FetchAs.json, TReturn = FetchResult<T>[TAs]>(url: string | URL, options?: FetchOptions & TOptions): IPromisE<TReturn>;
+    <T, TOptions extends FetchOptions = FetchOptions, TAs extends FetchAs = TOptions["as"] extends FetchAs ? TOptions["as"] : FetchAs.json, TReturn = FetchResult<T>[TAs]>(url: string | URL, options?: FetchOptions & TOptions): IPromisE_Timeout<TReturn>;
     /** Default fetch options */
-    defaults: FetchOptionsDefaults;
+    defaults: FetchOptionsDefault;
 };
 
 /**
@@ -528,7 +566,10 @@ declare const fetch: {
  *     .then(console.log, console.error)
  * ```
  */
-declare const fetchResponse: <T = Response, TOptions extends FetchOptions = FetchOptions, TAs extends FetchAs = TOptions["as"] extends FetchAs ? TOptions["as"] : FetchAs.response, TReturn = FetchResult<T>[TAs]>(url: FetchArgs[0], options: Parameters<typeof fetch<T, TOptions, TAs, TReturn>>[1]) => IPromisE<TReturn>;
+declare const fetchResponse: {
+    <T = Response, TOptions extends FetchOptions = FetchOptions, TAs extends FetchAs = TOptions["as"] extends FetchAs ? TOptions["as"] : FetchAs.response, TReturn = FetchResult<T>[TAs]>(url: FetchArgs[0], options?: Parameters<typeof fetch<T, TOptions, TAs, TReturn>>[1]): IPromisE_Timeout<TReturn>;
+    defaults: FetchOptionsDefault;
+};
 
 declare const methods: {
     /** Make HTTP requests with method GET */
@@ -537,7 +578,7 @@ declare const methods: {
             headers?: HeadersInit | undefined;
         } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
             headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<T>[TAs]>(url: FetchArgs[0], options?: TOptions | undefined): _superutils_promise.IPromisE<TReturn>;
+        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<T>[TAs]>(url: FetchArgs[0], options?: TOptions | undefined): _superutils_promise.IPromisE_Timeout<TReturn>;
         deferred<ThisArg = unknown, Delay extends number = number, DefaultUrl extends FetchArgs[0] | undefined = string | URL | undefined, DefaultOptions extends ({
             headers?: HeadersInit | undefined;
         } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
@@ -546,7 +587,7 @@ declare const methods: {
             headers?: HeadersInit | undefined;
         } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
             headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<TResult>[TAs]>(...args: DefaultUrl extends undefined ? [url: string | URL, options?: TOptions | undefined] : [options?: TOptions | undefined]) => _superutils_promise.IPromisE<TReturn>;
+        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<TResult>[TAs]>(...args: DefaultUrl extends undefined ? [url: string | URL, options?: TOptions | undefined] : [options?: TOptions | undefined]) => _superutils_promise.IPromisE_Timeout<TReturn>;
     };
     /** Make HTTP requests with method HEAD */
     head: {
@@ -554,7 +595,7 @@ declare const methods: {
             headers?: HeadersInit | undefined;
         } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
             headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<T>[TAs]>(url: FetchArgs[0], options?: TOptions | undefined): _superutils_promise.IPromisE<TReturn>;
+        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<T>[TAs]>(url: FetchArgs[0], options?: TOptions | undefined): _superutils_promise.IPromisE_Timeout<TReturn>;
         deferred<ThisArg = unknown, Delay extends number = number, DefaultUrl extends FetchArgs[0] | undefined = string | URL | undefined, DefaultOptions extends ({
             headers?: HeadersInit | undefined;
         } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
@@ -563,7 +604,7 @@ declare const methods: {
             headers?: HeadersInit | undefined;
         } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
             headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<TResult>[TAs]>(...args: DefaultUrl extends undefined ? [url: string | URL, options?: TOptions | undefined] : [options?: TOptions | undefined]) => _superutils_promise.IPromisE<TReturn>;
+        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<TResult>[TAs]>(...args: DefaultUrl extends undefined ? [url: string | URL, options?: TOptions | undefined] : [options?: TOptions | undefined]) => _superutils_promise.IPromisE_Timeout<TReturn>;
     };
     /** Make HTTP requests with method OPTIONS */
     options: {
@@ -571,7 +612,7 @@ declare const methods: {
             headers?: HeadersInit | undefined;
         } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
             headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<T>[TAs]>(url: FetchArgs[0], options?: TOptions | undefined): _superutils_promise.IPromisE<TReturn>;
+        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<T>[TAs]>(url: FetchArgs[0], options?: TOptions | undefined): _superutils_promise.IPromisE_Timeout<TReturn>;
         deferred<ThisArg = unknown, Delay extends number = number, DefaultUrl extends FetchArgs[0] | undefined = string | URL | undefined, DefaultOptions extends ({
             headers?: HeadersInit | undefined;
         } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
@@ -580,7 +621,7 @@ declare const methods: {
             headers?: HeadersInit | undefined;
         } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
             headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<TResult>[TAs]>(...args: DefaultUrl extends undefined ? [url: string | URL, options?: TOptions | undefined] : [options?: TOptions | undefined]) => _superutils_promise.IPromisE<TReturn>;
+        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<TResult>[TAs]>(...args: DefaultUrl extends undefined ? [url: string | URL, options?: TOptions | undefined] : [options?: TOptions | undefined]) => _superutils_promise.IPromisE_Timeout<TReturn>;
     };
     /** Make HTTP requests with method DELETE */
     delete: {
@@ -588,14 +629,14 @@ declare const methods: {
             headers?: HeadersInit | undefined;
         } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
             headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<T>[TAs]>(url: PostArgs[0], data?: PostArgs[1], options?: TOptions | undefined): _superutils_promise.IPromisE<TReturn>;
+        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<T>[TAs]>(url: PostArgs[0], data?: PostArgs[1], options?: TOptions | undefined): _superutils_promise.IPromisE_Timeout<TReturn>;
         deferred<ThisArg, Delay extends number, DefaultUrl extends PostArgs[0] | undefined, DefaultData extends PostArgs[1] = undefined, DefaultOptions extends ({
             headers?: HeadersInit | undefined;
         } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = undefined>(deferOptions?: _superutils_promise.DeferredAsyncOptions<ThisArg, Delay>, defaultUrl?: DefaultUrl | undefined, defaultData?: DefaultData | undefined, defaultOptions?: DefaultOptions | undefined): <TResult = unknown, TOptions extends ({
             headers?: HeadersInit | undefined;
         } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = {
             headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<TResult>[TAs]>(...args: PostDeferredCbArgs<DefaultUrl, DefaultData, TOptions, [url: string | URL, data: PostBody | (() => PostBody), options: PostOptions]>) => _superutils_promise.IPromisE<TReturn>;
+        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<TResult>[TAs]>(...args: PostDeferredCbArgs<DefaultUrl, DefaultData, TOptions, [url: string | URL, data: PostBody | (() => PostBody), options: PostOptions]>) => _superutils_promise.IPromisE_Timeout<TReturn>;
     };
     /** Make HTTP requests with method PATCH */
     patch: {
@@ -603,14 +644,14 @@ declare const methods: {
             headers?: HeadersInit | undefined;
         } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
             headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<T>[TAs]>(url: PostArgs[0], data?: PostArgs[1], options?: TOptions | undefined): _superutils_promise.IPromisE<TReturn>;
+        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<T>[TAs]>(url: PostArgs[0], data?: PostArgs[1], options?: TOptions | undefined): _superutils_promise.IPromisE_Timeout<TReturn>;
         deferred<ThisArg, Delay extends number, DefaultUrl extends PostArgs[0] | undefined, DefaultData extends PostArgs[1] = undefined, DefaultOptions extends ({
             headers?: HeadersInit | undefined;
         } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = undefined>(deferOptions?: _superutils_promise.DeferredAsyncOptions<ThisArg, Delay>, defaultUrl?: DefaultUrl | undefined, defaultData?: DefaultData | undefined, defaultOptions?: DefaultOptions | undefined): <TResult = unknown, TOptions extends ({
             headers?: HeadersInit | undefined;
         } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = {
             headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<TResult>[TAs]>(...args: PostDeferredCbArgs<DefaultUrl, DefaultData, TOptions, [url: string | URL, data: PostBody | (() => PostBody), options: PostOptions]>) => _superutils_promise.IPromisE<TReturn>;
+        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<TResult>[TAs]>(...args: PostDeferredCbArgs<DefaultUrl, DefaultData, TOptions, [url: string | URL, data: PostBody | (() => PostBody), options: PostOptions]>) => _superutils_promise.IPromisE_Timeout<TReturn>;
     };
     /** Make HTTP requests with method POST */
     post: {
@@ -618,14 +659,14 @@ declare const methods: {
             headers?: HeadersInit | undefined;
         } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
             headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<T>[TAs]>(url: PostArgs[0], data?: PostArgs[1], options?: TOptions | undefined): _superutils_promise.IPromisE<TReturn>;
+        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<T>[TAs]>(url: PostArgs[0], data?: PostArgs[1], options?: TOptions | undefined): _superutils_promise.IPromisE_Timeout<TReturn>;
         deferred<ThisArg, Delay extends number, DefaultUrl extends PostArgs[0] | undefined, DefaultData extends PostArgs[1] = undefined, DefaultOptions extends ({
             headers?: HeadersInit | undefined;
         } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = undefined>(deferOptions?: _superutils_promise.DeferredAsyncOptions<ThisArg, Delay>, defaultUrl?: DefaultUrl | undefined, defaultData?: DefaultData | undefined, defaultOptions?: DefaultOptions | undefined): <TResult = unknown, TOptions extends ({
             headers?: HeadersInit | undefined;
         } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = {
             headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<TResult>[TAs]>(...args: PostDeferredCbArgs<DefaultUrl, DefaultData, TOptions, [url: string | URL, data: PostBody | (() => PostBody), options: PostOptions]>) => _superutils_promise.IPromisE<TReturn>;
+        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<TResult>[TAs]>(...args: PostDeferredCbArgs<DefaultUrl, DefaultData, TOptions, [url: string | URL, data: PostBody | (() => PostBody), options: PostOptions]>) => _superutils_promise.IPromisE_Timeout<TReturn>;
     };
     /** Make HTTP requests with method PUT */
     put: {
@@ -633,14 +674,14 @@ declare const methods: {
             headers?: HeadersInit | undefined;
         } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
             headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<T>[TAs]>(url: PostArgs[0], data?: PostArgs[1], options?: TOptions | undefined): _superutils_promise.IPromisE<TReturn>;
+        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<T>[TAs]>(url: PostArgs[0], data?: PostArgs[1], options?: TOptions | undefined): _superutils_promise.IPromisE_Timeout<TReturn>;
         deferred<ThisArg, Delay extends number, DefaultUrl extends PostArgs[0] | undefined, DefaultData extends PostArgs[1] = undefined, DefaultOptions extends ({
             headers?: HeadersInit | undefined;
         } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = undefined>(deferOptions?: _superutils_promise.DeferredAsyncOptions<ThisArg, Delay>, defaultUrl?: DefaultUrl | undefined, defaultData?: DefaultData | undefined, defaultOptions?: DefaultOptions | undefined): <TResult = unknown, TOptions extends ({
             headers?: HeadersInit | undefined;
         } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = {
             headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<TResult>[TAs]>(...args: PostDeferredCbArgs<DefaultUrl, DefaultData, TOptions, [url: string | URL, data: PostBody | (() => PostBody), options: PostOptions]>) => _superutils_promise.IPromisE<TReturn>;
+        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>, TAs extends FetchAs = FetchAsFromOptions<TOptions, FetchAs.json>, TReturn = FetchResult<TResult>[TAs]>(...args: PostDeferredCbArgs<DefaultUrl, DefaultData, TOptions, [url: string | URL, data: PostBody | (() => PostBody), options: PostOptions]>) => _superutils_promise.IPromisE_Timeout<TReturn>;
     };
 };
 /**
@@ -688,16 +729,29 @@ declare const methods: {
  * @param url
  * @param options (optional) Standard `fetch` options extended with {@link FetchCustomOptions}
  * @param options.abortCtrl (optional) if not provided `AbortController` will be instantiated when `timeout` used.
- * @param options.as (optional) (optional) specify how to parse the result. Default: {@link FetchAs.json}
+ *
+ * Default: `new AbortController()`
+ * @param options.as (optional) (optional) specify how to parse the result.
  * For raw `Response` use {@link FetchAs.response}
+ *
+ * Default: {@link FetchAs.json}
  * @param options.headers (optional) request headers
- * Default: `{ 'content-type': 'application/json' }` (or whaterver is set in the `fetch.defaults`).
- * @param options.interceptors (optional) request interceptor callbacks.  See {@link FetchInterceptors} for details.
- * @param options.method (optional) fetch method. Default: `'get'`
- * @param options.timeout (optional) duration in milliseconds to abort the request if it takes longer.
  *
+ * Default: `{ 'content-type': 'application/json' }`
+ * @param options.interceptors (optional) request interceptor/transformer callbacks.
+ * See {@link FetchInterceptors} for details.
+ * @param options.method (optional) fetch method.
+ *
+ * Default: `'get'`
+ * @param options.timeout (optional) duration in milliseconds to abort the request.
+ * This duration includes the execution of all interceptors/transformers.
+ *
+ * Default: `30_000`
+ *
+ * ---
  *
  * @example Drop-in replacement for built-in fetch
+ *
  * ```javascript
  * import fetch from '@superutils/fetch'
  *
@@ -729,27 +783,49 @@ declare const methods: {
  * ```typescript
  * import fetch from '@superutils/fetch'
  *
- * fetch.defaults = {
- *     errMsgs: {
- *        invalidUrl: 'Invalid URL',
- *        parseFailed: 'Failed to parse response as',
- *        reqTimedout: 'Request timed out',
- *        requestFailed: 'Request failed with status code:',
- *     },
- *     headers: new Headers([['content-type', 'application/json']]),
- * 	   // Global/application-wide Interceptor & Transfermers
- *     interceptors: {
- *     	   error: [],
- *     	   request: [],
- *     	   response: [],
- *     	   result: [],
- *     },
- *     timeout: 0,
- *     //........
- * }
+ * const { defaults, errorMsgs, interceptors } = fetch
+ *
+ * // set default request timeout duration in milliseconds
+ * defaults.timeout = 40_000
+ *
+ * // default headers
+ * defaults.headers = { 'content-type': 'text/plain' }
+ *
+ * // override error messages
+ * errorMsgs.invalidUrl = 'URL is not valid'
+ * errorMsgs.timedout = 'Request took longer than expected'
+ *
+ * // add an interceptor to log all request failures.
+ * const fetchLogger = (fetchErr, url, options) => console.log('Fetch error log', fetchErr)
+ * interceptors.error.push(fetchLogger)
+ *
+ * // add an interceptor to conditionally include header before making requests
+ * interceptors.request.push((url, options) => {
+ * 		// ignore login requests
+ *     if (`${url}`.includes('/login')) return
+ *
+ *     options.headers.set('x-auth-token', 'my-auth-token')
+ * })
  * ```
  */
-declare const fetchDefault: typeof fetchResponse & typeof methods;
+declare const defaultFetch: typeof fetchResponse & typeof methods;
+
+/**
+ * Gracefully executes interceptors and returns the processed value.
+ * If the value is not transformed (by returning a new value) by the interceptors,
+ * the original value is returned.
+ *
+ * @param	value value to be passed to the interceptors
+ * @param	signal The AbortController used to monitor the request status. If the signal is aborted (e.g. due to
+ * timeout or manual cancellation), the interceptor chain halts immediately. Note: This does not interrupt the
+ * currently executing interceptor, but prevents subsequent ones from running.
+ * @param	interceptors interceptor/transformer callbacks
+ * @param	args (optional) common arguments to be supplied to all the interceptors in addition to
+ * the `value' which will always be the first argument.
+ *
+ * Interceptor arguments: `[value, ...args]`
+ */
+declare const executeInterceptors: <T, TArgs extends unknown[]>(value: T, signal?: AbortSignal, interceptors?: Interceptor<T, TArgs>[], ...args: TArgs) => Promise<T>;
 
 /**
  * Add AbortController to options if not present and propagate external abort signal if provided.
@@ -788,4 +864,4 @@ declare const mergeFetchOptions: (...allOptions: FetchOptions[]) => FetchOptions
 /** Merges partial fetch options ignoring empty or undefined. Otherwise, will return the first argument. */
 declare const mergePartialOptions: (...optionsAr: (Partial<FetchOptions> | undefined)[]) => Partial<FetchOptions> | undefined;
 
-export { ContentType, type ExcludeOptions, type ExcludePostOptions, type FetchArgs, type FetchArgsInterceptor, FetchAs, type FetchAsFromOptions, type FetchCustomOptions, type FetchDeferredArgs, type FetchErrMsgs, FetchError, type FetchInterceptorError, type FetchInterceptorRequest, type FetchInterceptorResponse, type FetchInterceptorResult, type FetchInterceptors, type FetchOptions, type FetchOptionsDefaults, type FetchOptionsInterceptor, type FetchResult, type FetchRetryOptions, type Interceptor, type PostArgs, type PostBody, type PostDeferredCbArgs, type PostOptions, createClient, createPostClient, fetchDefault as default, executeInterceptors, fetch, fetchResponse, getAbortCtrl, getResponse, mergeFetchOptions, mergePartialOptions };
+export { ContentType, type ExcludeOptions, type ExcludePostOptions, type FetchArgs, type FetchArgsInterceptor, FetchAs, type FetchAsFromOptions, type FetchCustomOptions, type FetchDeferredArgs, type FetchErrMsgs, FetchError, type FetchInterceptorError, type FetchInterceptorRequest, type FetchInterceptorResponse, type FetchInterceptorResult, type FetchInterceptors, type FetchOptions, type FetchOptionsDefault, type FetchOptionsInterceptor, type FetchResult, type FetchRetryOptions, type Interceptor, MAX_TIMEOUT, type PostArgs, type PostBody, type PostDeferredCbArgs, type PostOptions, createClient, createPostClient, defaultFetch as default, executeInterceptors, fetch, fetchResponse, getAbortCtrl, getResponse, mergeFetchOptions, mergePartialOptions };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/createClient.ts
-import PromisE3 from "@superutils/promise";
+import { deferredCallback } from "@superutils/promise";
 
 // src/fetch.ts
 import {
@@ -9,13 +9,16 @@ import {
   isPromise,
   isUrlValid
 } from "@superutils/core";
-import PromisE2 from "@superutils/promise";
+import {
+  timeout as PromisE_timeout
+} from "@superutils/promise";
 
 // src/executeInterceptors.ts
 import { fallbackIfFails, isFn } from "@superutils/core";
-var executeInterceptors = async (value, interceptors, ...args) => {
+var executeInterceptors = async (value, signal, interceptors, ...args) => {
   var _a;
   for (const interceptor of [...interceptors != null ? interceptors : []].filter(isFn)) {
+    if (signal == null ? void 0 : signal.aborted) return value;
     value = (_a = await fallbackIfFails(
       interceptor,
       [value, ...args],
@@ -46,13 +49,13 @@ var getAbortCtrl = (options) => {
 
 // src/getResponse.ts
 import { fallbackIfFails as fallbackIfFails2, isPositiveInteger } from "@superutils/core";
-import PromisE from "@superutils/promise";
+import { retry } from "@superutils/promise";
 var getResponse = async (url, options = {}) => {
-  const fetchFunc = globalThis.fetch;
+  const { abortCtrl, fetchFunc = globalThis.fetch } = options;
   if (!isPositiveInteger(options.retry))
     return fetchFunc(url, options);
   let attemptCount = 0;
-  const response = PromisE.retry(
+  const response = retry(
     () => {
       attemptCount++;
       return fetchFunc(url, options);
@@ -61,6 +64,7 @@ var getResponse = async (url, options = {}) => {
       ...options,
       retryIf: async (res, count, error) => {
         var _a, _b;
+        if (abortCtrl == null ? void 0 : abortCtrl.signal.aborted) return false;
         const failed = !!error || !(res == null ? void 0 : res.ok);
         return !!((_b = await fallbackIfFails2(
           (_a = options == null ? void 0 : options.retryIf) != null ? _a : failed,
@@ -84,7 +88,7 @@ var getResponse_default = getResponse;
 import { isEmpty, isObj, objKeys } from "@superutils/core";
 var mergeFetchOptions = (...allOptions) => allOptions.reduce(
   (merged, next) => {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i;
     next = isObj(next) ? next : {};
     const { errMsgs = {}, headers, interceptors: ints1 = {} } = merged;
     const { errMsgs: msgs2 = {}, interceptors: ints2 = {} } = next;
@@ -114,7 +118,7 @@ var mergeFetchOptions = (...allOptions) => allOptions.reduce(
           ...(_h = ints2 == null ? void 0 : ints2.result) != null ? _h : []
         ]
       },
-      timeout: (_j = (_i = next.timeout) != null ? _i : merged.timeout) != null ? _j : 0
+      timeout: (_i = next.timeout) != null ? _i : merged.timeout
     };
   },
   { headers: new Headers() }
@@ -125,11 +129,7 @@ var mergePartialOptions = (...optionsAr) => {
   return optionsAr.length <= 1 ? optionsAr[0] : mergeFetchOptions(...optionsAr);
 };
 
-// src/types.ts
-import {
-  ResolveError,
-  ResolveIgnored
-} from "@superutils/promise";
+// src/types/constants.ts
 var ContentType = {
   APPLICATION_JAVASCRIPT: "application/javascript",
   APPLICATION_JSON: "application/json",
@@ -155,56 +155,99 @@ var FetchAs = /* @__PURE__ */ ((FetchAs2) => {
   FetchAs2["text"] = "text";
   return FetchAs2;
 })(FetchAs || {});
+
+// src/types/FetchError.ts
 var FetchError = class _FetchError extends Error {
   constructor(message, options) {
     super(message, { cause: options.cause });
-    this.clone = (newMessage) => new _FetchError(newMessage, {
-      cause: this.cause,
-      options: this.options,
-      response: this.response,
-      url: this.url
-    });
     this.name = "FetchError";
-    this.options = options.options;
-    this.response = options.response;
-    this.url = options.url;
+    Object.defineProperties(this, {
+      clone: {
+        get() {
+          return (newMessage) => new _FetchError(newMessage, {
+            cause: options.cause,
+            options: options.options,
+            response: options.response,
+            url: options.url
+          });
+        }
+      },
+      options: {
+        get() {
+          return options.options;
+        }
+      },
+      response: {
+        get() {
+          return options.response;
+        }
+      },
+      url: {
+        get() {
+          return options.url;
+        }
+      }
+    });
   }
 };
 
+// src/types/options.ts
+import {
+  ResolveError,
+  ResolveIgnored
+} from "@superutils/promise";
+
 // src/fetch.ts
+var MAX_TIMEOUT = 2147483647;
 var fetch = (url, options = {}) => {
-  let timeoutId;
-  const abortCtrl = getAbortCtrl(options);
-  const promise = new PromisE2(async (resolve, reject) => {
-    var _a, _b, _c;
-    let errResponse;
-    const _options = mergeFetchOptions_default(fetch.defaults, options);
-    (_a = _options.as) != null ? _a : _options.as = "json" /* json */;
-    (_b = _options.method) != null ? _b : _options.method = "get";
-    let contentType = _options.headers.get("content-type");
-    if (!contentType) {
-      _options.headers.set("content-type", ContentType.APPLICATION_JSON);
-      contentType = ContentType.APPLICATION_JSON;
-    }
-    url = await executeInterceptors_default(
+  var _a, _b, _c;
+  let errResponse;
+  const _options = mergeFetchOptions_default(fetch.defaults, options);
+  _options.abortCtrl = getAbortCtrl(_options);
+  (_a = _options.as) != null ? _a : _options.as = "json" /* json */;
+  (_b = _options.method) != null ? _b : _options.method = "get";
+  (_c = _options.signal) != null ? _c : _options.signal = _options.abortCtrl.signal;
+  _options.timeout = Math.min(
+    isPositiveNumber(_options.timeout) ? _options.timeout : fetch.defaults.timeout,
+    MAX_TIMEOUT
+  );
+  const { abortCtrl, as: parseAs, headers, timeout } = _options;
+  let contentType = headers.get("content-type");
+  if (!contentType) {
+    headers.set("content-type", ContentType.APPLICATION_JSON);
+    contentType = ContentType.APPLICATION_JSON;
+  }
+  const processErr = (err) => {
+    var _a2, _b2, _c2, _d, _e;
+    let msg = (_a2 = err == null ? void 0 : err.message) != null ? _a2 : err;
+    if ((err == null ? void 0 : err.name) === "AbortError") msg = (_c2 = (_b2 = _options.errMsgs) == null ? void 0 : _b2.aborted) != null ? _c2 : msg;
+    return executeInterceptors_default(
+      new FetchError(msg, {
+        cause: (_d = err == null ? void 0 : err.cause) != null ? _d : err,
+        response: errResponse,
+        options: _options,
+        url
+      }),
+      void 0,
+      // should execute regardless of abort status
+      (_e = _options.interceptors) == null ? void 0 : _e.error,
       url,
-      _options.interceptors.request,
       _options
-    );
-    const {
-      as: parseAs,
-      body,
-      errMsgs,
-      timeout,
-      validateUrl = true
-    } = _options;
-    if (isPositiveNumber(timeout)) {
-      timeoutId = setTimeout(() => abortCtrl.abort(), timeout);
-    }
-    if (_options.abortCtrl) _options.signal = _options.abortCtrl.signal;
+    ).then((err2) => Promise.reject(err2));
+  };
+  const start = async () => {
+    var _a2, _b2, _c2, _d;
     try {
+      url = await executeInterceptors_default(
+        url,
+        abortCtrl.signal,
+        (_a2 = _options.interceptors) == null ? void 0 : _a2.request,
+        _options
+      );
+      const { body, errMsgs, validateUrl = true } = _options;
+      (_b2 = _options.signal) != null ? _b2 : _options.signal = abortCtrl.signal;
       if (validateUrl && !isUrlValid(url, false))
-        throw new Error(errMsgs.invalidUrl);
+        return processErr(new Error(errMsgs.invalidUrl));
       const shouldStringifyBody = [
         ContentType.APPLICATION_JSON,
         ContentType.APPLICATION_X_WWW_FORM_URLENCODED
@@ -216,7 +259,8 @@ var fetch = (url, options = {}) => {
       let response = await getResponse_default(url, _options);
       response = await executeInterceptors_default(
         response,
-        _options.interceptors.response,
+        abortCtrl.signal,
+        (_c2 = _options.interceptors) == null ? void 0 : _c2.response,
         url,
         _options
       );
@@ -224,83 +268,69 @@ var fetch = (url, options = {}) => {
       const { status = 0 } = response;
       const isSuccess = status >= 200 && status < 300;
       if (!isSuccess) {
-        const fallbackMsg = `${errMsgs.requestFailed} ${status}`;
         const jsonError = await fallbackIfFails3(
           // try to parse error response as json first
           () => response.json(),
           [],
           void 0
         );
-        const message = (jsonError == null ? void 0 : jsonError.message) || fallbackMsg;
-        throw new Error(`${message}`.replace("Error: ", ""), {
-          cause: jsonError
-        });
+        throw new Error(
+          (jsonError == null ? void 0 : jsonError.message) || `${errMsgs.requestFailed} ${status}`,
+          { cause: jsonError }
+        );
       }
-      let result = response;
       const parseFunc = response[parseAs];
-      if (isFn2(parseFunc)) {
-        const handleErr = (err) => {
-          err = new Error(
-            `${errMsgs.parseFailed} ${parseAs}. ${err == null ? void 0 : err.message}`,
-            { cause: err }
-          );
-          return Promise.reject(err);
-        };
-        result = parseFunc.bind(response)();
-        if (isPromise(result)) result = result.catch(handleErr);
-      }
+      let result = !isFn2(parseFunc) ? response : parseFunc.bind(response)();
+      if (isPromise(result))
+        result = await result.catch(
+          (err) => Promise.reject(
+            new Error(
+              `${errMsgs.parseFailed} ${parseAs}. ${err == null ? void 0 : err.message}`,
+              { cause: err }
+            )
+          )
+        );
       result = await executeInterceptors_default(
         result,
-        _options.interceptors.result,
+        abortCtrl.signal,
+        (_d = _options.interceptors) == null ? void 0 : _d.result,
         url,
         _options
       );
-      resolve(result);
-    } catch (err) {
-      const errX = err;
-      const msg = (errX == null ? void 0 : errX.name) === "AbortError" ? errMsgs.reqTimedout : err == null ? void 0 : err.message;
-      let error = new FetchError(msg, {
-        cause: (_c = errX == null ? void 0 : errX.cause) != null ? _c : err,
-        response: errResponse,
-        options: _options,
-        url
-      });
-      error = await executeInterceptors_default(
-        error,
-        _options.interceptors.error,
-        url,
-        _options
-      );
-      reject(error);
+      return result;
+    } catch (_err) {
+      return processErr(_err);
     }
-    timeoutId && clearTimeout(timeoutId);
-  });
-  promise.onEarlyFinalize.push(() => abortCtrl.abort());
-  return promise;
+  };
+  return PromisE_timeout(
+    {
+      ...options,
+      abortCtrl,
+      onAbort: () => processErr(new Error(_options.errMsgs.aborted)),
+      onTimeout: async () => processErr(new Error(_options.errMsgs.timedout)),
+      signal: _options.signal,
+      timeout
+    },
+    start
+  );
 };
 fetch.defaults = {
   errMsgs: {
+    aborted: "Request aborted",
     invalidUrl: "Invalid URL",
     parseFailed: "Failed to parse response as",
-    reqTimedout: "Request timed out",
+    timedout: "Request timed out",
     requestFailed: "Request failed with status code:"
   },
   // all error messages must be defined here
   headers: new Headers(),
-  /** 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: []
   },
-  /** Request timeout duration in milliseconds. Default: `0` */
-  timeout: 0,
+  timeout: 3e4,
   validateUrl: true
 };
 var fetch_default = fetch;
@@ -336,7 +366,7 @@ var createClient = (fixedOptions, commonOptions, commonDeferOptions) => {
       promise.onEarlyFinalize.push(() => _abortCtrl == null ? void 0 : _abortCtrl.abort());
       return promise;
     };
-    return PromisE3.deferredCallback(fetchCb, {
+    return deferredCallback(fetchCb, {
       ...commonDeferOptions,
       ...deferOptions
     });
@@ -346,9 +376,9 @@ var createClient = (fixedOptions, commonOptions, commonDeferOptions) => {
 var createClient_default = createClient;
 
 // src/createPostClient.ts
-import PromisE4 from "@superutils/promise";
+import { deferredCallback as deferredCallback2 } from "@superutils/promise";
 var createPostClient = (fixedOptions, commonOptions, commonDeferOptions) => {
-  const client2 = (url, data, options) => {
+  const client = (url, data, options) => {
     var _a;
     const _options = mergePartialOptions(
       commonOptions,
@@ -359,7 +389,7 @@ var createPostClient = (fixedOptions, commonOptions, commonDeferOptions) => {
     (_a = _options.method) != null ? _a : _options.method = "post";
     return fetch_default(url, _options);
   };
-  client2.deferred = (deferOptions = {}, defaultUrl, defaultData, defaultOptions) => {
+  client.deferred = (deferOptions = {}, defaultUrl, defaultData, defaultOptions) => {
     let _abortCtrl;
     const postCb = (...args) => {
       var _a, _b, _c, _d;
@@ -379,16 +409,14 @@ var createPostClient = (fixedOptions, commonOptions, commonDeferOptions) => {
       promise.onEarlyFinalize.push(() => _abortCtrl == null ? void 0 : _abortCtrl.abort());
       return promise;
     };
-    return PromisE4.deferredCallback(postCb, {
+    return deferredCallback2(postCb, {
       ...commonDeferOptions,
       ...deferOptions
     });
   };
-  return client2;
+  return client;
 };
 var createPostClient_default = createPostClient;
-var client = createPostClient();
-client.deferred();
 
 // src/fetchResponse.ts
 var fetchResponse = (url, options) => {
@@ -397,9 +425,18 @@ var fetchResponse = (url, options) => {
   (_a = options.as) != null ? _a : options.as = "response" /* response */;
   return fetch_default(url, options);
 };
+fetchResponse.defaults = fetch_default.defaults;
+Object.defineProperty(fetchResponse, "defaults", {
+  get() {
+    return fetch_default.defaults;
+  },
+  set(newDefaults) {
+    fetch_default.defaults = newDefaults;
+  }
+});
 var fetchResponse_default = fetchResponse;
 
-// src/fetchDefault.ts
+// src/defaultFetch.ts
 var methods = {
   /** Make HTTP requests with method GET */
   get: createClient_default({ method: "get" }),
@@ -416,31 +453,23 @@ var methods = {
   /** Make HTTP requests with method PUT */
   put: createPostClient_default({ method: "put" })
 };
-var fetchDefault = fetchResponse_default;
-Object.defineProperty(fetchDefault, "defaults", {
-  get() {
-    return fetch_default.defaults;
-  },
-  set(newDefaults) {
-    fetch_default.defaults = newDefaults;
-  }
-});
-fetchDefault.delete = methods.delete;
-fetchDefault.get = methods.get;
-fetchDefault.head = methods.head;
-fetchDefault.options = methods.options;
-fetchDefault.patch = methods.patch;
-fetchDefault.post = methods.post;
-fetchDefault.put = methods.put;
-var fetchDefault_default = fetchDefault;
+var defaultFetch = fetchResponse_default;
+defaultFetch.delete = methods.delete;
+defaultFetch.get = methods.get;
+defaultFetch.head = methods.head;
+defaultFetch.options = methods.options;
+defaultFetch.patch = methods.patch;
+defaultFetch.post = methods.post;
+defaultFetch.put = methods.put;
+var defaultFetch_default = defaultFetch;
 
 // src/index.ts
-var index_default = fetchDefault_default;
-fetchDefault_default.get;
+var index_default = defaultFetch_default;
 export {
   ContentType,
   FetchAs,
   FetchError,
+  MAX_TIMEOUT,
   ResolveError,
   ResolveIgnored,
   createClient,

package/package.json

@@ -5,8 +5,8 @@
 	},
 	"description": "A lightweight `fetch` wrapper for browsers and Node.js, designed to simplify data fetching and reduce boilerplate.",
 	"dependencies": {
-		"@superutils/core": "^1.1.6",
-		"@superutils/promise": "^1.1.6"
+		"@superutils/core": "^1.1.8",
+		"@superutils/promise": "^1.2.0"
 	},
 	"files": [
 		"dist",
@@ -24,8 +24,8 @@
 	"main": "dist/index.js",
 	"name": "@superutils/fetch",
 	"peerDependencies": {
-		"@superutils/core": "^1.1.6",
-		"@superutils/promise": "^1.1.6"
+		"@superutils/core": "^1.2.0",
+		"@superutils/promise": "^1.1.7"
 	},
 	"publishConfig": {
 		"access": "public"
@@ -45,5 +45,5 @@
 	"sideEffects": false,
 	"type": "module",
 	"types": "dist/index.d.ts",
-	"version": "1.2.3"
+	"version": "1.3.0"
 }