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 |