Function fetchWithCache

src/cache.ts:749–832

(
  url: RequestInfo,
  options: RequestInit = {},
  timeout: number = getRequestTimeoutMs(),
  format: 'json' | 'text' = 'json',
  bustOrOptions: boolean | CacheOptions | undefined = false,
  maxRetries?: number,
)

 * @see enableCache / disableCache for cache control
 */
export async function fetchWithCache<T = unknown>(
  url: RequestInfo,
  options: RequestInit = {},
  timeout: number = getRequestTimeoutMs(),
  format: 'json' | 'text' = 'json',
  bustOrOptions: boolean | CacheOptions | undefined = false,
  maxRetries?: number,
): Promise<FetchWithCacheResult<T>> {
  const cacheOptions: CacheOptions =
    typeof bustOrOptions === 'boolean' ? { bust: bustOrOptions } : (bustOrOptions ?? {});
  const { bust = false, repeatIndex } = cacheOptions;

  // Only retry body-read for idempotent methods to avoid double-submitting
  // POST/PATCH requests (the server already processed the request once
  // headers arrived; only the response body stream failed).
  const method = (options.method ?? (url instanceof Request ? url.method : 'GET')).toUpperCase();
  const isIdempotent = ['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE'].includes(method);

  const cacheEnabled = getEffectiveCacheEnabled();
  const cacheKey =
    cacheEnabled && !bust ? getFetchCacheKey(url, options, method, format, repeatIndex) : null;

  if (!cacheEnabled || bust || cacheKey == null) {
    const { respText, resp, fetchLatencyMs } = await fetchAndReadBody(
      url,
      options,
      timeout,
      maxRetries,
      isIdempotent,
    );
    try {
      return {
        cached: false,
        data: format === 'json' ? JSON.parse(respText) : respText,
        status: resp.status,
        statusText: resp.statusText,
        headers: Object.fromEntries(resp.headers.entries()),
        latencyMs: fetchLatencyMs,
        deleteFromCache: async () => {
          // No-op when cache is disabled
        },
      };
    } catch (err) {
      throw new Error(
        `Error parsing response from ${url}: ${
          (err as Error).message
        }. HTTP ${resp.status} ${resp.statusText}. Received text: ${respText}`,
      );
    }
  }

  const cache = getCacheInstance();

  const cachedResponse = await cache.get<SerializedFetchResponse>(cacheKey);
  if (cachedResponse != null) {
    logger.debug(`Returning cached response for ${url}: ${cachedResponse}`);
    return deserializeFetchResponse<T>(cachedResponse, true, cache, cacheKey);
  }