@superutils/fetch 1.0.0 → 1.0.2

package/README.md

@@ -10,9 +10,10 @@ This package enhances the native `fetch` API by providing a streamlined interfac
 - Installation
 - Usage
     - [`fetch()`](#fetch): make HTTP requests just like built-in `fetch()`
-    - [`fetchDeferred()`](#fetch-deferred): cancellable and debounced or throttled `fetch()`
-    - [`post()`](#post): make post-like requests
-    - [`postDeferred()`](#post-deferred) cancellable and debounced or throttled `post()`
+    - [`Method Specific Functions`](#methods)
+    - [`fetch.get.deferred()`](#fetch-deferred): cancellable and debounced or throttled `fetch()`
+    - [`fetch.post()`](#post): make post requests
+    - [`fetch.post.deferred()`](#post-deferred) cancellable and debounced or throttled `post()`
 
 ## Features
 
@@ -39,25 +40,49 @@ npm install @superutils/fetch
 Make a simple GET request. No need for `response.json()` or `result.data.theActualData` drilling.
 
 ```typescript
-import { fetch } from '@superutils/fetch'
+import fetch from '@superutils/fetch'
 
 const theActualData = await fetch('https://dummyjson.com/products/1', {
 	method: 'get', // default
 })
 console.log(theActualData)
 // Alternative:
-const theActualData = await fetch.get('https://dummyjson.com/products/1')
-console.log(theActualData)
+const theActualData2 = await fetch.get('https://dummyjson.com/products/1')
+console.log(theActualData2)
 ```
 
+<div id="methods"></div>
+
+### Method Specific Functions
+
+While `fetch()` provides access to all HTTP request methods by specifying it in options (eg: `{ method: 'get' }`), for ease of use you can also use the following:
+
+- `fetch.delete(...)`
+- `fetch.get(...)`
+- `fetch.head(...)`
+- `fetch.options(...)`
+- `fetch.patch(...)`
+- `fetch.post(...)`
+- `fetch.put(...)`
+
+**Deferred variants:** To debounce/throttle requests.
+
+- `fetch.delete.deferred(...)`
+- `fetch.get.deferred(...)`
+- `fetch.head.deferred(...)`
+- `fetch.options.deferred(...)`
+- `fetch.patch.deferred(...)`
+- `fetch.post.deferred(...)`
+- `fetch.put.deferred(...)`
+
 <div id="fetch-deferred"></div>
 
-### `fetch.get.deferred(deferOptions, url, fetchOptions)`
+### `fetch.get.deferred(deferOptions, defaultUrl, defaultOptions)`
 
 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'
+import fetch, { fetchDeferred, ResolveIgnored } from '@superutils/fetch'
 
 // Create a debounced search function with a 300ms delay.
 const searchProducts = fetch.get.deferred({
@@ -99,16 +124,20 @@ setTimeout(() => {
        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`.
+- **`resolveError`**: Controls how failed requests are handled.
+    1.  `ResolveError.NEVER`: Never resolve ignored promises. Caution: make sure this doesn't cause any memory leaks.
+    2.  `ResolveError.WITH_LAST`: (default) resolve with active promise result, the one that caused the current promise/callback to be ignored.
+    3.  `ResolveError.WITH_UNDEFINED`: resolve failed requests with `undefined` value
+    4.  `ResolveError.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'
+import fetch, { 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(
+const getRandomQuote = fetch.get.deferred(
 	{
 		delayMs: 300, // Throttle window
 		throttle: true,
@@ -135,8 +164,107 @@ getRandomQuote().then(quote => console.log('Call 3 resolved:', quote.id))
 
 ### `fetch.post(url, options)`
 
+Send a POST request to create a new product and receive the parsed JSON response.
+
+```javascript
+import fetch from '@superutils/fetch'
+
+const newProduct = { title: 'Perfume Oil' }
+
+fetch.post('https://dummyjson.com/products/add', newProduct).then(
+	createdProduct => console.log('Product created:', createdProduct),
+	error => console.error('Failed to create product:', error),
+)
+```
+
 <div id="post-deferred"></div>
 
-### `fetch.post.deferred(deferOptions, url, postOptions)`
+### `fetch.post.deferred(deferOptions, url, data, options)`
+
+HTTP POST request with debounce/throttle.
+
+#### Example 1: Auto-saving form data with throttling
+
+```typescript
+import fetch from '@superutils/fetch'
+import PromisE from '@superutils/promise'
+
+// Create a throttled function to auto-save product updates.
+const saveProductThrottled = fetch.post.deferred(
+	{
+		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.
+```
+
+#### Example 2: debouncing an authentication token refresh
+
+```typescript
+import fetch from '@superutils/fetch'
+import PromisE from '@superutils/promise'
+
+// Mock a simple token store
+let currentRefreshToken = ''
+// Create a debounced function to refresh the auth token.
+// It waits 300ms after the last call before executing.
+const requestNewToken = fetch.post.deferred(
+	{
+		delayMs: 300, // debounce delay
+		onResult: ({ token = '' }) => {
+			console.log(
+				`Auth token successfully refreshed at ${new Date().toISOString()}`,
+			)
+			currentRefreshToken = token
+		},
+	},
+	'https://dummyjson.com/auth/refresh', // Default URL
+	() => ({
+		refreshToken: currentRefreshToken,
+		expiresInMins: 30,
+	}),
+)
 
-<div id="method-specific"></div>
+// First authenticate user to get the initial refresh token and then request new referesh tokens
+fetch
+	.post<{ refreshToken: string }>(
+		'https://dummyjson.com/auth/login',
+		{
+			username: 'emilys',
+			password: 'emilyspass',
+			expiresInMins: 30,
+		},
+		{ credentials: 'include' },
+	)
+	.then(result => {
+		currentRefreshToken = result?.refreshToken
+
+		requestNewToken() // Called at 0ms
+		PromisE.delay(50, requestNewToken) // Called at 50ms
+		PromisE.delay(100, requestNewToken) // Called at 100ms
+	}, console.error)
+// 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.
+```

package/dist/index.d.ts

@@ -1,9 +1,12 @@
+import { ValueOrPromise } from '@superutils/core';
 import * as _superutils_promise from '@superutils/promise';
 import { RetryOptions, IPromisE, DeferredAsyncOptions } from '@superutils/promise';
 export { DeferredAsyncOptions, ResolveError, ResolveIgnored } from '@superutils/promise';
-import { ValueOrPromise } from '@superutils/core';
 
-type FetchArgs = [url: string | URL, options?: FetchOptions];
+type FetchArgs<OmitMethod extends boolean = false> = [
+    url: string | URL,
+    options?: OmitMethod extends true ? Omit<FetchOptions, 'method'> : FetchOptions
+];
 type FetchArgsInterceptor = [
     url: string | URL,
     options: FetchOptionsInterceptor
@@ -17,7 +20,8 @@ declare enum FetchAs {
     response = "response",
     text = "text"
 }
-type FetchConf = {
+/** 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'
@@ -28,11 +32,11 @@ type FetchConf = {
     interceptors?: FetchInterceptors;
     /** Request timeout in milliseconds. */
     timeout?: number;
-};
+} & FetchRetryOptions;
 /** Default args */
-type FetchDeferredArgs = [
+type FetchDeferredArgs<OmitMethod extends boolean = false> = [
     url?: string | URL,
-    options?: Omit<FetchOptions, 'abortCtrl'>
+    options?: Omit<FetchOptions, 'abortCtrl' | (OmitMethod extends true ? 'method' : never)>
 ];
 type FetchErrMsgs = {
     invalidUrl?: string;
@@ -230,7 +234,8 @@ type FetchInterceptors = {
 /**
  * Fetch request options
  */
-type FetchOptions = RequestInit & FetchConf & FetchRetryOptions;
+type FetchOptions = RequestInit & FetchCustomOptions;
+type FetchOptionsDefaults = Omit<FetchOptionsInterceptor, 'method' | 'retryIf'>;
 /**
  * Fetch options available to interceptors
  */
@@ -271,10 +276,10 @@ type FetchRetryOptions = Omit<Partial<RetryOptions>, 'retry' | 'retryIf'> & {
  */
 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 = [
+type PostArgs<OmitMethod = false> = [
     url: string | URL,
-    data?: PostBody,
-    options?: PostOptions
+    data?: PostBody | (() => PostBody),
+    options?: OmitMethod extends true ? Omit<FetchOptions, 'method'> : PostOptions
 ];
 /**
  *
@@ -306,15 +311,16 @@ type PostArgs = [
  * f4().then(console.log, console.warn)
  * ```
  */
-type PostDeferredCallbackArgs<TUrl = undefined, TData = undefined, RPA extends unknown[] = Required<PostArgs>> = [TUrl, TData] extends [RPA[0], undefined] ? [data?: PostArgs[1], options?: PostArgs[2]] : [TUrl, TData] extends [undefined, RPA[1]] ? [url: PostArgs[0], options?: PostArgs[2]] : [TUrl, TData] extends [RPA[0], RPA[1]] ? [options?: PostArgs[2]] : PostArgs;
+type PostDeferredCallbackArgs<TUrl = undefined, TData = undefined, OmitMethod extends boolean = true, CbArgs extends PostArgs<OmitMethod> = PostArgs<OmitMethod>, Options = CbArgs[2], RPA extends unknown[] = Required<CbArgs>> = [TUrl, TData] extends [RPA[0], undefined] ? [data?: CbArgs[1], options?: Options] : [TUrl, TData] extends [undefined, RPA[1]] ? [url: CbArgs[0], options?: Options] : [TUrl, TData] extends [RPA[0], RPA[1]] ? [options?: Options] : CbArgs;
 type PostOptions = Omit<FetchOptions, 'method'> & {
     /** Default: `'post'` */
-    method?: 'post' | 'put' | 'patch' | 'delete';
+    method?: 'post' | 'put' | 'patch' | 'delete' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 };
 
 declare const fetch$1: {
-    <TJSON, TOptions extends FetchOptions = FetchOptions, TReturn = TOptions["as"] extends FetchAs ? FetchResult<TJSON>[TOptions["as"]] : TJSON>(url: string | URL, options?: TOptions): IPromisE<TReturn>;
-    defaults: Omit<FetchOptionsInterceptor, "retryIf" | "method">;
+    <T, TOptions extends FetchOptions = FetchOptions, TReturn = TOptions["as"] extends FetchAs ? FetchResult<T>[TOptions["as"]] : T>(url: string | URL, options?: TOptions): IPromisE<TReturn>;
+    /** Default fetch options */
+    defaults: FetchOptionsDefaults;
 };
 
 /**
@@ -403,18 +409,18 @@ declare const fetch$1: {
  * // Console output will show the same quote ID for all three calls.
  * ```
  */
-declare function fetchDeferred<ThisArg = unknown, Delay extends number = number, GlobalUrl extends string | URL | undefined = string | URL | undefined, Args extends unknown[] = undefined extends GlobalUrl ? FetchArgs : [options?: FetchOptions]>(deferOptions?: DeferredAsyncOptions<ThisArg, Delay>, globalUrl?: GlobalUrl, defaultOptions?: FetchDeferredArgs[1]): <TResult = unknown>(...args: Args) => _superutils_promise.IPromisE<TResult>;
+declare function fetchDeferred<ThisArg = unknown, Delay extends number = number, GlobalUrl = FetchArgs[0] | undefined, CbArgs extends unknown[] = undefined extends GlobalUrl ? FetchArgs<true> : [options?: FetchArgs<true>[1]]>(deferOptions?: DeferredAsyncOptions<ThisArg, Delay>, globalUrl?: GlobalUrl, defaultOptions?: FetchArgs[1]): <TResult = unknown>(...args: CbArgs) => _superutils_promise.IPromisE<TResult>;
 
 /**
- * Creates a deferred/throttled function for making `POST`, `PUT`, or `PATCH` requests, powered by
+ * Creates a deferred/throttled function for making `DELETE`, `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.
  *
- *
  * @param deferOptions Configuration for the deferred execution behavior (e.g., `delayMs`, `throttle`).
  * See {@link DeferredAsyncOptions} for details.
  * @param globalUrl (optional) If global URL is `undefined`, returned callback will always require an URL.
@@ -424,86 +430,87 @@ declare function fetchDeferred<ThisArg = unknown, Delay extends number = number,
  * If the same property is provided in both cases, defaults will be overriden by the callback.
  *
  *
- * @example Debouncing an authentication token refresh
- * ```typescript
+ *
+ * @example Auto-saving form data with throttling
+ * ```javascript
  * import { postDeferred } from '@superutils/fetch'
  * import PromisE from '@superutils/promise'
  *
- * // Mock a simple token store
- * let currentRefreshToken = 'initial-refresh-token'
+ * // Create a throttled function to auto-save product updates.
+ * const saveProductThrottled = fetch.post.deferred(
+ * 	{
+ * 		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...')
+ * // First call
+ * saveProductThrottled({ title: 'iPhone' }) // Executed immediately (leading edge)
+ * // Second call after 200ms => Ignored (within 1000ms throttle window)
+ * PromisE.delay(200, () => saveProductThrottled({ title: 'iPhone 15' }))
+ * // Third call 300ms after second call => Ignored
+ * PromisE.delay(500, () => saveProductThrottled({ title: 'iPhone 15 Pro' }))
+ * // Fourth call 400ms after third call => Queued to execute on the trailing edge
+ * PromisE.delay(900, () => saveProductThrottled({ title: 'iPhone 15 Pro Max' }))
+ * ```
+ *
+ * @example Advanced example: debouncing an authentication token refresh
+ * ```typescript
+ * import fetch from '@superutils/fetch'
+ * import PromisE from '@superutils/promise'
  *
+ * // Mock a simple token store
+ * let currentRefreshToken = ''
  * // Create a debounced function to refresh the auth token.
  * // It waits 300ms after the last call before executing.
- * const refreshAuthToken = postDeferred(
+ * const requestNewToken = fetch.post.deferred(
  * 	{
  * 		delayMs: 300, // debounce delay
- * 		onResult: (result: { token: string }) => {
- * 			console.log(`Auth token successfully refreshed at ${new Date().toISOString()}`)
- *          currentRefreshToken = result.token
- *      },
+ * 		onResult: ({ token = '' }) => {
+ * 			console.log(
+ * 				`Auth token successfully refreshed at ${new Date().toISOString()}`,
+ * 			)
+ * 			currentRefreshToken = token
+ * 		},
  * 	},
  * 	'https://dummyjson.com/auth/refresh', // Default URL
+ * 	() => ({
+ * 		refreshToken: currentRefreshToken,
+ * 		expiresInMins: 30,
+ * 	}),
  * )
  *
- * // 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
- *
+ * // First authenticate user to get the initial refresh token and then request new referesh tokens
+ * fetch
+ * 	.post<{ refreshToken: string }>(
+ * 		'https://dummyjson.com/auth/login',
+ * 		{
+ * 			username: 'emilys',
+ * 			password: 'emilyspass',
+ * 			expiresInMins: 30,
+ * 		},
+ * 		{ credentials: 'include' },
+ * 	)
+ * 	.then(result => {
+ * 		currentRefreshToken = result?.refreshToken
+ *
+ * 		requestNewToken() // Called at 0ms
+ * 		PromisE.delay(50, requestNewToken) // Called at 50ms
+ * 		PromisE.delay(100, requestNewToken) // Called at 100ms
+ * 	}, console.error)
  * // 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, Delay extends number = number, GlobalUrl extends PostArgs[0] | undefined = undefined, GlobalData extends PostArgs[1] | undefined = undefined, Args extends unknown[] = PostDeferredCallbackArgs<GlobalUrl, GlobalData>>(deferOptions?: DeferredAsyncOptions<ThisArg, Delay>, globalUrl?: GlobalUrl, // The default URL for all calls
-globalData?: GlobalData, // The default data for all calls
-defaultOptions?: PostOptions): <TResult = unknown>(...args: Args) => _superutils_promise.IPromisE<TResult>;
+declare function postDeferred<ThisArg, Delay extends number = number, GlobalUrl extends PostArgs[0] | undefined = undefined, GlobalData extends PostArgs[1] | undefined = undefined, Args extends unknown[] = PostDeferredCallbackArgs<GlobalUrl, GlobalData, true>>(deferOptions?: DeferredAsyncOptions<ThisArg, Delay>, globalUrl?: GlobalUrl, globalData?: GlobalData, defaultOptions?: PostArgs[2]): <TResult = unknown>(...args: Args) => _superutils_promise.IPromisE<TResult>;
 
 /**
  * Merge one or more {@link FetchOptions}
@@ -522,32 +529,102 @@ defaultOptions?: PostOptions): <TResult = unknown>(...args: Args) => _superutils
 declare const mergeFetchOptions: (...allOptions: FetchOptions[]) => FetchOptionsInterceptor;
 
 type FetchWithoutMethods = typeof fetch$1;
-/** Describes method-specific fetch-functions that includes `.deferred()` function for deferred/throttled requests */
-type FetchMethodFunc = (<T, Options extends Omit<FetchOptions, 'method'>>(url: string | URL, options?: Options) => ReturnType<typeof fetch$1<T, Options>>) & {
-    deferred: typeof fetchDeferred;
+declare const _get: {
+    <T>(url: string | URL, options?: Omit<FetchOptions, "method">): _superutils_promise.IPromisE<T>;
+    deferred: <ThisArg, Delay extends number, GlobalUrl extends string | URL>(deferOptions?: DeferredAsyncOptions<ThisArg, Delay> | undefined, globalUrl?: GlobalUrl | undefined, defaultOptions?: FetchOptions | undefined) => <TResult = unknown>(...args: undefined extends GlobalUrl ? FetchArgs<true> : [options?: Omit<FetchOptions, "method"> | undefined]) => _superutils_promise.IPromisE<TResult>;
 };
-/** Describes method-specific fetch-functions that includes `.deferred()` function for deferred/throttled requests */
-type PostMethodFunc = (<T, Options extends Omit<FetchOptions, 'method'>>(url: string | URL, data?: PostBody, options?: Options) => ReturnType<typeof fetch$1<T, Options>>) & {
-    deferred: typeof postDeferred;
+declare const _head: {
+    <T>(url: string | URL, options?: Omit<FetchOptions, "method">): _superutils_promise.IPromisE<T>;
+    deferred: <ThisArg, Delay extends number, GlobalUrl extends string | URL>(deferOptions?: DeferredAsyncOptions<ThisArg, Delay> | undefined, globalUrl?: GlobalUrl | undefined, defaultOptions?: FetchOptions | undefined) => <TResult = unknown>(...args: undefined extends GlobalUrl ? FetchArgs<true> : [options?: Omit<FetchOptions, "method"> | undefined]) => _superutils_promise.IPromisE<TResult>;
+};
+declare const _options: {
+    <T>(url: string | URL, options?: Omit<FetchOptions, "method">): _superutils_promise.IPromisE<T>;
+    deferred: <ThisArg, Delay extends number, GlobalUrl extends string | URL>(deferOptions?: DeferredAsyncOptions<ThisArg, Delay> | undefined, globalUrl?: GlobalUrl | undefined, defaultOptions?: FetchOptions | undefined) => <TResult = unknown>(...args: undefined extends GlobalUrl ? FetchArgs<true> : [options?: Omit<FetchOptions, "method"> | undefined]) => _superutils_promise.IPromisE<TResult>;
+};
+declare const _delete: {
+    <T, Args extends PostArgs<true> = PostArgs<true>>(url: Args[0], data?: Args[1], options?: Args[2]): _superutils_promise.IPromisE<T>;
+    deferred: <ThisArg, Delay extends number = number, Args extends PostArgs<true> = PostArgs<true>, GlobalUrl extends Args[0] | undefined = undefined, GlobalData extends Args[1] | undefined = undefined>(deferOptions?: DeferredAsyncOptions<ThisArg, Delay>, globalUrl?: GlobalUrl, globalData?: GlobalData, defaultOptions?: Args[2]) => <TResult = unknown>(...args: PostDeferredCallbackArgs<GlobalUrl, GlobalData, true, PostArgs<true>, Omit<FetchOptions, "method"> | undefined, [url: string | URL, data: PostBody | (() => PostBody), options: Omit<FetchOptions, "method">]>) => _superutils_promise.IPromisE<TResult>;
+};
+declare const _patch: {
+    <T, Args extends PostArgs<true> = PostArgs<true>>(url: Args[0], data?: Args[1], options?: Args[2]): _superutils_promise.IPromisE<T>;
+    deferred: <ThisArg, Delay extends number = number, Args extends PostArgs<true> = PostArgs<true>, GlobalUrl extends Args[0] | undefined = undefined, GlobalData extends Args[1] | undefined = undefined>(deferOptions?: DeferredAsyncOptions<ThisArg, Delay>, globalUrl?: GlobalUrl, globalData?: GlobalData, defaultOptions?: Args[2]) => <TResult = unknown>(...args: PostDeferredCallbackArgs<GlobalUrl, GlobalData, true, PostArgs<true>, Omit<FetchOptions, "method"> | undefined, [url: string | URL, data: PostBody | (() => PostBody), options: Omit<FetchOptions, "method">]>) => _superutils_promise.IPromisE<TResult>;
+};
+declare const _post: {
+    <T, Args extends PostArgs<true> = PostArgs<true>>(url: Args[0], data?: Args[1], options?: Args[2]): _superutils_promise.IPromisE<T>;
+    deferred: <ThisArg, Delay extends number = number, Args extends PostArgs<true> = PostArgs<true>, GlobalUrl extends Args[0] | undefined = undefined, GlobalData extends Args[1] | undefined = undefined>(deferOptions?: DeferredAsyncOptions<ThisArg, Delay>, globalUrl?: GlobalUrl, globalData?: GlobalData, defaultOptions?: Args[2]) => <TResult = unknown>(...args: PostDeferredCallbackArgs<GlobalUrl, GlobalData, true, PostArgs<true>, Omit<FetchOptions, "method"> | undefined, [url: string | URL, data: PostBody | (() => PostBody), options: Omit<FetchOptions, "method">]>) => _superutils_promise.IPromisE<TResult>;
+};
+declare const _put: {
+    <T, Args extends PostArgs<true> = PostArgs<true>>(url: Args[0], data?: Args[1], options?: Args[2]): _superutils_promise.IPromisE<T>;
+    deferred: <ThisArg, Delay extends number = number, Args extends PostArgs<true> = PostArgs<true>, GlobalUrl extends Args[0] | undefined = undefined, GlobalData extends Args[1] | undefined = undefined>(deferOptions?: DeferredAsyncOptions<ThisArg, Delay>, globalUrl?: GlobalUrl, globalData?: GlobalData, defaultOptions?: Args[2]) => <TResult = unknown>(...args: PostDeferredCallbackArgs<GlobalUrl, GlobalData, true, PostArgs<true>, Omit<FetchOptions, "method"> | undefined, [url: string | URL, data: PostBody | (() => PostBody), options: Omit<FetchOptions, "method">]>) => _superutils_promise.IPromisE<TResult>;
 };
-interface FetchWithMethods extends FetchWithoutMethods {
-    get: FetchMethodFunc;
-    head: FetchMethodFunc;
-    options: FetchMethodFunc;
-    delete: PostMethodFunc;
-    patch: PostMethodFunc;
-    post: PostMethodFunc;
-    put: PostMethodFunc;
-}
 /**
+ * @function fetch
+ *
  * 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.
+ * and handy interceptors that also work as transformers. 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).
  *
+ * ## Method Specific Functions
+ *
+ * While `fetch()` provides access to all HTTP request methods by specifying it in options (eg: `{ method: 'get' }`),
+ * for ease of use you can also use the following:
+ *
+ * - `fetch.delete(...)`
+ * - `fetch.get(...)`
+ * - `fetch.head(...)`
+ * - `fetch.options(...)`
+ * - `fetch.patch(...)`
+ * - `fetch.post(...)`
+ * - `fetch.put(...)`
+ *
+ * **Deferred variants:** To debounce/throttle requests.
+ *
+ * - `fetch.delete.deferred(...)`
+ * - `fetch.get.deferred(...)`
+ * - `fetch.head.deferred(...)`
+ * - `fetch.options.deferred(...)`
+ * - `fetch.patch.deferred(...)`
+ * - `fetch.post.deferred(...)`
+ * - `fetch.put.deferred(...)`
+ *
+ * @template T The type of the value that the `fetch` resolves to.
+ * @template TReturn Return value type.
+ *
+ * If `T` is not specified defaults to the following based on the value of `options.as`:
+ * - FetchAs.arrayBuffer: `ArrayBuffer`
+ * - FetchAs.blob: `Blob`
+ * - FetchAs.bytes: `Uint8Array<ArrayBuffer>`
+ * - FetchAs.formData: `FormData`
+ * - FetchAs.json: `unknown`
+ * - FetchAs.text: `string`
+ * - FetchAs.response: `Response`
  * @param url
  * @param options (optional) all built-in `fetch()` options such as "method", "headers" and the additionals below.
+ *
+ * Options' default values (excluding `method` and `retryIf`) can be configured to be EFFECTIVE GLOBALLY.
+ *
+ * ```typescript
+ * fetch.defaults = {
+ *     as: FetchAs.json,
+ *     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']]),
+ *     interceptors: {
+ *     	   error: [],
+ *     	   request: [],
+ *     	   response: [],
+ *     	   result: [],
+ *     },
+ *     timeout: 0,
+ *     ........
+ * }
+ * ```
  * @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.
@@ -565,6 +642,14 @@ interface FetchWithMethods extends FetchWithoutMethods {
  * fetch('https://dummyjson.com/products/1').then(theActualData => console.log(theActualData))
  * ```
  */
-declare const fetch: FetchWithMethods;
+declare const fetch: typeof fetch$1 & {
+    get: typeof _get;
+    head: typeof _head;
+    options: typeof _options;
+    delete: typeof _delete;
+    patch: typeof _patch;
+    post: typeof _post;
+    put: typeof _put;
+};
 
-export { type FetchArgs, type FetchArgsInterceptor, FetchAs, type FetchConf, type FetchDeferredArgs, type FetchErrMsgs, FetchError, type FetchInterceptorError, type FetchInterceptorRequest, type FetchInterceptorResponse, type FetchInterceptorResult, type FetchInterceptors, type FetchMethodFunc, type FetchOptions, type FetchOptionsInterceptor, type FetchResult, type FetchRetryOptions, type FetchWithMethods, type FetchWithoutMethods, type Interceptor, type PostArgs, type PostBody, type PostDeferredCallbackArgs, type PostMethodFunc, type PostOptions, fetch as default, fetch, fetchDeferred, mergeFetchOptions, postDeferred };
+export { type FetchArgs, type FetchArgsInterceptor, FetchAs, 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 FetchWithoutMethods, type Interceptor, type PostArgs, type PostBody, type PostDeferredCallbackArgs, type PostOptions, fetch as default, fetch, fetchDeferred, mergeFetchOptions, postDeferred };

package/dist/index.js

@@ -43,9 +43,9 @@ var getResponse = async (...[url, options = {}]) => {
   if (!isPositiveInteger(options.retry)) return doFetch();
   const response = PromisE.retry(doFetch, {
     ...options,
-    retryIf: async (res, count, err) => {
+    retryIf: async (res, count) => {
       var _a;
-      return (res == null ? void 0 : res.ok) === false || await ((_a = options == null ? void 0 : options.retryIf) == null ? void 0 : _a.call(options, res, count, err)) === true;
+      return (res == null ? void 0 : res.ok) === false || await ((_a = options == null ? void 0 : options.retryIf) == null ? void 0 : _a.call(options, res, count)) === true;
     }
   }).catch(
     (err) => Promise.reject(
@@ -116,32 +116,32 @@ var fetch = (url, options = {}) => {
   let timeoutId;
   const promise = new PromisE2(async (resolve, reject) => {
     var _a, _b;
-    const _options = mergeFetchOptions_default(defaults, options);
-    if (isEmpty2(_options.method)) _options.method = "get";
-    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;
+    const _options2 = mergeFetchOptions_default(fetch.defaults, options);
+    if (isEmpty2(_options2.method)) _options2.method = "get";
+    const errorInterceptors = [..._options2.interceptors.error];
+    const requestInterceptors = [..._options2.interceptors.request];
+    const responseInterceptors = [..._options2.interceptors.response];
+    const resultInterceptors = [..._options2.interceptors.result];
+    url = await executeInterceptors_default(url, requestInterceptors, url, _options2);
+    const { as: parseAs, errMsgs, timeout } = _options2;
     if (isPositiveNumber(timeout)) {
-      (_a = _options.abortCtrl) != null ? _a : _options.abortCtrl = new AbortController();
+      (_a = _options2.abortCtrl) != null ? _a : _options2.abortCtrl = new AbortController();
       timeoutId = setTimeout(() => {
         var _a2;
-        return (_a2 = _options.abortCtrl) == null ? void 0 : _a2.abort();
+        return (_a2 = _options2.abortCtrl) == null ? void 0 : _a2.abort();
       }, timeout);
     }
-    abortCtrl = _options.abortCtrl;
-    if (_options.abortCtrl) _options.signal = _options.abortCtrl.signal;
+    abortCtrl = _options2.abortCtrl;
+    if (_options2.abortCtrl) _options2.signal = _options2.abortCtrl.signal;
     let errResponse;
     try {
-      if (!isUrlValid(url, false)) throw errMsgs.invalidUrl;
-      let response = await getResponse_default(url, _options);
+      if (!isUrlValid(url, false)) throw new Error(errMsgs.invalidUrl);
+      let response = await getResponse_default(url, _options2);
       response = await executeInterceptors_default(
         response,
         responseInterceptors,
         url,
-        _options
+        _options2
       );
       errResponse = response;
       const { status = 0 } = response;
@@ -157,43 +157,36 @@ var fetch = (url, options = {}) => {
       const parseFunc = response[parseAs];
       if (isFn2(parseFunc)) {
         const handleErr = (err) => {
-          var _a2, _b2;
           err = new Error(
-            [
-              errMsgs.parseFailed,
-              parseAs + ".",
-              (_b2 = `${(_a2 = err == null ? void 0 : err.message) != null ? _a2 : err}`) == null ? void 0 : _b2.replace("Error: ", "")
-            ].join(" "),
+            `${errMsgs.parseFailed} ${parseAs}. ${err == null ? void 0 : err.message}`,
             { cause: err }
           );
           return globalThis.Promise.reject(err);
         };
-        result = parseFunc();
+        result = parseFunc.bind(response)();
         if (isPromise(result)) result = result.catch(handleErr);
         result = await executeInterceptors_default(
           result,
           resultInterceptors,
           url,
-          _options
+          _options2
         );
       }
-      resolve(await result);
+      resolve(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
-        }
-      );
+      const msg = (errX == null ? void 0 : errX.name) === "AbortError" ? errMsgs.reqTimedout : err == null ? void 0 : err.message;
+      let error = new FetchError(msg, {
+        cause: (_b = errX == null ? void 0 : errX.cause) != null ? _b : err,
+        response: errResponse,
+        options: _options2,
+        url
+      });
       error = await executeInterceptors_default(
         error,
         errorInterceptors,
         url,
-        _options
+        _options2
       );
       reject(error);
     }
@@ -202,7 +195,7 @@ var fetch = (url, options = {}) => {
   promise.onEarlyFinalize.push(() => abortCtrl == null ? void 0 : abortCtrl.abort());
   return promise;
 };
-var defaults = {
+fetch.defaults = {
   as: "json" /* json */,
   errMsgs: {
     invalidUrl: "Invalid URL",
@@ -226,7 +219,6 @@ var defaults = {
   },
   timeout: 0
 };
-fetch.defaults = defaults;
 var fetch_default = fetch;
 
 // src/fetchDeferred.ts
@@ -261,14 +253,14 @@ var fetchDeferred_default = fetchDeferred;
 import PromisE4 from "@superutils/promise";
 
 // src/post.ts
-import { isStr } from "@superutils/core";
+import { isFn as isFn3, isStr } from "@superutils/core";
 function post(...[url = "", data, options = {}]) {
   return fetch_default(
     url,
     mergeFetchOptions_default(
       {
         method: "post",
-        body: isStr(data) ? data : JSON.stringify(data)
+        body: isStr(data) ? data : JSON.stringify(isFn3(data) ? data() : data)
       },
       options
     )
@@ -288,10 +280,7 @@ function postDeferred(deferOptions = {}, globalUrl, globalData, defaultOptions)
     if (globalData !== void 0) args.splice(1, 0, globalData);
     const url = args[0];
     const data = args[1];
-    const options = mergeFetchOptions_default(
-      defaultOptions != null ? defaultOptions : {},
-      (_a = args[2]) != null ? _a : {}
-    );
+    const options = mergeFetchOptions_default(defaultOptions != null ? defaultOptions : {}, (_a = args[2]) != null ? _a : {});
     (_b = options.abortCtrl) != null ? _b : options.abortCtrl = new AbortController();
     (_c = _abortCtrl == null ? void 0 : _abortCtrl.abort) == null ? void 0 : _c.call(_abortCtrl);
     _abortCtrl = options.abortCtrl;
@@ -304,33 +293,50 @@ function postDeferred(deferOptions = {}, globalUrl, globalData, defaultOptions)
 var postDeferred_default = postDeferred;
 
 // src/index.ts
-import { isObj } from "@superutils/core";
 var createFetchMethodFunc = (method = "get") => {
-  const methodFunc = ((url, options) => {
-    const _options = isObj(options) ? options : {};
-    _options.method = method;
-    return fetch_default(url, _options);
-  });
-  methodFunc.deferred = ((...args) => fetchDeferred_default(...args));
+  const deferred = (...args) => fetchDeferred_default(...args);
+  const methodFunc = (url, options) => {
+    options != null ? options : options = {};
+    options.method = method;
+    return fetch_default(url, options);
+  };
+  methodFunc.deferred = deferred;
   return methodFunc;
 };
 var createPostMethodFunc = (method = "post") => {
-  const methodFunc = ((url, data, options) => {
-    const _options = isObj(options) ? options : {};
-    _options.method = method;
-    return post(url, data, _options);
-  });
-  methodFunc.deferred = ((...args) => postDeferred_default(...args));
+  const deferredFunc = (deferOptions = {}, globalUrl, globalData, defaultOptions) => {
+    defaultOptions != null ? defaultOptions : defaultOptions = {};
+    defaultOptions.method = method;
+    return postDeferred_default(
+      deferOptions,
+      globalUrl,
+      globalData,
+      defaultOptions
+    );
+  };
+  const methodFunc = (url, data, options) => {
+    options != null ? options : options = {};
+    options.method = method;
+    return post(url, data, options);
+  };
+  methodFunc.deferred = deferredFunc;
   return methodFunc;
 };
+var _get = createFetchMethodFunc("get");
+var _head = createFetchMethodFunc("head");
+var _options = createFetchMethodFunc("options");
+var _delete = createPostMethodFunc("delete");
+var _patch = createPostMethodFunc("patch");
+var _post = createPostMethodFunc("post");
+var _put = createPostMethodFunc("put");
 var fetch2 = fetch_default;
-fetch2.get = createFetchMethodFunc("get");
-fetch2.head = createFetchMethodFunc("head");
-fetch2.options = createFetchMethodFunc("options");
-fetch2.delete = createPostMethodFunc("delete");
-fetch2.patch = createPostMethodFunc("patch");
-fetch2.post = createPostMethodFunc("post");
-fetch2.put = createPostMethodFunc("put");
+fetch2.get = _get;
+fetch2.head = _head;
+fetch2.options = _options;
+fetch2.delete = _delete;
+fetch2.patch = _patch;
+fetch2.post = _post;
+fetch2.put = _put;
 var index_default = fetch2;
 export {
   FetchAs,

package/package.json

@@ -2,8 +2,8 @@
 	"author": "Toufiqur Rahaman Chowdhury",
 	"description": "A lightweight `fetch` wrapper for browsers and Node.js, designed to simplify data fetching and reduce boilerplate.",
 	"dependencies": {
-		"@superutils/core": "^1.0.5",
-		"@superutils/promise": "^1.0.5"
+		"@superutils/core": "^1.0.8",
+		"@superutils/promise": "^1.0.9"
 	},
 	"files": [
 		"dist",
@@ -20,8 +20,8 @@
 	"main": "dist/index.js",
 	"name": "@superutils/fetch",
 	"peerDependencies": {
-		"@superutils/core": "^1.0.5",
-		"@superutils/promise": "^1.0.5"
+		"@superutils/core": "^1.0.8",
+		"@superutils/promise": "^1.0.9"
 	},
 	"publishConfig": {
 		"access": "public"
@@ -37,5 +37,5 @@
 	"sideEffects": false,
 	"type": "module",
 	"types": "dist/index.d.ts",
-	"version": "1.0.0"
+	"version": "1.0.2"
 }