undici-cache-store-better-sqlite3

A undici cache store powered by better-sqlite3 instead of node:sqlite.

Installation

# npm
npm install undici-cache-store-better-sqlite3
# yarn
yarn add undici-cache-store-better-sqlite3
# pnpm
pnpm add undici-cache-store-better-sqlite3

Usage

import { BetterSqlite3CacheStore } from 'undici-cache-store-better-sqlite3';
import undici, {
  interceptors,
  Agent,
  setGlobalDispatcher
} from 'undici';

const agent = new Agent({});

setGlobalDispatcher(agent.compose(
  interceptors.cache({
    store: new BetterSqlite3CacheStore({
      /**
       * Location of the database
       * @default ':memory:'
       */
      location: ':memory:';
      /**
       * @default Infinity
       */
      maxCount: Infinity;
      /**
       * @default Infinity
       */
      maxEntrySize: Infinity;
      /**
       * Keep stale, validated entries available for HTTP revalidation.
       * @default 0
       */
      revalidationRetention: 7 * 24 * 60 * 60 * 1000;
    })
  })
));

Retaining entries for revalidation

Set revalidationRetention to keep stale entries with an ETag or Last-Modified validator in the store long enough for undici to make a conditional request:

const store = new BetterSqlite3CacheStore({
  revalidationRetention: 7 * 24 * 60 * 60 * 1000
});

At write time, the store applies deleteAt = max(deleteAt, staleAt + revalidationRetention). It does not change staleAt, so stale responses are still revalidated before they are served.

Undici 8.7.0 does not rewrite a cache entry after its cache interceptor handles a successful 304 Not Modified, so the retention period remains anchored to the most recent cacheable 200 response. A later cacheable response that replaces the stored representation starts a new retention period.

This option works around undici 8's short default retention for responses such as Cache-Control: max-age=0, must-revalidate. In undici 8.7.0, verified on 2026-07-13, entries without explicit stale-serving directives are deleted after roughly one additional freshness lifetime. Once deleted, their validators can no longer be used and the next request downloads the full response. Undici's cacheByDefault value is measured in milliseconds, despite older JSDoc that described it as seconds.

revalidationRetention defaults to 0, preserving undici's native behavior. It must be a non-negative finite number unless loose mode is enabled. Retained entries still count toward maxCount; size maxCount above the expected number of distinct cached URLs, or eviction can reduce revalidation effectiveness.

License

MIT

undici-cache-store-better-sqlite3 © Sukka, Released under the MIT License. Authored and maintained by Sukka with help from contributors (list).

Personal Website · Blog · GitHub @SukkaW · Telegram Channel @SukkaChannel · Mastodon @[email protected] · Twitter @isukkaw · Keybase @sukka