@alwatr/fetch 10.0.3 → 10.1.0

package/src/cache.ts

@@ -0,0 +1,146 @@
+import {FetchError} from './error.js';
+import {handleRemoveDuplicate_} from './dedupe.js';
+import {logger_} from './options.js';
+import {delay} from '@alwatr/delay';
+
+import type {InternalFetchOptions_} from './type.js';
+
+/**
+ * Executes the caching lifecycle according to `cacheStrategy`.
+ *
+ * Interacts safely with Cache API:
+ * - Falls back to network when Cache API is unavailable or throws.
+ * - Guards against caching non-GET requests.
+ * - Clones responses before storing to keep response bodies consumable.
+ *
+ * @param options - Processed internal fetch options.
+ * @returns A promise resolving to a cached or freshly fetched `Response`.
+ * @internal
+ */
+export async function handleCacheStrategy_(options: InternalFetchOptions_): Promise<Response> {
+  if (options.cacheStrategy === 'network_only') {
+    return handleRemoveDuplicate_(options);
+  }
+
+  DEV_MODE && logger_.logMethod?.('handleCacheStrategy_');
+
+  let cacheStorage: Cache;
+  try {
+    cacheStorage = await caches.open(options.cacheStorageName);
+  } catch (err) {
+    DEV_MODE && logger_.accident('handleCacheStrategy_', 'cache_open_failed', {err});
+    options.cacheStrategy = 'network_only';
+    return handleRemoveDuplicate_(options);
+  }
+
+  const request = new Request(options.url, options);
+
+  switch (options.cacheStrategy) {
+    case 'cache_first': {
+      try {
+        const cachedResponse = await cacheStorage.match(request);
+        if (cachedResponse != null) {
+          return cachedResponse;
+        }
+      } catch (err) {
+        DEV_MODE && logger_.accident('handleCacheStrategy_', 'cache_match_failed', {err});
+      }
+
+      const response = await handleRemoveDuplicate_(options);
+      if (response.ok) {
+        try {
+          await cacheStorage.put(request, response.clone());
+        } catch {
+          // ignore cache put failures
+        }
+      }
+      return response;
+    }
+
+    case 'cache_only': {
+      let cachedResponse: Response | undefined;
+      try {
+        cachedResponse = await cacheStorage.match(request);
+      } catch (err) {
+        DEV_MODE && logger_.accident('handleCacheStrategy_', 'cache_only_match_failed', {err});
+      }
+
+      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) {
+          try {
+            await cacheStorage.put(request, networkResponse.clone());
+          } catch {
+            // ignore cache put failures
+          }
+        }
+        return networkResponse;
+      } catch (err) {
+        try {
+          const cachedResponse = await cacheStorage.match(request);
+          if (cachedResponse != null) {
+            return cachedResponse;
+          }
+        } catch {
+          // ignore cache match error and throw original error
+        }
+        throw err;
+      }
+    }
+
+    case 'update_cache': {
+      const networkResponse = await handleRemoveDuplicate_(options);
+      if (networkResponse.ok) {
+        try {
+          await cacheStorage.put(request, networkResponse.clone());
+        } catch {
+          // ignore cache put failures
+        }
+      }
+      return networkResponse;
+    }
+
+    case 'stale_while_revalidate': {
+      let cachedResponse: Response | undefined;
+      try {
+        cachedResponse = await cacheStorage.match(request);
+      } catch {
+        // ignore cache match error
+      }
+
+      const fetchedResponsePromise = handleRemoveDuplicate_(options).then(async (networkResponse) => {
+        if (networkResponse.ok) {
+          try {
+            await cacheStorage.put(request, networkResponse.clone());
+          } catch {
+            // ignore cache put failures
+          }
+          if (typeof options.revalidateCallback === 'function') {
+            const callback = options.revalidateCallback;
+            const revalidatePayload = networkResponse.clone();
+            await delay.nextMacrotask();
+            try {
+              await callback(revalidatePayload);
+            } catch (err) {
+              DEV_MODE && logger_.accident('handleCacheStrategy_', 'revalidate_callback_failed', {err});
+            }
+          }
+        }
+        return networkResponse;
+      });
+
+      return cachedResponse ?? fetchedResponsePromise;
+    }
+
+    default: {
+      return handleRemoveDuplicate_(options);
+    }
+  }
+}

