@superutils/fetch 1.5.14 → 1.5.16

package/README.md

@@ -14,25 +14,26 @@ For full API reference check out the [docs page](https://alien45.github.io/super
 
 - [Features](#features)
 - [Installation](#installation)
-    - [NPM](#npm)
-    - [CDN / Browser](#cdn--browser)
-    - [Defaults](#defaults)
-        - [Timeout](#timeout)
-        - [Conent Type](#content-type)
-        - [Response Parsing](#fetch-as)
+  - [NPM](#npm)
+  - [CDN / Browser](#cdn--browser)
+  - [Defaults](#defaults)
+    - [Timeout](#timeout)
+    - [Conent Type](#content-type)
+    - [Response Parsing](#fetch-as)
 - [Usage](#usage)
-    - [`fetch()`](#fetch): drop-in replacement for built-in `fetch()`
-    - [`TimeoutPromise` Instance](#promise-features): finer control over the request
-    - [`Method Specific Functions`](#methods)
-    - [`fetch.get()`](#fetch-get)
-    - [`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()`
-    - [`Interceptors/Transformers`](#interceptors)
-    - [`Retry`](#retry) Retry on request failure
-    - [`Timeout`](#timeout) Abort request on timeout
-    - [`createClient()`](#create-client)
-    - [`createPostClient()`](#create-post-client)
+  - [`fetch()`](#fetch): drop-in replacement for built-in `fetch()`
+  - [`TimeoutPromise` Instance](#promise-features): finer control over the request
+  - [`Method Specific Functions`](#methods)
+  - [`fetch.get()`](#fetch-get)
+  - [`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()`
+  - [`Interceptors/Transformers`](#interceptors)
+  - [`Retry`](#retry) Retry on request failure
+  - [`Timeout`](#timeout) Abort request on timeout
+  - [`createClient()`](#create-client):
+  - [`createPostClient()`](#create-post-client):
+  - [`fetchFunc`](#fetch-func): Using with third-party libraries (e.g., Axios)
 
 ## Features
 
@@ -141,8 +142,8 @@ To retrieve the response in a different format (e.g., as text, a blob, or the ra
 import fetch, { FetchAs } from '@superutils/fetch'
 
 fetch
-	.get('[DUMMYJSON-DOT-COM]/products/1', { as: FetchAs.text })
-	.then(console.log)
+  .get('[DUMMYJSON-DOT-COM]/products/1', { as: FetchAs.text })
+  .then(console.log)
 ```
 
 > **Note:** To ensure type safety, the `as` property is excluded from `fetch.defaults` in TypeScript. Since this option determines the function's return type, setting it globally would prevent accurate type inference for individual requests.
@@ -159,8 +160,8 @@ Use as a drop-in replacement to built-in `fetch()`.
 import fetch from '@superutils/fetch'
 
 fetch('[DUMMYJSON-DOT-COM]/products/1')
-	.then(response => response.json())
-	.then(console.log)
+  .then(response => response.json())
+  .then(console.log)
 ```
 
 <div id="promise-features"></div>
@@ -179,11 +180,11 @@ const request = fetch('[DUMMYJSON-DOT-COM]/products/1')
 console.log(request.pending) // true
 
 request.then(() => {
-	console.log(request.resolved) // true
-	console.log(request.pending) // false
-	console.log(request.rejected) // false
-	console.log(request.aborted) // false
-	console.log(request.timedout) // false
+  console.log(request.resolved) // true
+  console.log(request.pending) // false
+  console.log(request.rejected) // false
+  console.log(request.aborted) // false
+  console.log(request.timedout) // false
 })
 ```
 
@@ -200,7 +201,7 @@ 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 }),
+  console.log('Aborted externally:', { resolved, valueOrReason }),
 )
 
 // resolve/reject before the promise is finalized
@@ -260,8 +261,8 @@ Equivalent to `fetch(url, { method: 'get', as: 'json' })`.
 import fetch from '@superutils/fetch'
 
 fetch
-	.get('[DUMMYJSON-DOT-COM]/products/1')
-	.then(product => console.log({ product }))
+  .get('[DUMMYJSON-DOT-COM]/products/1')
+  .then(product => console.log({ product }))
 ```
 
 <div id="fetch-deferred"></div>
@@ -275,22 +276,22 @@ import fetch from '@superutils/fetch'
 
 // Create a debounced search function with a 300ms delay.
 const searchProducts = fetch.get.deferred({
-	delay: 300, // Debounce delay
-	resolveIgnored: 'WITH_UNDEFINED', // Ignored (aborted) promises will resolve with `undefined`
+  delay: 300, // Debounce delay
+  resolveIgnored: 'WITH_UNDEFINED', // Ignored (aborted) promises will resolve with `undefined`
 })
 
 // User types 'iphone'
 searchProducts('[DUMMYJSON-DOT-COM]/products/search?q=iphone').then(result => {
-	console.log('Result for "iphone":', result)
+  console.log('Result for "iphone":', result)
 })
 
 // Before 300ms has passed, the user continues typing 'iphone 12'
 setTimeout(() => {
-	searchProducts('[DUMMYJSON-DOT-COM]/products/search?q=iphone 12').then(
-		result => {
-			console.log('Result for "iphone 12":', result)
-		},
-	)
+  searchProducts('[DUMMYJSON-DOT-COM]/products/search?q=iphone 12').then(
+    result => {
+      console.log('Result for "iphone 12":', result)
+    },
+  )
 }, 200)
 // Outcome:
 // The first request for "iphone" is aborted.
@@ -305,18 +306,18 @@ setTimeout(() => {
 - **`delay: 0`**: Disables debouncing and throttling, enabling sequential/queue mode. Both requests ("iphone"
   and "iphone 12") would execute, but one after the other, never simultaneously.
 - **`resolveIgnored` (enum)**: Controls how the promise for an aborted request (like the first "iphone" call) resolves.
-    1. `ResolveIgnored.WITH_UNDEFINED` (used in the example): The promise for the aborted "iphone"
-       request resolves with `undefined`.
-    2. `ResolveIgnored.WITH_LAST`: The promise for the aborted "iphone" request waits and resolves with the result
-       of the final "iphone 12" 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.
+  1. `ResolveIgnored.WITH_UNDEFINED` (used in the example): The promise for the aborted "iphone"
+     request resolves with `undefined`.
+  2. `ResolveIgnored.WITH_LAST`: The promise for the aborted "iphone" request waits and resolves with the result
+     of the final "iphone 12" 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.
 - **`resolveError` (enum)**: Controls how failed requests are handled.
-    1.  `ResolveError.NEVER`: The promise for a failed request will neither resolve nor reject, causing it to remain pending indefinitely.
-        > **Warning:** Use with caution, as this may lead to memory leaks if not handled properly.
-    2.  `ResolveError.WITH_ERROR`: The promise resolves with the `FetchError` object instead of being rejected.
-    3.  `ResolveError.WITH_UNDEFINED`: The promise resolves with an `undefined` value upon failure.
-    4.  `ResolveError.REJECT`: (Default) The promise is rejected with a `FetchError`, adhering to standard promise behavior.
+  1.  `ResolveError.NEVER`: The promise for a failed request will neither resolve nor reject, causing it to remain pending indefinitely.
+      > **Warning:** Use with caution, as this may lead to memory leaks if not handled properly.
+  2.  `ResolveError.WITH_ERROR`: The promise resolves with the `FetchError` object instead of being rejected.
+  3.  `ResolveError.WITH_UNDEFINED`: The promise resolves with an `undefined` value upon failure.
+  4.  `ResolveError.REJECT`: (Default) The promise is rejected with a `FetchError`, adhering to standard promise behavior.
 
 <!-- #### Using defaults to reduce redundancy
 
@@ -360,8 +361,8 @@ import fetch from '@superutils/fetch'
 const newProduct = { title: 'Perfume Oil' }
 
 fetch.post('[DUMMYJSON-DOT-COM]/products/add', newProduct).then(
-	createdProduct => console.log('Product created:', createdProduct),
-	error => console.error('Failed to create product:', error),
+  createdProduct => console.log('Product created:', createdProduct),
+  error => console.error('Failed to create product:', error),
 )
 ```
 
@@ -379,13 +380,13 @@ import PromisE from '@superutils/promise'
 
 // Create a throttled function to auto-save product updates.
 const saveProductThrottled = fetch.post.deferred(
-	{
-		delay: 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}`),
-	},
-	'[DUMMYJSON-DOT-COM]/products/add', // Default URL
+  {
+    delay: 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}`),
+  },
+  '[DUMMYJSON-DOT-COM]/products/add', // Default URL
 )
 // Simulate a user typing quickly, triggering multiple saves.
 console.log('User starts typing...')
@@ -417,41 +418,40 @@ 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(
-	{
-		delay: 300, // debounce delay
-		onResult: ({ refreshToken = '' }) => {
-			console.log(
-				`Auth token successfully refreshed at ${new Date().toISOString()}`,
-			)
-			currentRefreshToken = refreshToken
-		},
-	},
-	'[DUMMYJSON-DOT-COM]/auth/refresh', // Default URL
-	() => ({
-		refreshToken: currentRefreshToken,
-		expiresInMins: 30,
-	}),
+  {
+    delay: 300, // debounce delay
+    onResult: ({ refreshToken = '' }) => {
+      console.log(
+        `Auth token successfully refreshed at ${new Date().toISOString()}`,
+      )
+      currentRefreshToken = refreshToken
+    },
+  },
+  '[DUMMYJSON-DOT-COM]/auth/refresh', // Default URL
+  () => ({
+    refreshToken: currentRefreshToken,
+    expiresInMins: 30,
+  }),
 )
 
-// First authenticate user to get the initial refresh token and then request new referesh tokens
 // First authenticate user to get the initial refresh token and then request new refresh tokens
 fetch
-	.post<{ refreshToken: string }>(
-		'[DUMMYJSON-DOT-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)
+  .post<{ refreshToken: string }>(
+    '[DUMMYJSON-DOT-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).
@@ -467,8 +467,8 @@ The following interceptor callbacks allow intercepting and/or transforming at di
 #### Interceptor types (executed in sequence):
 
 1. `request`: Request interceptors are executed before a HTTP request is made.
-    - To transform the URL simply return a new or modified URL.
-    - To transform `fetch` options simply modify the options parameter
+   - To transform the URL simply return a new or modified URL.
+   - To transform `fetch` options simply modify the options parameter
 2. `response`: Response interceptors are executed after receiving a `fetch` Response regardless of the HTTP status code.
 3. `result`: Result interceptors are executed before returning the result. To transform the result simply return a new value.
    PS: if the value of `options.as` is `FetchAs.response` (`"response"`), the value received in result will be a `Response` object.
@@ -480,8 +480,8 @@ The following interceptor callbacks allow intercepting and/or transforming at di
 - If an exception is raised while executing the interceptors, it will be gracefully ignored.
 - 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.
+  - 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**
 
@@ -489,51 +489,48 @@ The following interceptor callbacks allow intercepting and/or transforming at di
 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('[DUMMYJSON-DOT-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
-		},
-	],
+  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 not successful', { url, options })
+
+      // 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('[DUMMYJSON-DOT-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('[DUMMYJSON-DOT-COM]/products/1', { interceptors })
-	.then(product => console.log({ product }))
+  .get('[DUMMYJSON-DOT-COM]/products/1', { interceptors })
+  .then(product => console.log({ product }))
 ```
 
 **Example: Add global request and error interceptors**
@@ -544,14 +541,14 @@ import fetch from '@superutils/fetch'
 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')
+  // 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)
+  // 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
@@ -568,19 +565,12 @@ The `retry` option provides a robust mechanism to automatically re-attempt faile
 import fetch from '@superutils/fetch'
 
 fetch
-	.get('[DUMMYJSON-DOT-COM]/products/1', {
-		retry: 3, // If request fails, retry up to three more times
-		// Additionally, you can control the retry strategy by using a function
-		retryIf: async (response, retryCount, error) => {
-			if (!!error) return true
-
-			// Mke sure to clone the response if result stream must be consumed here.
-			// Cloning is required to avoid "body stream already read" error.
-			const result = await response.clone().json()
-			return result !== 'expected value'
-		},
-	})
-	.then(console.log)
+  .get('[DUMMYJSON-DOT-COM]/products/1', {
+    retry: 3, // If request fails, retry up to three more times
+    // Retry on rate limits (429) or transient server errors (5xx).
+    retryIf: r => r.status === 429 || r.status >= 500,
+  })
+  .then(console.log)
 ```
 
 <div id="create-client"></div>
@@ -596,42 +586,42 @@ import { createClient } from '@superutils/fetch'
 
 // Create a "GET" client with default headers and a 5-second timeout
 const apiClient = createClient(
-	{
-		// fixed options (cannot be overridden)
-		method: 'get',
-	},
-	{
-		// common options (can be overridden)
-		headers: {
-			Authorization: 'Bearer my-secret-token',
-			'Content-Type': 'application/json',
-		},
-		timeout: 5000,
-	},
-	{
-		// defer options (can be overridden)
-		delay: 300,
-		retry: 2, // If request fails, retry up to two more times
-	},
+  {
+    // fixed options (cannot be overridden)
+    method: 'get',
+  },
+  {
+    // common options (can be overridden)
+    headers: {
+      Authorization: 'Bearer my-secret-token',
+      'Content-Type': 'application/json',
+    },
+    timeout: 5000,
+  },
+  {
+    // defer options (can be overridden)
+    delay: 300,
+    retry: 2, // If request fails, retry up to two more times
+  },
 )
 
 // Use it just like the standard fetch
 apiClient('[DUMMYJSON-DOT-COM]/products/1', {
-	// The 'method' property cannot be overridden as it is used in the fixed options when creating the client.
-	// In TypeScript, the compiler will not allow this property.
-	// In Javascript, it will simply be ignored.
-	// method: 'post',
-	timeout: 3000, // The 'timeout' property can be overridden
+  // The 'method' property cannot be overridden as it is used in the fixed options when creating the client.
+  // In TypeScript, the compiler will not allow this property.
+  // In Javascript, it will simply be ignored.
+  // method: 'post',
+  timeout: 3000, // The 'timeout' property can be overridden
 }).then(console.log, console.warn)
 
 // create a deferred client using "apiClient"
 const deferredClient = apiClient.deferred(
-	{ retry: 0 }, // disable retrying by overriding the `retry` defer option
-	'[DUMMYJSON-DOT-COM]/products/1',
-	{ timeout: 3000 },
+  { retry: 0 }, // disable retrying by overriding the `retry` defer option
+  '[DUMMYJSON-DOT-COM]/products/1',
+  { timeout: 3000 },
 )
 deferredClient({ timeout: 10000 }) // timeout is overridden by individual request
-	.then(console.log, console.warn)
+  .then(console.log, console.warn)
 ```
 
 <div id="create-post-client"></div>
@@ -647,57 +637,72 @@ import { createPostClient } from '@superutils/fetch'
 
 // Create a POST client with 10-second as the default timeout
 const postClient = createPostClient(
-	{
-		headers: { 'content-type': 'application/json' },
-	},
-	{
-		method: 'post',
-		timeout: 10000,
-	},
+  {
+    headers: { 'content-type': 'application/json' },
+  },
+  {
+    method: 'post',
+    timeout: 10000,
+  },
 )
 
 // Invoking `postClient()` automatically applies the pre-configured options
 postClient(
-	'[DUMMYJSON-DOT-COM]/products/add',
-	{ title: 'New Product' }, // data/body
-	{}, // other options
+  '[DUMMYJSON-DOT-COM]/products/add',
+  { title: 'New Product' }, // data/body
+  {}, // other options
 ).then(result => console.log('Product created:', result))
 
 // create a deferred client using "postClient"
 const deferredPatchClient = postClient.deferred(
-	{
-		delay: 300,
-		// prints only successful results
-		onResult: result =>
-			console.log('Product updated using deferred funciton:', result),
-	},
-	'[DUMMYJSON-DOT-COM]/products/add',
-	undefined, // data to be provided later
-	{
-		method: 'patch', // default method for deferredPatchClient
-		timeout: 3000,
-	},
+  {
+    delay: 300,
+    // prints only successful results
+    onResult: result =>
+      console.log('Product updated using deferred function:', result),
+  },
+  '[DUMMYJSON-DOT-COM]/products/add',
+  undefined, // data to be provided later
+  {
+    method: 'patch', // default method for deferredPatchClient
+    timeout: 3000,
+  },
 )
 deferredPatchClient({ title: 'New title 1' }) // ignored by debounce
 deferredPatchClient({ title: 'New title 2' }) // executed
 ```
 
-<div id="fetchFunc"></div>
+<div id="fetch-func"></div>
 
-### `fetchFunc`: Using Third-Party Libraries (e.g., Axios)
+### `fetchFunc`: Using with third-party libraries (e.g., Axios)
 
 The `fetchFunc` option allows you to replace the default request engine. This enables the use of third-party libraries like `axios` while still leveraging `@superutils/fetch` features such as [retries](#retry), [timeouts](#timeout), [debouncing/throttling](#fetch-deferred), and [interceptors](#interceptors).
 
 ```typescript
-import fetch, { type FetchFunc } from '@superutils/fetch'
+import fetch, {
+  FetchCustomOptions,
+  FetchFunc,
+  FetchOptions,
+} from '@superutils/fetch'
 import axios from 'axios'
 
+type Product = {
+  id: number
+  title: string
+}
 fetch
-	.get('[DUMMYJSON-DOT-COM]/products/1', {
-		// Note: The custom function must resolve with a standard Response object
-		fetchFunc: axios as FetchFunc,
-		retry: 3,
-		// ...additional options
-	})
-	.then(console.log)
+  .get<{ data: Product }>('[DUMMYJSON-DOT-COM]/products/1', {
+    /**
+     * Note: Ensure request options are compatible with the third-party
+     * engine's configuration schema.
+     *
+     * Check {@link FetchOptions} (includes `FetchCustomOptions`).
+     */
+    fetchFunc: axios as FetchFunc,
+
+    // if request fails retry maximus 3 more times
+    retry: 3,
+    // ...additional options
+  })
+  .then(({ data }) => console.log({ product: data }))
 ```