@fluojs/cache-manager 1.0.4 → 2.0.0

package/README.md

@@ -13,9 +13,13 @@ General-purpose cache manager for fluo with pluggable memory, Redis, and custom
   - [Application-Level Caching](#application-level-caching)
 - [Common Patterns](#common-patterns)
   - [Redis Storage](#redis-storage)
+  - [TTL Jitter](#ttl-jitter)
   - [Query-Sensitive Caching](#query-sensitive-caching)
   - [Cache Ownership and Reset Scope](#cache-ownership-and-reset-scope)
+  - [Observing Cache Operations](#observing-cache-operations)
+  - [Async Configuration](#async-configuration)
   - [Manual Module Composition](#manual-module-composition)
+  - [NestJS Cache Migration](#nestjs-cache-migration)
 - [Public API Overview](#public-api-overview)
 - [Related Packages](#related-packages)
 - [Example Sources](#example-sources)
@@ -26,14 +30,18 @@ General-purpose cache manager for fluo with pluggable memory, Redis, and custom
 npm install @fluojs/cache-manager
 ```
 
-The root `@fluojs/cache-manager` import stays safe for memory-only installs. You only need Redis peers when you explicitly select the Redis-backed store path.
+`@fluojs/cache-manager` supports Node.js `>=24.0.0 <27` and declares that exact range through `engines.node`. That package-owned support contract means Node versions below 24 and Node 27+ are excluded. Earlier 1.x releases advertised `engines.node >=20.0.0`, which never matched the effective dependency floor.
 
-For Redis-backed caching:
+The root `@fluojs/cache-manager` import stays safe for memory-only installs. You only need a Redis client when you explicitly select the Redis-backed store path.
+
+For Redis-backed caching with a lifecycle-managed `@fluojs/redis` client:
 
 ```bash
 npm install @fluojs/cache-manager @fluojs/redis ioredis
 ```
 
+You can instead pass an application-owned compatible client through `redis.client`. That path does not require `@fluojs/redis`; install whichever client package provides the required `get`, `set`, `del`, and tuple-returning `scan` operations, and close that client from the application lifecycle.
+
 ## When to Use
 
 - When you want to cache expensive database queries or external API responses.
@@ -96,16 +104,30 @@ class UserService {
 
 ### Redis Storage
 
-To use Redis, ensure `@fluojs/redis` is configured and set the store to `'redis'`.
+Set `store: 'redis'`, then choose one of two supported client integration paths:
+
+1. Register a default or named raw client with `@fluojs/redis` and let the cache module resolve it through DI.
+2. Pass an application-owned `RedisCompatibleClient` directly through `redis.client`.
 
 Memory-only consumers can keep importing from `@fluojs/cache-manager` without installing `@fluojs/redis` or `ioredis`; those optional peers are resolved only when the Redis store path is selected.
 
 ```typescript
-CacheModule.forRoot({
-  store: 'redis',
-  ttl: 600,
-  keyPrefix: 'myapp:cache:',
+import { Module } from '@fluojs/core';
+import { CacheModule } from '@fluojs/cache-manager';
+import { RedisModule } from '@fluojs/redis';
+
+@Module({
+  imports: [
+    RedisModule.forRoot({ name: 'cache', host: 'localhost', port: 6379 }),
+    CacheModule.forRoot({
+      store: 'redis',
+      ttl: 600,
+      keyPrefix: 'myapp:cache:',
+      redis: { clientName: 'cache' },
+    }),
+  ],
 })
+class AppModule {}
 ```
 
 If you registered multiple Redis clients, set `redis.clientName` to target a named `@fluojs/redis` connection.
@@ -119,13 +141,54 @@ CacheModule.forRoot({
 })
 ```
 
-`redis.client` remains the highest-precedence override. Use it only when you need to bypass DI-based client selection entirely.
+`redis.client` is the highest-precedence override and bypasses DI-based client selection entirely. It accepts any client that satisfies the exported `RedisCompatibleClient` contract; `@fluojs/redis` is not loaded or required on this path. The application owns connection startup and shutdown for a directly supplied client.
+
+```typescript
+import Redis from 'ioredis';
+import { Module } from '@fluojs/core';
+import { CacheModule } from '@fluojs/cache-manager';
+
+const cacheClient = new Redis({ host: 'localhost', port: 6379 });
+
+@Module({
+  imports: [
+    CacheModule.forRoot({
+      store: 'redis',
+      keyPrefix: 'myapp:cache:',
+      redis: { client: cacheClient },
+    }),
+  ],
+})
+class AppModule {}
+```
 
 The built-in `RedisStore` persists entries with `JSON.stringify(...)`. Cache values therefore need to be JSON-compatible: plain objects, arrays, strings, numbers, booleans, and `null` round-trip cleanly, while values such as `Date` come back as JSON output (for example ISO strings), functions/`undefined`/symbols do not survive, and non-serializable values like `bigint` or cyclic graphs should be normalized before caching.
 
 Positive Redis TTL values are accepted in seconds and may be fractional. Redis expiry is rounded up to the next whole second because Redis `EX` uses integer seconds, while fluo also records the millisecond-precision expiry timestamp in the stored entry and treats the value as expired once that timestamp is reached. Use `ttl: 0` when you intentionally want no Redis expiry.
+Exceptionally large finite TTL values are capped at the largest safe JavaScript expiry timestamp by both built-in stores, so Redis JSON metadata remains finite and aligns with the memory path.
+
+Redis reset ownership is scoped by the top-level `keyPrefix` option, which defaults to `fluo:cache:` and is passed through to the built-in `RedisStore` namespace. `CacheService.reset()` deletes only keys under that prefix for Redis-backed stores, so application-owned Redis data outside the cache prefix is preserved. Redis glob metacharacters in a non-empty prefix (`*`, `?`, `[`, `]`, and `\`) are escaped before `SCAN`, so the configured prefix remains a literal namespace instead of broadening reset ownership. If you intentionally configure an empty `keyPrefix`, reset is limited to keys written by the current `RedisStore` instance instead of scanning `*`; use a non-empty, application-specific prefix when you need reset to cover cache entries across restarts or multiple processes.
+
+### TTL Jitter
 
-Redis reset ownership is scoped by the top-level `keyPrefix` option, which defaults to `fluo:cache:` and is passed through to the built-in `RedisStore` namespace. `CacheService.reset()` deletes only keys under that prefix for Redis-backed stores, so application-owned Redis data outside the cache prefix is preserved. If you intentionally configure an empty `keyPrefix`, reset is limited to keys written by the current `RedisStore` instance instead of scanning `*`; use a non-empty, application-specific prefix when you need reset to cover cache entries across restarts or multiple processes.
+Popular keys written together can otherwise expire together and synchronize origin load. Opt in to centralized positive-TTL jitter with `ttlJitter`; `CacheService` calculates the effective TTL once before handing the write to memory, Redis, or a custom store.
+
+```typescript
+CacheModule.forRoot({
+  store: 'redis',
+  ttl: 600,
+  ttlJitter: {
+    ratio: 0.1,
+    mode: 'symmetric',
+  },
+});
+```
+
+`ratio` must be greater than `0` and at most `1`. The default `symmetric` mode samples within `ttl ± (ttl * ratio)`; `shorten` only subtracts from the TTL and `lengthen` only adds to it. A `CacheService.set(...)` or `remember(...)` per-call TTL override is jittered instead of the module default. `ttl: 0` remains a no-expiry write, and negative or non-finite TTL values still skip the write.
+
+Jitter is disabled only when `ttlJitter` is omitted or `undefined`; `null`, primitives, arrays, and invalid option fields are rejected during module registration. The optional `random` function is a deterministic test seam and must return a finite value in `[0, 1]`; an invalid sample rejects the write instead of being coerced. Production code should normally keep the default `Math.random`.
+
+Every jittered positive TTL remains positive and finite within its selected direction. A fully shortened TTL uses JavaScript's smallest positive finite value rather than becoming the no-expiry sentinel, while an upward result beyond the representable range saturates at `Number.MAX_VALUE`. TTL jitter spreads expiry times only. It is not distributed locking, refresh-ahead caching, or cross-instance stampede coordination.
 
 ### Query-Sensitive Caching
 
@@ -140,7 +203,7 @@ CacheModule.forRoot({
 })
 ```
 
-For fully custom keying, pass a function as `httpKeyStrategy` or use `@CacheKey(...)` with either a literal key or a key factory. These function-based hooks are the supported extension path for request-aware keys; do not subclass `CacheInterceptor` just to replace cache-key generation.
+For fully custom keying, pass a function as `httpKeyStrategy` or use `@CacheKey(...)` with either a literal key or a key factory. An empty literal `@CacheKey('')` remains an explicit key; only absent decorator metadata selects the configured `httpKeyStrategy`. These function-based hooks are the supported extension path for request-aware keys; do not subclass `CacheInterceptor` just to replace cache-key generation.
 
 ```typescript
 CacheModule.forRoot({
@@ -170,7 +233,9 @@ The HTTP interceptor caches only successful, uncommitted GET handler results wit
 
 ### Cache Ownership and Reset Scope
 
-`CacheService.reset()` clears entries owned by the configured store, not unrelated application state. It also drops in-flight `remember(...)` bookkeeping so loaders that started before the reset cannot repopulate stale entries after the reset completes. For the built-in memory store that means the in-process entries held by that store instance. For Redis, ownership is the configured `keyPrefix` namespace; keep the default `fluo:cache:` or choose a dedicated prefix such as `myapp:cache:` for shared Redis deployments.
+Ordinary `get(...)`, `set(...)`, and `del(...)` calls run concurrently against the configured store, so a slow store call for one key does not delay unrelated keys.
+
+`CacheService.reset()` clears entries owned by the configured store, not unrelated application state. It also serializes store reads/writes across the reset boundary and invalidates in-flight `remember(...)` loaders so loaders that started before the reset cannot repopulate stale entries after the reset completes. For the built-in memory store that means the in-process entries held by that store instance. For Redis, ownership is the configured `keyPrefix` namespace; keep the default `fluo:cache:` or choose a dedicated prefix such as `myapp:cache:` for shared Redis deployments.
 
 ```typescript
 CacheModule.forRoot({
@@ -181,10 +246,89 @@ CacheModule.forRoot({
 
 Avoid sharing a Redis cache prefix with non-cache data. `del(key)` removes the exact cache key resolved by this package, while `reset()` removes only the store-owned cache namespace described above.
 
-When the application closes, `CacheService` forwards shutdown to custom stores that expose `close()` or `dispose()`. Use one of those optional hooks when a store owns sockets, pools, timers, or other external resources.
+When the application closes, `CacheService` stops new store reads/writes, waits for already-started store operations, and then forwards shutdown to custom stores that expose `close()` or `dispose()`. Concurrent and repeated `close()` or lifecycle-hook calls share that first teardown completion and failure, so every caller observes the same shutdown boundary while store teardown runs once. Use one of those optional hooks when a store owns sockets, pools, timers, or other external resources.
 
 Custom stores can be passed directly through `store` when they implement the `CacheStore` contract. This is the right option for in-process LRU stores, remote caches other than Redis, or test doubles that need to observe cache operations.
 
+### Observing Cache Operations
+
+The platform status helpers report cache availability only. To measure hit rate, latency, and error outcomes, pass an opt-in `observer` to `CacheModule.forRoot(...)`. The observer is independent of `@fluojs/metrics`; wire it to whichever metrics backend the application already uses.
+
+```typescript
+import { CacheModule, type CacheObservation } from '@fluojs/cache-manager';
+
+CacheModule.forRoot({
+  store: 'memory',
+  observer: {
+    onCacheOperation(observation: CacheObservation) {
+      cacheOperationCounter.inc({
+        operation: observation.operation,
+        outcome: observation.outcome,
+      });
+      cacheOperationLatency.observe(observation.durationMs);
+    },
+  },
+});
+```
+
+The contract is intentionally narrow:
+
+- **Privacy**: an observation carries only `operation`, `outcome`, and `durationMs`. Cache keys, cached values, loader results, and error objects are never passed to the observer, so instrumentation cannot leak application data.
+- **Operation taxonomy**: `operation` is one of `get`, `set`, `del`, `remember`, `reset`, or `close`. `remember` is reported once per call; its internal read is not reported as a separate `get`.
+- **Outcomes**: `CacheObservation` is a discriminated union: read operations (`get`, `remember`) can report only `hit`, `miss`, or `error`, while write, invalidation, and lifecycle operations can report only `success` or `error`. A `remember` call that joins an in-flight load for the same key reports `miss`, because that call did not read a cached value.
+- **Timing**: `durationMs` measures the full `CacheService` operation, including store-queue serialization, with the runtime's monotonic `performance.now()` clock.
+- **Failure containment**: observer errors are swallowed. A thrown error or a rejected promise never changes the value the caller receives and never surfaces as an unhandled rejection. Observer work is not awaited by the cache operation.
+- **HTTP fail-soft interaction**: `CacheInterceptor` still swallows store failures so cache problems cannot fail an otherwise successful handler. The observer sees those failures as `error` observations, which is the supported way to alert on a degraded cache while keeping requests served.
+
+When no `observer` is configured, the cache runs its original code path with no observation work.
+Lifecycle diagnostics report the same teardown owner that shutdown actually uses. `createCacheManagerPlatformStatusSnapshot(...)` resolves ownership from lifecycle responsibility rather than treating every non-memory store alike:
+
+- The built-in memory store is `framework`-owned because the framework creates and holds it in-process.
+- A custom store is `framework`-owned by default because `CacheService.close()` owns teardown dispatch to its optional `close()` or `dispose()` hook.
+- The Redis store is `external` to `CacheService`, which never closes the client. When the cache module resolves a client through `@fluojs/redis`, that integration owns its lifecycle; when `redis.client` supplies a client directly, the application owns its lifecycle.
+
+An explicit `storeOwnershipMode` still wins over the store default. Set it to `external` when the application intentionally retains lifecycle responsibility for a custom store.
+
+### Async Configuration
+
+Use `CacheModule.forRootAsync(...)` when the final store, TTL, `keyPrefix`, or key strategy must come from DI or asynchronous bootstrap work. List the dependency tokens in `inject`, return ordinary `CacheModuleOptions` from `useFactory`, and the module normalizes that result with the same defaults as `CacheModule.forRoot(...)`.
+
+```typescript
+import { Module } from '@fluojs/core';
+import { CacheModule } from '@fluojs/cache-manager';
+
+import { CacheSettingsService } from './cache-settings.service';
+
+@Module({
+  imports: [
+    CacheModule.forRootAsync({
+      inject: [CacheSettingsService],
+      useFactory: async (settings: CacheSettingsService) => ({
+        store: 'redis',
+        ttl: await settings.resolveTtlSeconds(),
+        keyPrefix: settings.keyPrefix,
+        redis: { clientName: 'cache' },
+      }),
+    }),
+  ],
+})
+class AppModule {}
+```
+
+Injected tokens must be visible to the container that instantiates the cache module. Provide them as bootstrap runtime providers or export them from a globally visible imported module before the cache options provider resolves. A provider local only to the importing parent module, or an ordinary sibling/parent export, is not visible to the async cache module. The factory runs once per registration when cache providers are first resolved, and a rejected factory fails bootstrap instead of registering a partially configured cache.
+
+Module visibility stays on the registration call: pass `global: true` to `CacheModule.forRootAsync({ global: true, ... })`. `useFactory` may return a prepared `CacheModuleOptions` value, including its `global` property; any returned `global` is ignored because module metadata is fixed before the factory runs.
+
+```typescript
+CacheModule.forRootAsync({
+  global: true,
+  inject: [CacheSettingsService],
+  useFactory: (settings: CacheSettingsService) => ({ store: settings.store }),
+})
+```
+
+The async path supports the same store selection as `forRoot(...)`: `'memory'`, `'redis'` with a DI-resolved or directly supplied client, and any custom `CacheStore` instance.
+
 ### Manual Module Composition
 
 Use `CacheModule.forRoot(...)` for normal application setup, including custom `defineModule(...)` composition.
@@ -201,6 +345,33 @@ defineModule(ManualCacheModule, {
 });
 ```
 
+### NestJS Cache Migration
+
+`@nestjs/cache-manager` and `@fluojs/cache-manager` expose overlapping cache concepts, but their option names, units, defaults, and ownership do not all carry over. Convert each of the following, and see [NestJS → fluo Migration Map](../../docs/getting-started/migrate-from-nestjs.md) for the full migration contract.
+
+| NestJS option or decorator | fluo equivalent | Conversion rule |
+| --- | --- | --- |
+| `ttl` when the installed underlying `cache-manager` generation uses milliseconds | `ttl` in seconds | Inspect the installed underlying `cache-manager` dependency/version. Divide by 1000 only when that generation defines TTLs in milliseconds. Omitting `ttl` applies `300` seconds on the memory path and `0` for the `redis` and custom-store paths. |
+| `ttl: 0` | `ttl: 0` | Means no expiry, not "do not cache". Negative or non-finite values are invalid: `CacheService.set(...)` drops the write, and `CacheInterceptor` skips both the cache read and write for that handler. |
+| `@CacheTTL(...)` | `@CacheTTL(ttlSeconds: number)` | Accepts one static number only. Move per-request lifetimes to `CacheService.set(key, value, ttlSeconds)`. |
+| implicit query-sensitive keys | `httpKeyStrategy` | Defaults to path-only `'route'`. Select `'route+query'` (or `'full'`), a function strategy, or `@CacheKey(...)` when a response varies by query parameters. |
+| `isGlobal: true` | `global: true` | Both NestJS `isGlobal` and fluo `global` default to `false`, so both cache modules are module-local unless you opt in or import the module everywhere it is resolved. |
+| NestJS store adapters such as `cache-manager-redis-store` | `store: 'redis'` or a `CacheStore` object | NestJS adapters do not satisfy the `CacheStore` contract; use the built-in Redis path or wrap the adapter so callback/options completion becomes a Promise, `ttlSeconds` maps to the legacy TTL in seconds, and `reset()` clears only the cache namespace. Never forward `reset()` blindly to a whole-database `flushDb`. |
+| adapter-owned client teardown | `close()` / `dispose()` on the store | Application shutdown forwards teardown only to those optional hooks. A raw client passed through `redis.client` stays application-owned and must be closed from the application lifecycle. |
+
+```typescript
+CacheModule.forRoot({
+  // If the installed underlying cache-manager generation uses milliseconds,
+  // NestJS `ttl: 60_000` becomes 60 seconds.
+  ttl: 60,
+  // NestJS `isGlobal: true` becomes `global: true`.
+  global: true,
+  // Opt in explicitly when responses vary by query parameters.
+  httpKeyStrategy: 'route+query',
+  store: 'redis',
+})
+```
+
 ### Memory Store Operational Limits
 
 The built-in memory store is designed for single-process, bounded caching:
@@ -211,29 +382,52 @@ The built-in memory store is designed for single-process, bounded caching:
 
 ### Deferred eviction timing
 
-For non-GET handlers decorated with `@CacheEvict(...)`, eviction is deferred until the response successfully commits. If `response.send(...)` rejects, the deferred eviction is cancelled so a failed commit does not drop the previous cached read result. If an adapter path never calls `response.send(...)`, the interceptor still runs a bounded fallback timer so successful writes do not leave stale entries behind indefinitely. Deferred eviction failures stay contained inside the interceptor, so cache-key factories or cache-store deletes cannot surface as post-response unhandled promise rejections.
+`@CacheEvict(...)` is HTTP route metadata, not a general service-method decorator. `CacheInterceptor` consumes it only when that interceptor runs around a non-GET controller handler. For service methods and other calls outside the HTTP interceptor pipeline, inject `CacheService` and call `del(...)` explicitly.
+
+```typescript
+import { CacheEvict, CacheInterceptor } from '@fluojs/cache-manager';
+import { Controller, Post, UseInterceptors } from '@fluojs/http';
+
+@Controller('/products')
+@UseInterceptors(CacheInterceptor)
+class ProductController {
+  @Post('/refresh')
+  @CacheEvict('/products')
+  refresh() {
+    return { refreshed: true };
+  }
+}
+```
+
+On that supported HTTP path, eviction is deferred until a framework response writer settles successfully and the response reports that it committed. If a writer rejects, settles without a confirmed commit, or the request aborts before commit because of disconnect or shutdown, deferred eviction is cancelled so the previous cached read result remains available. Adapter paths that commit without invoking `response.send(...)` retain the bounded five-second fallback: it evicts only when `response.committed` already confirms commit at the deadline. An unconfirmed response is cancelled instead, so elapsed time alone cannot evict before a later failed commit. The fallback timer is unreferenced on Node.js and cleared when a response writer settles, so pending fallback work does not keep process shutdown alive. Deferred eviction failures stay contained inside the interceptor, so cache-key factories or cache-store deletes cannot surface as post-response unhandled promise rejections.
 
 ## Public API Overview
 
 ### Modules
-- `CacheModule.forRoot(options)`: Configures the cache store (memory/redis/custom), default TTL, key strategies, `global`, `principalScopeResolver`, the Redis namespace `keyPrefix`, and Redis options such as `redis.scanCount`.
+- `CacheModule.forRoot(options)`: Configures the cache store (memory/redis/custom), default TTL, opt-in `ttlJitter`, key strategies, `global`, `principalScopeResolver`, the Redis namespace `keyPrefix`, and Redis options such as `redis.scanCount`.
   This is the primary package entrypoint for application modules.
+- `CacheModule.forRootAsync({ inject, useFactory, global? })`: Resolves the same options through an injected factory for applications that build cache configuration from DI or asynchronous bootstrap work. `global` belongs to this registration call, and a rejected factory fails bootstrap.
 
 ### Public types
-- `CacheModuleOptions`: Application-facing configuration accepted by `CacheModule.forRoot(...)`.
-- `NormalizedCacheModuleOptions`: Compatibility-only type export matching the normalized configuration shape after defaults are applied. Prefer `CacheModuleOptions` for application code; this type remains public so consumers that referenced the previously shipped declaration surface can keep compiling.
+- `CacheModuleOptions`: Application-facing configuration accepted by `CacheModule.forRoot(...)`, including optional `ttlJitter` and `observer`.
+- `CacheTtlJitterOptions` and `CacheTtlJitterMode`: Opt-in positive-TTL jitter bounds, direction, and deterministic randomness seam.
+- `NormalizedCacheTtlJitterOptions`: Normalized TTL jitter configuration after defaults are applied.
+- `CacheObserver`: Opt-in observation hook with a single `onCacheOperation(observation)` method.
+- `CacheObservation`: Privacy-safe discriminated union coupling each operation category to its valid outcomes and carrying `durationMs`.
+- `CacheAsyncModuleOptions`: Injected-factory configuration accepted by `CacheModule.forRootAsync(...)`. `useFactory` returns `CacheModuleOptions`; registration-level `global` alone controls module visibility.
+- `NormalizedCacheModuleOptions`: Compatibility-only type export matching the normalized module configuration shape after defaults are applied. Prefer `CacheModuleOptions` for application code; this type remains public so consumers that referenced the previously shipped declaration surface can keep compiling.
 
 ### Services
-- `CacheService`: Main API for manual cache operations (`get`, `set`, `del`, `remember`, `reset`, `close`). Application shutdown calls the same `close()` path, which forwards teardown to custom stores exposing `close()` or `dispose()`.
+- `CacheService`: Main API for manual cache operations (`get`, `set`, `del`, `remember`, `reset`, `close`). Application shutdown calls the same `close()` path, which forwards teardown to custom stores exposing `close()` or `dispose()` and shares the first teardown completion across concurrent or repeated callers.
 
 ### Decorators
 - `@CacheTTL(seconds)`: Sets the TTL for a specific handler.
 - `@CacheKey(key)`: Sets a custom cache key or key factory for a specific handler.
-- `@CacheEvict(key)`: Clears one or more cache keys after a successful non-GET handler completes.
+- `@CacheEvict(key)`: Stores HTTP route metadata that `CacheInterceptor` consumes after a successful non-GET controller handler completes; it does not intercept arbitrary service calls.
 - `cacheRouteMetadataKey`, `getCacheKeyMetadata(...)`, `getCacheTtlMetadata(...)`, and `getCacheEvictMetadata(...)`: Low-level metadata helpers exported for first-party interceptor integration, diagnostics, and advanced tooling that needs to inspect cache decorator metadata without reimplementing the metadata keys.
 
 ### Interceptors
-- `CacheInterceptor`: Handles automatic GET response caching and eviction logic.
+- `CacheInterceptor`: Handles automatic GET response caching and consumes `@CacheEvict(...)` metadata for non-GET HTTP handlers.
 
 ### Stores and status helpers
 - `MemoryStore` and `RedisStore`: Built-in store implementations.
@@ -242,7 +436,7 @@ For non-GET handlers decorated with `@CacheEvict(...)`, eviction is deferred unt
 
 ## Related Packages
 
-- `@fluojs/redis`: Required for Redis storage.
+- `@fluojs/redis`: Optional lifecycle-managed Redis client integration. It is not required when `redis.client` supplies an application-owned `RedisCompatibleClient` directly.
 - `@fluojs/http`: Required for HTTP interceptors and decorators.
 
 ## Example Sources
@@ -251,3 +445,4 @@ For non-GET handlers decorated with `@CacheEvict(...)`, eviction is deferred unt
 - `packages/cache-manager/src/interceptor.test.ts`: HTTP caching and eviction tests.
 - `packages/cache-manager/src/service.ts`: Core `CacheService` implementation.
 - `packages/cache-manager/src/status.test.ts`: Status and diagnostic helper tests.
+- `packages/cache-manager/src/cache-observer.test.ts`: Cache observation contract tests.

package/dist/decorators.js

@@ -1,10 +1,10 @@
-import { ensureMetadataSymbol } from '@fluojs/core/internal';
+import { ensureRequestPipelineMetadataSymbol } from '@fluojs/core/request-pipeline';
 /** Shared controller metadata key used to store per-route cache metadata records. */
 export const cacheRouteMetadataKey = Symbol.for('fluo.standard.route');
 const cacheKeyMetadataKey = Symbol.for('fluo.cache.key');
 const cacheTtlMetadataKey = Symbol.for('fluo.cache.ttl');
 const cacheEvictMetadataKey = Symbol.for('fluo.cache.evict');
-ensureMetadataSymbol();
+ensureRequestPipelineMetadataSymbol();
 function getMetadataBag(metadata) {
   return metadata;
 }

package/dist/deferred-eviction.d.ts

@@ -0,0 +1,13 @@
+import type { InterceptorContext } from '@fluojs/http';
+type RequestAbortState = Pick<InterceptorContext['requestContext']['request'], 'isAborted' | 'signal'>;
+/**
+ * Defers cache eviction until a response writer or bounded fallback confirms commit.
+ *
+ * @param response Active framework response whose writers and committed flag own cleanup.
+ * @param request Request cancellation surfaces used to discard eviction during shutdown or disconnect.
+ * @param evict Cache eviction work to run after a confirmed successful commit.
+ * @returns A cancellation function that restores the response writers and clears the fallback timer.
+ */
+export declare function installDeferredEviction(response: InterceptorContext['requestContext']['response'], request: RequestAbortState, evict: () => Promise<void>): () => void;
+export {};
+//# sourceMappingURL=deferred-eviction.d.ts.map

package/dist/deferred-eviction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred-eviction.d.ts","sourceRoot":"","sources":["../src/deferred-eviction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAIvD,KAAK,iBAAiB,GAAG,IAAI,CAC3B,kBAAkB,CAAC,gBAAgB,CAAC,CAAC,SAAS,CAAC,EAC/C,WAAW,GAAG,QAAQ,CACvB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,kBAAkB,CAAC,gBAAgB,CAAC,CAAC,UAAU,CAAC,EAC1D,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GACzB,MAAM,IAAI,CAwFZ"}

package/dist/deferred-eviction.js

@@ -0,0 +1,85 @@
+const EVICTION_FALLBACK_TIMEOUT_MS = 5_000;
+/**
+ * Defers cache eviction until a response writer or bounded fallback confirms commit.
+ *
+ * @param response Active framework response whose writers and committed flag own cleanup.
+ * @param request Request cancellation surfaces used to discard eviction during shutdown or disconnect.
+ * @param evict Cache eviction work to run after a confirmed successful commit.
+ * @returns A cancellation function that restores the response writers and clears the fallback timer.
+ */
+export function installDeferredEviction(response, request, evict) {
+  const originalSend = response.send;
+  const originalSimpleJsonSend = Reflect.get(response, 'sendSimpleJson');
+  const signal = request.signal;
+  let restored = false;
+  let completed = false;
+  let abortListenerInstalled = false;
+  let responseWriteStarted = false;
+  const requestAborted = () => signal?.aborted === true || request.isAborted?.() === true;
+  const runEviction = () => {
+    if (completed) {
+      return;
+    }
+    completed = true;
+    void evict().catch(() => {});
+  };
+  const restore = () => {
+    if (restored) {
+      return;
+    }
+    if (abortListenerInstalled) {
+      signal?.removeEventListener('abort', cancel);
+    }
+    clearTimeout(fallbackTimer);
+    response.send = originalSend;
+    if (typeof originalSimpleJsonSend === 'function') {
+      Reflect.set(response, 'sendSimpleJson', originalSimpleJsonSend);
+    }
+    restored = true;
+  };
+  const cancel = () => {
+    completed = true;
+    restore();
+  };
+  const runResponseWrite = async write => {
+    responseWriteStarted = true;
+    try {
+      await write();
+      if (requestAborted()) {
+        cancel();
+      } else if (response.committed) {
+        runEviction();
+      } else {
+        cancel();
+      }
+    } catch (error) {
+      cancel();
+      throw error;
+    } finally {
+      restore();
+    }
+  };
+  response.send = body => runResponseWrite(() => originalSend.call(response, body));
+  if (typeof originalSimpleJsonSend === 'function') {
+    Reflect.set(response, 'sendSimpleJson', body => {
+      return runResponseWrite(() => Reflect.apply(originalSimpleJsonSend, response, [body]));
+    });
+  }
+  const fallbackTimer = setTimeout(() => {
+    if (!responseWriteStarted && !requestAborted() && response.committed) {
+      runEviction();
+    }
+    restore();
+  }, EVICTION_FALLBACK_TIMEOUT_MS);
+  fallbackTimer.unref?.();
+  if (signal) {
+    signal.addEventListener('abort', cancel, {
+      once: true
+    });
+    abortListenerInstalled = true;
+  }
+  if (requestAborted()) {
+    cancel();
+  }
+  return cancel;
+}

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-export { CacheEvict, CacheKey, cacheRouteMetadataKey, CacheTTL, getCacheEvictMetadata, getCacheKeyMetadata, getCacheTtlMetadata, } from './decorators.js';
+export { CacheEvict, CacheKey, CacheTTL, cacheRouteMetadataKey, getCacheEvictMetadata, getCacheKeyMetadata, getCacheTtlMetadata, } from './decorators.js';
 export { CacheInterceptor } from './interceptor.js';
 export { CacheModule } from './module.js';
 export { CacheService } from './service.js';
+export type { CacheManagerPlatformStatusSnapshot, CacheManagerStatusAdapterInput, CacheManagerStoreKind, CacheManagerStoreOwnershipMode, } from './status.js';
 export { createCacheManagerPlatformDiagnosticIssues, createCacheManagerPlatformStatusSnapshot, } from './status.js';
 export { MemoryStore } from './stores/memory-store.js';
 export { RedisStore, type RedisStoreOptions } from './stores/redis-store.js';
 export { CACHE_OPTIONS, CACHE_STORE } from './tokens.js';
-export type { CacheEvictDecoratorValue, CacheEvictFactory, CacheKeyDecoratorValue, CacheKeyFactory, CacheKeyStrategy, CacheModuleOptions, CacheStore, NormalizedCacheModuleOptions, PrincipalScopeResolver, RedisCacheOptions, RedisCompatibleClient, } from './types.js';
-export type { CacheManagerPlatformStatusSnapshot, CacheManagerStatusAdapterInput, CacheManagerStoreKind, CacheManagerStoreOwnershipMode, } from './status.js';
+export type { CacheAsyncModuleOptions, CacheEvictDecoratorValue, CacheEvictFactory, CacheKeyDecoratorValue, CacheKeyFactory, CacheKeyStrategy, CacheModuleOptions, CacheObservation, CacheObserver, CacheStore, CacheTtlJitterMode, CacheTtlJitterOptions, NormalizedCacheModuleOptions, NormalizedCacheTtlJitterOptions, PrincipalScopeResolver, RedisCacheOptions, RedisCompatibleClient, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,QAAQ,EACR,qBAAqB,EACrB,QAAQ,EACR,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EACL,0CAA0C,EAC1C,wCAAwC,GACzC,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACzD,YAAY,EACV,wBAAwB,EACxB,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,EACV,4BAA4B,EAC5B,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,kCAAkC,EAClC,8BAA8B,EAC9B,qBAAqB,EACrB,8BAA8B,GAC/B,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EACV,kCAAkC,EAClC,8BAA8B,EAC9B,qBAAqB,EACrB,8BAA8B,GAC/B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,0CAA0C,EAC1C,wCAAwC,GACzC,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACzD,YAAY,EACV,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,qBAAqB,EACrB,4BAA4B,EAC5B,+BAA+B,EAC/B,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,4 +1,4 @@
-export { CacheEvict, CacheKey, cacheRouteMetadataKey, CacheTTL, getCacheEvictMetadata, getCacheKeyMetadata, getCacheTtlMetadata } from './decorators.js';
+export { CacheEvict, CacheKey, CacheTTL, cacheRouteMetadataKey, getCacheEvictMetadata, getCacheKeyMetadata, getCacheTtlMetadata } from './decorators.js';
 export { CacheInterceptor } from './interceptor.js';
 export { CacheModule } from './module.js';
 export { CacheService } from './service.js';

package/dist/interceptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interceptor.d.ts","sourceRoot":"","sources":["../src/interceptor.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,kBAAkB,EAAe,MAAM,cAAc,CAAC;AAGxG,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAsE,4BAA4B,EAA0B,MAAM,YAAY,CAAC;AA6L3J;;GAEG;AACH,qBACa,gBAAiB,YAAW,WAAW;IAEhD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B;IAGlD,SAAS,CAAC,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;YAanE,YAAY;YA2BZ,eAAe;YA2Bf,gBAAgB;IAY9B,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,gBAAgB;YAkBV,OAAO;YAQP,OAAO;YAOP,OAAO;CAMtB"}
+{"version":3,"file":"interceptor.d.ts","sourceRoot":"","sources":["../src/interceptor.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,kBAAkB,EAAe,MAAM,cAAc,CAAC;AAIxG,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAsE,4BAA4B,EAA0B,MAAM,YAAY,CAAC;AA2I3J;;GAEG;AACH,qBACa,gBAAiB,YAAW,WAAW;IAEhD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B;IAGlD,SAAS,CAAC,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;YAanE,YAAY;YA2BZ,eAAe;YAoCf,gBAAgB;IAY9B,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,gBAAgB;YAkBV,OAAO;YAQP,OAAO;YAOP,OAAO;CAMtB"}

package/dist/interceptor.js

@@ -5,16 +5,17 @@ function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e =
 function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
 function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
 import { Inject } from '@fluojs/core';
-import { getStandardMetadataBag } from '@fluojs/core/internal';
+import { getRequestPipelineMetadataBag } from '@fluojs/core/request-pipeline';
 import { SseResponse } from '@fluojs/http';
 import { cacheRouteMetadataKey, getCacheEvictMetadata, getCacheKeyMetadata, getCacheTtlMetadata } from './decorators.js';
+import { installDeferredEviction } from './deferred-eviction.js';
 import { CacheService } from './service.js';
 import { CACHE_OPTIONS } from './tokens.js';
 function isMetadataBag(value) {
   return typeof value === 'object' && value !== null;
 }
 function getMethodMetadataBag(controllerToken, methodName) {
-  const classBag = getStandardMetadataBag(controllerToken);
+  const classBag = getRequestPipelineMetadataBag(controllerToken);
   if (!isMetadataBag(classBag)) {
     return undefined;
   }
@@ -85,7 +86,7 @@ function isSuccessStatusCode(statusCode) {
   return statusCode >= 200 && statusCode < 300;
 }
 async function resolveCacheKeyValue(metadata, context, strategy, resolver) {
-  if (!metadata) {
+  if (metadata === undefined) {
     return defaultCacheKey(context, strategy, resolver);
   }
   if (typeof metadata === 'string') {
@@ -93,43 +94,6 @@ async function resolveCacheKeyValue(metadata, context, strategy, resolver) {
   }
   return metadata(context);
 }
-const EVICTION_FALLBACK_TIMEOUT_MS = 5_000;
-function installDeferredEviction(response, evict) {
-  const originalSend = response.send.bind(response);
-  let restored = false;
-  let completed = false;
-  const runEviction = () => {
-    if (completed) {
-      return;
-    }
-    completed = true;
-    void evict().catch(() => {});
-  };
-  const restore = () => {
-    if (restored) {
-      return;
-    }
-    clearTimeout(fallbackTimer);
-    response.send = originalSend;
-    restored = true;
-  };
-  const fallbackTimer = setTimeout(() => {
-    runEviction();
-    restore();
-  }, EVICTION_FALLBACK_TIMEOUT_MS);
-  response.send = async body => {
-    try {
-      await originalSend(body);
-      runEviction();
-    } catch (error) {
-      completed = true;
-      throw error;
-    } finally {
-      restore();
-    }
-  };
-  return restore;
-}
 
 /**
  * Caches GET responses and evicts related entries after successful write operations.
@@ -182,10 +146,14 @@ class CacheInterceptor {
       }));
     };
     if (context.requestContext.response.committed) {
+      const request = context.requestContext.request;
+      if (request.signal?.aborted === true || request.isAborted?.() === true) {
+        return;
+      }
       await runEviction();
       return;
     }
-    installDeferredEviction(context.requestContext.response, runEviction);
+    installDeferredEviction(context.requestContext.response, context.requestContext.request, runEviction);
   }
   async resolveEvictKeys(metadata, context, value) {
     if (typeof metadata === 'function') {

package/dist/module.d.ts

@@ -1,5 +1,5 @@
 import { type ModuleType } from '@fluojs/runtime';
-import type { CacheModuleOptions } from './types.js';
+import type { CacheAsyncModuleOptions, CacheModuleOptions } from './types.js';
 /**
  * Runtime module entrypoint for cache-manager services and interceptor wiring.
  *
@@ -28,5 +28,30 @@ export declare class CacheModule {
      * ```
      */
     static forRoot(options?: CacheModuleOptions): ModuleType;
+    /**
+     * Register cache providers from an injected async factory.
+     *
+     * @remarks
+     * The factory runs once per module registration through the application container,
+     * and its resolved options are normalized with the same defaults as
+     * {@link CacheModule.forRoot}. Module visibility comes from the `global` option on this
+     * call because module metadata is fixed before the factory runs; a `global` value in the
+     * factory result is ignored. A rejected factory fails bootstrap.
+     *
+     * @param options Injected factory registration options.
+     * @returns A runtime module exporting `CacheService` and `CacheInterceptor`.
+     *
+     * @example
+     * ```ts
+     * CacheModule.forRootAsync({
+     *   inject: [ConfigService],
+     *   useFactory: (config) => ({
+     *     store: 'redis',
+     *     ttl: config.cacheTtlSeconds,
+     *   }),
+     * });
+     * ```
+     */
+    static forRootAsync(options: CacheAsyncModuleOptions): ModuleType;
 }
 //# sourceMappingURL=module.d.ts.map