@alwatr/fetch 7.1.6 → 8.0.0

package/src/main.ts

@@ -0,0 +1,203 @@
+/**
+ * @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.
+ */
+
+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 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> {
+  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]> {
+  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];
+  }
+}

package/src/type.ts

@@ -0,0 +1,157 @@
+import type {FetchError} from './error.js';
+import type {HttpMethod, HttpRequestHeaders} from '@alwatr/http-primer';
+import type {Duration} from '@alwatr/parse-duration';
+import type {} from '@alwatr/type-helper';
+import type {} from '@alwatr/nano-build';
+
+/**
+ * A dictionary of query parameters.
+ * Keys are strings, and values can be strings, numbers, or booleans.
+ */
+export type QueryParams = DictionaryOpt<string | number | boolean>;
+
+/**
+ * Defines the caching strategy for a fetch request.
+ *
+ * - `network_only`: Always fetches from the network.
+ * - `network_first`: Tries the network first, then falls back to the cache.
+ * - `cache_only`: Only fetches from the cache; fails if not found.
+ * - `cache_first`: Tries the cache first, then falls back to the network.
+ * - `update_cache`: Fetches from the network and updates the cache.
+ * - `stale_while_revalidate`: Serves from cache while revalidating in the background.
+ */
+export type CacheStrategy =
+  | 'network_only'
+  | 'network_first'
+  | 'cache_only'
+  | 'cache_first'
+  | 'update_cache'
+  | 'stale_while_revalidate';
+
+/**
+ * Defines the caching behavior for identical, parallel requests.
+ * - `never`: No deduplication is performed.
+ * - `always`: The response is cached for the lifetime of the application.
+ * - `until_load`: The response is cached until the initial request is complete.
+ * - `auto`: Automatically selects the best strategy (`until_load` in browsers, `always` otherwise).
+ */
+export type CacheDuplicate = 'never' | 'always' | 'until_load' | 'auto';
+
+/**
+ * Defines the options for an Alwatr fetch request.
+ */
+export interface AlwatrFetchOptions_ {
+  /**
+   * The HTTP request method.
+   * @default 'GET'
+   */
+  method: HttpMethod;
+
+  /**
+   * An object of request headers.
+   */
+  headers: HttpRequestHeaders & DictionaryReq<string>;
+
+  /**
+   * Request timeout duration. Can be a number (milliseconds) or a string (e.g., '5s').
+   * Set to `0` to disable.
+   * @default '8s'
+   */
+  timeout: Duration;
+
+  /**
+   * Number of times to retry a failed request.
+   * Retries occur on network errors, timeouts, or 5xx server responses.
+   * @default 3
+   */
+  retry: number;
+
+  /**
+   * Delay before each retry attempt. Can be a number (milliseconds) or a string (e.g., '2s').
+   * @default '1s'
+   */
+  retryDelay: Duration;
+
+  /**
+   * Strategy for handling duplicate parallel requests.
+   * Uniqueness is determined by method, URL, and request body.
+   * @default 'never'
+   */
+  removeDuplicate: CacheDuplicate;
+
+  /**
+   * The caching strategy to use for the request.
+   * Requires a browser environment with Cache API support.
+   * @default 'network_only'
+   */
+  cacheStrategy: CacheStrategy;
+
+  /**
+   * A callback function that is executed with the fresh response when using the 'stale_while_revalidate' cache strategy.
+   */
+  revalidateCallback?: (response: Response) => void | Promise<void>;
+
+  /**
+   * Custom name for the CacheStorage instance.
+   * @default 'fetch_cache'
+   */
+  cacheStorageName: string;
+
+  /**
+   * A JavaScript object to be sent as the request's JSON body.
+   * Automatically sets the 'Content-Type' header to 'application/json'.
+   */
+  bodyJson?: JsonValue;
+
+  /**
+   * A JavaScript object of query parameters to be appended to the request URL.
+   */
+  queryParams?: QueryParams;
+
+  /**
+   * A bearer token to be added to the 'Authorization' header.
+   */
+  bearerToken?: string;
+
+  /**
+   * Alwatr-specific authentication credentials.
+   */
+  alwatrAuth?: {
+    userId: string;
+    userToken: string;
+  };
+}
+
+/**
+ * Combined type for fetch options, including standard RequestInit properties.
+ */
+export type FetchOptions = Partial<AlwatrFetchOptions_> & Omit<RequestInit, 'headers'>;
+
+export type FetchJsonOptions = FetchOptions & {requireJsonResponseWithOkTrue?: true};
+
+/**
+ * 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.
+ * - `json_parse_error`: The response body could not be parsed as JSON.
+ * - `json_response_error`: The response JSON "ok" property is not true.
+ * - `unknown_error`: An unspecified error occurred.
+ */
+export type FetchErrorReason =
+  | 'http_error'
+  | 'cache_not_found'
+  | 'timeout'
+  | 'network_error'
+  | 'aborted'
+  | 'json_parse_error'
+  | 'json_response_error'
+  | 'unknown_error';