Disk-Cached Fetch Gateway

Build a fetch wrapper that persists GET/HEAD responses on disk and honors fetch-style cache modes so callers can reuse cached content, refresh it, or fail fast when offline.

Capabilities

Stores and reuses cached responses

• First GET stores the body in the cache directory and the next GET with the default cache mode returns the cached body, marks the response as coming from cache, and avoids a new network request while the entry is still fresh. @test

Reload refreshes cache

• With the cache mode set to "reload", the wrapper bypasses any cached entry, performs a network request, returns the new body, and replaces the cached value for subsequent calls. @test

Only-if-cached behavior

• With the cache mode set to "only-if-cached" and no entry present, the wrapper rejects with a cache-miss error; when an entry exists it returns the cached response without issuing a network request. @test

Conditional revalidation

• With the cache mode set to "no-cache" and a stored ETag or Last-Modified value, the wrapper issues a conditional request; if the server responds 304 it returns the cached body and updates headers metadata, and if the server responds with a new 200 body it returns and stores that new body. @test

Implementation

Use the dependency's disk-backed caching behavior instead of writing custom cache files.

@generates

API

export function createCachedFetcher(config)
/**
 * @typedef {Object} CacheConfig
 * @property {string} cacheDirectory - Folder for the persistent HTTP cache.
 * @property {"default"|"reload"|"no-cache"|"force-cache"|"only-if-cached"} [defaultCacheMode]
 * @property {string} [baseUrl]
 *
 * @typedef {Object} CachedFetchOptions
 * @property {"default"|"reload"|"no-cache"|"force-cache"|"only-if-cached"} [cacheMode]
 * @property {Object.<string, string>} [headers]
 *
 * @typedef {Object} CachedResponse
 * @property {number} status
 * @property {Object.<string, string>} headers
 * @property {boolean} fromCache
 * @property {() => Promise<string>} text
 *
 * @param {CacheConfig} config
 * @returns {(url: string, options?: CachedFetchOptions) => Promise<CachedResponse>}
 */

Dependencies { .dependencies }

make-fetch-happen { .dependency }

Fetch-compatible HTTP client with persistent disk cache, cache mode support, and conditional request handling.