package/src/dedupe.ts

@@ -0,0 +1,64 @@
+import {logger_} from './options.js';
+import {handleRetryPattern_} from './retry.js';
+
+import type {InternalFetchOptions_} from './type.js';
+
+/**
+ * Storage for tracking in-flight duplicate requests.
+ */
+const duplicateRequestStorage_: Map<string, Promise<Response>> = new Map();
+
+/**
+ * Computes a secure cache key for request deduplication.
+ * Includes method, full URL, authorization header, and request body.
+ *
+ * @param options - Processed internal fetch options.
+ * @returns Unique string identifier for the request intent.
+ */
+export function computeDedupeKey_(options: InternalFetchOptions_): string {
+  const bodyString = typeof options.body === 'string' ? options.body : '';
+  const auth = options.headers['authorization'] ?? '';
+  return `${options.method} ${options.url} [auth:${auth}] [body:${bodyString}]`;
+}
+
+/**
+ * Handles duplicate parallel request coalescing.
+ *
+ * If an identical request is already in-flight, returns a cloned response of the existing
+ * promise to avoid redundant network round-trips.
+ *
+ * @param options - Processed internal fetch options.
+ * @returns A promise resolving to an independent cloned `Response`.
+ * @internal
+ */
+export async function handleRemoveDuplicate_(options: InternalFetchOptions_): Promise<Response> {
+  if (options.removeDuplicate === 'never') {
+    return handleRetryPattern_(options);
+  }
+
+  DEV_MODE && logger_.logMethod?.('handleRemoveDuplicate_');
+
+  const cacheKey = computeDedupeKey_(options);
+
+  let requestAsync = duplicateRequestStorage_.get(cacheKey);
+  if (requestAsync == null) {
+    requestAsync = handleRetryPattern_(options);
+    duplicateRequestStorage_.set(cacheKey, requestAsync);
+  }
+
+  try {
+    const response = await requestAsync;
+
+    // Clean up stored promise for 'until_load' or failed responses
+    if (!response.ok || options.removeDuplicate === 'until_load') {
+      duplicateRequestStorage_.delete(cacheKey);
+    }
+
+    // Return a clone so every concurrent caller can independently consume the body
+    return response.clone();
+  } catch (err) {
+    // If request failed, remove from storage immediately
+    duplicateRequestStorage_.delete(cacheKey);
+    throw err;
+  }
+}

package/src/error.ts

@@ -1,43 +1,95 @@
-import type {JsonObject} from '@alwatr/type-helper';
+import {HttpStatusCodes} from '@alwatr/http-primer';
 import type {FetchErrorReason} from './type.js';
 
+/**
+ * Maps an HTTP status code to a semantic `FetchErrorReason`.
+ *
+ * @param status - The HTTP response status code.
+ * @returns The mapped `FetchErrorReason`.
+ *
+ * @example
+ * ```typescript
+ * httpStatusToErrorReason(401); // 'unauthorized'
+ * httpStatusToErrorReason(404); // 'not_found'
+ * httpStatusToErrorReason(500); // 'server_error'
+ * ```
+ */
+export function httpStatusToErrorReason(status: number): FetchErrorReason {
+  switch (status) {
+    case HttpStatusCodes.Error_Client_400_Bad_Request:
+      return 'bad_request';
+    case HttpStatusCodes.Error_Client_401_Unauthorized:
+      return 'unauthorized';
+    case HttpStatusCodes.Error_Client_403_Forbidden:
+      return 'forbidden';
+    case HttpStatusCodes.Error_Client_404_Not_Found:
+      return 'not_found';
+    case HttpStatusCodes.Error_Client_408_Request_Timeout:
+      return 'request_timeout';
+    case HttpStatusCodes.Error_Client_409_Conflict:
+      return 'conflict';
+    case HttpStatusCodes.Error_Client_413_Payload_Too_Large:
+      return 'payload_too_large';
+    case HttpStatusCodes.Error_Client_422_Unprocessable_Entity:
+      return 'unprocessable_content';
+    case HttpStatusCodes.Error_Client_429_Too_Many_Requests:
+      return 'rate_limited';
+    default:
+      if (status >= 500 && status < 600) {
+        return 'server_error';
+      }
+      return 'http_error';
+  }
+}
+
 /**
  * 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.
+ * This error is returned in the `[null, FetchError]` tuple when a request fails.
+ * It enriches the standard `Error` with the `response`, the parsed `data` body,
+ * and the specific `reason` enum.
  *
  * @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);
+ *   if (error.reason === 'unauthorized') {
+ *     redirectToLogin();
+ *   } else if (error.reason === 'server_error') {
+ *     showToast('Server unavailable, please try again later');
+ *   }
  * }
  * ```
  */
 export 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.
