@fluojs/cache-manager 1.0.0-beta.5 → 1.0.0-beta.6

package/README.ko.md

@@ -2,7 +2,7 @@
 
 <p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
 
-메모리(Memory) 및 Redis 저장소 어댑터를 지원하는 fluo 애플리케이션용 범용 캐시 관리 패키지입니다. 데코레이터 기반의 HTTP 응답 캐싱과 프로그래밍 방식의 애플리케이션 레벨 캐시 API를 모두 제공합니다.
+메모리(Memory), Redis, custom store 어댑터를 지원하는 fluo 애플리케이션용 범용 캐시 관리 패키지입니다. 데코레이터 기반의 HTTP 응답 캐싱과 프로그래밍 방식의 애플리케이션 레벨 캐시 API를 모두 제공합니다.
 
 ## 목차
 
@@ -127,7 +127,7 @@ Redis reset 소유권은 기본값이 `fluo:cache:`인 `keyPrefix`로 제한됩
 
 내장 HTTP 캐시 키 전략은 경로 부분을 route template metadata가 아니라 구체적인 요청 경로(`requestContext.request.path`)에서 계산합니다. 따라서 같은 `@Get('/:id')` 핸들러를 타더라도 `/users/1`과 `/users/2` 같은 요청은 항상 서로 다른 캐시 키로 분리됩니다.
 
-기본적으로 캐시 키는 쿼리 매개변수를 무시하고 구체적인 요청 경로만 사용합니다. 검색 조건 등에 따라 다른 응답을 캐싱하려면 `httpKeyStrategy: 'route+query'`를 활성화하세요. 내장 전략에서는 `full`도 동일하게 query-aware 키를 만듭니다. query-aware 키는 매개변수 이름과 반복 값 모두를 정규화하므로 `/products?tag=a&tag=b`와 `/products?tag=b&tag=a`는 같은 캐시 엔트리를 공유합니다.
+기본적으로 익명 요청은 구체적인 요청 경로만 사용하고 쿼리 매개변수를 무시합니다. 인증된 요청은 principal scope가 있으면 이를 suffix로 덧붙이며, `principalScopeResolver`로 이 suffix를 커스터마이즈할 수 있습니다. 검색 조건 등에 따라 다른 응답을 캐싱하려면 `httpKeyStrategy: 'route+query'`를 활성화하세요. 내장 전략에서는 `full`도 동일하게 query-aware 키를 만듭니다. query-aware 키는 매개변수 이름과 반복 값 모두를 정규화하므로 `/products?tag=a&tag=b`와 `/products?tag=b&tag=a`는 같은 캐시 엔트리를 공유합니다.
 
 ```typescript
 CacheModule.forRoot({
@@ -136,6 +136,8 @@ CacheModule.forRoot({
 })
 ```
 
+완전히 다른 키 전략이 필요하다면 `httpKeyStrategy`에 함수를 전달하거나, literal key 또는 key factory를 받는 `@CacheKey(...)`를 사용하세요.
+
 ### 캐시 소유권과 reset 범위
 
 `CacheService.reset()`은 관련 없는 애플리케이션 상태가 아니라 설정된 store가 소유한 엔트리만 삭제합니다. 또한 진행 중인 `remember(...)` bookkeeping을 제거하므로 reset 전에 시작된 loader가 reset 완료 후 stale 엔트리를 다시 채우지 못합니다. 내장 메모리 저장소에서는 해당 store 인스턴스가 보유한 in-process 엔트리를 의미합니다. Redis에서는 설정된 `keyPrefix` namespace가 소유권 경계입니다. 공유 Redis 배포에서는 기본 `fluo:cache:`를 유지하거나 `myapp:cache:`처럼 전용 prefix를 선택하세요.
