Offline Cache JSON Fetcher

Fetches JSON resources with a persistent cache that supports offline reads, stale reuse, and explicit reloads.

Behavior

• Use the provided cacheDirectory for persistent storage; set cacheStatus from cache metadata headers (e.g., x-local-cache-status) or to null when absent; set fromCache when metadata indicates a cache hit (hit, stale, revalidated, or updated); set revalidated when metadata reports a conditional validation instead of a full fetch.
• Honor offline by avoiding network requests entirely and letting the dependency surface its cache-miss error if no entry exists.
• When reload is requested, bypass any cached copy and replace it with a fresh response.
• Parse successful responses as JSON before returning results.

Capabilities

Offline cache-only mode

• When offline mode is enabled and a cached response exists, returns the cached JSON payload and indicates cache usage. @test
• When offline mode is enabled and no cached response exists, surfaces the dependency's cache-miss error without substituting data. @test

Stale revalidation fallback

• With a stale cached response, attempts conditional revalidation; if the origin replies 304, returns cached data and marks it as revalidated using cache metadata. @test
• With a stale cached response and a failing revalidation attempt (e.g., 503 or network error), returns the stale payload while signaling stale cache use. @test

Explicit reload

• When reload is requested, bypasses existing cache, fetches a fresh copy, stores it, and reports network retrieval in cache metadata. @test

Implementation

@generates

API

export interface CachedFetchOptions {
  cacheDirectory: string;
  offline?: boolean;
  reload?: boolean;
  requestInit?: RequestInit;
}

export interface CachedFetchResult<T = unknown> {
  status: number;
  data: T;
  fromCache: boolean;
  cacheStatus?: string | null;
  revalidated?: boolean;
}

export async function fetchJsonWithCache<T = unknown>(
  url: string,
  options: CachedFetchOptions
): Promise<CachedFetchResult<T>>;

Dependencies { .dependencies }

make-fetch-happen { .dependency }

HTTP client with persistent caching, revalidation, and offline cache-only mode.