Skip to content
VibORM
Esc
↑↓navigate↵open⌘Jpreview
On this page

Caching

Official query-cache extension with invalidation and stale-while-revalidate

Caching is an official client extension. A base client has no $withCache() or $invalidate() method; the derived client created by cache() has both.

Setup

import { createClient } from "viborm";
import { cache } from "viborm/cache";
import { MemoryCache } from "viborm/cache/memory";

const client = createClient({ schema, driver }).$extends(
  cache({ driver: new MemoryCache(), version: "2026-08" })
);

cache(config) reads its configuration once, when it is called, and refuses a missing CacheDriver, a version that is neither a string nor a finite number, and a waitUntil that is no function, with a CacheConfigurationError. version and waitUntil belong to that exact extension, not to the shared cache driver. Two clients can share one CacheDriver while using different namespaces and background schedulers.

The extension is written with the public parts (Create an extension): an args part (the mutation option cache, and a bound argument that $withCache() binds), a call on target(writes) whose settled invalidates, an around on target(reads) with { inner: true } that reads key(run), codec(run) and database(run), and methods for $withCache() and $invalidate().

Cached reads

$withCache() returns a read-only view:

const users = await client
  .$withCache({ ttl: "5 minutes" })
  .user.findMany({ where: { active: true } });

const fresh = await client
  .$withCache({ ttl: 30_000, bypass: true })
  .post.findMany();
Option Type Default Meaning
ttl string | number 5 minutes Freshness duration
swr boolean | string | number false Stale-while-revalidate window; needs cache({ swr: staleWhileRevalidate })
key string absent Suffix contributed to the canonical key
bypass boolean false Skip lookup, execute core, then store

A read is keyed by the statement it would send: its model, its operation, its validated arguments, and the prepared statement’s text and parameters (key(run)), inside a namespace made of the cache’s private storage revision, the database (dialect and SQL namespace, so one store can serve several databases) and the extension’s version. A rule that changes the statement (a tenant, soft delete’s deleted, a permission) changes the key; an argument that changes no statement does not, unless it is declared .volatile(), in which case the read is not cached. A custom key is only a suffix contribution. It does not replace the canonical identity, so two different queries using the same suffix do not collide.

Official invalidation accepts relative keys and prefixes such as user:*. Strings beginning with viborm: are refused before backend effects; only the cache’s own module can address its private namespace. Cache-key construction is private; no public helper can address the official namespace.

Detached values

The cache sits closest to the core (around with { inner: true }), so it stores what the driver returned before any other extension’s second moment can change the answer. An entry holds the driver’s rows for the read’s one statement, as JSON data, not a copy of the parsed result. A value JSON cannot carry (a bigint, a Date, bytes, a non-finite number, -0) is written as a tagged array, and every array is tagged, so no document a JSON column holds can be mistaken for one.

Every hit hands the stored rows to the same decoding a driver’s answer goes through: the driver’s result parser, then the engine’s result decoder. A hit is therefore a fresh complete graph, with no mutable reference shared between calls, and every value is decided again as on a miss: relations, JSON, decimals, bigints, dates, bytes, aggregates, counts and grouped results take their documented public values. Decimals are rebuilt as a fresh Decimal on every hit (compare them with .eq(), not by identity), and GeoPoint values as a fresh { longitude, latitude }; a selected _distance remains a number (or null for a nullable point).

A driver result parser of your own (a custom driver’s result) is called on hits too. It sees the restored values, which are the driver’s values after a round trip through JSON: a Uint8Array where the driver gave a Buffer, a plain object or array where it gave one.

A row value the cache cannot store (a class instance a driver did not turn into plain data) does not fail the read: the read answers uncached, and the operation records a cache-set-failed outcome. Entries are written under a private storage revision (r6); an entry written by an earlier VibORM version is never read. A stored entry that is malformed, or that the decoder refuses as it would refuse a driver’s value, fails the read with a CacheConfigurationError whose meta.method is "materialize"; it exposes no stored value.

Two checks are looser than when the cache stored the parsed result: a column the read does not decode is ignored, as it is in a driver’s answer, and an object read through getters or a proxy (from an in-memory backend that hands back live objects) is read as the plain data it shows, not refused.

Stale-while-revalidate

Stale-while-revalidate is a value the cache is configured with, so an application that never serves stale entries carries none of its code:

import { cache, staleWhileRevalidate } from "viborm/cache";

const client = createClient({ schema, driver }).$extends(
  cache({ driver: new MemoryCache(), swr: staleWhileRevalidate })
);
const cached = client.$withCache({ ttl: "5 minutes", swr: "1 hour" });

