L10 - Cache
Cache read results without moving query execution or persistence into the cache layer
Location: src/cache/
Why This Layer Exists
Repeated reads should not always reach the database. L10 provides cache keys, TTL handling, stale-while-revalidate behavior, invalidation, and backend abstractions while keeping database queries in the query engine and drivers.
The official cache() extension exposes $withCache() and $invalidate() on
its derived client only: they are its client methods, typed as any
extension’s are (CacheMethods, through this). Cache backends implement storage; they do not know how
VibORM builds or executes SQL.
Boundary
| Cache owns | Cache does not own |
|---|---|
Private extension namespaces around the prepared call’s key (key(run)) |
Query construction |
| TTL and stale-while-revalidate policy | Database execution |
| Storing a read’s driver rows as portable JSON data | Decoding them: a hit goes through the driver’s result parser and the engine’s decoder |
| Explicit and mutation-triggered invalidation | Result parsing |
See Caching for configuration and backend documentation.
Connection to Other Layers
- L9 (Client): Applies the cache extension, whose methods create cached views
- L11 (Instrumentation): Presents the
cacheunits the cache emits (hits, misses, writes, refreshes) from their notes - L6-L8 (Execution): Run only when the cache path requires a database read
Read caching deliberately bypasses callback and array transactions, raw calls,
and chains that rewrite statements. Mutation invalidation runs through
settled, so savepoint rollback discards it and outer commit publishes it
once. The official factory stays in src/cache/extension.ts: an ordinary
extension of args (the mutation option cache, and a bound argument
$withCache() binds), a call on target(writes) whose settled
invalidates, an around on target(reads) with { inner: true } reading
key(run), codec(run) and database(run), and methods. A read is keyed
by the statement it would send, inside a namespace of the private storage
revision, the database and the extension’s version; a custom read key is a
suffix of that key, never a replacement. An entry holds the rows the driver
returned for that statement, and a hit hands them to the engine’s decoder as
a driver’s answer, so the cache keeps no second codec of the result’s
shape. The cache imports only names a public entry exports
(tests/contracts/public-client/extension-imports.core.test.ts holds it to
that), and presents its own cache units through notes the instrumentation
reads, never through a name the instrumentation knows.