Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

    Documentation menu
    Docs / APIs and data / Data cachingRead Markdown
    On this page

    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:

    src/data-cache.ts
    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:

    src/brix.server.ts
    "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, or d unit, such as "500ms", "30s", or "1.5h". Each must resolve to whole milliseconds. ttl and fallbackFor must be positive; use cache: false rather than a zero TTL to bypass caching.
    • Retention is at most 30 days: ttl plus staleIfError, or fallbackFor alone. Shared stores keep invalidation markers for that maximum lifetime, so the bound is protocol-wide.
    • version defaults to 1 and 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.
    • tags are 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.