A view’s swr option on a cache configured without it is refused with a CacheConfigurationError when the view is made.

  • A fresh hit returns immediately.
  • A stale hit returns a fresh decoding of the old entry and schedules one background promise covering claim, inner core replay, storing its rows, set, and marker cleanup.
  • A miss runs the inner prepared/core read and stores the driver’s rows.

Background replay runs the core alone: it does not rerun any extension’s first or second moment, or another logical application operation. The stale application result remains authoritative if replay, storing, or cleanup fails. The built-in marker is best-effort; it is not an atomic distributed lock and does not promise a single winner across concurrent workers.

For serverless runtimes, give the scheduler to this cache extension:

const client = createClient({ schema, driver }).$extends(
  cache({
    driver: new CloudflareKVCache(env.CACHE),
    waitUntil: ctx.waitUntil.bind(ctx),
  })
);

The stale call hands the complete background promise to waitUntil synchronously, before asynchronous marker I/O. A throwing scheduler is contained and cannot replace the read result.

Invalidation

await client.$invalidate("user:*", "post:findMany:*");

await client.user.update({
  where: { id: "123" },
  data: { name: "Alice" },
  cache: {
    autoInvalidate: true,
    invalidate: ["post:findMany:*"],
  },
});

A mutation’s cache option is the cache extension’s own declared argument (args). VibORM takes it out of the arguments and checks it before any first moment runs, so other extensions never see it and no c.set can add or replace it. A malformed value is refused before the write runs. Invalidation runs when the write is durable (settled): a rollback or savepoint rollback publishes none, and a write that may have committed (a statement that failed after it was sent) invalidates too. A backend failure during that invalidation rejects the write’s promise as a CacheConfigurationError (the write is not undone). settled functions run in chain order and the first failure rejects the write’s promise, so apply cache() before on() for a write to invalidate before its hooks run.

$invalidate() runs at once outside a transaction. On an interactive transaction’s client (tx.$invalidate()) it runs after the outermost commit. tx.$withCache() exists too; its reads, like every read in a transaction, bypass the cache (below). A key it refuses is refused as it is; a backend that fails is a CacheConfigurationError.

autoInvalidate clears the bound extension’s entire cache scope, including reads whose nested relations depend on the mutation. Manual invalidation uses exact canonical relative keys or a trailing * for a prefix; it is not a glob or tag system. Custom read keys are suffixes of the canonical query identity, so a custom key such as dashboard does not create a dashboard:* prefix. Use the model/operation prefix above, or * for the entire scope. Manual invalidation validates every target before starting backend work, so an invalid mixed list has no partial effects.

Deliberate bypasses

Official read caching is bypassed for callback and nested callback transactions, $transaction([...]) on both substrates, any chain with a statement rewrite (a unit declared { rewrites: true }), safe and unsafe raw operations, and a read that carries a .volatile() argument (it runs without being served or stored, and without an error).

Every other extension’s around stays outside the cache, on hits and misses alike, whatever the order of the chain: each sees every call. Bypass preserves their behavior and the existing transaction, statement, raw, and result-ownership contracts.

Writes the cache does not see

A model write through the cached client invalidates its scope unless it passes autoInvalidate: false (see Invalidation). A write through the base client you extended, through raw SQL ($executeRaw or $queryRaw, also on the cached client), or outside VibORM invalidates nothing: cached reads keep returning the old rows until their ttl runs out. After such a write, invalidate yourself:

await base.post.update({ where: { id }, data: { title } });
await client.$executeRaw(sql`UPDATE post SET title = ${title} WHERE id = ${id}`);

// What a model write does: clear the whole scope
await client.$invalidate("*");
// Or only the reads that can contain posts
await client.$invalidate("post:*", "user:*");

A key prefix names the model a cached read starts from. A narrower list must also name every model whose reads reach the changed rows through include or select, such as user:* for users read with their posts.

Observability

The cache presents its get, set, invalidate, and revalidate work as cache units, seen by every unit part that listens to them. With the official instrumentation() extension, logs and spans report hit, miss, stale, bypass, duration, model, operation, and correlation where applicable. Cache keys and custom suffixes are never disclosed. Instrumentation contains its own failures, so they do not alter cache, application, or commit behavior; a unit part of your own that throws fails the call.

Drivers

Driver Best for Persistence
MemoryCache Development and single-instance deployments No
CloudflareKVCache Cloudflare Workers Yes
Custom driver Redis, Upstash, or another backend Varies

Was this page helpful?