@superutils/fetch 1.0.0 → 1.0.1

package/README.md

@@ -10,6 +10,7 @@ This package enhances the native `fetch` API by providing a streamlined interfac
 - Installation
 - Usage
     - [`fetch()`](#fetch): make HTTP requests just like built-in `fetch()`
+    - [`Method Specific Functions`](#methods)
     - [`fetchDeferred()`](#fetch-deferred): cancellable and debounced or throttled `fetch()`
     - [`post()`](#post): make post-like requests
     - [`postDeferred()`](#post-deferred) cancellable and debounced or throttled `post()`
@@ -39,7 +40,7 @@ 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
@@ -50,14 +51,38 @@ const theActualData = await fetch.get('https://dummyjson.com/products/1')
 console.log(theActualData)
 ```
 
+<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({
@@ -104,11 +129,11 @@ setTimeout(() => {
 #### 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,

package/dist/index.d.ts

@@ -17,7 +17,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,7 +29,7 @@ type FetchConf = {
     interceptors?: FetchInterceptors;
     /** Request timeout in milliseconds. */
     timeout?: number;
-};
+} & FetchRetryOptions;
 /** Default args */
 type FetchDeferredArgs = [
     url?: string | URL,
@@ -230,7 +231,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
  */
@@ -313,8 +315,9 @@ type PostOptions = Omit<FetchOptions, 'method'> & {
 };
 
 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;
 };
 
 /**
@@ -540,14 +543,73 @@ interface FetchWithMethods extends FetchWithoutMethods {
     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.
  *
  * 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.
@@ -567,4 +629,4 @@ interface FetchWithMethods extends FetchWithoutMethods {
  */
 declare const fetch: FetchWithMethods;
 
-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 FetchMethodFunc, type FetchOptions, type FetchOptionsDefaults, 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 };

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,7 +116,7 @@ var fetch = (url, options = {}) => {
   let timeoutId;
   const promise = new PromisE2(async (resolve, reject) => {
     var _a, _b;
-    const _options = mergeFetchOptions_default(defaults, options);
+    const _options = mergeFetchOptions_default(fetch.defaults, options);
     if (isEmpty2(_options.method)) _options.method = "get";
     const errorInterceptors = [..._options.interceptors.error];
     const requestInterceptors = [..._options.interceptors.request];
@@ -202,7 +202,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 +226,6 @@ var defaults = {
   },
   timeout: 0
 };
-fetch.defaults = defaults;
 var fetch_default = fetch;
 
 // src/fetchDeferred.ts

package/package.json

@@ -3,7 +3,7 @@
 	"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/promise": "^1.0.6"
 	},
 	"files": [
 		"dist",
@@ -21,7 +21,7 @@
 	"name": "@superutils/fetch",
 	"peerDependencies": {
 		"@superutils/core": "^1.0.5",
-		"@superutils/promise": "^1.0.5"
+		"@superutils/promise": "^1.0.6"
 	},
 	"publishConfig": {
 		"access": "public"
@@ -37,5 +37,5 @@
 	"sideEffects": false,
 	"type": "module",
 	"types": "dist/index.d.ts",
-	"version": "1.0.0"
+	"version": "1.0.1"
 }