@superutils/fetch 1.5.1 → 1.5.3

package/README.md

@@ -14,9 +14,11 @@ For full API reference check out the [docs page](https://alien45.github.io/super
 
 - [Features](#features)
 - [Installation](#installation)
+    - [NPM](#npm)
+    - [CDN / Browser](#cdn--browser)
 - [Usage](#usage)
     - [`fetch()`](#fetch): drop-in replacement for built-in `fetch()`
-    - [`PromisE Features`](#promise-features): status, early finalization etc
+    - [`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()`
@@ -39,10 +41,57 @@ For full API reference check out the [docs page](https://alien45.github.io/super
 
 ## Installation
 
+### NPM
+
+Install using your favorite package manager (e.g., `npm`, `yarn`, `pnpm`, `bun`, etc.):
+
 ```bash
 npm install @superutils/fetch
 ```
 
+Dependency: `@superutils/core` and `@superutils/promise` will be automatically installed by package manager
+
+### CDN / Browser
+
+If you are not using a bundler, you can include the browser build directly:
+
+```xml
+<script src="https://cdn.jsdelivr.net/npm/@superutils/fetch/dist/browser/index.min.js"></script>
+```
+
+OR,
+
+```xml
+<script src="https://cdn.jsdelivr.net/npm/@superutils/fetch@latest/dist/browser/index.min.js"></script>
+```
+
+This will expose a global namespace with the following:
+
+```javascript
+// Namespace: default export (function) from '@superutils/fetch' and all the exports as properties
+superutils.fetch
+// Namespace: default export (class) from '@superutils/promise' and all the exports as properties
+superutils.PromisE
+
+const { fetch, PromisE } = superutils
+
+// Fetch usage
+fetch('url', { method: 'get', timeout: 10_000 })
+fetch.get()
+fetch.createClient({ method: 'post', timeout: 30_000 }, {}, { delay: 500 })
+
+// PromisE usage
+new PromisE()
+await PromisE.delay(1000)
+const handleChange = PromisE.deferredCallback(
+	event => console.log({ value: event.target.value }),
+	{ delay: 300 },
+)
+```
+
+The `@superutils/fetch` browser build includes `PromisE` most (if not all) of it is used internally.
+Loading `@superutils/promise` separately will take precedence and override it.
+
 ## Usage
 
 <div id="fetch"></div>
@@ -61,9 +110,9 @@ fetch('https://dummyjson.com/products/1')
 
 <div id="promise-features"></div>
 
-### PromisE Instance: status, early cancellation
+### `TimeoutPromise` Instance (extends `PromisE`): finer control over the request
 
-All fetch calls return a `PromisE` (`@superutils/promise`) instance which means they come with additional features available in `PromisE`:
+All fetch calls return a `TimeoutPromise` instance from (`@superutils/promise`) 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.
 
@@ -78,6 +127,8 @@ 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
 })
 ```
 
@@ -101,6 +152,21 @@ request.onEarlyFinalize.push((resolved, valueOrReason) =>
 request.reject(new Error('No longer needed'))
 ```
 
+3. `abortCtrl`: an `AbortController` instance either provided in the options or created internally.
+
+4. `cancelAbort()`: function internally stop listening to abort signals. PS: the signal that has been passed to built-in `fetch` cannot be undone.
+
+5. `clearTimeout()`: function to clear timeout, effectively disabling abort on timeout.
+
+6. Promises:
+
+- `data`: the fetch result promise and also an instance of `PromisE`.
+- `timeout`: a promise that automatically rejects if request has not completed within provided `options.timeout` duration.
+
+Both of these promises can be externally finalized which will result in the fetch/timeout promise to be resolved or rejected and `abortCtrl` aborted.
+
+7. `options`: all options provided to the fetch function
+
 <div id="methods"></div>
 
 ### Method Specific Functions