+   * The original `Response` object, if one was received.
    */
   public response?: Response;
 
   /**
-   * The parsed body of the error response, typically a JSON object.
-   * It will be `undefined` for non-HTTP errors.
+   * The parsed body of the error response, if available (JSON object, string, etc.).
    */
-  public data?: JsonObject | string;
+  public data?: unknown;
 
   /**
-   * The specific reason for the fetch failure.
+   * The specific semantic reason for the fetch failure.
    */
   public reason: FetchErrorReason;
 
-  constructor(reason: FetchErrorReason, message: string, response?: Response, data?: JsonObject | string) {
+  /**
+   * Helper getter for the HTTP status code.
+   */
+  get status(): number | undefined {
+    return this.response?.status;
+  }
+
+  /**
+   * Always `false` to indicate error status.
+   */
+  readonly ok: false = false;
+
+  constructor(reason: FetchErrorReason, message: string, response?: Response, data?: unknown) {
     super(message);
     this.name = 'FetchError';
     this.reason = reason;

package/src/fetch.ts

@@ -0,0 +1,169 @@
+import {FetchError, httpStatusToErrorReason} from './error.js';
+import {handleCacheStrategy_} from './cache.js';
+import {processOptions_, logger_} from './options.js';
+
+import type {FetchJsonOptions, FetchJsonResponse, FetchOptions, FetchResponse} from './type.js';
+
+/**
+ * An enhanced wrapper for the native `fetch` function.
+ *
+ * Provides:
+ * - **Deterministic Errors**: Semantic `FetchError` reasons (e.g. `unauthorized`, `forbidden`, `not_found`, `server_error`, `timeout`, `aborted`, `rate_limited`).
+ * - **Go-Style Tuple Return**: Never throws, returns `[response, null]` on success or `[null, FetchError]` on failure.
+ * - **Automatic Timeout**: Aborts the request if it exceeds `timeout` duration.
+ * - **Configurable Retry**: Automatically retries transient 5xx, 429, 408, or network errors with `retryDelay` and `Retry-After` support.
+ * - **Parallel Deduplication**: Collapses identical concurrent in-flight requests.
+ * - **Cache Strategies**: Integrates with Cache API (`cache_first`, `stale_while_revalidate`, etc.).
+ * - **Isolated Headers & Query Params**: Safely formats query parameters and authorization credentials without mutating caller objects.
+ *
+ * @param url - The URL to fetch.
+ * @param options - Configuration options for the fetch request.
+ * @returns A promise resolving to `[Response, null]` on success, or `[null, FetchError]` on failure.
+ *
+ * @example
+ * ```typescript
+ * import {fetch} from '@alwatr/fetch';
+ *
+ * const [response, error] = await fetch('/api/products', {
+ *   queryParams: { limit: 10 },
+ *   timeout: '5s',
+ * });
+ *
+ * if (error) {
+ *   if (error.reason === 'not_found') {
+ *     console.warn('Product not found');
+ *   }
+ *   return;
+ * }
+ *
+ * const data = await response.json();
+ * ```
+ */
+export async function fetch(url: string, options: FetchOptions = {}): Promise<FetchResponse> {
+  const options_ = processOptions_(url, options);
+  DEV_MODE && logger_.logMethodArgs?.('fetch', options_);
+
+  try {
+    const response = await handleCacheStrategy_(options_);
+
+    if (!response.ok) {
+      const reason = httpStatusToErrorReason(response.status);
+      throw new FetchError(reason, `HTTP error! status: ${response.status} ${response.statusText}`, response);
+    }
+
+    return [response, null];
+  } catch (err) {
+    let error: FetchError;
+
+    if (err instanceof FetchError) {
+      error = err;
+
+      if (error.response !== undefined && error.data === undefined) {
+        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'));
+    }
+
+    DEV_MODE && logger_.accident('fetch', error.reason, {error});
+    return [null, error];
+  }
+}
+
+/**
+ * An enhanced wrapper for `fetch` that automatically parses JSON responses.
+ *
+ * Accepts unconstrained generic interfaces, DTOs, and arrays without requiring index signatures.
+ *
+ * @template T - The expected type of the JSON response payload.
+ *
+ * @param url - The URL to fetch.
+ * @param options - Configuration options for the fetch request.
+ * @returns A promise resolving to `[data, null]` where data is typed as `T`, or `[null, FetchError]`.
+ *
+ * @example
+ * ```typescript
+ * import {fetchJson} from '@alwatr/fetch';
+ *
+ * interface User {
+ *   id: string;
+ *   name: string;
+ * }
+ *
+ * const [users, error] = await fetchJson<User[]>('/api/users');
+ * if (error) {
+ *   console.error('Failed to load users:', error.reason);
+ *   return;
+ * }
+ * console.log('Users count:', users.length);
+ * ```
+ */
+export async function fetchJson<T = unknown>(
+  url: string,
+  options: FetchJsonOptions = {},
+): Promise<FetchJsonResponse<T>> {
+  DEV_MODE && logger_.logMethod?.('fetchJson');
+
+  const [response, error] = await fetch(url, options);
+
+  if (error) {
+    return [null, error];
+  }
+
+  const bodyText = await response.text().catch(() => '');
+  if (bodyText.trim().length === 0) {
+    const parseError = new FetchError(
+      'json_parse_error',
+      'Response body is empty, cannot parse JSON',
+      response,
+      bodyText,
+    );
+    DEV_MODE && logger_.accident('fetchJson', parseError.reason, {error: parseError});
+    return [null, parseError];
+  }
+
+  try {
+    const data = JSON.parse(bodyText) as T;
+
+    if (
+      options.requireJsonResponseWithOkTrue
+      && (typeof data !== 'object' || data === null || (data as Record<string, unknown>).ok !== true)
+    ) {
+      const parseError = new FetchError(
+        'json_response_error',
+        'Response JSON "ok" property is not true',
+        response,
+        data,
+      );
+      DEV_MODE && logger_.accident('fetchJson', parseError.reason, {error: parseError});
+      return [null, parseError];
+    }
+
+    return [data, null];
+  } catch (err) {
+    const parseError = new FetchError(
+      'json_parse_error',
+      err instanceof Error ? err.message : 'Failed to parse JSON response',
+      response,
+      bodyText,
+    );
+    DEV_MODE && logger_.accident('fetchJson', parseError.reason, {error: parseError});
+    return [null, parseError];
+  }
+}
+
+fetchJson.version = fetch.version = __package_version__;

package/src/main.ts

@@ -6,193 +6,6 @@
  * timeouts, and duplicate request handling.
  */
 
-import type {JsonObject} from '@alwatr/type-helper';
-import {_processOptions, handleCacheStrategy_, logger_, cacheSupported} from './core.js';
-import {FetchError} from './error.js';
-
-import type {FetchJsonOptions, FetchOptions, FetchResponse} from './type.js';
-
-export {cacheSupported};
 export * from './error.js';
+export * from './fetch.js';
 export type * from './type.js';
-
-/**
- * An enhanced wrapper for the native `fetch` function.
- *
- * This function extends the standard `fetch` with additional features such as:
- * - **Timeout**: Aborts the request if it takes too long.
- * - **Retry Pattern**: Automatically retries the request on failure (e.g., server errors or network issues).
- * - **Duplicate Request Handling**: Prevents sending multiple identical requests in parallel.
- * - **Cache Strategies**: Provides various caching mechanisms using the browser's Cache API.
- * - **Simplified API**: Offers convenient options for adding query parameters, JSON bodies, and auth tokens.
- *
- * @see {@link FetchOptions} for a detailed list of available options.
- *
- * @param {string} url - The URL to fetch.
- * @param {FetchOptions} options - Optional configuration for the fetch 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() {
- *   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 async function fetch(url: string, options: FetchOptions = {}): Promise<FetchResponse> {
-  DEV_MODE && logger_.logMethodArgs?.('fetch', {url, options});
-
-  const options_ = _processOptions(url, options);
-
-  try {
-    // Start the fetch lifecycle, beginning with the cache strategy.
-    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: FetchError;
-
-    if (err instanceof FetchError) {
-      error = err;
-
-      if (error.response !== undefined && error.data === undefined) {
-        const bodyText = await error.response.text().catch(() => '');
-
-        if (bodyText.trim().length > 0) {
-          try {
-            // Try to parse as JSON
-            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];
-  }
-}
-
-fetch.version = __package_version__;
-
-/**
- * An enhanced wrapper for the native `fetch` function that automatically parses JSON responses.
- *
- * This function extends the standard `fetch` with the same features (timeout, retry, caching, etc.)
- * and automatically parses the response body as JSON. It returns a tuple with the parsed data or an error.
- *
- * @template T - The expected type of the JSON response data.
- *
- * @param {string} url - The URL to fetch.
- * @param {FetchOptions} options - Optional configuration for the fetch request.
- * @returns {Promise<[T, null] | [null, FetchError]>} A promise that resolves to a tuple.
- * On success, it returns `[data, null]` where data is the parsed JSON.
- * On failure, it returns `[null, FetchError]`.
- *
- * @example
- * ```typescript
- * import {fetchJson} from '@alwatr/fetch';
- *
- * interface Product {
- *   ok: true;
- *   id: number;
- *   name: string;
- *   price: number;
- * }
- *
- * async function getProduct(id: number) {
- *   const [data, error] = await fetchJson<Product>(`/api/products/${id}`, {
- *     timeout: 5_000,
- *     cacheStrategy: 'cache_first',
- *     requireResponseJsonWithOkTrue: true,
- *   });
- *
- *   if (error) {
- *     console.error('Failed to fetch product:', error.reason);
- *     return;
- *   }
- *
- *   // data is now typed as Product and guaranteed to be valid
- *   console.log('Product name:', data.name);
- * }
- * ```
- */
-export async function fetchJson<T extends JsonObject = JsonObject>(
-  url: string,
-  options: FetchJsonOptions = {},
-): Promise<[T, null] | [null, FetchError]> {
-  DEV_MODE && logger_.logMethodArgs?.('fetchJson', {url, options});
-
-  const [response, error] = await fetch(url, options);
-
-  if (error) {
-    return [null, error];
-  }
-
-  const bodyText = await response.text().catch(() => '');
-  if (bodyText.trim().length === 0) {
-    const parseError = new FetchError(
-      'json_parse_error',
-      'Response body is empty, cannot parse JSON',
-      response,
-      bodyText,
-    );
-    logger_.error('fetchJson', parseError.reason, {error: parseError});
-    return [null, parseError];
-  }
-
-  try {
-    const data = JSON.parse(bodyText) as T;
-    if (options.requireJsonResponseWithOkTrue && data.ok !== true) {
-      const parseError = new FetchError(
-        'json_response_error',
-        'Response JSON "ok" property is not true',
-        response,
-        data,
-      );
-      logger_.error('fetchJson', parseError.reason, {error: parseError});
-      return [null, parseError];
-    }
-    return [data, null];
-  } catch (err) {
-    const parseError = new FetchError(
-      'json_parse_error',
-      err instanceof Error ? err.message : 'Failed to parse JSON response',
-      response,
-      bodyText,
-    );
-    logger_.error('fetchJson', parseError.reason, {error: parseError});
-    return [null, parseError];
-  }
-}