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

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 cache units 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.

Was this page helpful?