@superutils/fetch 1.2.1 → 1.2.3

package/README.md

@@ -4,19 +4,28 @@ A lightweight `fetch` wrapper for browsers and Node.js, designed to simplify dat
 
 This package enhances the native `fetch` API by providing a streamlined interface and integrating practical & useful features from `@superutils/promise`. It offers built-in support for automatic retries, request timeouts, interceptors, and effortless request cancellation, making complex asynchronous flows simple and manageable.
 
+<div v-if="false">
+
+For full API reference check out the [docs page](https://alien45.github.io/superutils/packages/@superutils/fetch/).
+
+</div>
+
 ## Table of Contents
 
 - Features
 - Installation
 - Usage
-    - [`fetch()`](#fetch): make HTTP requests just like built-in `fetch()`
+    - [`fetch()`](#fetch): drop-in replacement for built-in `fetch()`
+    - [`PromisE Features`](#promise-features): status, early finalization etc
     - [`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()`
     - [`Retry`](#retry) Retry on request failure
     - [`Timeout`](#timeout) Abort request on timeout
     - [`Interceptors/Transformers`](#interceptors)
+    - [`Reusable Clients`](#reusable-clients)
 
 ## Features
 
@@ -40,7 +49,7 @@ npm install @superutils/fetch
 
 ### `fetch(url, options)`
 
-Use as a drop-in replacement to the built-in `fetch()`.
+Use as a drop-in replacement to built-in `fetch()`.
 
 ```javascript
 import fetch from '@superutils/fetch'
@@ -50,6 +59,48 @@ fetch('https://dummyjson.com/products/1')
 	.then(console.log)
 ```
 
+<div id="promise-features"></div>
+
+### PromisE Instance: status, early cancellation
+
+All fetch calls return a `PromisE` (`@superutils/promise`) instance which means they come with additional features available in `PromisE`:
+
+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'
+
+    const request = fetch('https://dummyjson.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
+    })
+    ```
+
+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'
+
+    // 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)
+
+    // 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'))
+    ```
+
 <div id="methods"></div>
 
 ### Method Specific Functions
@@ -76,6 +127,14 @@ While `fetch()` provides access to all HTTP request methods by specifying it in
 
 All method specific functions by default return result parsed as JSON. No need for `response.json()` or `result.data.data` drilling.
 
+<div id="fetch-get"></div>
+
+### `fetch.get(url, options)`
+
+Performs a GET request and returns the result parsed as JSON by default.
+
+Equivalent to `fetch(url, { method: 'get', as: 'json' })`.
+
 ```javascript
 import fetch from '@superutils/fetch'
 
@@ -134,10 +193,11 @@ setTimeout(() => {
     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`: 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`.
+    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
 
@@ -255,6 +315,7 @@ const requestNewToken = fetch.post.deferred(
 )
 
 // 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 }>(
 		'https://dummyjson.com/auth/login',
@@ -301,74 +362,86 @@ 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: intereptors 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: Add global request and error interceptors**
+    **Example: Interceptor usage**
 
     ```javascript
-    import fetch from '@superutils/fetch'
+    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 }))
+    ```
 
-    const { interceptors } = fetch.defaults
-    interceptors.request.push((url, options) => {
-    	// a headers to all requests make by the application
-    	options.headers.append('x-auth', 'token')
-    })
+    - 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.
 
-    interceptors.error.push((err, url, options) => {
-    	// log whenever a request fails
-    	console.log('Error interceptor', err)
-    })
-    ```
+        **Example: Add global request and error 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.
-			// 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 }))
-```
+        ```javascript
+        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')
+        })
+
+        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,
+        )
+        ```
 
 <div id="retry"></div>
 
@@ -437,3 +510,94 @@ fetch.get('https://dummyjson.com/products/1', {
 	as: FetchAs.text,
 })
 ```
+
+<div id="reusable-clients"></div>
+
+### `createClient(fixedOptions, commonOptions, commonDeferOptions)`: Reusable Clients
+
+The `createClient` utility streamlines the creation of dedicated API clients by generating pre-configured fetch functions. These functions can be equipped with default options like headers, timeouts, or a specific HTTP method, which minimizes code repetition across your application. If a method is not specified during creation, the client will default to `GET`.
+
+The returned client also includes a `.deferred()` method, providing the same debounce, throttle, and sequential execution capabilities found in functions like `fetch.get.deferred()`.
+
+```javascript
+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',
+	},
+	{
+		// default options can be overridden
+		headers: {
+			Authorization: 'Bearer my-secret-token',
+			'Content-Type': 'application/json',
+		},
+		timeout: 5000,
+	},
+	{
+		// default defer options (can be overridden)
+		delayMs: 300,
+		retry: 2, // If request fails, retry up to two more times
+	},
+)
+
+// Use it just like the standard fetch
+apiClient('https://dummyjson.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
+}).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
+	'https://dummyjson.com/products/1',
+	{ timeout: 3000 },
+)
+deferredClient({ timeout: 10000 }) // timeout is overridden by individual request
+	.then(console.log, console.warn)
+```
+
+### `createPostClient(mandatoryOptions, commonOptions, commonDeferOptions)`: Reusable Post-like Clients
+
+While `createClient()` is versatile enough for any HTTP method, `createPostClient()` is specifically designed for methods that require a request body, such as `DELETE`, `PATCH`, `POST`, and `PUT`. If a method is not provided, it defaults to `POST`. The generated client accepts an additional second parameter (`data`) for the request payload.
+
+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'
+
+// Create a POST client with 10-second as the default timeout
+const postClient = createPostClient(
+	{
+		method: 'post',
+		headers: { 'content-type': 'application/json' },
+	},
+	{ timeout: 10000 },
+)
+
+// Invoking `postClient()` automatically applies the pre-configured options
+postClient(
+	'https://dummyjson.com/products/add',
+	{ title: 'New Product' }, // data/body
+	{}, // other options
+).then(console.log)
+
+// create a deferred client using "postClient"
+const updateProduct = postClient.deferred(
+	{
+		delayMs: 300, // debounce duration
+	},
+	'https://dummyjson.com/products/1',
+	{
+		method: 'patch',
+		timeout: 3000,
+	},
+)
+updateProduct({ title: 'New title 1' }) // ignored by debounce
+updateProduct({ title: 'New title 2' }) // executed
+```