@fluojs/cache-manager 1.0.0-beta.4 → 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 키를 만듭니다.
+기본적으로 익명 요청은 구체적인 요청 경로만 사용하고 쿼리 매개변수를 무시합니다. 인증된 요청은 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,9 +136,11 @@ CacheModule.forRoot({
 })
 ```
 
+완전히 다른 키 전략이 필요하다면 `httpKeyStrategy`에 함수를 전달하거나, literal key 또는 key factory를 받는 `@CacheKey(...)`를 사용하세요.
+
 ### 캐시 소유권과 reset 범위
 
-`CacheService.reset()`은 관련 없는 애플리케이션 상태가 아니라 설정된 store가 소유한 엔트리만 삭제합니다. 내장 메모리 저장소에서는 해당 store 인스턴스가 보유한 in-process 엔트리를 의미합니다. Redis에서는 설정된 `keyPrefix` namespace가 소유권 경계입니다. 공유 Redis 배포에서는 기본 `fluo:cache:`를 유지하거나 `myapp:cache:`처럼 전용 prefix를 선택하세요.
+`CacheService.reset()`은 관련 없는 애플리케이션 상태가 아니라 설정된 store가 소유한 엔트리만 삭제합니다. 또한 진행 중인 `remember(...)` bookkeeping을 제거하므로 reset 전에 시작된 loader가 reset 완료 후 stale 엔트리를 다시 채우지 못합니다. 내장 메모리 저장소에서는 해당 store 인스턴스가 보유한 in-process 엔트리를 의미합니다. Redis에서는 설정된 `keyPrefix` namespace가 소유권 경계입니다. 공유 Redis 배포에서는 기본 `fluo:cache:`를 유지하거나 `myapp:cache:`처럼 전용 prefix를 선택하세요.
 
 ```typescript
 CacheModule.forRoot({
@@ -149,6 +151,10 @@ CacheModule.forRoot({
 
 Redis cache prefix를 cache가 아닌 데이터와 공유하지 마세요. `del(key)`은 이 패키지가 해석한 정확한 캐시 키를 삭제하고, `reset()`은 위에서 설명한 store 소유 캐시 namespace만 삭제합니다.
 
+애플리케이션이 종료될 때 `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(...)`를 사용합니다.
@@ -180,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 저장소 사용 시 필요합니다.
@@ -205,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.
+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,9 +136,11 @@ 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. 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.
+`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.
 
 ```typescript
 CacheModule.forRoot({
@@ -149,6 +151,10 @@ 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.
+
+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.
@@ -180,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.
@@ -205,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/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;AA+K3J;;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;YA0BZ,eAAe;YA2Bf,gBAAgB;IAY9B,OAAO,CAAC,gBAAgB;YAYV,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;AAGxG,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAsE,4BAA4B,EAA0B,MAAM,YAAY,CAAC;AAmL3J;;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;YA0BZ,eAAe;YA2Bf,gBAAgB;IAY9B,OAAO,CAAC,gBAAgB;YAYV,OAAO;YAQP,OAAO;YAOP,OAAO;CAMtB"}

package/dist/interceptor.js

@@ -31,7 +31,7 @@ function normalizeCacheMethod(method) {
 function buildSortedQueryString(query) {
   const entries = Object.entries(query).filter(([, value]) => value !== undefined).sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => {
     if (Array.isArray(value)) {
-      return value.map(v => `${encodeURIComponent(key)}=${encodeURIComponent(String(v))}`).join('&');
+      return [...value].map(v => String(v)).sort((a, b) => a.localeCompare(b)).map(v => `${encodeURIComponent(key)}=${encodeURIComponent(v)}`).join('&');
     }
     return `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`;
   });

package/dist/service.d.ts

@@ -7,7 +7,9 @@ export declare class CacheService {
     private readonly options;
     private readonly inflight;
     private readonly pendingLoads;
+    private readonly pendingInvalidations;
     private readonly invalidatedInflight;
+    private closed;
     private resetVersion;
     private beginPendingLoad;
     private endPendingLoad;
@@ -50,5 +52,17 @@ export declare class CacheService {
      * @returns A promise that resolves after the store reset completes.
      */
     reset(): Promise<void>;
+    /**
+     * Close the configured store when it exposes an optional teardown hook.
+     *
+     * @returns A promise that resolves after store teardown completes.
+     */
+    close(): Promise<void>;
+    /**
+     * Runtime shutdown hook that releases resource-owning stores during application close.
+     *
+     * @returns A promise that resolves after store teardown completes.
+     */
+    onModuleDestroy(): Promise<void>;
 }
 //# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAE3E;;GAEG;AACH,qBACa,YAAY;IAsBrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAtB1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;IAChE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAC1D,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IACzD,OAAO,CAAC,YAAY,CAAK;IAEzB,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,cAAc;gBAYH,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,4BAA4B;IAGxD;;;;;OAKG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAIrD;;;;;;;OAOG;IACG,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUjF;;;;;;;OAOG;IACG,QAAQ,CAAC,CAAC,GAAG,OAAO,EACxB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,CAAC,CAAC;IAyCb;;;;;OAKG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrC;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7B"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAQ3E;;GAEG;AACH,qBACa,YAAY;IAqCrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IArC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0C;IACvE,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAA6B;IAClE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IACzD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAAK;IAEzB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,cAAc;gBAsBH,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,4BAA4B;IAGxD;;;;;OAKG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAIrD;;;;;;;OAOG;IACG,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUjF;;;;;;;OAOG;IACG,QAAQ,CAAC,CAAC,GAAG,OAAO,EACxB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,CAAC,CAAC;IAsDb;;;;;OAKG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcrC;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB5B;;;;OAIG;IACH,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;CAGjC"}

package/dist/service.js

@@ -16,18 +16,29 @@ class CacheService {
   }
   inflight = new Map();
   pendingLoads = new Map();
+  pendingInvalidations = new Map();
   invalidatedInflight = new Set();
+  closed = false;
   resetVersion = 0;
-  beginPendingLoad(key) {
-    this.pendingLoads.set(key, (this.pendingLoads.get(key) ?? 0) + 1);
+  beginPendingLoad(key, generation) {
+    const generations = this.pendingLoads.get(key) ?? new Map();
+    generations.set(generation, (generations.get(generation) ?? 0) + 1);
+    this.pendingLoads.set(key, generations);
   }
-  endPendingLoad(key) {
-    const remaining = (this.pendingLoads.get(key) ?? 0) - 1;
+  endPendingLoad(key, generation) {
+    const generations = this.pendingLoads.get(key);
+    if (!generations) {
+      return;
+    }
+    const remaining = (generations.get(generation) ?? 0) - 1;
     if (remaining > 0) {
-      this.pendingLoads.set(key, remaining);
+      generations.set(generation, remaining);
       return;
     }
-    this.pendingLoads.delete(key);
+    generations.delete(generation);
+    if (generations.size === 0) {
+      this.pendingLoads.delete(key);
+    }
   }
   constructor(store, options) {
     this.store = store;
@@ -69,34 +80,45 @@ class CacheService {
    * @returns The cached or freshly loaded value.
    */
   async remember(key, loader, ttlSeconds) {
-    this.beginPendingLoad(key);
+    const resetVersion = this.resetVersion;
+    this.beginPendingLoad(key, resetVersion);
     try {
-      const resetVersion = this.resetVersion;
       const cached = await this.get(key);
       if (cached !== undefined) {
         return cached;
       }
       const existing = this.inflight.get(key);
       if (existing) {
-        return existing;
+        return existing.promise;
       }
+      const entry = {
+        generation: resetVersion,
+        invalidated: this.pendingInvalidations.get(key) === resetVersion,
+        promise: Promise.resolve(undefined)
+      };
       const promise = loader().then(async value => {
-        if (this.invalidatedInflight.has(key) || this.resetVersion !== resetVersion) {
+        if (entry.invalidated || this.resetVersion !== resetVersion) {
           return value;
         }
         await this.set(key, value, ttlSeconds);
-        if (this.invalidatedInflight.has(key) || this.resetVersion !== resetVersion) {
+        if (entry.invalidated || this.resetVersion !== resetVersion) {
           await this.store.del(key);
         }
         return value;
       }).finally(() => {
-        this.inflight.delete(key);
-        this.invalidatedInflight.delete(key);
+        if (this.inflight.get(key) === entry) {
+          this.inflight.delete(key);
+          this.invalidatedInflight.delete(key);
+        }
+        if (this.pendingInvalidations.get(key) === entry.generation) {
+          this.pendingInvalidations.delete(key);
+        }
       });
-      this.inflight.set(key, promise);
+      entry.promise = promise;
+      this.inflight.set(key, entry);
       return promise;
     } finally {
-      this.endPendingLoad(key);
+      this.endPendingLoad(key, resetVersion);
     }
   }
 
@@ -107,7 +129,12 @@ class CacheService {
    * @returns A promise that resolves after the entry is removed.
    */
   async del(key) {
-    if (this.pendingLoads.has(key) || this.inflight.has(key)) {
+    const entry = this.inflight.get(key);
+    if (entry) {
+      entry.invalidated = true;
+      this.invalidatedInflight.add(key);
+    } else if (this.pendingLoads.has(key)) {
+      this.pendingInvalidations.set(key, this.resetVersion);
       this.invalidatedInflight.add(key);
     }
     await this.store.del(key);
@@ -120,9 +147,44 @@ class CacheService {
    */
   async reset() {
     this.resetVersion += 1;
+    this.inflight.clear();
+    this.pendingLoads.clear();
+    this.pendingInvalidations.clear();
     this.invalidatedInflight.clear();
     await this.store.reset();
   }
+
+  /**
+   * Close the configured store when it exposes an optional teardown hook.
+   *
+   * @returns A promise that resolves after store teardown completes.
+   */
+  async close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    this.inflight.clear();
+    this.pendingLoads.clear();
+    this.pendingInvalidations.clear();
+    this.invalidatedInflight.clear();
+    if (this.store.close) {
+      await this.store.close();
+      return;
+    }
+    if (this.store.dispose) {
+      await this.store.dispose();
+    }
+  }
+
+  /**
+   * Runtime shutdown hook that releases resource-owning stores during application close.
+   *
+   * @returns A promise that resolves after store teardown completes.
+   */
+  onModuleDestroy() {
+    return this.close();
+  }
   static {
     _initClass();
   }

package/dist/types.d.ts

@@ -8,6 +8,14 @@ export interface CacheStore {
     set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
     del(key: string): Promise<void>;
     reset(): Promise<void>;
+    /**
+     * Optional lifecycle hook for stores that own sockets, pools, timers, or other resources.
+     */
+    close?(): Awaitable<void>;
+    /**
+     * Optional lifecycle hook accepted as an alias for resource-owning stores that expose dispose semantics.
+     */
+    dispose?(): Awaitable<void>;
 }
 /**
  * Redis client subset required by `RedisStore`.

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

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