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.