@alwatr/fetch 10.0.3 → 10.1.0

package/src/options.ts

@@ -0,0 +1,191 @@
+import {MimeTypes, type HttpMethod} from '@alwatr/http-primer';
+import {createLogger} from '@alwatr/logger';
+import {getGlobalThis} from '@alwatr/global-this';
+import {parseDuration} from '@alwatr/parse-duration';
+
+import type {AlwatrFetchOptions_, FetchOptions, InternalFetchOptions_, QueryParams} from './type.js';
+
+export const logger_ = createLogger('@alwatr/fetch');
+
+export const globalThis_ = getGlobalThis();
+
+/**
+ * Immutable default options for all fetch requests.
+ */
+export const defaultFetchOptions: Readonly<AlwatrFetchOptions_> = {
+  method: 'GET',
+  timeout: 8_000,
+  retry: 3,
+  retryDelay: 1_000,
+  removeDuplicate: 'never',
+  cacheStrategy: 'network_only',
+  cacheStorageName: 'fetch_cache',
+  // headers: {}, // --- IGNORED ---
+};
+
+/**
+ * Normalizes any standard `HeadersInit` into a fresh, isolated lowercase string record.
+ *
+ * @param headers - User-provided headers (plain object, Headers instance, or entries array).
+ * @param baseHeaders - Optional base headers to merge with the user-provided headers.
+ * @returns An isolated `Record<string, string>`.
+ */
+export function normalizeHeaders_(
+  headers?: HeadersInit,
+  baseHeaders: Record<string, string> = {},
+): Record<string, string> {
+  if (headers == null) {
+    return baseHeaders;
+  }
+
+  if (typeof Headers !== 'undefined' && headers instanceof Headers) {
+    headers.forEach((value, key) => {
+      baseHeaders[key.toLowerCase()] = value;
+    });
+    return baseHeaders;
+  }
+
+  if (Array.isArray(headers)) {
+    for (const [key, value] of headers) {
+      if (typeof key === 'string' && typeof value === 'string') {
+        baseHeaders[key.toLowerCase()] = value;
+      }
+    }
+    return baseHeaders;
+  }
+
+  if (typeof headers === 'object') {
+    for (const key of Object.keys(headers)) {
+      const val = (headers as Record<string, unknown>)[key];
+      if (val != null) {
+        baseHeaders[key.toLowerCase()] = String(val);
+      }
+    }
+  }
+
+  return baseHeaders;
+}
+
+/**
+ * Serializes query parameters into a query string.
+ *
+ * @param queryParams - Dictionary of query parameters.
+ * @returns Serialized URL query string (without leading `?` or `&`).
+ */
+export function serializeQueryParams_(queryParams: QueryParams): string {
+  const parts: string[] = [];
+
+  for (const key of Object.keys(queryParams)) {
+    const value = queryParams[key];
+    if (value === undefined || value === null) {
+      continue;
+    }
+
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item !== undefined && item !== null) {
+          parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(item))}`);
+        }
+      }
+    } else {
+      parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+    }
+  }
+
+  return parts.join('&');
+}
+
+/**
+ * Appends query parameters to a URL, correctly respecting existing query parameters and hash anchors.
+ *
+ * @param url - The target URL.
+ * @param queryParams - Query parameters to append.
+ * @returns The resulting URL string.
+ */
+export function appendQueryParams_(url: string, queryParams?: QueryParams): string {
+  if (queryParams == null) {
+    return url;
+  }
+
+  const queryString = serializeQueryParams_(queryParams);
+  if (queryString.length === 0) {
+    return url;
+  }
+
+  // Handle hash fragment if present in URL
+  let baseUrl = url;
+  let hashPart = '';
+  const hashIndex = url.indexOf('#');
+
+  if (hashIndex !== -1) {
+    baseUrl = url.slice(0, hashIndex);
+    hashPart = url.slice(hashIndex);
+  }
+
+  const separator = baseUrl.includes('?') ? '&' : '?';
+  return `${baseUrl}${separator}${queryString}${hashPart}`;
+}
+
+/**
+ * Processes, sanitizes, and normalizes user-provided fetch options into a complete, isolated options object.
+ *
+ * @param url - The target URL.
+ * @param options - User-provided options.
+ * @returns Internal, complete, and isolated fetch options.
+ * @internal
+ */
+export function processOptions_(url: string, options: FetchOptions = {}): InternalFetchOptions_ {
+  DEV_MODE && logger_.logMethod?.('processOptions_');
+
+  const processedUrl = appendQueryParams_(url, options.queryParams);
+
+  const options_: InternalFetchOptions_ = {
+    ...defaultFetchOptions,
+    ...options,
+    headers: normalizeHeaders_(options.headers),
+    url: processedUrl,
+    method: (options.method?.toUpperCase() as HttpMethod) ?? defaultFetchOptions.method,
+    timeout: parseDuration(options.timeout ?? defaultFetchOptions.timeout),
+    retryDelay: parseDuration(options.retryDelay ?? defaultFetchOptions.retryDelay),
+    retry:
+      typeof options.retry === 'number' && Number.isFinite(options.retry) ?
+        Math.max(1, Math.floor(options.retry))
+      : defaultFetchOptions.retry,
+  };
+
+  options_.window ??= null;
+
+  // Cache API Preconditions: requires Cache API runtime support and cacheable HTTP method (GET/HEAD)
+  if (
+    options_.cacheStrategy !== 'network_only'
+    && (typeof caches === 'undefined' || (options_.method !== 'GET' && options_.method !== 'HEAD'))
+  ) {
+    DEV_MODE
+      && logger_.incident?.('processOptions_', 'fetch_cache_strategy_unsupported', {
+        method: options_.method,
+        cacheStrategy: options_.cacheStrategy,
+        hasCaches: typeof caches !== 'undefined',
+      });
+    options_.cacheStrategy = 'network_only';
+  }
+
+  // Deduplication auto selection
+  if (options_.removeDuplicate === 'auto') {
+    options_.removeDuplicate = typeof caches !== 'undefined' ? 'until_load' : 'always';
+  }
+
+  // JSON Body serialization
+  if (options.bodyJson !== undefined) {
+    options_.body = JSON.stringify(options.bodyJson);
+    options_.headers['content-type'] = MimeTypes.JSON;
+  }
+
+  // Authorization header configuration
+  if (options.bearerToken !== undefined) {
+    options_.headers.authorization = `Bearer ${options.bearerToken}`;
+  } else if (options.alwatrAuth !== undefined) {
+    options_.headers.authorization = `Alwatr ${options.alwatrAuth.userId}:${options.alwatrAuth.userToken}`;
+  }
+
+  return options_;
+}

package/src/retry.ts

@@ -0,0 +1,106 @@
+import {delay} from '@alwatr/delay';
+import {getGlobalThis} from '@alwatr/global-this';
+import {HttpStatusCodes} from '@alwatr/http-primer';
+import {FetchError} from './error.js';
+import {logger_} from './options.js';
+import {handleTimeout_} from './timeout.js';
+
+import type {InternalFetchOptions_} from './type.js';
+
+const globalThis_ = getGlobalThis();
+
+/**
+ * Checks whether an HTTP response status code is retryable.
+ *
+ * Retryable statuses:
+ * - Any 5xx Server Error (500, 502, 503, 504, ...)
+ * - 408 Request Timeout
+ * - 429 Too Many Requests
+ */
+export function isRetryableStatus_(status: number): boolean {
+  return (
+    status >= HttpStatusCodes.Error_Server_500_Internal_Server_Error
+    || status === HttpStatusCodes.Error_Client_408_Request_Timeout
+    || status === HttpStatusCodes.Error_Client_429_Too_Many_Requests
+  );
+}
+
+/**
+ * Parses the `Retry-After` header value (in seconds or HTTP-date) if present.
+ *
+ * @param response - The HTTP Response object.
+ * @returns Delay duration in milliseconds, or undefined if absent/invalid.
+ */
+export function parseRetryAfterHeader_(response?: Response): number | undefined {
+  const retryAfter = response?.headers?.get('retry-after');
+  if (!retryAfter) return undefined;
+
+  const seconds = Number(retryAfter);
+  if (!isNaN(seconds) && seconds > 0) {
+    return seconds * 1000;
+  }
+
+  const dateMs = Date.parse(retryAfter);
+  if (!isNaN(dateMs)) {
+    const diff = dateMs - Date.now();
+    return diff > 0 ? diff : 0;
+  }
+
+  return undefined;
+}
+
+/**
+ * Executes a fetch request with automatic retries on transient errors (5xx, 429, 408, network failures, timeouts).
+ *
+ * @param options - Processed internal fetch options.
+ * @returns A promise resolving to the final `Response` after retry cycles.
+ * @internal
+ */
+export async function handleRetryPattern_(options: InternalFetchOptions_): Promise<Response> {
+  if (options.retry <= 1) {
+    return handleTimeout_(options);
+  }
+
+  DEV_MODE && logger_.logMethod?.('handleRetryPattern_');
+  options.retry--;
+
+  let response: Response;
+  try {
+    response = await handleTimeout_(options);
+
+    if (response.ok || !isRetryableStatus_(response.status)) {
+      return response;
+    }
+  } catch (err) {
+    DEV_MODE && logger_.accident('fetch', 'fetch_failed_retry', err);
+
+    // Never retry if the request was intentionally aborted
+    if (options.signal?.aborted || (err instanceof FetchError && err.reason === 'aborted')) {
+      throw err;
+    }
+
+    // Do not retry if the runtime is offline
+    if (globalThis_.navigator?.onLine === false) {
+      DEV_MODE && logger_.accident('handleRetryPattern_', 'offline', 'Skip retry because offline');
+      throw err;
+    }
+
+    await delay.by(options.retryDelay);
+
+    return handleRetryPattern_(options);
+  }
+
+  // Handle transient retryable HTTP status (5xx, 429, 408)
+  DEV_MODE && logger_.accident('fetch', 'fetch_failed_retry', {status: response.status});
+
+  if (globalThis_.navigator?.onLine === false) {
+    DEV_MODE && logger_.accident('handleRetryPattern_', 'offline', 'Skip retry because offline');
+    return response;
+  }
+
+  const retryDelay = parseRetryAfterHeader_(response) ?? options.retryDelay;
+
+  await delay.by(retryDelay);
+
+  return handleRetryPattern_(options);
+}

package/src/timeout.ts

@@ -0,0 +1,85 @@
+import {getGlobalThis} from '@alwatr/global-this';
+import {FetchError} from './error.js';
+import {logger_} from './options.js';
+
+import type {InternalFetchOptions_} from './type.js';
+
+const globalThis_ = getGlobalThis();
+
+/**
+ * Executes a native `fetch` wrapped with an `AbortController` timeout.
+ *
+ * Checks for pre-aborted external signals, respects external cancellation,
+ * and guarantees listener and timer cleanup on completion.
+ *
+ * @param options - Processed internal fetch options.
+ * @returns A promise resolving to the native `Response` or rejecting with `FetchError`.
+ * @internal
+ */
+export function handleTimeout_(options: InternalFetchOptions_): Promise<Response> {
+  const externalSignal = options.signal;
+
+  // Immediate abort check: If signal is already aborted, reject immediately without network overhead
+  if (externalSignal?.aborted) {
+    DEV_MODE && logger_.incident?.('handleTimeout_', 'already_aborted', {reason: externalSignal.reason});
+    return Promise.reject(new FetchError('aborted', 'The operation was aborted'));
+  }
+
+  // If timeout is disabled (0), invoke native fetch directly with external signal
+  if (options.timeout === 0) {
+    return globalThis_.fetch(options.url, options as RequestInit);
+  }
+
+  DEV_MODE && logger_.logMethod?.('handleTimeout_');
+
+  return new Promise((resolve, reject) => {
+    const abortController = typeof AbortController === 'function' ? new AbortController() : null;
+
+    let onExternalAbort: (() => void) | undefined;
+
+    if (abortController !== null) {
+      options.signal = abortController.signal;
+
+      if (externalSignal != null) {
+        onExternalAbort = () => {
+          abortController.abort(externalSignal.reason);
+        };
+        externalSignal.addEventListener('abort', onExternalAbort, {once: true});
+      }
+    }
+
+    let timeoutFired = false;
+
+    const timeoutId = setTimeout(() => {
+      timeoutFired = true;
+      abortController?.abort('fetch_timeout');
+      reject(new FetchError('timeout', 'fetch_timeout'));
+    }, options.timeout);
+
+    globalThis_
+      .fetch(options.url, options as RequestInit)
+      .then((response) => {
+        if (!timeoutFired) {
+          resolve(response);
+        }
+      })
+      .catch((err: unknown) => {
+        if (timeoutFired) {
+          return;
+        }
+
+        if (externalSignal?.aborted || (err instanceof Error && err.name === 'AbortError')) {
+          reject(new FetchError('aborted', 'The operation was aborted'));
+        } else {
+          reject(err);
+        }
+      })
+      .finally(() => {
+        clearTimeout(timeoutId);
+        options.signal = externalSignal;
+        if (externalSignal != null && onExternalAbort !== undefined) {
+          externalSignal.removeEventListener('abort', onExternalAbort);
+        }
+      });
+  });
+}

package/src/type.ts

@@ -1,13 +1,15 @@
-import type {DictionaryOpt, DictionaryReq, JsonValue} from '@alwatr/type-helper';
+import type {DictionaryOpt, JsonValue} from '@alwatr/type-helper';
 import type {FetchError} from './error.js';
 import type {HttpMethod, HttpRequestHeaders} from '@alwatr/http-primer';
 import type {Duration} from '@alwatr/parse-duration';
 
 /**
  * A dictionary of query parameters.
- * Keys are strings, and values can be strings, numbers, or booleans.
+ * Keys are strings, and values can be strings, numbers, booleans, or arrays of these primitives.
  */
-export type QueryParams = DictionaryOpt<string | number | boolean>;
+export type QueryParams = DictionaryOpt<
+  string | number | boolean | readonly (string | number | boolean)[] | (string | number | boolean)[]
+>;
 
 /**
  * Defines the caching strategy for a fetch request.
@@ -47,9 +49,9 @@ export interface AlwatrFetchOptions_ {
   method: HttpMethod;
 
   /**
-   * An object of request headers.
+   * Request headers. Supports plain object, Web Standard `Headers`, or entries array.
    */
-  headers: HttpRequestHeaders & DictionaryReq<string>;
+  headers?: HttpRequestHeaders | HeadersInit;
 
   /**
    * Request timeout duration. Can be a number (milliseconds) or a string (e.g., '5s').
@@ -60,33 +62,33 @@ export interface AlwatrFetchOptions_ {
 
   /**
    * Number of times to retry a failed request.
-   * Retries occur on network errors, timeouts, or 5xx server responses.
+   * Retries occur on network errors, timeouts, 408/429 status codes, or 5xx server responses.
    * @default 3
    */
   retry: number;
 
   /**
-   * Delay before each retry attempt. Can be a number (milliseconds) or a string (e.g., '2s').
+   * Delay before each retry attempt. Can be a number (milliseconds) or a string (e.g., '1s').
    * @default '1s'
    */
   retryDelay: Duration;
 
   /**
    * Strategy for handling duplicate parallel requests.
-   * Uniqueness is determined by method, URL, and request body.
+   * Uniqueness is determined by method, URL, query parameters, request body, and authorization context.
    * @default 'never'
    */
   removeDuplicate: CacheDuplicate;
 
   /**
    * The caching strategy to use for the request.
-   * Requires a browser environment with Cache API support.
+   * Requires a browser or 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.
+   * A callback function executed with the fresh response when using 'stale_while_revalidate'.
    */
   revalidateCallback?: (response: Response) => void | Promise<void>;
 
@@ -97,7 +99,7 @@ export interface AlwatrFetchOptions_ {
   cacheStorageName: string;
 
   /**
-   * A JavaScript object to be sent as the request's JSON body.
+   * A JavaScript value to be serialized as the request's JSON body.
    * Automatically sets the 'Content-Type' header to 'application/json'.
    */
   bodyJson?: JsonValue;
@@ -126,31 +128,86 @@ export interface AlwatrFetchOptions_ {
  */
 export type FetchOptions = Partial<AlwatrFetchOptions_> & Omit<RequestInit, 'headers'>;
 
-export type FetchJsonOptions = FetchOptions & {requireJsonResponseWithOkTrue?: true};
+/**
+ * Options for `fetchJson`, extending `FetchOptions` with JSON-specific flags.
+ */
+export type FetchJsonOptions = FetchOptions & {
+  /**
+   * If `true`, requires the parsed JSON body to have an `ok: true` property.
+   * If `ok` is missing or not `true`, fails with `json_response_error`.
+   */
+  requireJsonResponseWithOkTrue?: true;
+};
+
+/**
+ * Represents the tuple returned by the `fetch` function.
+ * On success: `[Response, null]`. On failure: `[null, FetchError]`.
+ */
+export type FetchResponse = readonly [Response, null] | readonly [null, FetchError];
 
 /**
- * Represents the tuple returned by the fetch function.
- * On success, it's `[Response, null]`. On failure, it's `[null, FetchError]`.
+ * Represents the tuple returned by `fetchJson`.
+ * On success: `[T, null]`. On failure: `[null, FetchError]`.
  */
-export type FetchResponse = Promise<[Response, null] | [null, FetchError]>;
+export type FetchJsonResponse<T = unknown> = readonly [T, null] | readonly [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.
+ *
+ * Semantic HTTP Client Errors (4xx):
+ * - `bad_request`: 400 Bad Request
+ * - `unauthorized`: 401 Unauthorized
+ * - `forbidden`: 403 Forbidden
+ * - `not_found`: 404 Not Found
+ * - `request_timeout`: 408 Request Timeout
+ * - `conflict`: 409 Conflict
+ * - `payload_too_large`: 413 Payload Too Large
+ * - `unprocessable_content`: 422 Unprocessable Entity / Content
+ * - `rate_limited`: 429 Too Many Requests
+ * - `http_error`: Other 4xx client errors
+ *
+ * Semantic HTTP Server Errors (5xx):
+ * - `server_error`: Any 5xx server-side error (500, 502, 503, 504, etc.)
+ *
+ * Network & Lifecycle Errors:
+ * - `timeout`: The request exceeded the configured timeout duration.
+ * - `aborted`: The request was cancelled by an AbortSignal.
+ * - `network_error`: A network-level failure occurred (DNS, connection reset, offline).
+ * - `cache_not_found`: Resource was not found when using `cache_only`.
+ * - `json_parse_error`: Response body could not be parsed as valid JSON.
+ * - `json_response_error`: Response JSON `ok` property was not true when `requireJsonResponseWithOkTrue` was set.
+ * - `unknown_error`: An unexpected or untyped error occurred.
  */
 export type FetchErrorReason =
+  | 'bad_request'
+  | 'unauthorized'
+  | 'forbidden'
+  | 'not_found'
+  | 'request_timeout'
+  | 'conflict'
+  | 'payload_too_large'
+  | 'unprocessable_content'
+  | 'rate_limited'
   | 'http_error'
-  | 'cache_not_found'
+  | 'server_error'
   | 'timeout'
-  | 'network_error'
   | 'aborted'
+  | 'network_error'
+  | 'cache_not_found'
   | 'json_parse_error'
   | 'json_response_error'
   | 'unknown_error';
+
+/**
+ * Internal-only normalized fetch options type.
+ * @internal
+ */
+export interface InternalFetchOptions_
+  extends Omit<AlwatrFetchOptions_, 'headers' | 'method' | 'timeout' | 'retryDelay'>,
+    Omit<RequestInit, 'headers' | 'method'> {
+  url: string;
+  method: HttpMethod;
+  headers: HttpRequestHeaders;
+  timeout: number;
+  retryDelay: number;
+}

package/dist/core.d.ts

@@ -1,34 +0,0 @@
-import type { AlwatrFetchOptions_, FetchOptions } from './type.js';
-export declare const logger_: import("@alwatr/logger").AlwatrLogger;
-/**
- * A boolean flag indicating whether the browser's Cache API is supported.
- */
-export declare const cacheSupported: boolean;
-/**
- * Internal-only fetch options type, which includes the URL and ensures all
- * optional properties from AlwatrFetchOptions_ are present.
- */
-type FetchOptions__ = AlwatrFetchOptions_ & Omit<RequestInit, 'headers'> & {
-    url: string;
-};
-/**
- * Processes and sanitizes the fetch options.
- *
- * @param {string} url - The URL to fetch.
- * @param {FetchOptions} options - The user-provided options.
- * @returns {FetchOptions__} The processed and complete fetch options.
- * @private
- */
-export declare function _processOptions(url: string, options: FetchOptions): FetchOptions__;
-/**
- * Manages caching strategies for the fetch request.
- * If the strategy is `network_only`, it bypasses caching and proceeds to the next step.
- * Otherwise, it interacts with the browser's Cache API based on the selected strategy.
- *
- * @param {FetchOptions__} options - The fully configured fetch options.
- * @returns {Promise<Response>} A promise resolving to a `Response` object, either from the cache or the network.
- * @private
- */
-export declare function handleCacheStrategy_(options: FetchOptions__): Promise<Response>;
-export {};
-//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAC,mBAAmB,EAAE,YAAY,EAAC,MAAM,WAAW,CAAC;AAEjE,eAAO,MAAM,OAAO,uCAAgC,CAAC;AAIrD;;GAEG;AACH,eAAO,MAAM,cAAc,SAAgD,CAAC;AAwB5E;;;GAGG;AACH,KAAK,cAAc,GAAG,mBAAmB,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,GAAG;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,CAAC;AAEzF;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,cAAc,CAoDlF;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CA6FrF"}