@@ -151,6 +153,8 @@ Redis cache prefix를 cache가 아닌 데이터와 공유하지 마세요. `del(
 
 애플리케이션이 종료될 때 `CacheService`는 `close()` 또는 `dispose()`를 노출하는 custom store로 shutdown을 전달합니다. store가 socket, pool, timer 또는 기타 외부 리소스를 소유한다면 이 optional hook 중 하나를 사용하세요.
 
+`CacheStore` 계약을 구현한 custom store는 `store` 옵션에 직접 전달할 수 있습니다. in-process LRU store, Redis 외 원격 캐시, 또는 cache operation을 관찰해야 하는 테스트 더블에 적합합니다.
+
 ### 수동 모듈 조합
 
 일반적인 애플리케이션 설정과 커스텀 `defineModule(...)` 조합에서는 `CacheModule.forRoot(...)`를 사용합니다.
@@ -182,21 +186,26 @@ defineModule(ManualCacheModule, {
 ## 공개 API 개요
 
 ### 모듈
-- `CacheModule.forRoot(options)`: 캐시 저장소(memory/redis), 기본 TTL, 키 전략 등을 설정합니다.
+- `CacheModule.forRoot(options)`: 캐시 저장소(memory/redis/custom), 기본 TTL, 키 전략, `isGlobal`, `principalScopeResolver`, `redis.scanCount` 같은 Redis 옵션을 설정합니다.
   애플리케이션 모듈에서 사용하는 기본 패키지 진입점입니다.
 
 
 ### 서비스
-- `CacheService`: 수동 캐시 작업(`get`, `set`, `del`, `remember`, `reset`)을 위한 기본 API입니다.
+- `CacheService`: 수동 캐시 작업(`get`, `set`, `del`, `remember`, `reset`, `close`)을 위한 기본 API입니다.
 
 ### 데코레이터
 - `@CacheTTL(seconds)`: 특정 핸들러의 TTL을 설정합니다.
-- `@CacheKey(key)`: 특정 핸들러의 커스텀 캐시 키를 설정합니다.
-- `@CacheEvict(key)`: 성공적인 데이터 변경(POST/PUT/DELETE) 후 특정 캐시 키를 삭제합니다.
+- `@CacheKey(key)`: 특정 핸들러의 custom cache key 또는 key factory를 설정합니다.
+- `@CacheEvict(key)`: 성공적인 non-GET 핸들러가 완료된 뒤 하나 이상의 cache key를 삭제합니다.
 
 ### 인터셉터
 - `CacheInterceptor`: 자동 GET 응답 캐싱 및 삭제 로직을 처리합니다.
 
+### 저장소와 status helper
+- `MemoryStore`, `RedisStore`: 내장 store 구현입니다.
+- `CACHE_OPTIONS`, `CACHE_STORE`: 패키지 내부와 custom composition에서 사용하는 DI 토큰입니다.
+- `createCacheManagerPlatformStatusSnapshot(...)`, `createCacheManagerPlatformDiagnosticIssues(...)`: 플랫폼 status와 diagnostic helper입니다.
+
 ## 관련 패키지
 
 - `@fluojs/redis`: Redis 저장소 사용 시 필요합니다.
@@ -207,3 +216,4 @@ defineModule(ManualCacheModule, {
 - `packages/cache-manager/src/module.test.ts`: 모듈 설정 및 프로바이더 테스트.
 - `packages/cache-manager/src/interceptor.test.ts`: HTTP 캐싱 및 삭제 테스트.
 - `packages/cache-manager/src/service.ts`: 코어 `CacheService` 구현.
+- `packages/cache-manager/src/status.test.ts`: status 및 diagnostic helper 테스트.

package/README.md

@@ -2,7 +2,7 @@
 
 <p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
 
-General-purpose cache manager for fluo with pluggable memory and Redis stores. Provides both decorator-driven HTTP response caching and a standalone cache API for application-level caching.
+General-purpose cache manager for fluo with pluggable memory, Redis, and custom store adapters. Provides both decorator-driven HTTP response caching and a standalone cache API for application-level caching.
 
 ## Table of Contents
 
@@ -127,7 +127,7 @@ Redis reset ownership is scoped by `keyPrefix`, which defaults to `fluo:cache:`.
 
 Built-in HTTP cache key strategies derive their path segment from the concrete request path (`requestContext.request.path`), not the route template metadata. That means requests such as `/users/1` and `/users/2` always resolve to different cache keys even when they hit the same `@Get('/:id')` handler.
 
-By default, the cache key ignores query parameters and uses only the concrete request path. Enable `httpKeyStrategy: 'route+query'` (or `full`, which is equivalent for the built-in strategy set) to cache different responses for different search parameters. Query-aware keys canonicalize both parameter names and repeated values, so `/products?tag=a&tag=b` and `/products?tag=b&tag=a` share one cache entry.
+By default, anonymous requests use the concrete request path and ignore query parameters. Authenticated requests append a principal scope when one is available; use `principalScopeResolver` to customize that suffix. Enable `httpKeyStrategy: 'route+query'` (or `full`, which is equivalent for the built-in strategy set) to cache different responses for different search parameters. Query-aware keys canonicalize both parameter names and repeated values, so `/products?tag=a&tag=b` and `/products?tag=b&tag=a` share one cache entry.
 
 ```typescript
 CacheModule.forRoot({
@@ -136,6 +136,8 @@ CacheModule.forRoot({
 })
 ```
 
+For fully custom keying, pass a function as `httpKeyStrategy` or use `@CacheKey(...)` with either a literal key or a key factory.
+
 ### 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.
@@ -151,6 +153,8 @@ Avoid sharing a Redis cache prefix with non-cache data. `del(key)` removes the e
 
 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.
 
+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.
+
 ### Manual Module Composition
 
 Use `CacheModule.forRoot(...)` for normal application setup, including custom `defineModule(...)` composition.
@@ -182,21 +186,26 @@ For non-GET handlers decorated with `@CacheEvict(...)`, eviction is deferred unt
 ## Public API Overview
 
 ### Modules
-- `CacheModule.forRoot(options)`: Configures the cache store (memory/redis), default TTL, and key strategies.
+- `CacheModule.forRoot(options)`: Configures the cache store (memory/redis/custom), default TTL, key strategies, `isGlobal`, `principalScopeResolver`, and Redis options such as `redis.scanCount`.
   This is the primary package entrypoint for application modules.
 
 
 ### Services
-- `CacheService`: Main API for manual cache operations (`get`, `set`, `del`, `remember`, `reset`).
+- `CacheService`: Main API for manual cache operations (`get`, `set`, `del`, `remember`, `reset`, `close`).
 
 ### Decorators
 - `@CacheTTL(seconds)`: Sets the TTL for a specific handler.
-- `@CacheKey(key)`: Sets a custom cache key for a specific handler.
-- `@CacheEvict(key)`: Clears specific cache keys after a successful mutation (POST/PUT/DELETE).
+- `@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.
 
 ### Interceptors
 - `CacheInterceptor`: Handles automatic GET response caching and eviction logic.
 
+### Stores and status helpers
+- `MemoryStore` and `RedisStore`: Built-in store implementations.
+- `CACHE_OPTIONS` and `CACHE_STORE`: DI tokens for package internals and custom composition.
+- `createCacheManagerPlatformStatusSnapshot(...)` and `createCacheManagerPlatformDiagnosticIssues(...)`: Platform status and diagnostic helpers.
+
 ## Related Packages
 
 - `@fluojs/redis`: Required for Redis storage.
@@ -207,3 +216,4 @@ For non-GET handlers decorated with `@CacheEvict(...)`, eviction is deferred unt
 - `packages/cache-manager/src/module.test.ts`: Module configuration and provider tests.
 - `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.

package/dist/decorators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEnF,qFAAqF;AACrF,eAAO,MAAM,qBAAqB,eAAoC,CAAC;AAKvE,KAAK,mBAAmB,GAAG,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AACxD,KAAK,yBAAyB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,2BAA2B,KAAK,IAAI,CAAC;AAiCjG;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,sBAAsB,GAAG,yBAAyB,CAI/E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,yBAAyB,CAItE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,wBAAwB,GAAG,yBAAyB,CAIrF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,mBAAmB,GAAG,sBAAsB,GAAG,SAAS,CAEhG;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,GAAG,SAAS,CAQhF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,mBAAmB,GAAG,wBAAwB,GAAG,SAAS,CAIpG"}
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEnF,qFAAqF;AACrF,eAAO,MAAM,qBAAqB,eAAoC,CAAC;AAKvE,KAAK,mBAAmB,GAAG,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AACxD,KAAK,yBAAyB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,2BAA2B,KAAK,IAAI,CAAC;AAmCjG;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,sBAAsB,GAAG,yBAAyB,CAI/E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,yBAAyB,CAItE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,wBAAwB,GAAG,yBAAyB,CAIrF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,mBAAmB,GAAG,sBAAsB,GAAG,SAAS,CAEhG;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,GAAG,SAAS,CAQhF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,mBAAmB,GAAG,wBAAwB,GAAG,SAAS,CAIpG"}

package/dist/decorators.js

@@ -1,8 +1,10 @@
+import { ensureMetadataSymbol } from '@fluojs/core/internal';
 /** 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();
 function getMetadataBag(metadata) {
   return metadata;
 }

package/package.json

@@ -10,7 +10,7 @@
     "memory-store",
     "decorator"
   ],
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.6",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -37,10 +37,10 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.0-beta.3",
+    "@fluojs/core": "^1.0.0-beta.4",
     "@fluojs/di": "^1.0.0-beta.6",
-    "@fluojs/http": "^1.0.0-beta.9",
-    "@fluojs/runtime": "^1.0.0-beta.9"
+    "@fluojs/http": "^1.0.0-beta.10",
+    "@fluojs/runtime": "^1.0.0-beta.11"
   },
   "peerDependencies": {
     "ioredis": "^5.0.0",