cache

Package Contents

This package provides a class, Cache, that implements caching using a model inspired by HTTP's. The HTTP model is already incredibly powerful, and this class generalizes and extends it further in some ways.

Even though this package borrows ideas from HTTP, it can be used to cache any kind of data from any source, not just HTTP responses. Its implementation assumes no HTTP particulars (like specific header formats).

Still, you must understand a number of concepts from HTTP's caching model in order to use this package effectively. Those are explained in "Caching Model". Please read that, or many of the names and APIs in this package won't make sense.

Backing stores

The Cache class can only function with a "backing store" that actually holds the cache's entries. There is a common Store interface (see the types file) that all stores must implement. We currently have two backing stores, one that holds items in memory and one that stores items in Postgres.

Note that not all backing stores will be able to store all kinds of data, although it's recommended that general-purpose stores be able to store any data that's JSON-serializable. Store implementations can communicate the type of data they support by adding a constraint on their first type parameter, e.g., a store with the signature class MyStore<Spec extends CacheSpec<string, string[]>, ...> is indicating that it can only store string arrays. Trying to use a store with a Cache instance parameterized for entries of different types will yield a type error.

Per-id content typing (heterogeneous caches)

The Cache class is parameterized by a CacheSpec, which pairs each id type with the corresponding content type. In the simple case, all ids return the same kind of content, and Spec can stay as the default. To support multiple id-to-content mappings within a single cache, pass a union of CacheSpecs; the cache's get/store/getMany methods then narrow the content type based on each request's id, and reject mismatched (id, content) pairs at compile time.

For example, a cache that holds both individual stories and collections of stories:

type StoriesCacheSpec =
  | CacheSpec<`story:${string}`, Story>
  | CacheSpec<`collection:${string}`, Story[]>;

const cache = new Cache<StoriesCacheSpec>(new MemoryStore());

// Per-id content narrowing on read:
const storyRes = await cache.get({ id: "story:1", params: {}, directives: {} });
//    storyRes.usable?.content has type `Story | undefined`
const collRes = await cache.get({ id: "collection:top", params: {}, directives: {} });
//    collRes.usable?.content has type `Story[] | undefined`

// The (id, content) pair is also enforced on write:
await cache.store([
  { id: "story:1", content: aStory, directives: { freshUntilAge: 60 } },           // ok
  { id: "collection:top", content: [story1, story2], directives: { freshUntilAge: 60 } }, // ok
  // @ts-expect-error -- can't store a Story[] under a story:* id
  { id: "story:bad", content: [story1], directives: { freshUntilAge: 60 } },
]);

This is particularly useful when a producer that fetches a collection wants to additionally cache each individual entry (via supplementalResources), so that point lookups for each entry by id can also be served by the same cache.

Single-id-type vs. multi-id-type producers

RequestPairedProducer automatically takes one of two shapes depending on whether your Spec is a single CacheSpec or a union:

• Single-id-type mode (one CacheSpec variant — the most common case): the producer is a plain non-generic function (req) => Promise<RequestPairedProducerResult<...>>. There's only one possible content type, so per-id correlation is trivial.
• Multi-id-type mode (a union of CacheSpecs): the producer is generic over the request's specific id, so its return must match the spec variant that id selects. TypeScript can't narrow a free type parameter via runtime checks on req.id, so the recommended way to write a multi-id-type producer is via producerByIdType:

const fetcher = wrapProducer<StoriesCacheSpec>(
  cache,
  options,
  producerByIdType<StoriesCacheSpec>()
    .when(idStartsWith("story:"), async (req) => ({
      // req.id: `story:${string}`  ⇒  TS requires `content: Story`
      content: { id: req.id, title: `Story ${req.id}` },
      directives: { freshUntilAge: 60 },
    }))
    .when(idStartsWith("collection:"), async (req) => ({
      // req.id: `collection:${string}`  ⇒  TS requires `content: Story[]`
      content: [{ id: "1", title: "a" }, { id: "2", title: "b" }],
      directives: { freshUntilAge: 60 },
    }))
    .build(),
);

Each .when(...) call infers its own narrowed id type from the supplied type guard, so each handler's req.id is concrete and the (id, content) correlation is fully checked per-branch.

Key Files

• Cache.ts: this defines the basic cache class. Note that the class's job is just to return whether/which previously-stored responses are usable to satisfy an incoming request. It does not handle things like making requests to the producer for new responses when no cached response is usable.

• MemoryStore.ts: a store for retaining cached data in memory, with a TTL and optional LRU eviction to cap memory usage.

• PostgresStore.ts: a store for retaining cached data in Postgres.

• wrapProducer.ts: this is the package's most important export, arguably. It takes a producer (i.e., a function that returns some data to cache) and a Cache instance, and it returns an equivalent function that will used a cached value when a suitable one is available, but otherwise call through to the underlying producer and store its return value for future requests.