Data cache policies
Configure native data caching, identify eligible reads, choose sharing boundaries, and define freshness or fallback behavior.
Prefer a policy on each request: different reads may need different lifetimes, private partitions, or no caching. Share the cache instance across reads without giving every read the same strategy.
Configure a data cache
#For a browser or one-process service, create a stable bounded memory cache outside rendering:
import { createDataCache } from "brix/cache";
export const dataCache = createDataCache();
Creating the cache does not enable caching for any request. Pass a policy to the read, as shown below.
Each createDataCache() call gets an isolated process-local LRU store, limited to 1,000 entries by
default. Pass store: createMemoryDataCacheStore({ maxEntries, maxBytes }) to change that bound or to
cap retained memory. maxBytes (unbounded by default) estimates values and tags at two bytes per
string code unit and evicts the least recently used entries first. An entry larger than maxBytes
is not stored, and the request still returns the origin result. Both bounds must be positive integers.
brix/cache itself is runtime-neutral: background jobs and standalone services can call
createDataCache({ namespace, store }) directly without a Hono context or a Brix application.
Browser code must create its own instance; never import a server's configured cache into the browser.
Caching also works on plain-HTTP origins such as http://192.168.1.5:5173, where browsers withhold
crypto.subtle: Brix then derives the same cache identities with a bundled SHA-256.
Configure server ownership
#Configure the cache once on the server when routes and server integrations need the same instance:
"use server";
import { createMemoryDataCacheStore } from "brix/cache";
import { defineBrixServer } from "brix/server";
import { brix } from "./brix.ts";
import { env } from "./env.server.ts";
export const brixServer = defineBrixServer(brix, {
env,
dataCache: {
namespace: "storefront-production",
store: createMemoryDataCacheStore(),
},
});
export const { dataCache } = brixServer;
Import dataCache from #brix/server in server modules. Use a stable application-and-environment
namespace of 1–128 characters; do not generate it at startup or change it on every deployment.
Replicas share data only when they use that namespace and a shared store. The namespace defaults to
default.
When the store depends on request bindings, pass a function instead. brixServer.dataCache(c) then
returns one cache memoized for that request. c.env holds the validated environment; native platform
bindings, such as a Cloudflare KV namespace, come from getPlatformBindings(c) in brix/server
(see native Cloudflare bindings):
export const brixServer = defineBrixServer(brix, {
env,
dataCache: (c) => ({
namespace: c.env.STAGE,
store: createStoreFromBindings(getPlatformBindings(c)),
}),
});
Here createStoreFromBindings is an application function returning a DataCacheStore; see
cache stores for the bundled adapters.
Cache eligible reads
#Pass cache explicitly to executeApi. Here getProductApiContract is your existing JSON GET
contract; it defines the product path, productId parameter, and response schema.
import { executeApi } from "#brix";
import { dataCache } from "./data-cache.ts";
import { getProductApiContract } from "./features/products/api/get-product/contract.ts";
const product = await executeApi(getProductApiContract, {
baseUrl: "https://catalog.example.com",
params: { productId: "123" },
cache: dataCache.public("30s"),
}).unwrap();
The first call fetches and stores a cacheable response. An identical call using the same cache
reuses that response while it is fresh, for up to 30 seconds. Without cache, executeApi does not
use this data cache. The same cache option works on client.execute and useApi. Contentful
Delivery clients take a client-level cache instead; see
Contentful clients.
Optional: set a default for a client
#Use a client-level default only when its eligible reads should all share a policy. Otherwise, keep
cache on each request as above. For a client dedicated to short-lived public catalogue reads:
import { createApiClient } from "brix/contracts";
import { dataCache } from "./data-cache.ts";
import { getProductApiContract } from "./features/products/api/get-product/contract.ts";
const catalogClient = createApiClient({
baseUrl: "https://catalog.example.com",
cache: dataCache.public("30s"),
});
const product = await catalogClient
.execute(getProductApiContract, { params: { productId: "123" } })
.unwrap();
This .execute() call inherits the client's cache policy. A call-level cache overrides that
default; pass cache: false to bypass it for one request. Keep the configured client outside rendering.
Know which responses can be reused
#Only JSON GET responses with validation enabled participate. Mutations, text and streams, and cache: false bypass reuse. A schema-backed JSON call cannot disable validation; validateResponse: false is a request-encoding error. Schema-less calls may disable validation and then bypass reuse. HTTP failures, malformed JSON, and schema-invalid values are never stored.
Cache-first calls share fresh results and pending loads. Identity includes the complete URL, normalized explicit headers, effective Fetch credentials, redirect policy, scope, policy, version, and tags. Omitted credentials and explicit same-origin share identity; include and omit remain distinct. Brix stores JSON wire data, then validates it for each caller before returning parsed output.
Visible Cache-Control: no-store, no-cache, or private, Set-Cookie, and Vary: * veto storage. Browsers may hide Set-Cookie, and cross-origin Vary is visible only with Access-Control-Expose-Headers: Vary, so sensitive browser endpoints must send JavaScript-visible Cache-Control: private or no-store.
Choose public or private scope
#const shared = dataCache.public("5m");
const account = dataCache.private(session.cacheScope, "1m");
Public scope explicitly permits sharing between callers. Private scope requires a partition of 1–512 characters: a nonsecret user, tenant, or session scope, never an access token or cookie value. Partitioning is not authorization: authorize normally before the call, and do not cache sessions, permissions, carts, booking drafts, or revocation-sensitive decisions.
Rotate the scope, or invalidate, when identity or permissions change. Returning to an earlier scope
can reuse its still-fresh data. On logout, reset or unmount user UI, then await
dataCache.invalidateAll() before reuse. Browser-managed cookies are invisible to Brix's identity
calculation; never rely on a cookie alone to partition private data.
Freshness and fallback
#Duration shorthand is cache-first. Stale fallback is explicit:
dataCache.public("10m");
dataCache.public({ ttl: "1h", staleIfError: "1d" });
staleIfError may serve expired data after retries only for network or timeout failures and HTTP 429, 500, 502, 503, or 504. It never hides authorization, not-found, cancellation, decoding, or validation failures.
ttl is the fresh lifetime; staleIfError adds a stale retention window after that lifetime. In the
example above, data is fresh for one hour and eligible for fallback for one further day. Serving
stale data does not renew its age. This is not background refresh: the caller waits for the origin
attempt and retries before fallback is considered.
The caller's own timeout or AbortSignal.timeout ends that call without fallback. Only an
independent transport timeout occurring before the caller's deadline can qualify as a transient
origin failure. Leave enough request budget for the cache lookup, origin attempts, and retry delays.
Use network-first fallback when every call must try the origin:
dataCache.public({ fallbackFor: "1h" });
This mode does not deduplicate origin calls. It serves the last successful cacheable response only after an eligible failure. fallbackFor cannot be mixed with ttl or staleIfError.
Both fallback modes return ordinary successful Results containing the cached data. useApi reports
success, not an error or a stale flag, when fallback succeeds. The coordinator's onEvent emits
stale, but it does not identify an individual hook or include the failed origin response. Timing
summaries likewise measure attempts, not freshness. If showing a degraded state is required, do not
infer freshness from success or request duration; omit fallback for that read unless the application
already has an explicit freshness contract.
Store reads happen before origin work, so a stalled store adds up to the operation deadline to each
read. Read/write errors fail open to the origin, and a successful origin response may still be
written after a failed read. Explicit invalidation fails loud. Store operations default to a
one-second deadline; change it with createDataCache({ operationTimeoutMs }) after measuring your
provider. Request timeout and cancellation remain caller-specific.
Remote-store timing is request-local. On cache-first shared flights, each caller times its own lookup; the caller that starts the shared origin load owns the eventual remote write timing, while callers that join that flight do not duplicate it. The origin request retains its separate dependency timing.
Policy options and limits
#A policy is a duration shorthand, { ttl, staleIfError? }, or { fallbackFor }, plus optional
tags and version. Empty policies and mixed modes are rejected in types and at creation.
- Durations are milliseconds as a number, or strings with an
ms,s,m,h, ordunit, such as"500ms","30s", or"1.5h". Each must resolve to whole milliseconds.ttlandfallbackFormust be positive; usecache: falserather than a zero TTL to bypass caching. - Retention is at most 30 days:
ttlplusstaleIfError, orfallbackForalone. Shared stores keep invalidation markers for that maximum lifetime, so the bound is protocol-wide. versiondefaults to1and must be a positive integer. It is part of the cache identity: bump it when the same request starts meaning something incompatible without changing its URL, and old entries simply stop matching.tagsare application group names of 1–512 characters, at most 61 per policy, because three internal dependency tags are reserved. The Contentful client reserves one more. Duplicate tags are ignored.
policy.withTags(tags) derives a new immutable policy with extra tags, leaving the original
unchanged:
const catalog = dataCache.public({ ttl: "5m", tags: ["catalog"] });
const summer = catalog.withTags(["catalog:summer"]);
Tags and contracts are the invalidation targets; see invalidation.
Diagnose unexpected misses
#Check the effective policy first: a mutation, disabled validation, or cache: false bypasses it.
Then inspect response cache-control headers and whether the calls share a cache instance or shared
store/namespace. Different URLs, explicit headers, credentials modes, partitions, policies,
versions, or tags mean different identities. Keep the cache outside component rendering so each
render does not start empty.
The configured TTL controls reuse; origin max-age and Age do not replace it. This is an explicit
application data cache, not a general-purpose HTTP cache.
Observe cache events
#Pass onEvent to createDataCache to observe cache decisions. Each event has an operation
(read, write, or invalidate), an outcome, and a durationMs; store failures also carry the
error. For example, to distinguish origin work from coalesced callers:
import { createDataCache } from "brix/cache";
export const dataCache = createDataCache({
onEvent(event) {
if (event.operation !== "read") return;
if (event.outcome === "load" || event.outcome === "join") {
console.info(event.operation, event.outcome, event.durationMs);
}
},
});
Read outcomes are hit, load, join, miss, stale, corrupt (a stored entry that failed
parsing or validation), and error. Writes report stored or error; invalidations report
success or error.
read/load fires before each origin loader invocation, not each transport retry. The caller that
starts a shared flight emits load; each caller selecting that existing flight emits read/join
before waiting. A fresh cache hit emits neither. durationMs is elapsed time from that caller's
cache execution start, including hashing and lookup, not origin duration or time waiting for a flight.
These are decision events, not successful completion or one terminal outcome per request.
Cancellation or failure after the decision does not retract it or add a cancellation outcome.
Cancellation observed before the decision emits neither event. Cancelling the initiating caller
does not transfer ownership or emit another load while other callers remain. When everyone leaves,
the shared transport aborts and a subsequent read can start a new load.
Network-first calls and overflow beyond the 1,000 tracked pending identities emit independent load
events. Calls for identities already tracked can still emit join at capacity. Local invalidation
separates new calls from pre-invalidation flights; invalidation in another coordinator does not.
If a shared response vetoes reuse, each surviving joiner starts its own loader and emits load
after join. A join therefore does not guarantee that origin work was avoided.
miss reports a completed origin refresh, not every caller's lookup miss; stale and write
events likewise belong to the loader rather than each joiner. Events never contain cache
identities, URLs, headers, credentials, partitions, tags, or payloads, but error events may carry
provider error details: redact those before exporting telemetry. Synchronous throws and rejected
promises from onEvent cannot fail requests.