Cache Store

A cache store is the storage backend used by the cache interceptor to persist and retrieve cached responses. A store decides which stored response to serve for a request by comparing the request against the response's Vary header, and is expected to be compliant with RFC 9111.

undici ships two stores. MemoryCacheStore keeps responses in memory, while SqliteCacheStore persists them to a SQLite database. Both are available under the cacheStores export:

import { cacheStores } from 'undici'

const { MemoryCacheStore, SqliteCacheStore } = cacheStores

SqliteCacheStore requires the node:sqlite API. The class is always exported, but constructing one throws if node:sqlite is not available in the running Node.js version.

A cache store implements three methods — get(key), createWriteStream(key, value), and delete(key) — that operate on a CacheKey and a CacheValue. Any object implementing this contract can be passed to the cache interceptor, so custom stores (for example, backed by Redis or a remote service) are supported as well.

class MemoryCacheStore extends EventEmitter

Stores cached responses in memory. The store enforces upper bounds on the total number of responses, the total size of all responses, and the size of any single response. When a limit is exceeded, the store evicts approximately half of its entries and emits a 'maxSizeExceeded' event.

import { interceptors, cacheStores, Agent, setGlobalDispatcher } from 'undici'

const store = new cacheStores.MemoryCacheStore({ maxSize: 50 * 1024 * 1024 })

setGlobalDispatcher(
  new Agent().compose(interceptors.cache({ store }))
)

new MemoryCacheStore(options?): void

Each of maxCount, maxSize, and maxEntrySize must be a non-negative integer; a TypeError is thrown otherwise.

The current total size, in bytes, of all stored response bodies.

memoryCacheStore.isFull(): boolean

memoryCacheStore.get(key): GetResult | undefined

Looks up a cached response for key. A stored entry matches only when its method equals key.method, its deleteAt time is in the future, and every header listed in its vary map matches the corresponding header in key.headers.

memoryCacheStore.createWriteStream(key, value): Writable | undefined

Returns a <Writable> stream used to write the response body into the store. When the stream finishes, the entry is committed; if its accumulated size exceeds maxEntrySize, the stream is destroyed and nothing is stored. Writing a new entry whose key matches an existing one replaces that entry.

memoryCacheStore.delete(key): undefined

Removes every cached response stored for key.origin and key.path. Throws a TypeError if key is not an object.

Emitted when the store exceeds its maxSize or maxCount limit, immediately before entries are evicted. The event fires only once per overflow; it is not emitted again until the store drops back below both limits.

Stores cached responses in a SQLite database using the node:sqlite API. The constructor throws when node:sqlite is not available.

import { interceptors, cacheStores, Agent, setGlobalDispatcher } from 'undici'

const store = new cacheStores.SqliteCacheStore({ location: './cache.db' })

setGlobalDispatcher(
  new Agent().compose(interceptors.cache({ store }))
)

new SqliteCacheStore(options?): void

maxCount and maxEntrySize must be non-negative integers; a TypeError is thrown otherwise, or if maxEntrySize is greater than 2 GB.

sqliteCacheStore.close(): undefined

Closes the connection to the underlying SQLite database.

The number of responses currently stored in the database.

sqliteCacheStore.get(key): GetResult | undefined

Looks up a cached response for key, comparing the request method and every header named in the stored vary map.

sqliteCacheStore.set(key, value): undefined

Writes a response into the database directly, without going through a stream. If the body exceeds maxEntrySize, nothing is stored. When an entry already exists for key it is overwritten; otherwise a new row is inserted and old entries are pruned to honour maxCount. This method is used internally by sqliteCacheStore.createWriteStream().

sqliteCacheStore.createWriteStream(key, value): Writable | undefined

Returns a <Writable> stream used to write the response body into the store. When the stream finishes, the buffered body is committed via sqliteCacheStore.set(). If the body exceeds maxEntrySize, the stream is destroyed and nothing is stored.

sqliteCacheStore.delete(key): undefined

Removes every cached response stored for the URL derived from key.origin and key.path. Throws a TypeError if key is not an object.

A cache store is any object that implements the CacheStore interface:

• get(key) — Look up a response. Returns a GetResult, undefined, or a <Promise> resolving to either.
• createWriteStream(key, value) — Return a <Writable> to receive the response body, or undefined if the response cannot be stored.
• delete(key) — Remove all responses for key. May return a <Promise>.

Returning a <Promise> from get or delete lets a store be backed by an asynchronous resource; the cache interceptor awaits these values, including on the revalidation and stale-while-revalidate paths.

The request a response is being looked up or stored for.

The metadata of a cached response, excluding its body.

The vary map drives response selection. For a response such as:

Vary: content-encoding, accept
content-encoding: utf8
accept: application/json

the recorded map is:

{
  'content-encoding': 'utf8',
  accept: 'application/json'
}

If the original request did not include the accept header, its value is recorded as null:

{
  'content-encoding': 'utf8',
  accept: null
}

The value returned by get. It contains every field of CacheValue plus the response body.