A cache store is the storage backend used by the cache interceptor to persist\nand retrieve cached responses. A store decides which stored response to serve\nfor a request by comparing the request against the response's Vary header, and\nis expected to be compliant with RFC 9111.
undici ships two stores. MemoryCacheStore keeps responses in memory, while\nSqliteCacheStore persists them to a SQLite database. Both are available under\nthe cacheStores export:
import { cacheStores } from 'undici'\n\nconst { MemoryCacheStore, SqliteCacheStore } = cacheStores\nSqliteCacheStore requires the node:sqlite API. The class is always\nexported, but constructing one throws if node:sqlite is not available in the\nrunning Node.js version.
A cache store implements three methods — get(key), createWriteStream(key, value), and delete(key) — that operate on a CacheKey and a\nCacheValue. Any object implementing this contract can be passed\nto the cache interceptor, so custom stores (for example, backed by Redis or a\nremote service) are supported as well.
<EventEmitter>Stores cached responses in memory. The store enforces upper bounds on the total\nnumber of responses, the total size of all responses, and the size of any single\nresponse. When a limit is exceeded, the store evicts approximately half of its\nentries and emits a 'maxSizeExceeded' event.
import { interceptors, cacheStores, Agent, setGlobalDispatcher } from 'undici'\n\nconst store = new cacheStores.MemoryCacheStore({ maxSize: 50 * 1024 * 1024 })\n\nsetGlobalDispatcher(\n new Agent().compose(interceptors.cache({ store }))\n)\nEach of maxCount, maxSize, and maxEntrySize must be a non-negative\ninteger; a TypeError is thrown otherwise.
The current total size, in bytes, of all stored response bodies.
" } ], "methods": [ { "textRaw": "`memoryCacheStore.isFull()`", "name": "isFull", "type": "method", "meta": { "added": [ "v7.0.0" ], "changes": [] }, "signatures": [ { "params": [], "return": { "textRaw": "Returns: {boolean} `true` when the store has reached its `maxSize` or `maxCount` limit, `false` otherwise.", "name": "return", "type": "boolean", "desc": "`true` when the store has reached its `maxSize` or `maxCount` limit, `false` otherwise." } } ] }, { "textRaw": "`memoryCacheStore.get(key)`", "name": "get", "type": "method", "meta": { "added": [ "v7.0.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`key` {CacheKey} The request to look up. See `CacheKey`.", "name": "key", "type": "CacheKey", "desc": "The request to look up. See `CacheKey`." } ], "return": { "textRaw": "Returns: {GetResult|undefined} The matching cached response, or `undefined` when there is no fresh entry for `key`. See `GetResult`.", "name": "return", "type": "GetResult|undefined", "desc": "The matching cached response, or `undefined` when there is no fresh entry for `key`. See `GetResult`." } } ], "desc": "Looks up a cached response for key. A stored entry matches only when its\nmethod equals key.method, its deleteAt time is in the future, and every\nheader listed in its vary map matches the corresponding header in\nkey.headers.
Returns a <Writable> stream used to write the response body into the store. When\nthe stream finishes, the entry is committed; if its accumulated size exceeds maxEntrySize, the stream is destroyed and nothing is stored. Writing a new\nentry whose key matches an existing one replaces that entry.
Removes every cached response stored for key.origin and key.path. Throws a\nTypeError if key is not an object.
Emitted when the store exceeds its maxSize or maxCount limit, immediately\nbefore entries are evicted. The event fires only once per overflow; it is not\nemitted again until the store drops back below both limits.
Stores cached responses in a SQLite database using the node:sqlite API.\nThe constructor throws when node:sqlite is not available.
import { interceptors, cacheStores, Agent, setGlobalDispatcher } from 'undici'\n\nconst store = new cacheStores.SqliteCacheStore({ location: './cache.db' })\n\nsetGlobalDispatcher(\n new Agent().compose(interceptors.cache({ store }))\n)\nmaxCount and maxEntrySize must be non-negative integers; a TypeError is\nthrown otherwise, or if maxEntrySize is greater than 2 GB.
Closes the connection to the underlying SQLite database.
" }, { "textRaw": "`sqliteCacheStore.get(key)`", "name": "get", "type": "method", "meta": { "added": [ "v7.0.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`key` {CacheKey} The request to look up. See `CacheKey`.", "name": "key", "type": "CacheKey", "desc": "The request to look up. See `CacheKey`." } ], "return": { "textRaw": "Returns: {GetResult|undefined} The matching cached response, or `undefined` when there is no fresh entry for `key`. The returned `body` is a {Buffer}. See `GetResult`.", "name": "return", "type": "GetResult|undefined", "desc": "The matching cached response, or `undefined` when there is no fresh entry for `key`. The returned `body` is a {Buffer}. See `GetResult`." } } ], "desc": "Looks up a cached response for key, comparing the request method and every\nheader named in the stored vary map.
Writes a response into the database directly, without going through a stream. If\nthe body exceeds maxEntrySize, nothing is stored. When an entry already exists\nfor key it is overwritten; otherwise a new row is inserted and old entries are\npruned to honour maxCount. This method is used internally by\nsqliteCacheStore.createWriteStream().
Returns a <Writable> stream used to write the response body into the store. When\nthe stream finishes, the buffered body is committed via sqliteCacheStore.set(). If the body exceeds\nmaxEntrySize, the stream is destroyed and nothing is stored.
Removes every cached response stored for the URL derived from key.origin and\nkey.path. Throws a TypeError if key is not an object.
The number of responses currently stored in the database.
" } ] } ], "modules": [ { "textRaw": "Implementing a custom cache store", "name": "implementing_a_custom_cache_store", "type": "module", "desc": "A cache store is any object that implements the CacheStore interface:
get(key) — Look up a response. Returns a GetResult,\nundefined, or a <Promise> resolving to either.createWriteStream(key, value) — Return a <Writable> to receive the response\nbody, 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\nasynchronous resource; the cache interceptor awaits these values, including on\nthe revalidation and stale-while-revalidate paths.
The request a response is being looked up or stored for.
\norigin <string> The request origin.method <string> The request method.path <string> The request path.headers <Record><<string>, <string> | <string>[]> The request headers, used to\nsatisfy Vary. (optional)The metadata of a cached response, excluding its body.
\nstatusCode <number> The response's HTTP status code.statusMessage <string> The response's HTTP status message.headers <Record><<string>, <string> | <string>[]> The response headers.vary <Record><<string>, <string> | <string>[] | <null>> The header names listed in the\nresponse's Vary header mapped to the values they had in the original\nrequest. A value is null when that header was absent from the original\nrequest. (optional)etag <string> The response's entity tag. (optional)cacheControlDirectives <Object> The parsed Cache-Control directives of the\nresponse. (optional)cachedAt <number> The time, in milliseconds, at which the response was\ncached.staleAt <number> The time, in milliseconds, at which the response becomes\nstale.deleteAt <number> The time, in milliseconds, at which the response must be\nevicted. A store must not return a response once this time has passed.The vary map drives response selection. For a response such as:
Vary: content-encoding, accept\ncontent-encoding: utf8\naccept: application/json\nthe recorded map is:
\n{\n 'content-encoding': 'utf8',\n accept: 'application/json'\n}\nIf the original request did not include the accept header, its value is\nrecorded as null:
{\n 'content-encoding': 'utf8',\n accept: null\n}\nThe value returned by get. It contains every field of\nCacheValue plus the response body.
body <Readable> | <Iterable> | <AsyncIterable> | <Buffer> | <string> The cached response\nbody. (optional)