Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

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

    Cache invalidation

    Invalidate cached data after changes and preserve the boundaries between browser, server, Contentful, and edge caches.

    Invalidate after changes

    #

    Mutations do not invalidate automatically:

    await updateProductClient
      .execute(updateProductApiContract, { body: input, params: { productId } })
      .unwrap();
    await dataCache.invalidate(getProductApiContract);
    

    Here the two clients, contracts, dataCache, input, and productId are application values from the mutation's server operation. The ordering is the important part: await a successful mutation, then invalidate the read contract. A failed mutation leaves the existing cached reads intact.

    dataCache.invalidate(target) accepts a contract (anything with method and path) or a tag string. Contract invalidation covers every URL, parameter set, origin, and private partition for that method/path in the namespace. Use tags for narrower application groups:

    const summer = dataCache.public({ ttl: "5m", tags: ["catalog:summer"] });
    await catalogClient.execute(getProductApiContract, {
      params: { productId: "summer-bag" },
      cache: summer,
    });
    
    // After a successful change to that catalogue group:
    await dataCache.invalidate("catalog:summer");
    

    Creating a tagged policy alone does not tag existing entries. Apply it to the reads that should belong to the group. Choose tags for the data affected by a mutation, including list queries that could gain or lose the changed item. dataCache.invalidateAll() invalidates every entry in the cache's namespace, for example after logout from a browser session cache.

    For Contentful Delivery clients, call the client's invalidateCache() or register the clients with verified webhooks; it invalidates every cached Delivery read for that host, space, and environment.

    When invalidation belongs to a timed request, pass its timing scope explicitly:

    await dataCache.invalidate(getProductApiContract, { timings: c.timings });
    await dataCache.invalidateAll({ timings: c.timings });
    

    The scope is forwarded to the store operation for native provider instrumentation and is not retained by the coordinator.

    What awaiting invalidation guarantees

    #

    Awaiting invalidation confirms storage invalidation, not observer refresh completion. Store failures reject the awaited call, so retry it; a webhook should return a non-2xx status so the sender retries.

    Active local useApi observers of matching queries refresh in the background and retain old data while fetching; refresh failures cannot fail the mutation or invalidation. Observers exist only in the same createDataCache coordinator; there is no cross-tab or cross-replica notification, even between coordinators sharing one store.

    Invalidation is eventual, and in-flight work may repopulate shared storage. Within one createDataCache coordinator, a local generation for each tracked query prevents new callers from joining matching pre-invalidation work and prevents that work from writing its result to the store or publishing it to local observers. Callers that started before the invalidation still receive their own result. Invalidating unrelated tags does not interrupt sharing or suppress successful publications for other queries. Contract invalidation still covers all matching private partitions; invalidateAll() fences every tracked query. There is no such promise across coordinators or replicas. The stale fallback recheck is likewise best-effort and eventual.

    Non-transient 4xx responses (except 429) and successful uncacheable responses invalidate the matching entry when the initial lookup found one or failed. After a confirmed miss, Brix rereads the key first and invalidates only if another request stored a value before the response arrived, so repeated 404s for absent keys write no 30-day invalidation markers. Store failure preserves the origin outcome; a write that finishes after invalidation can still repopulate the entry.

    Boundaries to preserve

    #
    • Browser, server, Contentful delivery, and edge caches are separate scopes.
    • A Contentful webhook invalidates registered server delivery clients only.
    • Invalidation is not CDN propagation, authorization, or a browser purge.
    • There is no polling, focus/reconnect refetch, cross-tab broadcast, distributed load lease, or detached stale-while-revalidate.
    • Identities and tags are hashed, but bodies are not encrypted by Brix. Use store encryption and access controls.

    See API clients, Contentful clients, and server setup for each integration.