---
title: Caching
description: Official query-cache extension with invalidation and stale-while-revalidate
icon: database
---

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

## Setup

```ts
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](/docs/extensions/create#store-answers-key-codec-database)):
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:

```ts
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:

```ts
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:

```ts
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

```ts
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()`](/docs/extensions/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](#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:

```ts
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](/docs/extensions/cache/drivers/memory) | Development and single-instance deployments | No |
| [CloudflareKVCache](/docs/extensions/cache/drivers/cloudflare-kv) | Cloudflare Workers | Yes |
| [Custom driver](/docs/extensions/cache/drivers/custom) | Redis, Upstash, or another backend | Varies |
