CacheBehavior

Defined in: packages/pipeline-cache/src/cache.behavior.ts:106

Pipeline behavior that transparently caches handler results with cache-manager (v7) on top of Keyv.

Resolution of the effective options for a handler:

Application-wide defaults, the second constructor argument.
Per-operation options from the cache({ ... }) entry, shallow-merged on top of the defaults (handler keys win).

A key factory is required — see createPartitionedCacheKeyFactory. Only query requests are cached by default; commands and events pass through untouched. On a cache miss, null / undefined results are not written. Cache hits return the value from the single explicit lookup. This behavior intentionally does not use cache-manager.wrap() because its background refresh callback would re-enter every downstream pipeline behavior. Cached results are JSON values. A miss returns the JSON form of the handler result that it stores (a Date becomes an ISO string and a class instance a plain object), so a hit and a miss return the same shape. A result that cannot be JSON-serialized is returned unchanged and not cached.

Store errors fail open by default: read failures bypass caching for that execution, and write failures return the successful handler result. Set failOpen: false to propagate store failures instead.

Example

Principal/permission-scoped query cache

const userCacheKey = createPartitionedCacheKeyFactory({
  principal: (ctx) => ctx.items.get('userId') as string | undefined,
  scope: (ctx) => ctx.items.get('capabilityVersion') as string | undefined,
});

class GetUsersHandler {
  @pipeline.wrap({ kind: 'query' }, [CacheBehavior, { key: userCacheKey, ttl: 30_000 }])
  async handle(query: GetUsersQuery) {}
}