@alwatr/fetch 6.0.16 → 7.0.0

package/CHANGELOG.md

@@ -3,6 +3,108 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [7.0.0](https://github.com/Alwatr/nanolib/compare/@alwatr/fetch@6.0.17...@alwatr/fetch@7.0.0) (2025-11-06)
+
+### ⚠ BREAKING CHANGES
+
+* The `fetch` function no longer throws exceptions. Instead, it returns a **tuple** following the Go-style error handling pattern:
+
+```typescript
+// Old behavior (v1.x)
+type FetchResponse = Promise<Response>;
+
+// New behavior (v2.x)
+type FetchResponse = Promise<[Response, null] | [null, Error | FetchError]>;
+```
+
+### Why This Change?
+
+1. **Explicit Error Handling**: Forces developers to handle errors at the call site
+2. **Type Safety**: TypeScript can track whether you've handled errors
+3. **No Try-Catch Boilerplate**: Cleaner, more readable code
+4. **Better Error Context**: `FetchError` provides detailed error reasons and response data
+5. **Consistent Patterns**: Aligns with modern error handling practices (Go, Rust Result types)
+
+### Migration Guide
+
+#### Before (v1.x)
+
+```typescript
+import {fetch} from '@alwatr/fetch';
+
+async function getUser(id: string) {
+  try {
+    const response = await fetch(`/api/users/${id}`);
+
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+
+    return await response.json();
+  }
+  catch (error) {
+    console.error('Failed to fetch user:', error);
+    throw error;
+  }
+}
+```
+
+#### After (v2.x)
+
+```typescript
+import {fetch, FetchError} from '@alwatr/fetch';
+
+async function getUser(id: string) {
+  const [response, error] = await fetch(`/api/users/${id}`);
+
+  if (error) {
+    console.error('Failed to fetch user:', error.message, error.response);
+    return null; // or throw, or return a default value
+  }
+
+  // response is guaranteed to be ok here
+  return await response.json();
+}
+```
+
+* enhance error handling in README with Go-style tuple pattern and FetchError examples ([e1091ec](https://github.com/Alwatr/nanolib/commit/e1091eca2c27cf3aa03e046fed3ccfad6ce704ed))
+
+### ✨ Features
+
+* add custom FetchError class for enhanced error handling in fetch requests ([31891de](https://github.com/Alwatr/nanolib/commit/31891de09437ddb86fd2101124120bf78a9552eb))
+* enhance FetchError handling with specific reasons for fetch failures ([cc6569d](https://github.com/Alwatr/nanolib/commit/cc6569de16c27f2adaecefe3bef2c76ead29ffb8))
+* enhance FetchResponse type to include FetchError for improved error handling ([dd6a0ff](https://github.com/Alwatr/nanolib/commit/dd6a0ff31ddbcd6ccdfd6f65eccbbe83b9cce237))
+
+### 🐛 Bug Fixes
+
+* add 'cache_not_found' reason to FetchErrorReason type for improved error categorization ([14dddd5](https://github.com/Alwatr/nanolib/commit/14dddd5750140f60ed4305d21226eb348795c0a3))
+* add @alwatr/has-own dependency and update tsconfig references ([1bb1c71](https://github.com/Alwatr/nanolib/commit/1bb1c71bb8e7f6c2ffb0d6a563893e37183ec54b))
+* add missing type import from @alwatr/type-helper ([2326335](https://github.com/Alwatr/nanolib/commit/23263352c2698738c5a43a5deebdf1744268e8ce))
+* export error handling types from error.js ([bb88521](https://github.com/Alwatr/nanolib/commit/bb8852197cf0878f3ca62b14d3bd046a031e52a1))
+* improve error handling in fetch function to parse response body as JSON or fallback to text ([8e02ba8](https://github.com/Alwatr/nanolib/commit/8e02ba8b4733005e52095dc9833e1e36d1f3e94a))
+* refine error handling for fetch timeout and abort scenarios ([b5ac722](https://github.com/Alwatr/nanolib/commit/b5ac7229d713897f4d39d0c406dd3839792de680))
+* replace Object.hasOwn with hasOwn import and enhance FetchError handling for better error reporting ([c320420](https://github.com/Alwatr/nanolib/commit/c320420689543aab1eebd46fe7dd601bda281002))
+* set default options for fetch function ([7bda786](https://github.com/Alwatr/nanolib/commit/7bda786a8754d876e49d42ea1e5e7379ad70170d))
+* support nodejs ([fb6d993](https://github.com/Alwatr/nanolib/commit/fb6d993fe6af56a468c73fa31a960aa601279b75))
+* timeout abort issue ([bb3845d](https://github.com/Alwatr/nanolib/commit/bb3845d2b4cec705a8021f5c65de658fefc51e21))
+* update error handling in README to reference FetchError consistently ([1f6e240](https://github.com/Alwatr/nanolib/commit/1f6e240c946a07b7ce9c4489a509597fec8705f9))
+* update fetch function to return a tuple and add options processing ([d05bfb5](https://github.com/Alwatr/nanolib/commit/d05bfb59260be5eae5aeab7bd816aa2f613dd643))
+* update fetch function to return FetchResponse and handle FetchError for improved error reporting ([ddf47e0](https://github.com/Alwatr/nanolib/commit/ddf47e07510bb0cd38fa75c8921a3d64ed370afc))
+* update FetchError data type to ensure consistent error handling ([954b79a](https://github.com/Alwatr/nanolib/commit/954b79a7ba3954565c7d09db6b188b79f1fd8fa2))
+* update FetchResponse type to ensure consistent error handling ([8da0b3a](https://github.com/Alwatr/nanolib/commit/8da0b3a8ac2801494ffa214a99792215a403b16e))
+
+### 🧹 Miscellaneous Chores
+
+* reorder jest dependency in package.json ([a098ecf](https://github.com/Alwatr/nanolib/commit/a098ecf0489596104908627c759c8dcb092d2424))
+
+### 🔗 Dependencies update
+
+* add @jest/globals dependency and remove types from tsconfig ([47ee79a](https://github.com/Alwatr/nanolib/commit/47ee79a234a026ce28ab5671f84f72aea61d8508))
+
+## [6.0.17](https://github.com/Alwatr/nanolib/compare/@alwatr/fetch@6.0.16...@alwatr/fetch@6.0.17) (2025-11-04)
+
+**Note:** Version bump only for package @alwatr/fetch
+
 ## [6.0.16](https://github.com/Alwatr/nanolib/compare/@alwatr/fetch@6.0.15...@alwatr/fetch@6.0.16) (2025-10-06)
 
 ### 🔗 Dependencies update

package/README.md

@@ -8,6 +8,7 @@ It's designed to be a drop-in replacement for the standard `fetch` to instantly
 
 ## Key Features
 
+- **Go-Style Error Handling**: Returns a tuple `[Response, null]` on success or `[null, FetchError]` on failure—no exceptions thrown.
 - **Retry Pattern**: Automatically retries failed requests on timeouts or server errors (5xx).
 - **Request Timeout**: Aborts requests that take too long to complete.
 - **Duplicate Handling**: Prevents sending identical parallel requests, returning a single response for all callers.
@@ -32,34 +33,101 @@ pnpm add @alwatr/fetch
 
 ## Quick Start
 
-Import the `fetch` function and use it just like you would the native `fetch`. It accepts a URL and an options object with several powerful enhancements.
+Import the `fetch` function and use it with tuple destructuring for elegant error handling. The function returns `[Response, null]` on success or `[null, FetchError]` on failure—no exceptions are thrown.
 
 ```typescript
 import {fetch} from '@alwatr/fetch';
 
 async function fetchProducts() {
-  try {
-    console.log('Fetching product list...');
-    const response = await fetch('/api/products', {
-      queryParams: {limit: 10, category: 'electronics'},
-      cacheStrategy: 'stale_while_revalidate',
-      timeout: '5s', // Use string duration
-    });
-
-    if (!response.ok) {
-      throw new Error(`HTTP error! status: ${response.status}`);
-    }
-
-    const data = await response.json();
-    console.log('Products:', data);
-  } catch (error) {
-    console.error('Failed to fetch products:', error);
+  console.log('Fetching product list...');
+
+  const [response, error] = await fetch('/api/products', {
+    queryParams: {limit: 10, category: 'electronics'},
+    cacheStrategy: 'stale_while_revalidate',
+    timeout: '5s',
+  });
+
+  if (error) {
+    console.error('Failed to fetch products:', error.message);
+    console.error('Error reason:', error.reason);
+    return;
   }
+
+  // At this point, response is guaranteed to be valid and ok
+  const data = await response.json();
+  console.log('Products:', data);
 }
 
 fetchProducts();
 ```
 
+## Error Handling
+
+`@alwatr/fetch` uses a **Go-style tuple return pattern** instead of throwing exceptions. This provides explicit, type-safe error handling.
+
+### Return Type
+
+```typescript
+type FetchResponse = Promise<[Response, null] | [null, FetchError]>;
+```
+
+- **Success**: `[Response, null]` - The response is guaranteed to have `response.ok === true`
+- **Failure**: `[null, FetchError]` - Contains detailed information about what went wrong
+
+### FetchError Class
+
+All errors are returned as `FetchError` instances, which provide rich context about the failure:
+
+```typescript
+class FetchError extends Error {
+  reason: FetchErrorReason; // Specific error reason
+  response?: Response; // The HTTP response (if available)
+  data?: unknown; // Parsed response body (if available)
+}
+```
+
+### Error Reasons
+
+The `reason` property indicates why the request failed:
+
+- `'http_error'`: HTTP error status (e.g., 404, 500)
+- `'timeout'`: Request exceeded the timeout duration
+- `'cache_not_found'`: Resource not found in cache (when using `cache_only`)
+- `'network_error'`: Network-level error (e.g., DNS failure, connection refused)
+- `'aborted'`: Request was aborted via AbortSignal
+- `'unknown_error'`: Unspecified error
+
+### Error Handling Example
+
+```typescript
+const [response, error] = await fetch('/api/user/profile', {
+  bearerToken: 'jwt-token',
+});
+
+if (error) {
+  switch (error.reason) {
+    case 'http_error':
+      console.error(`HTTP ${error.response?.status}:`, error.data);
+      break;
+    case 'timeout':
+      console.error('Request timed out. Please try again.');
+      break;
+    case 'network_error':
+      console.error('Network error. Check your connection.');
+      break;
+    case 'cache_not_found':
+      console.error('Data not available offline.');
+      break;
+    default:
+      console.error('Request failed:', error.message);
+  }
+  return;
+}
+
+// Safe to use response here
+const userData = await response.json();
+```
+
 ## API and Options
 
 The `fetch` function takes a `url` string and an `options` object. The options object extends the standard `RequestInit` and adds several custom options for enhanced control.
@@ -91,14 +159,17 @@ The `fetch` function takes a `url` string and an `options` object. The options o
 The `queryParams` option simplifies adding search parameters to your request URL.
 
 ```typescript
-// This will make a GET request to:
-// /api/users?page=2&sort=asc
-const response = await fetch('/api/users', {
-  queryParams: {
-    page: 2,
-    sort: 'asc',
-  },
+// This will make a GET request to: /api/users?page=2&sort=asc
+const [response, error] = await fetch('/api/users', {
+  queryParams: {page: 2, sort: 'asc'},
 });
+
+if (error) {
+  console.error('Failed to fetch users:', error.message);
+  return;
+}
+
+const users = await response.json();
 ```
 
 ### JSON Body
@@ -107,23 +178,38 @@ Use `bodyJson` to send a JavaScript object as a JSON payload. The `Content-Type`
 
 ```typescript
 // This will make a POST request to /api/orders with a JSON body
-const response = await fetch('/api/orders', {
+const [response, error] = await fetch('/api/orders', {
   method: 'POST',
   bodyJson: {
     productId: 'xyz-123',
     quantity: 2,
   },
 });
+
+if (error) {
+  console.error('Failed to create order:', error.message);
+  return;
+}
+
+const order = await response.json();
+console.log('Order created:', order);
 ```
 
 ### Timeout
 
-Set a timeout for your requests. If the request takes longer than the specified duration, it will be aborted, and the promise will reject with a `fetch_timeout` error.
+Set a timeout for your requests. If the request takes longer than the specified duration, it will be aborted and return a `FetchError` with `reason: 'timeout'`.
 
 ```typescript
-await fetch('/api/slow-endpoint', {
+const [response, error] = await fetch('/api/slow-endpoint', {
   timeout: '2.5s', // You can use duration strings
 });
+
+if (error) {
+  if (error.reason === 'timeout') {
+    console.error('Request timed out after 2.5 seconds');
+  }
+  return;
+}
 ```
 
 ### Retry Pattern
@@ -132,10 +218,17 @@ The fetch operation will automatically retry on server errors (5xx status codes)
 
 ```typescript
 // Retry up to 5 times, with a 2-second delay between each attempt
-await fetch('/api/flaky-service', {
+const [response, error] = await fetch('/api/flaky-service', {
   retry: 5,
   retryDelay: '2s',
 });
+
+if (error) {
+  console.error('Request failed after 5 retries:', error.message);
+  return;
+}
+
+const data = await response.json();
 ```
 
 ### Duplicate Request Handling
@@ -150,10 +243,14 @@ The `removeDuplicate` option prevents multiple identical requests from being sen
 ```typescript
 // Both calls will result in only ONE network request.
 // The second call will receive the response from the first.
-const [res1, res2] = await Promise.all([
+const results = await Promise.all([
   fetch('/api/data', {removeDuplicate: 'until_load'}),
   fetch('/api/data', {removeDuplicate: 'until_load'}),
 ]);
+
+// Both results will have the same response or error
+const [response1, error1] = results[0];
+const [response2, error2] = results[1];
 ```
 
 ### Cache Strategies
@@ -163,17 +260,26 @@ Leverage the browser's Cache API with `cacheStrategy`.
 - `'network_only'` (default): Standard fetch behavior; no caching.
 - `'cache_first'`: Serves from cache if available. Otherwise, fetches from the network and caches the result.
 - `'network_first'`: Fetches from the network first. If the network fails, it falls back to the cache.
+- `'cache_only'`: Only serves from cache; returns an error if not found.
+- `'update_cache'`: Fetches from network and updates the cache.
 - `'stale_while_revalidate'`: The fastest strategy. It serves stale content from the cache immediately while sending a network request in the background to update the cache for the next time.
 
 ```typescript
 // Serve news from cache instantly, but update it in the background for the next visit.
-const response = await fetch('/api/news', {
+const [response, error] = await fetch('/api/news', {
   cacheStrategy: 'stale_while_revalidate',
   revalidateCallback: (freshResponse) => {
     console.log('Cache updated with fresh data!');
     // You can use freshResponse to update the UI if needed
   },
 });
+
+if (error) {
+  console.error('Failed to load news:', error.message);
+  return;
+}
+
+const news = await response.json();
 ```
 
 ### Authentication
@@ -182,12 +288,21 @@ Easily add authentication headers with `bearerToken` or the `alwatrAuth` scheme.
 
 ```typescript
 // Using a Bearer Token
-await fetch('/api/secure/data', {
+const [response, error] = await fetch('/api/secure/data', {
   bearerToken: 'your-jwt-token-here',
 });
 
+if (error) {
+  if (error.response?.status === 401) {
+    console.error('Authentication failed. Please log in again.');
+  }
+  return;
+}
+
+const data = await response.json();
+
 // Using Alwatr's authentication scheme
-await fetch('/api/secure/data', {
+const [response2, error2] = await fetch('/api/secure/data', {
   alwatrAuth: {
     userId: 'user-id',
     userToken: 'user-auth-token',

package/dist/error.d.ts

@@ -0,0 +1,37 @@
+import type { FetchErrorReason } from "./type.js";
+/**
+ * Custom error class for fetch-related failures.
+ *
+ * This error is thrown when a fetch request fails, either due to a network issue
+ * or an HTTP error status (i.e., `response.ok` is `false`). It enriches the
+ * standard `Error` object with the `response` and the parsed `data` from the
+ * response body, allowing for more detailed error handling.
+ *
+ * @example
+ * ```typescript
+ * const [response, error] = await fetch('/api/endpoint');
+ * if (error) {
+ *   console.error(`Request failed with status ${error.response?.status}`);
+ *   console.error('Server response:', error.data);
+ * }
+ * ```
+ */
+export declare class FetchError extends Error {
+    /**
+     * The original `Response` object.
+     * This is useful for accessing headers and other response metadata.
+     * It will be `undefined` for non-HTTP errors like network failures or timeouts.
+     */
+    response?: Response;
+    /**
+     * The parsed body of the error response, typically a JSON object.
+     * It will be `undefined` for non-HTTP errors.
+     */
+    data?: JsonObject | string;
+    /**
+     * The specific reason for the fetch failure.
+     */
+    reason: FetchErrorReason;
+    constructor(reason: FetchErrorReason, message: string, response?: Response, data?: JsonObject | string);
+}
+//# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC;;;;OAIG;IACI,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAE3B;;;OAGG;IACI,IAAI,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IAElC;;OAEG;IACI,MAAM,EAAE,gBAAgB,CAAC;gBAEpB,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,MAAM;CAOvG"}

package/dist/main.cjs

@@ -1,4 +1,4 @@
-/** 📦 @alwatr/fetch v6.0.16 */
-__dev_mode__: console.debug("📦 @alwatr/fetch v6.0.16");
-"use strict";var __defProp=Object.defineProperty;var __getOwnPropDesc=Object.getOwnPropertyDescriptor;var __getOwnPropNames=Object.getOwnPropertyNames;var __hasOwnProp=Object.prototype.hasOwnProperty;var __export=(target,all)=>{for(var name in all)__defProp(target,name,{get:all[name],enumerable:true})};var __copyProps=(to,from,except,desc)=>{if(from&&typeof from==="object"||typeof from==="function"){for(let key of __getOwnPropNames(from))if(!__hasOwnProp.call(to,key)&&key!==except)__defProp(to,key,{get:()=>from[key],enumerable:!(desc=__getOwnPropDesc(from,key))||desc.enumerable})}return to};var __toCommonJS=mod=>__copyProps(__defProp({},"__esModule",{value:true}),mod);var main_exports={};__export(main_exports,{cacheSupported:()=>cacheSupported,fetch:()=>fetch});module.exports=__toCommonJS(main_exports);var import_delay=require("@alwatr/delay");var import_global_this=require("@alwatr/global-this");var import_http_primer=require("@alwatr/http-primer");var import_logger=require("@alwatr/logger");var import_parse_duration=require("@alwatr/parse-duration");var logger_=(0,import_logger.createLogger)("@alwatr/fetch");var globalThis_=(0,import_global_this.getGlobalThis)();var cacheSupported=Object.hasOwn(globalThis_,"caches");var duplicateRequestStorage_={};var defaultFetchOptions={method:"GET",headers:{},timeout:8e3,retry:3,retryDelay:1e3,removeDuplicate:"never",cacheStrategy:"network_only",cacheStorageName:"fetch_cache"};function fetch(url,options){logger_.logMethodArgs?.("fetch",{url,options});const options_={...defaultFetchOptions,...options,url};options_.window??=null;if(options_.removeDuplicate==="auto"){options_.removeDuplicate=cacheSupported?"until_load":"always"}if(options_.url.lastIndexOf("?")===-1&&options_.queryParams!=null){const queryParams=options_.queryParams;const queryArray=Object.keys(queryParams).map(key=>`${encodeURIComponent(key)}=${encodeURIComponent(String(queryParams[key]))}`);if(queryArray.length>0){options_.url+="?"+queryArray.join("&")}}if(options_.bodyJson!==void 0){options_.body=JSON.stringify(options_.bodyJson);options_.headers["content-type"]=import_http_primer.MimeTypes.JSON}if(options_.bearerToken!==void 0){options_.headers.authorization=`Bearer ${options_.bearerToken}`}else if(options_.alwatrAuth!==void 0){options_.headers.authorization=`Alwatr ${options_.alwatrAuth.userId}:${options_.alwatrAuth.userToken}`}logger_.logProperty?.("fetch.options",options_);return handleCacheStrategy_(options_)}async function handleCacheStrategy_(options){if(options.cacheStrategy==="network_only"){return handleRemoveDuplicate_(options)}logger_.logMethod?.("handleCacheStrategy_");if(!cacheSupported){logger_.incident?.("fetch","fetch_cache_strategy_unsupported",{cacheSupported});options.cacheStrategy="network_only";return handleRemoveDuplicate_(options)}const cacheStorage=await caches.open(options.cacheStorageName);const request=new Request(options.url,options);switch(options.cacheStrategy){case"cache_first":{const cachedResponse=await cacheStorage.match(request);if(cachedResponse!=null){return cachedResponse}const response=await handleRemoveDuplicate_(options);if(response.ok){cacheStorage.put(request,response.clone())}return response}case"cache_only":{const cachedResponse=await cacheStorage.match(request);if(cachedResponse==null){logger_.accident("_handleCacheStrategy","fetch_cache_not_found",{url:request.url});throw new Error("fetch_cache_not_found")}return cachedResponse}case"network_first":{try{const networkResponse=await handleRemoveDuplicate_(options);if(networkResponse.ok){cacheStorage.put(request,networkResponse.clone())}return networkResponse}catch(err){const cachedResponse=await cacheStorage.match(request);if(cachedResponse!=null){return cachedResponse}throw err}}case"update_cache":{const networkResponse=await handleRemoveDuplicate_(options);if(networkResponse.ok){cacheStorage.put(request,networkResponse.clone())}return networkResponse}case"stale_while_revalidate":{const cachedResponse=await cacheStorage.match(request);const fetchedResponsePromise=handleRemoveDuplicate_(options).then(networkResponse=>{if(networkResponse.ok){cacheStorage.put(request,networkResponse.clone());if(typeof options.revalidateCallback==="function"){setTimeout(options.revalidateCallback,0,networkResponse.clone())}}return networkResponse});return cachedResponse??fetchedResponsePromise}default:{return handleRemoveDuplicate_(options)}}}async function handleRemoveDuplicate_(options){if(options.removeDuplicate==="never"){return handleRetryPattern_(options)}logger_.logMethod?.("handleRemoveDuplicate_");const bodyString=typeof options.body==="string"?options.body:"";const cacheKey=`${options.method} ${options.url} ${bodyString}`;duplicateRequestStorage_[cacheKey]??=handleRetryPattern_(options);try{const response=await duplicateRequestStorage_[cacheKey];if(duplicateRequestStorage_[cacheKey]!=null){if(response.ok!==true||options.removeDuplicate==="until_load"){delete duplicateRequestStorage_[cacheKey]}}return response.clone()}catch(err){delete duplicateRequestStorage_[cacheKey];throw err}}async function handleRetryPattern_(options){if(!(options.retry>1)){return handleTimeout_(options)}logger_.logMethod?.("handleRetryPattern_");options.retry--;const externalAbortSignal=options.signal;try{const response=await handleTimeout_(options);if(response.status<import_http_primer.HttpStatusCodes.Error_Server_500_Internal_Server_Error){return response}throw new Error("fetch_server_error")}catch(err){logger_.accident("fetch","fetch_failed_retry",err);if(globalThis_.navigator?.onLine===false){logger_.accident("handleRetryPattern_","offline","Skip retry because offline");throw err}await import_delay.delay.by(options.retryDelay);options.signal=externalAbortSignal;return handleRetryPattern_(options)}}function handleTimeout_(options){if(options.timeout===0){return globalThis_.fetch(options.url,options)}logger_.logMethod?.("handleTimeout_");return new Promise((resolved,reject)=>{const abortController=typeof AbortController==="function"?new AbortController:null;const externalAbortSignal=options.signal;options.signal=abortController?.signal;if(abortController!==null&&externalAbortSignal!=null){externalAbortSignal.addEventListener("abort",()=>abortController.abort(),{once:true})}const timeoutId=setTimeout(()=>{reject(new Error("fetch_timeout"));abortController?.abort("fetch_timeout")},(0,import_parse_duration.parseDuration)(options.timeout));globalThis_.fetch(options.url,options).then(response=>resolved(response)).catch(reason=>reject(reason)).finally(()=>{clearTimeout(timeoutId)})})}0&&(module.exports={cacheSupported,fetch});
+/** 📦 @alwatr/fetch v7.0.0 */
+__dev_mode__: console.debug("📦 @alwatr/fetch v7.0.0");
+"use strict";var __defProp=Object.defineProperty;var __getOwnPropDesc=Object.getOwnPropertyDescriptor;var __getOwnPropNames=Object.getOwnPropertyNames;var __hasOwnProp=Object.prototype.hasOwnProperty;var __export=(target,all)=>{for(var name in all)__defProp(target,name,{get:all[name],enumerable:true})};var __copyProps=(to,from,except,desc)=>{if(from&&typeof from==="object"||typeof from==="function"){for(let key of __getOwnPropNames(from))if(!__hasOwnProp.call(to,key)&&key!==except)__defProp(to,key,{get:()=>from[key],enumerable:!(desc=__getOwnPropDesc(from,key))||desc.enumerable})}return to};var __toCommonJS=mod=>__copyProps(__defProp({},"__esModule",{value:true}),mod);var main_exports={};__export(main_exports,{FetchError:()=>FetchError,cacheSupported:()=>cacheSupported,fetch:()=>fetch});module.exports=__toCommonJS(main_exports);var import_delay=require("@alwatr/delay");var import_global_this=require("@alwatr/global-this");var import_has_own=require("@alwatr/has-own");var import_http_primer=require("@alwatr/http-primer");var import_logger=require("@alwatr/logger");var import_parse_duration=require("@alwatr/parse-duration");var FetchError=class extends Error{constructor(reason,message,response,data){super(message);this.name="FetchError";this.reason=reason;this.response=response;this.data=data}};var logger_=(0,import_logger.createLogger)("@alwatr/fetch");var globalThis_=(0,import_global_this.getGlobalThis)();var cacheSupported=(0,import_has_own.hasOwn)(globalThis_,"caches");var duplicateRequestStorage_={};var defaultFetchOptions={method:"GET",headers:{},timeout:8e3,retry:3,retryDelay:1e3,removeDuplicate:"never",cacheStrategy:"network_only",cacheStorageName:"fetch_cache"};async function fetch(url,options={}){logger_.logMethodArgs?.("fetch",{url,options});const options_=_processOptions(url,options);try{const response=await handleCacheStrategy_(options_);if(!response.ok){throw new FetchError("http_error",`HTTP error! status: ${response.status} ${response.statusText}`,response)}return[response,null]}catch(err){let error;if(err instanceof FetchError){error=err;if(error.response!==void 0&&error.data===void 0){const bodyText=await error.response.text().catch(()=>"");if(bodyText.trim().length>0){try{error.data=JSON.parse(bodyText)}catch{error.data=bodyText}}}}else if(err instanceof Error){if(err.name==="AbortError"){error=new FetchError("aborted",err.message)}else{error=new FetchError("network_error",err.message)}}else{error=new FetchError("unknown_error",String(err??"unknown_error"))}logger_.error("fetch",error.reason,{error});return[null,error]}}function _processOptions(url,options){logger_.logMethodArgs?.("_processOptions",{url,options});const options_={...defaultFetchOptions,...options,url};options_.window??=null;if(options_.removeDuplicate==="auto"){options_.removeDuplicate=cacheSupported?"until_load":"always"}if(options_.url.lastIndexOf("?")===-1&&options_.queryParams!=null){const queryParams=options_.queryParams;const queryArray=Object.keys(queryParams).map(key=>`${encodeURIComponent(key)}=${encodeURIComponent(String(queryParams[key]))}`);if(queryArray.length>0){options_.url+="?"+queryArray.join("&")}}if(options_.bodyJson!==void 0){options_.body=JSON.stringify(options_.bodyJson);options_.headers["content-type"]=import_http_primer.MimeTypes.JSON}if(options_.bearerToken!==void 0){options_.headers.authorization=`Bearer ${options_.bearerToken}`}else if(options_.alwatrAuth!==void 0){options_.headers.authorization=`Alwatr ${options_.alwatrAuth.userId}:${options_.alwatrAuth.userToken}`}logger_.logProperty?.("fetch.options",options_);return options_}async function handleCacheStrategy_(options){if(options.cacheStrategy==="network_only"){return handleRemoveDuplicate_(options)}logger_.logMethod?.("handleCacheStrategy_");if(!cacheSupported){logger_.incident?.("fetch","fetch_cache_strategy_unsupported",{cacheSupported});options.cacheStrategy="network_only";return handleRemoveDuplicate_(options)}const cacheStorage=await caches.open(options.cacheStorageName);const request=new Request(options.url,options);switch(options.cacheStrategy){case"cache_first":{const cachedResponse=await cacheStorage.match(request);if(cachedResponse!=null){return cachedResponse}const response=await handleRemoveDuplicate_(options);if(response.ok){cacheStorage.put(request,response.clone())}return response}case"cache_only":{const cachedResponse=await cacheStorage.match(request);if(cachedResponse==null){throw new FetchError("cache_not_found","Resource not found in cache")}return cachedResponse}case"network_first":{try{const networkResponse=await handleRemoveDuplicate_(options);if(networkResponse.ok){cacheStorage.put(request,networkResponse.clone())}return networkResponse}catch(err){const cachedResponse=await cacheStorage.match(request);if(cachedResponse!=null){return cachedResponse}throw err}}case"update_cache":{const networkResponse=await handleRemoveDuplicate_(options);if(networkResponse.ok){cacheStorage.put(request,networkResponse.clone())}return networkResponse}case"stale_while_revalidate":{const cachedResponse=await cacheStorage.match(request);const fetchedResponsePromise=handleRemoveDuplicate_(options).then(networkResponse=>{if(networkResponse.ok){cacheStorage.put(request,networkResponse.clone());if(typeof options.revalidateCallback==="function"){setTimeout(options.revalidateCallback,0,networkResponse.clone())}}return networkResponse});return cachedResponse??fetchedResponsePromise}default:{return handleRemoveDuplicate_(options)}}}async function handleRemoveDuplicate_(options){if(options.removeDuplicate==="never"){return handleRetryPattern_(options)}logger_.logMethod?.("handleRemoveDuplicate_");const bodyString=typeof options.body==="string"?options.body:"";const cacheKey=`${options.method} ${options.url} ${bodyString}`;duplicateRequestStorage_[cacheKey]??=handleRetryPattern_(options);try{const response=await duplicateRequestStorage_[cacheKey];if(duplicateRequestStorage_[cacheKey]!=null){if(response.ok!==true||options.removeDuplicate==="until_load"){delete duplicateRequestStorage_[cacheKey]}}return response.clone()}catch(err){delete duplicateRequestStorage_[cacheKey];throw err}}async function handleRetryPattern_(options){if(!(options.retry>1)){return handleTimeout_(options)}logger_.logMethod?.("handleRetryPattern_");options.retry--;const externalAbortSignal=options.signal;try{const response=await handleTimeout_(options);if(!response.ok&&response.status>=import_http_primer.HttpStatusCodes.Error_Server_500_Internal_Server_Error){throw new FetchError("http_error",`HTTP error! status: ${response.status} ${response.statusText}`,response)}return response}catch(err){logger_.accident("fetch","fetch_failed_retry",err);if(globalThis_.navigator?.onLine===false){logger_.accident("handleRetryPattern_","offline","Skip retry because offline");throw err}await import_delay.delay.by(options.retryDelay);options.signal=externalAbortSignal;return handleRetryPattern_(options)}}function handleTimeout_(options){if(options.timeout===0){return globalThis_.fetch(options.url,options)}logger_.logMethod?.("handleTimeout_");return new Promise((resolved,reject)=>{const abortController=typeof AbortController==="function"?new AbortController:null;const externalAbortSignal=options.signal;options.signal=abortController?.signal;if(abortController!==null&&externalAbortSignal!=null){externalAbortSignal.addEventListener("abort",()=>abortController.abort(),{once:true})}const timeoutId=setTimeout(()=>{reject(new FetchError("timeout","fetch_timeout"));abortController?.abort("fetch_timeout")},(0,import_parse_duration.parseDuration)(options.timeout));globalThis_.fetch(options.url,options).then(response=>resolved(response)).catch(reason=>reject(reason)).finally(()=>{clearTimeout(timeoutId)})})}0&&(module.exports={FetchError,cacheSupported,fetch});
 //# sourceMappingURL=main.cjs.map

package/dist/main.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../src/main.ts"],
-  "sourcesContent": ["/**\n * @module @alwatr/fetch\n *\n * An enhanced, lightweight, and dependency-free wrapper for the native `fetch` API.\n * It provides modern features like caching strategies, request retries, timeouts, and\n * duplicate request handling.\n */\n\nimport {delay} from '@alwatr/delay';\nimport {getGlobalThis} from '@alwatr/global-this';\nimport {HttpStatusCodes, MimeTypes} from '@alwatr/http-primer';\nimport {createLogger} from '@alwatr/logger';\nimport {parseDuration} from '@alwatr/parse-duration';\n\nimport type {AlwatrFetchOptions_, FetchOptions} from './type.js';\n\nexport {cacheSupported};\nexport type * from './type.js';\n\nconst logger_ = createLogger('@alwatr/fetch');\nconst globalThis_ = getGlobalThis();\n\n/**\n * A boolean flag indicating whether the browser's Cache API is supported.\n */\nconst cacheSupported = Object.hasOwn(globalThis_, 'caches');\n\n/**\n * A simple in-memory storage for tracking and managing duplicate in-flight requests.\n * The key is a unique identifier for the request (e.g., method + URL + body),\n * and the value is the promise of the ongoing fetch operation.\n */\nconst duplicateRequestStorage_: Record<string, Promise<Response>> = {};\n\n/**\n * Default options for all fetch requests. These can be overridden by passing\n * a custom `options` object to the `fetch` function.\n */\nconst defaultFetchOptions: AlwatrFetchOptions_ = {\n  method: 'GET',\n  headers: {},\n  timeout: 8_000,\n  retry: 3,\n  retryDelay: 1_000,\n  removeDuplicate: 'never',\n  cacheStrategy: 'network_only',\n  cacheStorageName: 'fetch_cache',\n};\n\n/**\n * Internal-only fetch options type, which includes the URL and ensures all\n * optional properties from AlwatrFetchOptions_ are present.\n */\ntype FetchOptions__ = AlwatrFetchOptions_ & Omit<RequestInit, 'headers'> & {url: string};\n\n/**\n * An enhanced wrapper for the native `fetch` function.\n *\n * This function extends the standard `fetch` with additional features such as:\n * - **Timeout**: Aborts the request if it takes too long.\n * - **Retry Pattern**: Automatically retries the request on failure (e.g., server errors or network issues).\n * - **Duplicate Request Handling**: Prevents sending multiple identical requests in parallel.\n * - **Cache Strategies**: Provides various caching mechanisms using the browser's Cache API.\n * - **Simplified API**: Offers convenient options for adding query parameters, JSON bodies, and auth tokens.\n *\n * @see {@link FetchOptions} for a detailed list of available options.\n *\n * @param {string} url - The URL to fetch.\n * @param {FetchOptions} options - Optional configuration for the fetch request.\n * @returns {Promise<Response>} A promise that resolves to the `Response` object for the request.\n *\n * @example\n * ```typescript\n * async function fetchProducts() {\n *   try {\n *     const response = await fetch(\"/api/products\", {\n *       queryParams: { limit: 10, category: \"electronics\" },\n *       timeout: 5_000, // 5 seconds\n *       retry: 3,\n *       cacheStrategy: \"stale_while_revalidate\",\n *     });\n *\n *     if (!response.ok) {\n *       throw new Error(`HTTP error! status: ${response.status}`);\n *     }\n *\n *     const data = await response.json();\n *     console.log(\"Products:\", data);\n *   } catch (error) {\n *     console.error(\"Failed to fetch products:\", error);\n *   }\n * }\n *\n * fetchProducts();\n * ```\n */\nexport function fetch(url: string, options: FetchOptions): Promise<Response> {\n  logger_.logMethodArgs?.('fetch', {url, options});\n\n  const options_: FetchOptions__ = {\n    ...defaultFetchOptions,\n    ...options,\n    url,\n  };\n\n  options_.window ??= null;\n\n  if (options_.removeDuplicate === 'auto') {\n    options_.removeDuplicate = cacheSupported ? 'until_load' : 'always';\n  }\n\n  // Append query parameters to the URL if they are provided and the URL doesn't already have them.\n  if (options_.url.lastIndexOf('?') === -1 && options_.queryParams != null) {\n    const queryParams = options_.queryParams;\n    // prettier-ignore\n    const queryArray = Object\n      .keys(queryParams)\n      .map(key => `${encodeURIComponent(key)}=${encodeURIComponent(String(queryParams[key]))}`);\n\n    if (queryArray.length > 0) {\n      options_.url += '?' + queryArray.join('&');\n    }\n  }\n\n  // If `bodyJson` is provided, stringify it and set the appropriate 'Content-Type' header.\n  if (options_.bodyJson !== undefined) {\n    options_.body = JSON.stringify(options_.bodyJson);\n    options_.headers['content-type'] = MimeTypes.JSON;\n  }\n\n  // Set the 'Authorization' header for bearer tokens or Alwatr's authentication scheme.\n  if (options_.bearerToken !== undefined) {\n    options_.headers.authorization = `Bearer ${options_.bearerToken}`;\n  }\n  else if (options_.alwatrAuth !== undefined) {\n    options_.headers.authorization = `Alwatr ${options_.alwatrAuth.userId}:${options_.alwatrAuth.userToken}`;\n  }\n\n  logger_.logProperty?.('fetch.options', options_);\n\n  // Start the fetch lifecycle, beginning with the cache strategy.\n  return handleCacheStrategy_(options_);\n}\n\n/**\n * Manages caching strategies for the fetch request.\n * If the strategy is `network_only`, it bypasses caching and proceeds to the next step.\n * Otherwise, it interacts with the browser's Cache API based on the selected strategy.\n *\n * @param {FetchOptions__} options - The fully configured fetch options.\n * @returns {Promise<Response>} A promise resolving to a `Response` object, either from the cache or the network.\n * @private\n */\nasync function handleCacheStrategy_(options: FetchOptions__): Promise<Response> {\n  if (options.cacheStrategy === 'network_only') {\n    return handleRemoveDuplicate_(options);\n  }\n  // else\n\n  logger_.logMethod?.('handleCacheStrategy_');\n\n  if (!cacheSupported) {\n    logger_.incident?.('fetch', 'fetch_cache_strategy_unsupported', {\n      cacheSupported,\n    });\n    // Fallback to network_only if Cache API is not available.\n    options.cacheStrategy = 'network_only';\n    return handleRemoveDuplicate_(options);\n  }\n  // else\n\n  const cacheStorage = await caches.open(options.cacheStorageName);\n\n  const request = new Request(options.url, options);\n\n  switch (options.cacheStrategy) {\n    case 'cache_first': {\n      const cachedResponse = await cacheStorage.match(request);\n      if (cachedResponse != null) {\n        return cachedResponse;\n      }\n      // else\n\n      const response = await handleRemoveDuplicate_(options);\n      if (response.ok) {\n        cacheStorage.put(request, response.clone());\n      }\n      return response;\n    }\n\n    case 'cache_only': {\n      const cachedResponse = await cacheStorage.match(request);\n      if (cachedResponse == null) {\n        logger_.accident('_handleCacheStrategy', 'fetch_cache_not_found', {url: request.url});\n        throw new Error('fetch_cache_not_found');\n      }\n      // else\n\n      return cachedResponse;\n    }\n\n    case 'network_first': {\n      try {\n        const networkResponse = await handleRemoveDuplicate_(options);\n        if (networkResponse.ok) {\n          cacheStorage.put(request, networkResponse.clone());\n        }\n        return networkResponse;\n      }\n      catch (err) {\n        const cachedResponse = await cacheStorage.match(request);\n        if (cachedResponse != null) {\n          return cachedResponse;\n        }\n        // else\n\n        throw err;\n      }\n    }\n\n    case 'update_cache': {\n      const networkResponse = await handleRemoveDuplicate_(options);\n      if (networkResponse.ok) {\n        cacheStorage.put(request, networkResponse.clone());\n      }\n      return networkResponse;\n    }\n\n    case 'stale_while_revalidate': {\n      const cachedResponse = await cacheStorage.match(request);\n      const fetchedResponsePromise = handleRemoveDuplicate_(options).then((networkResponse) => {\n        if (networkResponse.ok) {\n          cacheStorage.put(request, networkResponse.clone());\n          if (typeof options.revalidateCallback === 'function') {\n            setTimeout(options.revalidateCallback, 0, networkResponse.clone());\n          }\n        }\n        return networkResponse;\n      });\n\n      return cachedResponse ?? fetchedResponsePromise;\n    }\n\n    default: {\n      return handleRemoveDuplicate_(options);\n    }\n  }\n}\n\n/**\n * Handles duplicate request elimination.\n *\n * It creates a unique key based on the request method, URL, and body. If a request with the\n * same key is already in flight, it returns the promise of the existing request instead of\n * creating a new one. This prevents redundant network calls for identical parallel requests.\n *\n * @param {FetchOptions__} options - The fully configured fetch options.\n * @returns {Promise<Response>} A promise resolving to a cloned `Response` object.\n * @private\n */\nasync function handleRemoveDuplicate_(options: FetchOptions__): Promise<Response> {\n  if (options.removeDuplicate === 'never') {\n    return handleRetryPattern_(options);\n  }\n  // else\n\n  logger_.logMethod?.('handleRemoveDuplicate_');\n\n  // Create a unique key for the request. Including the body is crucial to differentiate\n  // between requests to the same URL but with different payloads (e.g., POST requests).\n  const bodyString = typeof options.body === 'string' ? options.body : '';\n  const cacheKey = `${options.method} ${options.url} ${bodyString}`;\n\n  // If a request with the same key doesn't exist, create it and store its promise.\n  duplicateRequestStorage_[cacheKey] ??= handleRetryPattern_(options);\n\n  try {\n    // Await the shared promise to get the response.\n    const response = await duplicateRequestStorage_[cacheKey];\n\n    // Clean up the stored promise based on the removal strategy.\n    if (duplicateRequestStorage_[cacheKey] != null) {\n      if (response.ok !== true || options.removeDuplicate === 'until_load') {\n        // Remove after completion for 'until_load' or if the request failed.\n        delete duplicateRequestStorage_[cacheKey];\n      }\n    }\n\n    // Return a clone of the response, so each caller can consume the body independently.\n    return response.clone();\n  }\n  catch (err) {\n    // If the request fails, remove it from storage to allow for retries.\n    delete duplicateRequestStorage_[cacheKey];\n    throw err;\n  }\n}\n\n/**\n * Implements a retry mechanism for the fetch request.\n * If the request fails due to a server error (status >= 500) or a timeout,\n * it will be retried up to the specified number of times.\n *\n * @param {FetchOptions__} options - The fully configured fetch options.\n * @returns {Promise<Response>} A promise that resolves to the final `Response` after all retries.\n * @private\n */\nasync function handleRetryPattern_(options: FetchOptions__): Promise<Response> {\n  if (!(options.retry > 1)) {\n    return handleTimeout_(options);\n  }\n  // else\n\n  logger_.logMethod?.('handleRetryPattern_');\n  options.retry--;\n\n  const externalAbortSignal = options.signal;\n\n  try {\n    const response = await handleTimeout_(options);\n\n    // Only retry on server errors (5xx). Client errors (4xx) are not retried.\n    if (response.status < HttpStatusCodes.Error_Server_500_Internal_Server_Error) {\n      return response;\n    }\n    // else\n\n    throw new Error('fetch_server_error');\n  }\n  catch (err) {\n    logger_.accident('fetch', 'fetch_failed_retry', err);\n\n    // Do not retry if the browser is offline.\n    if (globalThis_.navigator?.onLine === false) {\n      logger_.accident('handleRetryPattern_', 'offline', 'Skip retry because offline');\n      throw err;\n    }\n\n    await delay.by(options.retryDelay);\n\n    // Restore the original signal for the next attempt.\n    options.signal = externalAbortSignal;\n    return handleRetryPattern_(options);\n  }\n}\n\n/**\n * Wraps the native fetch call with a timeout mechanism.\n *\n * It uses an `AbortController` to abort the request if it does not complete\n * within the specified `timeout` duration. It also respects external abort signals.\n *\n * @param {FetchOptions__} options - The fully configured fetch options.\n * @returns {Promise<Response>} A promise that resolves with the `Response` or rejects on timeout.\n * @private\n */\nfunction handleTimeout_(options: FetchOptions__): Promise<Response> {\n  if (options.timeout === 0) {\n    // If timeout is disabled, call fetch directly.\n    return globalThis_.fetch(options.url, options);\n  }\n\n  logger_.logMethod?.('handleTimeout_');\n\n  return new Promise((resolved, reject) => {\n    const abortController = typeof AbortController === 'function' ? new AbortController() : null;\n    const externalAbortSignal = options.signal;\n    options.signal = abortController?.signal;\n\n    // If an external AbortSignal is provided, listen to it and propagate the abort.\n    if (abortController !== null && externalAbortSignal != null) {\n      externalAbortSignal.addEventListener('abort', () => abortController.abort(), {once: true});\n    }\n\n    const timeoutId = setTimeout(() => {\n      reject(new Error('fetch_timeout'));\n      abortController?.abort('fetch_timeout');\n    }, parseDuration(options.timeout!));\n\n    globalThis_\n      .fetch(options.url, options)\n      .then((response) => resolved(response))\n      .catch((reason) => reject(reason))\n      .finally(() => {\n        // Clean up the timeout to prevent it from firing after the request has completed.\n        clearTimeout(timeoutId);\n      });\n  });\n}\n"],
-  "mappings": "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",
+  "sources": ["../src/main.ts", "../src/error.ts"],
+  "sourcesContent": ["/**\n * @module @alwatr/fetch\n *\n * An enhanced, lightweight, and dependency-free wrapper for the native `fetch`\n * API. It provides modern features like caching strategies, request retries,\n * timeouts, and duplicate request handling.\n */\n\nimport {delay} from '@alwatr/delay';\nimport {getGlobalThis} from '@alwatr/global-this';\nimport {hasOwn} from '@alwatr/has-own';\nimport {HttpStatusCodes, MimeTypes} from '@alwatr/http-primer';\nimport {createLogger} from '@alwatr/logger';\nimport {parseDuration} from '@alwatr/parse-duration';\n\nimport {FetchError} from './error.js';\n\nimport type {AlwatrFetchOptions_, FetchOptions, FetchResponse} from './type.js';\n\nexport {cacheSupported};\nexport type * from './type.js';\nexport * from './error.js';\n\nconst logger_ = createLogger('@alwatr/fetch');\nconst globalThis_ = getGlobalThis();\n\n/**\n * A boolean flag indicating whether the browser's Cache API is supported.\n */\nconst cacheSupported = /* #__PURE__ */ hasOwn(globalThis_, 'caches');\n\n/**\n * A simple in-memory storage for tracking and managing duplicate in-flight requests.\n * The key is a unique identifier for the request (e.g., method + URL + body),\n * and the value is the promise of the ongoing fetch operation.\n */\nconst duplicateRequestStorage_: Record<string, Promise<Response>> = {};\n\n/**\n * Default options for all fetch requests. These can be overridden by passing\n * a custom `options` object to the `fetch` function.\n */\nconst defaultFetchOptions: AlwatrFetchOptions_ = {\n  method: 'GET',\n  headers: {},\n  timeout: 8_000,\n  retry: 3,\n  retryDelay: 1_000,\n  removeDuplicate: 'never',\n  cacheStrategy: 'network_only',\n  cacheStorageName: 'fetch_cache',\n};\n\n/**\n * Internal-only fetch options type, which includes the URL and ensures all\n * optional properties from AlwatrFetchOptions_ are present.\n */\ntype FetchOptions__ = AlwatrFetchOptions_ & Omit<RequestInit, 'headers'> & {url: string};\n\n/**\n * An enhanced wrapper for the native `fetch` function.\n *\n * This function extends the standard `fetch` with additional features such as:\n * - **Timeout**: Aborts the request if it takes too long.\n * - **Retry Pattern**: Automatically retries the request on failure (e.g., server errors or network issues).\n * - **Duplicate Request Handling**: Prevents sending multiple identical requests in parallel.\n * - **Cache Strategies**: Provides various caching mechanisms using the browser's Cache API.\n * - **Simplified API**: Offers convenient options for adding query parameters, JSON bodies, and auth tokens.\n *\n * @see {@link FetchOptions} for a detailed list of available options.\n *\n * @param {string} url - The URL to fetch.\n * @param {FetchOptions} options - Optional configuration for the fetch request.\n * @returns {Promise<FetchResponse>} A promise that resolves to a tuple. On\n * success, it returns `[response, null]`. On failure, it returns `[null,\n * FetchError]`.\n *\n * @example\n * ```typescript\n * import {fetch} from '@alwatr/fetch';\n *\n * async function fetchProducts() {\n *   const [response, error] = await fetch('/api/products', {\n *     queryParams: { limit: 10 },\n *     timeout: 5_000,\n *   });\n *\n *   if (error) {\n *     console.error('Request failed:', error.reason);\n *     return;\n *   }\n *\n *   // At this point, response is guaranteed to be valid and ok.\n *   const data = await response.json();\n *   console.log('Products:', data);\n * }\n *\n * fetchProducts();\n * ```\n */\nexport async function fetch(url: string, options: FetchOptions = {}): Promise<FetchResponse> {\n  logger_.logMethodArgs?.('fetch', {url, options});\n\n  const options_ = _processOptions(url, options);\n\n  try {\n    // Start the fetch lifecycle, beginning with the cache strategy.\n    const response = await handleCacheStrategy_(options_);\n\n    if (!response.ok) {\n      throw new FetchError('http_error', `HTTP error! status: ${response.status} ${response.statusText}`, response);\n    }\n\n    return [response, null];\n  }\n  catch (err) {\n    let error: FetchError;\n\n    if (err instanceof FetchError) {\n      error = err;\n\n      if (error.response !== undefined && error.data === undefined) {\n        const bodyText = await error.response.text().catch(() => '');\n\n        if (bodyText.trim().length > 0) {\n          try {\n            // Try to parse as JSON\n            error.data = JSON.parse(bodyText);\n          }\n          catch {\n            error.data = bodyText;\n          }\n        }\n      }\n    }\n    else if (err instanceof Error) {\n      if (err.name === 'AbortError') {\n        error = new FetchError('aborted', err.message);\n      }\n      else {\n        error = new FetchError('network_error', err.message);\n      }\n    }\n    else {\n      error = new FetchError('unknown_error', String(err ?? 'unknown_error'));\n    }\n\n    logger_.error('fetch', error.reason, {error});\n    return [null, error];\n  }\n}\n\n/**\n * Processes and sanitizes the fetch options.\n *\n * @param {string} url - The URL to fetch.\n * @param {FetchOptions} options - The user-provided options.\n * @returns {FetchOptions__} The processed and complete fetch options.\n * @private\n */\nfunction _processOptions(url: string, options: FetchOptions): FetchOptions__ {\n  logger_.logMethodArgs?.('_processOptions', {url, options});\n\n  const options_: FetchOptions__ = {\n    ...defaultFetchOptions,\n    ...options,\n    url,\n  };\n\n  options_.window ??= null;\n\n  if (options_.removeDuplicate === 'auto') {\n    options_.removeDuplicate = cacheSupported ? 'until_load' : 'always';\n  }\n\n  // Append query parameters to the URL if they are provided and the URL doesn't already have them.\n  if (options_.url.lastIndexOf('?') === -1 && options_.queryParams != null) {\n    const queryParams = options_.queryParams;\n    // prettier-ignore\n    const queryArray = Object\n      .keys(queryParams)\n      .map(key => `${encodeURIComponent(key)}=${encodeURIComponent(String(queryParams[key]))}`);\n\n    if (queryArray.length > 0) {\n      options_.url += '?' + queryArray.join('&');\n    }\n  }\n\n  // If `bodyJson` is provided, stringify it and set the appropriate 'Content-Type' header.\n  if (options_.bodyJson !== undefined) {\n    options_.body = JSON.stringify(options_.bodyJson);\n    options_.headers['content-type'] = MimeTypes.JSON;\n  }\n\n  // Set the 'Authorization' header for bearer tokens or Alwatr's authentication scheme.\n  if (options_.bearerToken !== undefined) {\n    options_.headers.authorization = `Bearer ${options_.bearerToken}`;\n  }\n  else if (options_.alwatrAuth !== undefined) {\n    options_.headers.authorization = `Alwatr ${options_.alwatrAuth.userId}:${options_.alwatrAuth.userToken}`;\n  }\n\n  logger_.logProperty?.('fetch.options', options_);\n\n  return options_;\n}\n\n/**\n * Manages caching strategies for the fetch request.\n * If the strategy is `network_only`, it bypasses caching and proceeds to the next step.\n * Otherwise, it interacts with the browser's Cache API based on the selected strategy.\n *\n * @param {FetchOptions__} options - The fully configured fetch options.\n * @returns {Promise<Response>} A promise resolving to a `Response` object, either from the cache or the network.\n * @private\n */\nasync function handleCacheStrategy_(options: FetchOptions__): Promise<Response> {\n  if (options.cacheStrategy === 'network_only') {\n    return handleRemoveDuplicate_(options);\n  }\n  // else\n\n  logger_.logMethod?.('handleCacheStrategy_');\n\n  if (!cacheSupported) {\n    logger_.incident?.('fetch', 'fetch_cache_strategy_unsupported', {\n      cacheSupported,\n    });\n    // Fallback to network_only if Cache API is not available.\n    options.cacheStrategy = 'network_only';\n    return handleRemoveDuplicate_(options);\n  }\n  // else\n\n  const cacheStorage = await caches.open(options.cacheStorageName);\n\n  const request = new Request(options.url, options);\n\n  switch (options.cacheStrategy) {\n    case 'cache_first': {\n      const cachedResponse = await cacheStorage.match(request);\n      if (cachedResponse != null) {\n        return cachedResponse;\n      }\n      // else\n\n      const response = await handleRemoveDuplicate_(options);\n      if (response.ok) {\n        cacheStorage.put(request, response.clone());\n      }\n      return response;\n    }\n\n    case 'cache_only': {\n      const cachedResponse = await cacheStorage.match(request);\n      if (cachedResponse == null) {\n        throw new FetchError('cache_not_found', 'Resource not found in cache');\n      }\n      // else\n\n      return cachedResponse;\n    }\n\n    case 'network_first': {\n      try {\n        const networkResponse = await handleRemoveDuplicate_(options);\n        if (networkResponse.ok) {\n          cacheStorage.put(request, networkResponse.clone());\n        }\n        return networkResponse;\n      }\n      catch (err) {\n        const cachedResponse = await cacheStorage.match(request);\n        if (cachedResponse != null) {\n          return cachedResponse;\n        }\n        // else\n\n        throw err;\n      }\n    }\n\n    case 'update_cache': {\n      const networkResponse = await handleRemoveDuplicate_(options);\n      if (networkResponse.ok) {\n        cacheStorage.put(request, networkResponse.clone());\n      }\n      return networkResponse;\n    }\n\n    case 'stale_while_revalidate': {\n      const cachedResponse = await cacheStorage.match(request);\n      const fetchedResponsePromise = handleRemoveDuplicate_(options).then((networkResponse) => {\n        if (networkResponse.ok) {\n          cacheStorage.put(request, networkResponse.clone());\n          if (typeof options.revalidateCallback === 'function') {\n            setTimeout(options.revalidateCallback, 0, networkResponse.clone());\n          }\n        }\n        return networkResponse;\n      });\n\n      return cachedResponse ?? fetchedResponsePromise;\n    }\n\n    default: {\n      return handleRemoveDuplicate_(options);\n    }\n  }\n}\n\n/**\n * Handles duplicate request elimination.\n *\n * It creates a unique key based on the request method, URL, and body. If a request with the\n * same key is already in flight, it returns the promise of the existing request instead of\n * creating a new one. This prevents redundant network calls for identical parallel requests.\n *\n * @param {FetchOptions__} options - The fully configured fetch options.\n * @returns {Promise<Response>} A promise resolving to a cloned `Response` object.\n * @private\n */\nasync function handleRemoveDuplicate_(options: FetchOptions__): Promise<Response> {\n  if (options.removeDuplicate === 'never') {\n    return handleRetryPattern_(options);\n  }\n  // else\n\n  logger_.logMethod?.('handleRemoveDuplicate_');\n\n  // Create a unique key for the request. Including the body is crucial to differentiate\n  // between requests to the same URL but with different payloads (e.g., POST requests).\n  const bodyString = typeof options.body === 'string' ? options.body : '';\n  const cacheKey = `${options.method} ${options.url} ${bodyString}`;\n\n  // If a request with the same key doesn't exist, create it and store its promise.\n  duplicateRequestStorage_[cacheKey] ??= handleRetryPattern_(options);\n\n  try {\n    // Await the shared promise to get the response.\n    const response = await duplicateRequestStorage_[cacheKey];\n\n    // Clean up the stored promise based on the removal strategy.\n    if (duplicateRequestStorage_[cacheKey] != null) {\n      if (response.ok !== true || options.removeDuplicate === 'until_load') {\n        // Remove after completion for 'until_load' or if the request failed.\n        delete duplicateRequestStorage_[cacheKey];\n      }\n    }\n\n    // Return a clone of the response, so each caller can consume the body independently.\n    return response.clone();\n  }\n  catch (err) {\n    // If the request fails, remove it from storage to allow for retries.\n    delete duplicateRequestStorage_[cacheKey];\n    throw err;\n  }\n}\n\n/**\n * Implements a retry mechanism for the fetch request.\n * If the request fails due to a server error (status >= 500) or a timeout,\n * it will be retried up to the specified number of times.\n *\n * @param {FetchOptions__} options - The fully configured fetch options.\n * @returns {Promise<Response>} A promise that resolves to the final `Response` after all retries.\n * @private\n */\nasync function handleRetryPattern_(options: FetchOptions__): Promise<Response> {\n  if (!(options.retry > 1)) {\n    return handleTimeout_(options);\n  }\n  // else\n\n  logger_.logMethod?.('handleRetryPattern_');\n  options.retry--;\n\n  const externalAbortSignal = options.signal;\n\n  try {\n    const response = await handleTimeout_(options);\n\n    if (!response.ok && response.status >= HttpStatusCodes.Error_Server_500_Internal_Server_Error) {\n      // only retry for server errors (5xx)\n      throw new FetchError('http_error', `HTTP error! status: ${response.status} ${response.statusText}`, response);\n    }\n\n    return response;\n  }\n  catch (err) {\n    logger_.accident('fetch', 'fetch_failed_retry', err);\n\n    // Do not retry if the browser is offline.\n    if (globalThis_.navigator?.onLine === false) {\n      logger_.accident('handleRetryPattern_', 'offline', 'Skip retry because offline');\n      throw err;\n    }\n\n    await delay.by(options.retryDelay);\n\n    // Restore the original signal for the next attempt.\n    options.signal = externalAbortSignal;\n    return handleRetryPattern_(options);\n  }\n}\n\n/**\n * Wraps the native fetch call with a timeout mechanism.\n *\n * It uses an `AbortController` to abort the request if it does not complete\n * within the specified `timeout` duration. It also respects external abort signals.\n *\n * @param {FetchOptions__} options - The fully configured fetch options.\n * @returns {Promise<Response>} A promise that resolves with the `Response` or rejects on timeout.\n * @private\n */\nfunction handleTimeout_(options: FetchOptions__): Promise<Response> {\n  if (options.timeout === 0) {\n    // If timeout is disabled, call fetch directly.\n    return globalThis_.fetch(options.url, options);\n  }\n\n  logger_.logMethod?.('handleTimeout_');\n\n  return new Promise((resolved, reject) => {\n    const abortController = typeof AbortController === 'function' ? new AbortController() : null;\n    const externalAbortSignal = options.signal;\n    options.signal = abortController?.signal;\n\n    // If an external AbortSignal is provided, listen to it and propagate the abort.\n    if (abortController !== null && externalAbortSignal != null) {\n      externalAbortSignal.addEventListener('abort', () => abortController.abort(), {once: true});\n    }\n\n    const timeoutId = setTimeout(() => {\n      reject(new FetchError('timeout', 'fetch_timeout'));\n      abortController?.abort('fetch_timeout');\n    }, parseDuration(options.timeout!));\n\n    globalThis_\n      .fetch(options.url, options)\n      .then((response) => resolved(response))\n      .catch((reason) => reject(reason))\n      .finally(() => {\n        // Clean up the timeout to prevent it from firing after the request has completed.\n        clearTimeout(timeoutId);\n      });\n  });\n}\n", "import type { FetchErrorReason } from \"./type.js\";\n\n/**\n * Custom error class for fetch-related failures.\n *\n * This error is thrown when a fetch request fails, either due to a network issue\n * or an HTTP error status (i.e., `response.ok` is `false`). It enriches the\n * standard `Error` object with the `response` and the parsed `data` from the\n * response body, allowing for more detailed error handling.\n *\n * @example\n * ```typescript\n * const [response, error] = await fetch('/api/endpoint');\n * if (error) {\n *   console.error(`Request failed with status ${error.response?.status}`);\n *   console.error('Server response:', error.data);\n * }\n * ```\n */\nexport class FetchError extends Error {\n  /**\n   * The original `Response` object.\n   * This is useful for accessing headers and other response metadata.\n   * It will be `undefined` for non-HTTP errors like network failures or timeouts.\n   */\n  public response?: Response;\n\n  /**\n   * The parsed body of the error response, typically a JSON object.\n   * It will be `undefined` for non-HTTP errors.\n   */\n  public data?: JsonObject | string;\n\n  /**\n   * The specific reason for the fetch failure.\n   */\n  public reason: FetchErrorReason;\n\n  constructor(reason: FetchErrorReason, message: string, response?: Response, data?: JsonObject | string) {\n    super(message);\n    this.name = 'FetchError';\n    this.reason = reason;\n    this.response = response;\n    this.data = data;\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/main.d.ts

@@ -1,13 +1,14 @@
 /**
  * @module @alwatr/fetch
  *
- * An enhanced, lightweight, and dependency-free wrapper for the native `fetch` API.
- * It provides modern features like caching strategies, request retries, timeouts, and
- * duplicate request handling.
+ * An enhanced, lightweight, and dependency-free wrapper for the native `fetch`
+ * API. It provides modern features like caching strategies, request retries,
+ * timeouts, and duplicate request handling.
  */
-import type { FetchOptions } from './type.js';
+import type { FetchOptions, FetchResponse } from './type.js';
 export { cacheSupported };
 export type * from './type.js';
+export * from './error.js';
 /**
  * A boolean flag indicating whether the browser's Cache API is supported.
  */
@@ -26,32 +27,32 @@ declare const cacheSupported: boolean;
  *
  * @param {string} url - The URL to fetch.
  * @param {FetchOptions} options - Optional configuration for the fetch request.
- * @returns {Promise<Response>} A promise that resolves to the `Response` object for the request.
+ * @returns {Promise<FetchResponse>} A promise that resolves to a tuple. On
+ * success, it returns `[response, null]`. On failure, it returns `[null,
+ * FetchError]`.
  *
  * @example
  * ```typescript
+ * import {fetch} from '@alwatr/fetch';
+ *
  * async function fetchProducts() {
- *   try {
- *     const response = await fetch("/api/products", {
- *       queryParams: { limit: 10, category: "electronics" },
- *       timeout: 5_000, // 5 seconds
- *       retry: 3,
- *       cacheStrategy: "stale_while_revalidate",
- *     });
- *
- *     if (!response.ok) {
- *       throw new Error(`HTTP error! status: ${response.status}`);
- *     }
- *
- *     const data = await response.json();
- *     console.log("Products:", data);
- *   } catch (error) {
- *     console.error("Failed to fetch products:", error);
+ *   const [response, error] = await fetch('/api/products', {
+ *     queryParams: { limit: 10 },
+ *     timeout: 5_000,
+ *   });
+ *
+ *   if (error) {
+ *     console.error('Request failed:', error.reason);
+ *     return;
  *   }
+ *
+ *   // At this point, response is guaranteed to be valid and ok.
+ *   const data = await response.json();
+ *   console.log('Products:', data);
  * }
  *
  * fetchProducts();
  * ```
  */
-export declare function fetch(url: string, options: FetchOptions): Promise<Response>;
+export declare function fetch(url: string, options?: FetchOptions): Promise<FetchResponse>;
 //# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,OAAO,KAAK,EAAsB,YAAY,EAAC,MAAM,WAAW,CAAC;AAEjE,OAAO,EAAC,cAAc,EAAC,CAAC;AACxB,mBAAmB,WAAW,CAAC;AAK/B;;GAEG;AACH,QAAA,MAAM,cAAc,SAAuC,CAAC;AA8B5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,CA8C3E"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH,OAAO,KAAK,EAAsB,YAAY,EAAE,aAAa,EAAC,MAAM,WAAW,CAAC;AAEhF,OAAO,EAAC,cAAc,EAAC,CAAC;AACxB,mBAAmB,WAAW,CAAC;AAC/B,cAAc,YAAY,CAAC;AAK3B;;GAEG;AACH,QAAA,MAAM,cAAc,SAAgD,CAAC;AA8BrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CAkD3F"}

package/dist/main.mjs

@@ -1,4 +1,4 @@
-/** 📦 @alwatr/fetch v6.0.16 */
-__dev_mode__: console.debug("📦 @alwatr/fetch v6.0.16");
-import{delay}from"@alwatr/delay";import{getGlobalThis}from"@alwatr/global-this";import{HttpStatusCodes,MimeTypes}from"@alwatr/http-primer";import{createLogger}from"@alwatr/logger";import{parseDuration}from"@alwatr/parse-duration";var logger_=createLogger("@alwatr/fetch");var globalThis_=getGlobalThis();var cacheSupported=Object.hasOwn(globalThis_,"caches");var duplicateRequestStorage_={};var defaultFetchOptions={method:"GET",headers:{},timeout:8e3,retry:3,retryDelay:1e3,removeDuplicate:"never",cacheStrategy:"network_only",cacheStorageName:"fetch_cache"};function fetch(url,options){logger_.logMethodArgs?.("fetch",{url,options});const options_={...defaultFetchOptions,...options,url};options_.window??=null;if(options_.removeDuplicate==="auto"){options_.removeDuplicate=cacheSupported?"until_load":"always"}if(options_.url.lastIndexOf("?")===-1&&options_.queryParams!=null){const queryParams=options_.queryParams;const queryArray=Object.keys(queryParams).map(key=>`${encodeURIComponent(key)}=${encodeURIComponent(String(queryParams[key]))}`);if(queryArray.length>0){options_.url+="?"+queryArray.join("&")}}if(options_.bodyJson!==void 0){options_.body=JSON.stringify(options_.bodyJson);options_.headers["content-type"]=MimeTypes.JSON}if(options_.bearerToken!==void 0){options_.headers.authorization=`Bearer ${options_.bearerToken}`}else if(options_.alwatrAuth!==void 0){options_.headers.authorization=`Alwatr ${options_.alwatrAuth.userId}:${options_.alwatrAuth.userToken}`}logger_.logProperty?.("fetch.options",options_);return handleCacheStrategy_(options_)}async function handleCacheStrategy_(options){if(options.cacheStrategy==="network_only"){return handleRemoveDuplicate_(options)}logger_.logMethod?.("handleCacheStrategy_");if(!cacheSupported){logger_.incident?.("fetch","fetch_cache_strategy_unsupported",{cacheSupported});options.cacheStrategy="network_only";return handleRemoveDuplicate_(options)}const cacheStorage=await caches.open(options.cacheStorageName);const request=new Request(options.url,options);switch(options.cacheStrategy){case"cache_first":{const cachedResponse=await cacheStorage.match(request);if(cachedResponse!=null){return cachedResponse}const response=await handleRemoveDuplicate_(options);if(response.ok){cacheStorage.put(request,response.clone())}return response}case"cache_only":{const cachedResponse=await cacheStorage.match(request);if(cachedResponse==null){logger_.accident("_handleCacheStrategy","fetch_cache_not_found",{url:request.url});throw new Error("fetch_cache_not_found")}return cachedResponse}case"network_first":{try{const networkResponse=await handleRemoveDuplicate_(options);if(networkResponse.ok){cacheStorage.put(request,networkResponse.clone())}return networkResponse}catch(err){const cachedResponse=await cacheStorage.match(request);if(cachedResponse!=null){return cachedResponse}throw err}}case"update_cache":{const networkResponse=await handleRemoveDuplicate_(options);if(networkResponse.ok){cacheStorage.put(request,networkResponse.clone())}return networkResponse}case"stale_while_revalidate":{const cachedResponse=await cacheStorage.match(request);const fetchedResponsePromise=handleRemoveDuplicate_(options).then(networkResponse=>{if(networkResponse.ok){cacheStorage.put(request,networkResponse.clone());if(typeof options.revalidateCallback==="function"){setTimeout(options.revalidateCallback,0,networkResponse.clone())}}return networkResponse});return cachedResponse??fetchedResponsePromise}default:{return handleRemoveDuplicate_(options)}}}async function handleRemoveDuplicate_(options){if(options.removeDuplicate==="never"){return handleRetryPattern_(options)}logger_.logMethod?.("handleRemoveDuplicate_");const bodyString=typeof options.body==="string"?options.body:"";const cacheKey=`${options.method} ${options.url} ${bodyString}`;duplicateRequestStorage_[cacheKey]??=handleRetryPattern_(options);try{const response=await duplicateRequestStorage_[cacheKey];if(duplicateRequestStorage_[cacheKey]!=null){if(response.ok!==true||options.removeDuplicate==="until_load"){delete duplicateRequestStorage_[cacheKey]}}return response.clone()}catch(err){delete duplicateRequestStorage_[cacheKey];throw err}}async function handleRetryPattern_(options){if(!(options.retry>1)){return handleTimeout_(options)}logger_.logMethod?.("handleRetryPattern_");options.retry--;const externalAbortSignal=options.signal;try{const response=await handleTimeout_(options);if(response.status<HttpStatusCodes.Error_Server_500_Internal_Server_Error){return response}throw new Error("fetch_server_error")}catch(err){logger_.accident("fetch","fetch_failed_retry",err);if(globalThis_.navigator?.onLine===false){logger_.accident("handleRetryPattern_","offline","Skip retry because offline");throw err}await delay.by(options.retryDelay);options.signal=externalAbortSignal;return handleRetryPattern_(options)}}function handleTimeout_(options){if(options.timeout===0){return globalThis_.fetch(options.url,options)}logger_.logMethod?.("handleTimeout_");return new Promise((resolved,reject)=>{const abortController=typeof AbortController==="function"?new AbortController:null;const externalAbortSignal=options.signal;options.signal=abortController?.signal;if(abortController!==null&&externalAbortSignal!=null){externalAbortSignal.addEventListener("abort",()=>abortController.abort(),{once:true})}const timeoutId=setTimeout(()=>{reject(new Error("fetch_timeout"));abortController?.abort("fetch_timeout")},parseDuration(options.timeout));globalThis_.fetch(options.url,options).then(response=>resolved(response)).catch(reason=>reject(reason)).finally(()=>{clearTimeout(timeoutId)})})}export{cacheSupported,fetch};
+/** 📦 @alwatr/fetch v7.0.0 */
+__dev_mode__: console.debug("📦 @alwatr/fetch v7.0.0");
+import{delay}from"@alwatr/delay";import{getGlobalThis}from"@alwatr/global-this";import{hasOwn}from"@alwatr/has-own";import{HttpStatusCodes,MimeTypes}from"@alwatr/http-primer";import{createLogger}from"@alwatr/logger";import{parseDuration}from"@alwatr/parse-duration";var FetchError=class extends Error{constructor(reason,message,response,data){super(message);this.name="FetchError";this.reason=reason;this.response=response;this.data=data}};var logger_=createLogger("@alwatr/fetch");var globalThis_=getGlobalThis();var cacheSupported=hasOwn(globalThis_,"caches");var duplicateRequestStorage_={};var defaultFetchOptions={method:"GET",headers:{},timeout:8e3,retry:3,retryDelay:1e3,removeDuplicate:"never",cacheStrategy:"network_only",cacheStorageName:"fetch_cache"};async function fetch(url,options={}){logger_.logMethodArgs?.("fetch",{url,options});const options_=_processOptions(url,options);try{const response=await handleCacheStrategy_(options_);if(!response.ok){throw new FetchError("http_error",`HTTP error! status: ${response.status} ${response.statusText}`,response)}return[response,null]}catch(err){let error;if(err instanceof FetchError){error=err;if(error.response!==void 0&&error.data===void 0){const bodyText=await error.response.text().catch(()=>"");if(bodyText.trim().length>0){try{error.data=JSON.parse(bodyText)}catch{error.data=bodyText}}}}else if(err instanceof Error){if(err.name==="AbortError"){error=new FetchError("aborted",err.message)}else{error=new FetchError("network_error",err.message)}}else{error=new FetchError("unknown_error",String(err??"unknown_error"))}logger_.error("fetch",error.reason,{error});return[null,error]}}function _processOptions(url,options){logger_.logMethodArgs?.("_processOptions",{url,options});const options_={...defaultFetchOptions,...options,url};options_.window??=null;if(options_.removeDuplicate==="auto"){options_.removeDuplicate=cacheSupported?"until_load":"always"}if(options_.url.lastIndexOf("?")===-1&&options_.queryParams!=null){const queryParams=options_.queryParams;const queryArray=Object.keys(queryParams).map(key=>`${encodeURIComponent(key)}=${encodeURIComponent(String(queryParams[key]))}`);if(queryArray.length>0){options_.url+="?"+queryArray.join("&")}}if(options_.bodyJson!==void 0){options_.body=JSON.stringify(options_.bodyJson);options_.headers["content-type"]=MimeTypes.JSON}if(options_.bearerToken!==void 0){options_.headers.authorization=`Bearer ${options_.bearerToken}`}else if(options_.alwatrAuth!==void 0){options_.headers.authorization=`Alwatr ${options_.alwatrAuth.userId}:${options_.alwatrAuth.userToken}`}logger_.logProperty?.("fetch.options",options_);return options_}async function handleCacheStrategy_(options){if(options.cacheStrategy==="network_only"){return handleRemoveDuplicate_(options)}logger_.logMethod?.("handleCacheStrategy_");if(!cacheSupported){logger_.incident?.("fetch","fetch_cache_strategy_unsupported",{cacheSupported});options.cacheStrategy="network_only";return handleRemoveDuplicate_(options)}const cacheStorage=await caches.open(options.cacheStorageName);const request=new Request(options.url,options);switch(options.cacheStrategy){case"cache_first":{const cachedResponse=await cacheStorage.match(request);if(cachedResponse!=null){return cachedResponse}const response=await handleRemoveDuplicate_(options);if(response.ok){cacheStorage.put(request,response.clone())}return response}case"cache_only":{const cachedResponse=await cacheStorage.match(request);if(cachedResponse==null){throw new FetchError("cache_not_found","Resource not found in cache")}return cachedResponse}case"network_first":{try{const networkResponse=await handleRemoveDuplicate_(options);if(networkResponse.ok){cacheStorage.put(request,networkResponse.clone())}return networkResponse}catch(err){const cachedResponse=await cacheStorage.match(request);if(cachedResponse!=null){return cachedResponse}throw err}}case"update_cache":{const networkResponse=await handleRemoveDuplicate_(options);if(networkResponse.ok){cacheStorage.put(request,networkResponse.clone())}return networkResponse}case"stale_while_revalidate":{const cachedResponse=await cacheStorage.match(request);const fetchedResponsePromise=handleRemoveDuplicate_(options).then(networkResponse=>{if(networkResponse.ok){cacheStorage.put(request,networkResponse.clone());if(typeof options.revalidateCallback==="function"){setTimeout(options.revalidateCallback,0,networkResponse.clone())}}return networkResponse});return cachedResponse??fetchedResponsePromise}default:{return handleRemoveDuplicate_(options)}}}async function handleRemoveDuplicate_(options){if(options.removeDuplicate==="never"){return handleRetryPattern_(options)}logger_.logMethod?.("handleRemoveDuplicate_");const bodyString=typeof options.body==="string"?options.body:"";const cacheKey=`${options.method} ${options.url} ${bodyString}`;duplicateRequestStorage_[cacheKey]??=handleRetryPattern_(options);try{const response=await duplicateRequestStorage_[cacheKey];if(duplicateRequestStorage_[cacheKey]!=null){if(response.ok!==true||options.removeDuplicate==="until_load"){delete duplicateRequestStorage_[cacheKey]}}return response.clone()}catch(err){delete duplicateRequestStorage_[cacheKey];throw err}}async function handleRetryPattern_(options){if(!(options.retry>1)){return handleTimeout_(options)}logger_.logMethod?.("handleRetryPattern_");options.retry--;const externalAbortSignal=options.signal;try{const response=await handleTimeout_(options);if(!response.ok&&response.status>=HttpStatusCodes.Error_Server_500_Internal_Server_Error){throw new FetchError("http_error",`HTTP error! status: ${response.status} ${response.statusText}`,response)}return response}catch(err){logger_.accident("fetch","fetch_failed_retry",err);if(globalThis_.navigator?.onLine===false){logger_.accident("handleRetryPattern_","offline","Skip retry because offline");throw err}await delay.by(options.retryDelay);options.signal=externalAbortSignal;return handleRetryPattern_(options)}}function handleTimeout_(options){if(options.timeout===0){return globalThis_.fetch(options.url,options)}logger_.logMethod?.("handleTimeout_");return new Promise((resolved,reject)=>{const abortController=typeof AbortController==="function"?new AbortController:null;const externalAbortSignal=options.signal;options.signal=abortController?.signal;if(abortController!==null&&externalAbortSignal!=null){externalAbortSignal.addEventListener("abort",()=>abortController.abort(),{once:true})}const timeoutId=setTimeout(()=>{reject(new FetchError("timeout","fetch_timeout"));abortController?.abort("fetch_timeout")},parseDuration(options.timeout));globalThis_.fetch(options.url,options).then(response=>resolved(response)).catch(reason=>reject(reason)).finally(()=>{clearTimeout(timeoutId)})})}export{FetchError,cacheSupported,fetch};
 //# sourceMappingURL=main.mjs.map

package/dist/main.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../src/main.ts"],
-  "sourcesContent": ["/**\n * @module @alwatr/fetch\n *\n * An enhanced, lightweight, and dependency-free wrapper for the native `fetch` API.\n * It provides modern features like caching strategies, request retries, timeouts, and\n * duplicate request handling.\n */\n\nimport {delay} from '@alwatr/delay';\nimport {getGlobalThis} from '@alwatr/global-this';\nimport {HttpStatusCodes, MimeTypes} from '@alwatr/http-primer';\nimport {createLogger} from '@alwatr/logger';\nimport {parseDuration} from '@alwatr/parse-duration';\n\nimport type {AlwatrFetchOptions_, FetchOptions} from './type.js';\n\nexport {cacheSupported};\nexport type * from './type.js';\n\nconst logger_ = createLogger('@alwatr/fetch');\nconst globalThis_ = getGlobalThis();\n\n/**\n * A boolean flag indicating whether the browser's Cache API is supported.\n */\nconst cacheSupported = Object.hasOwn(globalThis_, 'caches');\n\n/**\n * A simple in-memory storage for tracking and managing duplicate in-flight requests.\n * The key is a unique identifier for the request (e.g., method + URL + body),\n * and the value is the promise of the ongoing fetch operation.\n */\nconst duplicateRequestStorage_: Record<string, Promise<Response>> = {};\n\n/**\n * Default options for all fetch requests. These can be overridden by passing\n * a custom `options` object to the `fetch` function.\n */\nconst defaultFetchOptions: AlwatrFetchOptions_ = {\n  method: 'GET',\n  headers: {},\n  timeout: 8_000,\n  retry: 3,\n  retryDelay: 1_000,\n  removeDuplicate: 'never',\n  cacheStrategy: 'network_only',\n  cacheStorageName: 'fetch_cache',\n};\n\n/**\n * Internal-only fetch options type, which includes the URL and ensures all\n * optional properties from AlwatrFetchOptions_ are present.\n */\ntype FetchOptions__ = AlwatrFetchOptions_ & Omit<RequestInit, 'headers'> & {url: string};\n\n/**\n * An enhanced wrapper for the native `fetch` function.\n *\n * This function extends the standard `fetch` with additional features such as:\n * - **Timeout**: Aborts the request if it takes too long.\n * - **Retry Pattern**: Automatically retries the request on failure (e.g., server errors or network issues).\n * - **Duplicate Request Handling**: Prevents sending multiple identical requests in parallel.\n * - **Cache Strategies**: Provides various caching mechanisms using the browser's Cache API.\n * - **Simplified API**: Offers convenient options for adding query parameters, JSON bodies, and auth tokens.\n *\n * @see {@link FetchOptions} for a detailed list of available options.\n *\n * @param {string} url - The URL to fetch.\n * @param {FetchOptions} options - Optional configuration for the fetch request.\n * @returns {Promise<Response>} A promise that resolves to the `Response` object for the request.\n *\n * @example\n * ```typescript\n * async function fetchProducts() {\n *   try {\n *     const response = await fetch(\"/api/products\", {\n *       queryParams: { limit: 10, category: \"electronics\" },\n *       timeout: 5_000, // 5 seconds\n *       retry: 3,\n *       cacheStrategy: \"stale_while_revalidate\",\n *     });\n *\n *     if (!response.ok) {\n *       throw new Error(`HTTP error! status: ${response.status}`);\n *     }\n *\n *     const data = await response.json();\n *     console.log(\"Products:\", data);\n *   } catch (error) {\n *     console.error(\"Failed to fetch products:\", error);\n *   }\n * }\n *\n * fetchProducts();\n * ```\n */\nexport function fetch(url: string, options: FetchOptions): Promise<Response> {\n  logger_.logMethodArgs?.('fetch', {url, options});\n\n  const options_: FetchOptions__ = {\n    ...defaultFetchOptions,\n    ...options,\n    url,\n  };\n\n  options_.window ??= null;\n\n  if (options_.removeDuplicate === 'auto') {\n    options_.removeDuplicate = cacheSupported ? 'until_load' : 'always';\n  }\n\n  // Append query parameters to the URL if they are provided and the URL doesn't already have them.\n  if (options_.url.lastIndexOf('?') === -1 && options_.queryParams != null) {\n    const queryParams = options_.queryParams;\n    // prettier-ignore\n    const queryArray = Object\n      .keys(queryParams)\n      .map(key => `${encodeURIComponent(key)}=${encodeURIComponent(String(queryParams[key]))}`);\n\n    if (queryArray.length > 0) {\n      options_.url += '?' + queryArray.join('&');\n    }\n  }\n\n  // If `bodyJson` is provided, stringify it and set the appropriate 'Content-Type' header.\n  if (options_.bodyJson !== undefined) {\n    options_.body = JSON.stringify(options_.bodyJson);\n    options_.headers['content-type'] = MimeTypes.JSON;\n  }\n\n  // Set the 'Authorization' header for bearer tokens or Alwatr's authentication scheme.\n  if (options_.bearerToken !== undefined) {\n    options_.headers.authorization = `Bearer ${options_.bearerToken}`;\n  }\n  else if (options_.alwatrAuth !== undefined) {\n    options_.headers.authorization = `Alwatr ${options_.alwatrAuth.userId}:${options_.alwatrAuth.userToken}`;\n  }\n\n  logger_.logProperty?.('fetch.options', options_);\n\n  // Start the fetch lifecycle, beginning with the cache strategy.\n  return handleCacheStrategy_(options_);\n}\n\n/**\n * Manages caching strategies for the fetch request.\n * If the strategy is `network_only`, it bypasses caching and proceeds to the next step.\n * Otherwise, it interacts with the browser's Cache API based on the selected strategy.\n *\n * @param {FetchOptions__} options - The fully configured fetch options.\n * @returns {Promise<Response>} A promise resolving to a `Response` object, either from the cache or the network.\n * @private\n */\nasync function handleCacheStrategy_(options: FetchOptions__): Promise<Response> {\n  if (options.cacheStrategy === 'network_only') {\n    return handleRemoveDuplicate_(options);\n  }\n  // else\n\n  logger_.logMethod?.('handleCacheStrategy_');\n\n  if (!cacheSupported) {\n    logger_.incident?.('fetch', 'fetch_cache_strategy_unsupported', {\n      cacheSupported,\n    });\n    // Fallback to network_only if Cache API is not available.\n    options.cacheStrategy = 'network_only';\n    return handleRemoveDuplicate_(options);\n  }\n  // else\n\n  const cacheStorage = await caches.open(options.cacheStorageName);\n\n  const request = new Request(options.url, options);\n\n  switch (options.cacheStrategy) {\n    case 'cache_first': {\n      const cachedResponse = await cacheStorage.match(request);\n      if (cachedResponse != null) {\n        return cachedResponse;\n      }\n      // else\n\n      const response = await handleRemoveDuplicate_(options);\n      if (response.ok) {\n        cacheStorage.put(request, response.clone());\n      }\n      return response;\n    }\n\n    case 'cache_only': {\n      const cachedResponse = await cacheStorage.match(request);\n      if (cachedResponse == null) {\n        logger_.accident('_handleCacheStrategy', 'fetch_cache_not_found', {url: request.url});\n        throw new Error('fetch_cache_not_found');\n      }\n      // else\n\n      return cachedResponse;\n    }\n\n    case 'network_first': {\n      try {\n        const networkResponse = await handleRemoveDuplicate_(options);\n        if (networkResponse.ok) {\n          cacheStorage.put(request, networkResponse.clone());\n        }\n        return networkResponse;\n      }\n      catch (err) {\n        const cachedResponse = await cacheStorage.match(request);\n        if (cachedResponse != null) {\n          return cachedResponse;\n        }\n        // else\n\n        throw err;\n      }\n    }\n\n    case 'update_cache': {\n      const networkResponse = await handleRemoveDuplicate_(options);\n      if (networkResponse.ok) {\n        cacheStorage.put(request, networkResponse.clone());\n      }\n      return networkResponse;\n    }\n\n    case 'stale_while_revalidate': {\n      const cachedResponse = await cacheStorage.match(request);\n      const fetchedResponsePromise = handleRemoveDuplicate_(options).then((networkResponse) => {\n        if (networkResponse.ok) {\n          cacheStorage.put(request, networkResponse.clone());\n          if (typeof options.revalidateCallback === 'function') {\n            setTimeout(options.revalidateCallback, 0, networkResponse.clone());\n          }\n        }\n        return networkResponse;\n      });\n\n      return cachedResponse ?? fetchedResponsePromise;\n    }\n\n    default: {\n      return handleRemoveDuplicate_(options);\n    }\n  }\n}\n\n/**\n * Handles duplicate request elimination.\n *\n * It creates a unique key based on the request method, URL, and body. If a request with the\n * same key is already in flight, it returns the promise of the existing request instead of\n * creating a new one. This prevents redundant network calls for identical parallel requests.\n *\n * @param {FetchOptions__} options - The fully configured fetch options.\n * @returns {Promise<Response>} A promise resolving to a cloned `Response` object.\n * @private\n */\nasync function handleRemoveDuplicate_(options: FetchOptions__): Promise<Response> {\n  if (options.removeDuplicate === 'never') {\n    return handleRetryPattern_(options);\n  }\n  // else\n\n  logger_.logMethod?.('handleRemoveDuplicate_');\n\n  // Create a unique key for the request. Including the body is crucial to differentiate\n  // between requests to the same URL but with different payloads (e.g., POST requests).\n  const bodyString = typeof options.body === 'string' ? options.body : '';\n  const cacheKey = `${options.method} ${options.url} ${bodyString}`;\n\n  // If a request with the same key doesn't exist, create it and store its promise.\n  duplicateRequestStorage_[cacheKey] ??= handleRetryPattern_(options);\n\n  try {\n    // Await the shared promise to get the response.\n    const response = await duplicateRequestStorage_[cacheKey];\n\n    // Clean up the stored promise based on the removal strategy.\n    if (duplicateRequestStorage_[cacheKey] != null) {\n      if (response.ok !== true || options.removeDuplicate === 'until_load') {\n        // Remove after completion for 'until_load' or if the request failed.\n        delete duplicateRequestStorage_[cacheKey];\n      }\n    }\n\n    // Return a clone of the response, so each caller can consume the body independently.\n    return response.clone();\n  }\n  catch (err) {\n    // If the request fails, remove it from storage to allow for retries.\n    delete duplicateRequestStorage_[cacheKey];\n    throw err;\n  }\n}\n\n/**\n * Implements a retry mechanism for the fetch request.\n * If the request fails due to a server error (status >= 500) or a timeout,\n * it will be retried up to the specified number of times.\n *\n * @param {FetchOptions__} options - The fully configured fetch options.\n * @returns {Promise<Response>} A promise that resolves to the final `Response` after all retries.\n * @private\n */\nasync function handleRetryPattern_(options: FetchOptions__): Promise<Response> {\n  if (!(options.retry > 1)) {\n    return handleTimeout_(options);\n  }\n  // else\n\n  logger_.logMethod?.('handleRetryPattern_');\n  options.retry--;\n\n  const externalAbortSignal = options.signal;\n\n  try {\n    const response = await handleTimeout_(options);\n\n    // Only retry on server errors (5xx). Client errors (4xx) are not retried.\n    if (response.status < HttpStatusCodes.Error_Server_500_Internal_Server_Error) {\n      return response;\n    }\n    // else\n\n    throw new Error('fetch_server_error');\n  }\n  catch (err) {\n    logger_.accident('fetch', 'fetch_failed_retry', err);\n\n    // Do not retry if the browser is offline.\n    if (globalThis_.navigator?.onLine === false) {\n      logger_.accident('handleRetryPattern_', 'offline', 'Skip retry because offline');\n      throw err;\n    }\n\n    await delay.by(options.retryDelay);\n\n    // Restore the original signal for the next attempt.\n    options.signal = externalAbortSignal;\n    return handleRetryPattern_(options);\n  }\n}\n\n/**\n * Wraps the native fetch call with a timeout mechanism.\n *\n * It uses an `AbortController` to abort the request if it does not complete\n * within the specified `timeout` duration. It also respects external abort signals.\n *\n * @param {FetchOptions__} options - The fully configured fetch options.\n * @returns {Promise<Response>} A promise that resolves with the `Response` or rejects on timeout.\n * @private\n */\nfunction handleTimeout_(options: FetchOptions__): Promise<Response> {\n  if (options.timeout === 0) {\n    // If timeout is disabled, call fetch directly.\n    return globalThis_.fetch(options.url, options);\n  }\n\n  logger_.logMethod?.('handleTimeout_');\n\n  return new Promise((resolved, reject) => {\n    const abortController = typeof AbortController === 'function' ? new AbortController() : null;\n    const externalAbortSignal = options.signal;\n    options.signal = abortController?.signal;\n\n    // If an external AbortSignal is provided, listen to it and propagate the abort.\n    if (abortController !== null && externalAbortSignal != null) {\n      externalAbortSignal.addEventListener('abort', () => abortController.abort(), {once: true});\n    }\n\n    const timeoutId = setTimeout(() => {\n      reject(new Error('fetch_timeout'));\n      abortController?.abort('fetch_timeout');\n    }, parseDuration(options.timeout!));\n\n    globalThis_\n      .fetch(options.url, options)\n      .then((response) => resolved(response))\n      .catch((reason) => reject(reason))\n      .finally(() => {\n        // Clean up the timeout to prevent it from firing after the request has completed.\n        clearTimeout(timeoutId);\n      });\n  });\n}\n"],
-  "mappings": "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",
+  "sources": ["../src/main.ts", "../src/error.ts"],
+  "sourcesContent": ["/**\n * @module @alwatr/fetch\n *\n * An enhanced, lightweight, and dependency-free wrapper for the native `fetch`\n * API. It provides modern features like caching strategies, request retries,\n * timeouts, and duplicate request handling.\n */\n\nimport {delay} from '@alwatr/delay';\nimport {getGlobalThis} from '@alwatr/global-this';\nimport {hasOwn} from '@alwatr/has-own';\nimport {HttpStatusCodes, MimeTypes} from '@alwatr/http-primer';\nimport {createLogger} from '@alwatr/logger';\nimport {parseDuration} from '@alwatr/parse-duration';\n\nimport {FetchError} from './error.js';\n\nimport type {AlwatrFetchOptions_, FetchOptions, FetchResponse} from './type.js';\n\nexport {cacheSupported};\nexport type * from './type.js';\nexport * from './error.js';\n\nconst logger_ = createLogger('@alwatr/fetch');\nconst globalThis_ = getGlobalThis();\n\n/**\n * A boolean flag indicating whether the browser's Cache API is supported.\n */\nconst cacheSupported = /* #__PURE__ */ hasOwn(globalThis_, 'caches');\n\n/**\n * A simple in-memory storage for tracking and managing duplicate in-flight requests.\n * The key is a unique identifier for the request (e.g., method + URL + body),\n * and the value is the promise of the ongoing fetch operation.\n */\nconst duplicateRequestStorage_: Record<string, Promise<Response>> = {};\n\n/**\n * Default options for all fetch requests. These can be overridden by passing\n * a custom `options` object to the `fetch` function.\n */\nconst defaultFetchOptions: AlwatrFetchOptions_ = {\n  method: 'GET',\n  headers: {},\n  timeout: 8_000,\n  retry: 3,\n  retryDelay: 1_000,\n  removeDuplicate: 'never',\n  cacheStrategy: 'network_only',\n  cacheStorageName: 'fetch_cache',\n};\n\n/**\n * Internal-only fetch options type, which includes the URL and ensures all\n * optional properties from AlwatrFetchOptions_ are present.\n */\ntype FetchOptions__ = AlwatrFetchOptions_ & Omit<RequestInit, 'headers'> & {url: string};\n\n/**\n * An enhanced wrapper for the native `fetch` function.\n *\n * This function extends the standard `fetch` with additional features such as:\n * - **Timeout**: Aborts the request if it takes too long.\n * - **Retry Pattern**: Automatically retries the request on failure (e.g., server errors or network issues).\n * - **Duplicate Request Handling**: Prevents sending multiple identical requests in parallel.\n * - **Cache Strategies**: Provides various caching mechanisms using the browser's Cache API.\n * - **Simplified API**: Offers convenient options for adding query parameters, JSON bodies, and auth tokens.\n *\n * @see {@link FetchOptions} for a detailed list of available options.\n *\n * @param {string} url - The URL to fetch.\n * @param {FetchOptions} options - Optional configuration for the fetch request.\n * @returns {Promise<FetchResponse>} A promise that resolves to a tuple. On\n * success, it returns `[response, null]`. On failure, it returns `[null,\n * FetchError]`.\n *\n * @example\n * ```typescript\n * import {fetch} from '@alwatr/fetch';\n *\n * async function fetchProducts() {\n *   const [response, error] = await fetch('/api/products', {\n *     queryParams: { limit: 10 },\n *     timeout: 5_000,\n *   });\n *\n *   if (error) {\n *     console.error('Request failed:', error.reason);\n *     return;\n *   }\n *\n *   // At this point, response is guaranteed to be valid and ok.\n *   const data = await response.json();\n *   console.log('Products:', data);\n * }\n *\n * fetchProducts();\n * ```\n */\nexport async function fetch(url: string, options: FetchOptions = {}): Promise<FetchResponse> {\n  logger_.logMethodArgs?.('fetch', {url, options});\n\n  const options_ = _processOptions(url, options);\n\n  try {\n    // Start the fetch lifecycle, beginning with the cache strategy.\n    const response = await handleCacheStrategy_(options_);\n\n    if (!response.ok) {\n      throw new FetchError('http_error', `HTTP error! status: ${response.status} ${response.statusText}`, response);\n    }\n\n    return [response, null];\n  }\n  catch (err) {\n    let error: FetchError;\n\n    if (err instanceof FetchError) {\n      error = err;\n\n      if (error.response !== undefined && error.data === undefined) {\n        const bodyText = await error.response.text().catch(() => '');\n\n        if (bodyText.trim().length > 0) {\n          try {\n            // Try to parse as JSON\n            error.data = JSON.parse(bodyText);\n          }\n          catch {\n            error.data = bodyText;\n          }\n        }\n      }\n    }\n    else if (err instanceof Error) {\n      if (err.name === 'AbortError') {\n        error = new FetchError('aborted', err.message);\n      }\n      else {\n        error = new FetchError('network_error', err.message);\n      }\n    }\n    else {\n      error = new FetchError('unknown_error', String(err ?? 'unknown_error'));\n    }\n\n    logger_.error('fetch', error.reason, {error});\n    return [null, error];\n  }\n}\n\n/**\n * Processes and sanitizes the fetch options.\n *\n * @param {string} url - The URL to fetch.\n * @param {FetchOptions} options - The user-provided options.\n * @returns {FetchOptions__} The processed and complete fetch options.\n * @private\n */\nfunction _processOptions(url: string, options: FetchOptions): FetchOptions__ {\n  logger_.logMethodArgs?.('_processOptions', {url, options});\n\n  const options_: FetchOptions__ = {\n    ...defaultFetchOptions,\n    ...options,\n    url,\n  };\n\n  options_.window ??= null;\n\n  if (options_.removeDuplicate === 'auto') {\n    options_.removeDuplicate = cacheSupported ? 'until_load' : 'always';\n  }\n\n  // Append query parameters to the URL if they are provided and the URL doesn't already have them.\n  if (options_.url.lastIndexOf('?') === -1 && options_.queryParams != null) {\n    const queryParams = options_.queryParams;\n    // prettier-ignore\n    const queryArray = Object\n      .keys(queryParams)\n      .map(key => `${encodeURIComponent(key)}=${encodeURIComponent(String(queryParams[key]))}`);\n\n    if (queryArray.length > 0) {\n      options_.url += '?' + queryArray.join('&');\n    }\n  }\n\n  // If `bodyJson` is provided, stringify it and set the appropriate 'Content-Type' header.\n  if (options_.bodyJson !== undefined) {\n    options_.body = JSON.stringify(options_.bodyJson);\n    options_.headers['content-type'] = MimeTypes.JSON;\n  }\n\n  // Set the 'Authorization' header for bearer tokens or Alwatr's authentication scheme.\n  if (options_.bearerToken !== undefined) {\n    options_.headers.authorization = `Bearer ${options_.bearerToken}`;\n  }\n  else if (options_.alwatrAuth !== undefined) {\n    options_.headers.authorization = `Alwatr ${options_.alwatrAuth.userId}:${options_.alwatrAuth.userToken}`;\n  }\n\n  logger_.logProperty?.('fetch.options', options_);\n\n  return options_;\n}\n\n/**\n * Manages caching strategies for the fetch request.\n * If the strategy is `network_only`, it bypasses caching and proceeds to the next step.\n * Otherwise, it interacts with the browser's Cache API based on the selected strategy.\n *\n * @param {FetchOptions__} options - The fully configured fetch options.\n * @returns {Promise<Response>} A promise resolving to a `Response` object, either from the cache or the network.\n * @private\n */\nasync function handleCacheStrategy_(options: FetchOptions__): Promise<Response> {\n  if (options.cacheStrategy === 'network_only') {\n    return handleRemoveDuplicate_(options);\n  }\n  // else\n\n  logger_.logMethod?.('handleCacheStrategy_');\n\n  if (!cacheSupported) {\n    logger_.incident?.('fetch', 'fetch_cache_strategy_unsupported', {\n      cacheSupported,\n    });\n    // Fallback to network_only if Cache API is not available.\n    options.cacheStrategy = 'network_only';\n    return handleRemoveDuplicate_(options);\n  }\n  // else\n\n  const cacheStorage = await caches.open(options.cacheStorageName);\n\n  const request = new Request(options.url, options);\n\n  switch (options.cacheStrategy) {\n    case 'cache_first': {\n      const cachedResponse = await cacheStorage.match(request);\n      if (cachedResponse != null) {\n        return cachedResponse;\n      }\n      // else\n\n      const response = await handleRemoveDuplicate_(options);\n      if (response.ok) {\n        cacheStorage.put(request, response.clone());\n      }\n      return response;\n    }\n\n    case 'cache_only': {\n      const cachedResponse = await cacheStorage.match(request);\n      if (cachedResponse == null) {\n        throw new FetchError('cache_not_found', 'Resource not found in cache');\n      }\n      // else\n\n      return cachedResponse;\n    }\n\n    case 'network_first': {\n      try {\n        const networkResponse = await handleRemoveDuplicate_(options);\n        if (networkResponse.ok) {\n          cacheStorage.put(request, networkResponse.clone());\n        }\n        return networkResponse;\n      }\n      catch (err) {\n        const cachedResponse = await cacheStorage.match(request);\n        if (cachedResponse != null) {\n          return cachedResponse;\n        }\n        // else\n\n        throw err;\n      }\n    }\n\n    case 'update_cache': {\n      const networkResponse = await handleRemoveDuplicate_(options);\n      if (networkResponse.ok) {\n        cacheStorage.put(request, networkResponse.clone());\n      }\n      return networkResponse;\n    }\n\n    case 'stale_while_revalidate': {\n      const cachedResponse = await cacheStorage.match(request);\n      const fetchedResponsePromise = handleRemoveDuplicate_(options).then((networkResponse) => {\n        if (networkResponse.ok) {\n          cacheStorage.put(request, networkResponse.clone());\n          if (typeof options.revalidateCallback === 'function') {\n            setTimeout(options.revalidateCallback, 0, networkResponse.clone());\n          }\n        }\n        return networkResponse;\n      });\n\n      return cachedResponse ?? fetchedResponsePromise;\n    }\n\n    default: {\n      return handleRemoveDuplicate_(options);\n    }\n  }\n}\n\n/**\n * Handles duplicate request elimination.\n *\n * It creates a unique key based on the request method, URL, and body. If a request with the\n * same key is already in flight, it returns the promise of the existing request instead of\n * creating a new one. This prevents redundant network calls for identical parallel requests.\n *\n * @param {FetchOptions__} options - The fully configured fetch options.\n * @returns {Promise<Response>} A promise resolving to a cloned `Response` object.\n * @private\n */\nasync function handleRemoveDuplicate_(options: FetchOptions__): Promise<Response> {\n  if (options.removeDuplicate === 'never') {\n    return handleRetryPattern_(options);\n  }\n  // else\n\n  logger_.logMethod?.('handleRemoveDuplicate_');\n\n  // Create a unique key for the request. Including the body is crucial to differentiate\n  // between requests to the same URL but with different payloads (e.g., POST requests).\n  const bodyString = typeof options.body === 'string' ? options.body : '';\n  const cacheKey = `${options.method} ${options.url} ${bodyString}`;\n\n  // If a request with the same key doesn't exist, create it and store its promise.\n  duplicateRequestStorage_[cacheKey] ??= handleRetryPattern_(options);\n\n  try {\n    // Await the shared promise to get the response.\n    const response = await duplicateRequestStorage_[cacheKey];\n\n    // Clean up the stored promise based on the removal strategy.\n    if (duplicateRequestStorage_[cacheKey] != null) {\n      if (response.ok !== true || options.removeDuplicate === 'until_load') {\n        // Remove after completion for 'until_load' or if the request failed.\n        delete duplicateRequestStorage_[cacheKey];\n      }\n    }\n\n    // Return a clone of the response, so each caller can consume the body independently.\n    return response.clone();\n  }\n  catch (err) {\n    // If the request fails, remove it from storage to allow for retries.\n    delete duplicateRequestStorage_[cacheKey];\n    throw err;\n  }\n}\n\n/**\n * Implements a retry mechanism for the fetch request.\n * If the request fails due to a server error (status >= 500) or a timeout,\n * it will be retried up to the specified number of times.\n *\n * @param {FetchOptions__} options - The fully configured fetch options.\n * @returns {Promise<Response>} A promise that resolves to the final `Response` after all retries.\n * @private\n */\nasync function handleRetryPattern_(options: FetchOptions__): Promise<Response> {\n  if (!(options.retry > 1)) {\n    return handleTimeout_(options);\n  }\n  // else\n\n  logger_.logMethod?.('handleRetryPattern_');\n  options.retry--;\n\n  const externalAbortSignal = options.signal;\n\n  try {\n    const response = await handleTimeout_(options);\n\n    if (!response.ok && response.status >= HttpStatusCodes.Error_Server_500_Internal_Server_Error) {\n      // only retry for server errors (5xx)\n      throw new FetchError('http_error', `HTTP error! status: ${response.status} ${response.statusText}`, response);\n    }\n\n    return response;\n  }\n  catch (err) {\n    logger_.accident('fetch', 'fetch_failed_retry', err);\n\n    // Do not retry if the browser is offline.\n    if (globalThis_.navigator?.onLine === false) {\n      logger_.accident('handleRetryPattern_', 'offline', 'Skip retry because offline');\n      throw err;\n    }\n\n    await delay.by(options.retryDelay);\n\n    // Restore the original signal for the next attempt.\n    options.signal = externalAbortSignal;\n    return handleRetryPattern_(options);\n  }\n}\n\n/**\n * Wraps the native fetch call with a timeout mechanism.\n *\n * It uses an `AbortController` to abort the request if it does not complete\n * within the specified `timeout` duration. It also respects external abort signals.\n *\n * @param {FetchOptions__} options - The fully configured fetch options.\n * @returns {Promise<Response>} A promise that resolves with the `Response` or rejects on timeout.\n * @private\n */\nfunction handleTimeout_(options: FetchOptions__): Promise<Response> {\n  if (options.timeout === 0) {\n    // If timeout is disabled, call fetch directly.\n    return globalThis_.fetch(options.url, options);\n  }\n\n  logger_.logMethod?.('handleTimeout_');\n\n  return new Promise((resolved, reject) => {\n    const abortController = typeof AbortController === 'function' ? new AbortController() : null;\n    const externalAbortSignal = options.signal;\n    options.signal = abortController?.signal;\n\n    // If an external AbortSignal is provided, listen to it and propagate the abort.\n    if (abortController !== null && externalAbortSignal != null) {\n      externalAbortSignal.addEventListener('abort', () => abortController.abort(), {once: true});\n    }\n\n    const timeoutId = setTimeout(() => {\n      reject(new FetchError('timeout', 'fetch_timeout'));\n      abortController?.abort('fetch_timeout');\n    }, parseDuration(options.timeout!));\n\n    globalThis_\n      .fetch(options.url, options)\n      .then((response) => resolved(response))\n      .catch((reason) => reject(reason))\n      .finally(() => {\n        // Clean up the timeout to prevent it from firing after the request has completed.\n        clearTimeout(timeoutId);\n      });\n  });\n}\n", "import type { FetchErrorReason } from \"./type.js\";\n\n/**\n * Custom error class for fetch-related failures.\n *\n * This error is thrown when a fetch request fails, either due to a network issue\n * or an HTTP error status (i.e., `response.ok` is `false`). It enriches the\n * standard `Error` object with the `response` and the parsed `data` from the\n * response body, allowing for more detailed error handling.\n *\n * @example\n * ```typescript\n * const [response, error] = await fetch('/api/endpoint');\n * if (error) {\n *   console.error(`Request failed with status ${error.response?.status}`);\n *   console.error('Server response:', error.data);\n * }\n * ```\n */\nexport class FetchError extends Error {\n  /**\n   * The original `Response` object.\n   * This is useful for accessing headers and other response metadata.\n   * It will be `undefined` for non-HTTP errors like network failures or timeouts.\n   */\n  public response?: Response;\n\n  /**\n   * The parsed body of the error response, typically a JSON object.\n   * It will be `undefined` for non-HTTP errors.\n   */\n  public data?: JsonObject | string;\n\n  /**\n   * The specific reason for the fetch failure.\n   */\n  public reason: FetchErrorReason;\n\n  constructor(reason: FetchErrorReason, message: string, response?: Response, data?: JsonObject | string) {\n    super(message);\n    this.name = 'FetchError';\n    this.reason = reason;\n    this.response = response;\n    this.data = data;\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/type.d.ts

@@ -1,3 +1,4 @@
+import type { FetchError } from './error.js';
 import type { HttpMethod, HttpRequestHeaders } from '@alwatr/http-primer';
 import type { Duration } from '@alwatr/parse-duration';
 /**
@@ -100,4 +101,19 @@ export interface AlwatrFetchOptions_ {
  * Combined type for fetch options, including standard RequestInit properties.
  */
 export type FetchOptions = Partial<AlwatrFetchOptions_> & Omit<RequestInit, 'headers'>;
+/**
+ * Represents the tuple returned by the fetch function.
+ * On success, it's `[Response, null]`. On failure, it's `[null, FetchError]`.
+ */
+export type FetchResponse = Promise<[Response, null] | [null, FetchError]>;
+/**
+ * Defines the specific reason for a fetch failure.
+ * - `http_error`: An HTTP error status was received (e.g., 404, 500).
+ * - `timeout`: The request was aborted due to a timeout.
+ * - `cache_not_found`: The requested resource was not found in the cache_only strategy.
+ * - `network_error`: A generic network-level error occurred.
+ * - `aborted`: The request was aborted by a user-provided signal.
+ * - `unknown_error`: An unspecified error occurred.
+ */
+export type FetchErrorReason = 'http_error' | 'cache_not_found' | 'timeout' | 'network_error' | 'aborted' | 'unknown_error';
 //# sourceMappingURL=type.d.ts.map

package/dist/type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../src/type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAE,kBAAkB,EAAC,MAAM,qBAAqB,CAAC;AACxE,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,wBAAwB,CAAC;AAErD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,aAAa,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAEnE;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,eAAe,GAAG,YAAY,GAAG,aAAa,GAAG,cAAc,GAAG,wBAAwB,CAAC;AAExI;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,GAAG,YAAY,GAAG,MAAM,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,MAAM,EAAE,UAAU,CAAC;IAEnB;;OAEG;IACH,OAAO,EAAE,kBAAkB,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAEpD;;;;OAIG;IACH,OAAO,EAAE,QAAQ,CAAC;IAElB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,UAAU,EAAE,QAAQ,CAAC;IAErB;;;;OAIG;IACH,eAAe,EAAE,cAAc,CAAC;IAEhC;;;;OAIG;IACH,aAAa,EAAE,aAAa,CAAC;IAE7B;;OAEG;IACH,kBAAkB,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElE;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;OAEG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAE1B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,UAAU,CAAC,EAAE;QACX,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC"}
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../src/type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAC,UAAU,EAAE,kBAAkB,EAAC,MAAM,qBAAqB,CAAC;AACxE,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,wBAAwB,CAAC;AAGrD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,aAAa,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAEnE;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,eAAe,GAAG,YAAY,GAAG,aAAa,GAAG,cAAc,GAAG,wBAAwB,CAAC;AAExI;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,GAAG,YAAY,GAAG,MAAM,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,MAAM,EAAE,UAAU,CAAC;IAEnB;;OAEG;IACH,OAAO,EAAE,kBAAkB,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAEpD;;;;OAIG;IACH,OAAO,EAAE,QAAQ,CAAC;IAElB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,UAAU,EAAE,QAAQ,CAAC;IAErB;;;;OAIG;IACH,eAAe,EAAE,cAAc,CAAC;IAEhC;;;;OAIG;IACH,aAAa,EAAE,aAAa,CAAC;IAE7B;;OAEG;IACH,kBAAkB,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElE;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;OAEG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAE1B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,UAAU,CAAC,EAAE;QACX,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;AAEvF;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;AAE3E;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,iBAAiB,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,GAAG,eAAe,CAAC"}

package/package.json

@@ -1,21 +1,23 @@
 {
   "name": "@alwatr/fetch",
   "description": "`@alwatr/fetch` is an enhanced, lightweight, and dependency-free wrapper for the native `fetch` API. It provides modern features like caching strategies, request retries, timeouts, and intelligent duplicate request handling, all in a compact package.",
-  "version": "6.0.16",
+  "version": "7.0.0",
   "author": "S. Ali Mihandoost <ali.mihandoost@gmail.com>",
   "bugs": "https://github.com/Alwatr/nanolib/issues",
   "dependencies": {
-    "@alwatr/delay": "6.0.12",
-    "@alwatr/global-this": "5.6.1",
-    "@alwatr/http-primer": "6.0.12",
-    "@alwatr/logger": "6.0.9",
-    "@alwatr/parse-duration": "5.5.21"
+    "@alwatr/delay": "6.0.13",
+    "@alwatr/global-this": "5.6.2",
+    "@alwatr/has-own": "5.6.0",
+    "@alwatr/http-primer": "6.0.13",
+    "@alwatr/logger": "6.0.10",
+    "@alwatr/parse-duration": "5.5.22"
   },
   "devDependencies": {
-    "@alwatr/nano-build": "6.3.5",
+    "@alwatr/nano-build": "6.3.6",
     "@alwatr/prettier-config": "5.0.5",
     "@alwatr/tsconfig-base": "6.0.3",
     "@alwatr/type-helper": "6.1.5",
+    "@jest/globals": "^30.2.0",
     "jest": "^30.2.0",
     "typescript": "^5.9.3"
   },
@@ -86,5 +88,5 @@
   "sideEffects": false,
   "type": "module",
   "types": "./dist/main.d.ts",
-  "gitHead": "b141732f4dab13542e3cc99926a250fd5c74bad3"
+  "gitHead": "211a46c74acca97bf4b570b20c6dffbdf8bcccfe"
 }