Class HTTPCache

RFC 7234-compliant HTTP cache with LRU eviction, Vary support, stale-while-revalidate, stale-if-error, tag-based invalidation, and pluggable storage backends.

Example

const cache = new HTTPCache({ maxEntries: 200, defaultTtlMs: 30_000 });
await cache.set(req, res);
const result = await cache.get(req);

Index

Constructors

constructor

Methods

get set buildConditionalHeaders revalidate markSWRInFlight clearSWRInFlight isSWRInFlight delete invalidateByURL invalidateByTag clear warm getStats resetStats serialize deserialize

Constructors

constructor

new HTTPCache(config?: CacheConfig): HTTPCache
Parameters
- config: CacheConfig = {}
  Cache configuration
Returns HTTPCache
- Defined in src/cache.ts:809

Methods

get

get(
req: CacheableRequest,
): Promise<{ entry: CacheEntry; stale: boolean } | null>
Look up a cached response.
Parameters
- req: CacheableRequest
Returns Promise<{ entry: CacheEntry; stale: boolean } | null>
An object with entry (the cached CacheEntry) and stale (boolean indicating the entry is expired but within the stale-while-revalidate or stale-if-error window), or null if no matching entry was found.
- Defined in src/cache.ts:846

set

set(
    req: CacheableRequest,
    res: CacheableResponse,
    options?: { tags?: string[]; ttlMs?: number; force?: boolean },
): Promise<boolean>
Store a response in the cache.
Parameters
- req: CacheableRequest
  The request used as the cache key
- res: CacheableResponse
  The response to cache
- options: { tags?: string[]; ttlMs?: number; force?: boolean } = {}
  Optional tags, per-entry TTL override, or force flag to bypass no-store
Returns Promise<boolean>
true if the entry was stored, false if rejected (uncacheable, too large, or quota exceeded)
- Defined in src/cache.ts:928

buildConditionalHeaders

buildConditionalHeaders(entry: CacheEntry): Record<string, string>
Build conditional request headers (If-None-Match / If-Modified-Since) for cache revalidation.
Parameters
- entry: CacheEntry
Returns Record<string, string>
- Defined in src/cache.ts:1005

revalidate

revalidate(
req: CacheableRequest,
res: CacheableResponse,
): Promise<CacheEntry | null>
Handle a 304 Not Modified response — refresh the entry TTL in place.
Parameters
- req: CacheableRequest
- res: CacheableResponse
Returns Promise<CacheEntry | null>
- Defined in src/cache.ts:1015

markSWRInFlight

markSWRInFlight(req: CacheableRequest): Promise<boolean>
Mark a request as being revalidated for stale-while-revalidate. Returns false if the key is already in flight.
Parameters
- req: CacheableRequest
Returns Promise<boolean>
- Defined in src/cache.ts:1062

clearSWRInFlight

clearSWRInFlight(req: CacheableRequest): Promise<void>
Clear the SWR in-flight flag for a request.
Parameters
- req: CacheableRequest
Returns Promise<void>
- Defined in src/cache.ts:1070

isSWRInFlight

isSWRInFlight(req: CacheableRequest): Promise<boolean>
Check whether a request is currently being revalidated.
Parameters
- req: CacheableRequest
Returns Promise<boolean>
- Defined in src/cache.ts:1076

delete

delete(req: CacheableRequest): Promise<boolean>
Delete a single entry from the cache.
Parameters
- req: CacheableRequest
Returns Promise<boolean>
true if the entry existed and was deleted
- Defined in src/cache.ts:1087

invalidateByURL

invalidateByURL(urlPrefix: string): Promise<number>
Delete all entries whose URLs start with a given prefix. Works with namespaces.
Parameters
- urlPrefix: string
Returns Promise<number>
- Defined in src/cache.ts:1096

invalidateByTag

invalidateByTag(tag: string): Promise<number>
Delete all entries with a specific tag.
Parameters
- tag: string
Returns Promise<number>
- Defined in src/cache.ts:1135

clear

clear(): Promise<void>
Clear all cached entries.

Returns Promise<void>
- Defined in src/cache.ts:1150

warm

warm(
    entries: {
        req: CacheableRequest;
        res: CacheableResponse;
        tags?: string[];
    }[],
): Promise<void>
Pre-populate the cache with a set of request/response pairs.
Parameters
- entries: { req: CacheableRequest; res: CacheableResponse; tags?: string[] }[]
Returns Promise<void>
- Defined in src/cache.ts:1164

getStats

getStats(): Readonly<CacheStats>
Get a snapshot of current cache statistics.

Returns Readonly<CacheStats>
- Defined in src/cache.ts:1175

resetStats

resetStats(): void
Reset all cache statistics to zero.

Returns void
- Defined in src/cache.ts:1180

serialize

serialize(): Promise<string>
Serialize cache entries to a JSON string for persistence. Expired entries are excluded. Format: { version: 1, entries: [[key, entry], ...] }.

Returns Promise<string>
- Defined in src/cache.ts:1199

deserialize

deserialize(data: string): Promise<void>
Restore cache entries from a previously serialized JSON string. Validates structure, enforces max age and body size limits, skips expired entries.
Parameters
- data: string
Returns Promise<void>
Throws
If the JSON format is invalid or unexpected.
- Defined in src/cache.ts:1220

Class HTTPCache

Example

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns HTTPCache

Methods

get

Parameters

Returns Promise<{ entry: CacheEntry; stale: boolean } | null>

set

Parameters

Returns Promise<boolean>

buildConditionalHeaders

Parameters

Returns Record<string, string>

revalidate

Parameters

Returns Promise<CacheEntry | null>

markSWRInFlight

Parameters

Returns Promise<boolean>

clearSWRInFlight

Parameters

Returns Promise<void>

isSWRInFlight

Parameters

Returns Promise<boolean>

delete

Parameters

Returns Promise<boolean>

invalidateByURL

Parameters

Returns Promise<number>

invalidateByTag

Parameters

Returns Promise<number>

clear

Returns Promise<void>

warm

Parameters

Returns Promise<void>

getStats

Returns Readonly<CacheStats>

resetStats

Returns void

serialize

Returns Promise<string>

deserialize

Parameters

Returns Promise<void>

Throws

Settings

On This Page