@fluojs/cache-manager 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fluo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,189 @@
+# @fluojs/cache-manager
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+메모리(Memory) 및 Redis 저장소 어댑터를 지원하는 fluo 애플리케이션용 범용 캐시 관리 패키지입니다. 데코레이터 기반의 HTTP 응답 캐싱과 프로그래밍 방식의 애플리케이션 레벨 캐시 API를 모두 제공합니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+  - [HTTP 응답 캐싱](#http-응답-캐싱)
+  - [애플리케이션 레벨 캐싱](#애플리케이션-레벨-캐싱)
+- [공통 패턴](#공통-패턴)
+  - [Redis 저장소 사용](#redis-저장소-사용)
+  - [쿼리 매개변수 기반 캐싱](#쿼리-매개변수-기반-캐싱)
+  - [수동 모듈 조합](#수동-모듈-조합)
+- [공개 API 개요](#공개-api-개요)
+- [관련 패키지](#관련-패키지)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+npm install @fluojs/cache-manager
+```
+
+root `@fluojs/cache-manager` import는 memory-only 설치에서도 안전합니다. Redis peer는 Redis 저장소 경로를 명시적으로 선택할 때만 필요합니다.
+
+Redis 기반 캐싱을 사용하는 경우:
+
+```bash
+npm install @fluojs/cache-manager @fluojs/redis ioredis
+```
+
+## 사용 시점
+
+- 비용이 많이 드는 데이터베이스 쿼리나 외부 API 응답을 캐싱하고 싶을 때 사용합니다.
+- GET 응답을 캐싱하여 HTTP 성능을 향상시키고 싶을 때 적합합니다.
+- 여러 인스턴스 간에 캐시 상태를 공유해야 할 때(Redis 사용) 사용합니다.
+- "Remember" 패턴(값이 없으면 조회 후 캐싱)을 간편하게 구현하고 싶을 때 사용합니다.
+
+## 빠른 시작
+
+### HTTP 응답 캐싱
+
+`CacheModule`을 등록하고 컨트롤러에 `CacheInterceptor`를 사용합니다.
+
+내장 메모리 경로는 기본적으로 안전한 상한을 갖습니다. `ttl`을 생략하면 fluo는 기본 TTL 300초를 적용하고, 메모리 저장소의 live 엔트리가 1,000개를 넘으면 가장 오래된 키부터 제거합니다.
+
+```typescript
+import { Module } from '@fluojs/core';
+import { Controller, Get, UseInterceptors } from '@fluojs/http';
+import { CacheModule, CacheInterceptor, CacheTTL } from '@fluojs/cache-manager';
+
+@Controller('/products')
+class ProductController {
+  @Get('/')
+  @UseInterceptors(CacheInterceptor)
+  @CacheTTL(60) // 60초 동안 캐싱
+  list() {
+    return [{ id: 1, name: 'Product A' }];
+  }
+}
+
+@Module({
+  imports: [CacheModule.forRoot({ store: 'memory' })],
+  controllers: [ProductController],
+})
+class AppModule {}
+```
+
+### 애플리케이션 레벨 캐싱
+
+`CacheService`를 주입받아 프로그래밍 방식으로 캐시를 관리합니다.
+
+```typescript
+import { Inject } from '@fluojs/core';
+import { CacheService } from '@fluojs/cache-manager';
+
+class UserService {
+  constructor(@Inject(CacheService) private readonly cache: CacheService) {}
+
+  async getProfile(userId: string) {
+    return this.cache.remember(`user:${userId}`, async () => {
+      // 캐시에 값이 없을 때만 이 로직이 실행됩니다.
+      return fetchUserProfile(userId);
+    }, 300); // 5분
+  }
+}
+```
+
+## 공통 패턴
+
+### Redis 저장소 사용
+
+Redis를 사용하려면 `@fluojs/redis`가 설정되어 있어야 하며, `store` 옵션을 `'redis'`로 설정합니다.
+
+memory-only 소비자는 `@fluojs/redis`나 `ioredis`를 설치하지 않아도 `@fluojs/cache-manager`를 계속 import할 수 있습니다. 이 optional peer들은 Redis 저장소 경로를 선택할 때만 해석됩니다.
+
+```typescript
+CacheModule.forRoot({
+  store: 'redis',
+  ttl: 600,
+})
+```
+
+여러 Redis 클라이언트를 등록했다면 `redis.clientName`으로 사용할 `@fluojs/redis` 연결을 지정할 수 있습니다.
+
+`redis.clientName`을 생략하면 `REDIS_CLIENT`를 통해 해석되는 기본 Redis 클라이언트를 계속 사용합니다.
+
+```typescript
+CacheModule.forRoot({
+  store: 'redis',
+  redis: { clientName: 'cache' },
+})
+```
+
+`redis.client`는 여전히 가장 높은 우선순위의 명시적 override입니다. DI 기반 선택을 완전히 우회해야 할 때만 사용하세요.
+
+내장 `RedisStore`는 엔트리를 `JSON.stringify(...)`로 저장합니다. 따라서 캐시 값은 JSON 호환 형태여야 합니다. 일반 객체, 배열, 문자열, 숫자, 불리언, `null`은 안정적으로 round-trip 되지만, `Date`는 JSON 결과(예: ISO 문자열)로 돌아오고, 함수/`undefined`/`symbol`은 유지되지 않으며, `bigint`나 순환 그래프처럼 직렬화 불가능한 값은 캐싱 전에 정규화해야 합니다.
+
+### 쿼리 매개변수 기반 캐싱
+
+기본적으로 캐시 키는 쿼리 매개변수를 무시합니다. 검색 조건 등에 따라 다른 응답을 캐싱하려면 `httpKeyStrategy: 'route+query'`를 활성화하세요.
+
+```typescript
+CacheModule.forRoot({
+  store: 'memory',
+  httpKeyStrategy: 'route+query',
+})
+```
+
+### 수동 모듈 조합
+
+일반적인 애플리케이션 설정과 커스텀 `defineModule(...)` 조합에서는 `CacheModule.forRoot(...)`를 사용합니다.
+
+```typescript
+import { defineModule } from '@fluojs/runtime';
+import { CacheInterceptor, CacheModule, CacheService } from '@fluojs/cache-manager';
+
+class ManualCacheModule {}
+
+defineModule(ManualCacheModule, {
+  exports: [CacheService, CacheInterceptor],
+  imports: [CacheModule.forRoot({ store: 'memory', ttl: 60 })],
+});
+```
+
+### 메모리 저장소 운영 한계
+
+내장 메모리 저장소는 단일 프로세스의 bounded cache 용도로 설계되어 있습니다.
+
+- 기본 메모리 경로에서 `ttl`을 생략하면 `CacheModule.forRoot()`는 300초 TTL을 사용합니다.
+- `ttl: 0`은 만료 없는 엔트리로 계속 지원되지만, 메모리 저장소는 가장 최근의 live 키 1,000개만 유지합니다.
+- 키 종류가 매우 많거나 여러 인스턴스가 캐시를 공유해야 한다면 프로세스 로컬 메모리 대신 Redis 저장소를 사용하세요.
+
+### 지연 삭제 시점
+
+`@CacheEvict(...)`가 붙은 non-GET 핸들러는 응답이 성공적으로 commit된 뒤에 캐시를 삭제합니다. 어댑터 경로가 `response.send(...)`를 호출하지 않더라도, 인터셉터는 bounded fallback timer를 통해 성공한 쓰기 이후 stale 엔트리가 무기한 남지 않도록 보장합니다. 또한 지연 eviction 실패는 인터셉터 내부에 containment되어 cache key factory나 cache store 삭제 오류가 응답 이후 unhandled promise rejection으로 노출되지 않습니다.
+
+## 공개 API 개요
+
+### 모듈
+- `CacheModule.forRoot(options)`: 캐시 저장소(memory/redis), 기본 TTL, 키 전략 등을 설정합니다.
+  애플리케이션 모듈에서 사용하는 기본 패키지 진입점입니다.
+
+
+### 서비스
+- `CacheService`: 수동 캐시 작업(`get`, `set`, `del`, `remember`, `reset`)을 위한 기본 API입니다.
+
+### 데코레이터
+- `@CacheTTL(seconds)`: 특정 핸들러의 TTL을 설정합니다.
+- `@CacheKey(key)`: 특정 핸들러의 커스텀 캐시 키를 설정합니다.
+- `@CacheEvict(key)`: 성공적인 데이터 변경(POST/PUT/DELETE) 후 특정 캐시 키를 삭제합니다.
+
+### 인터셉터
+- `CacheInterceptor`: 자동 GET 응답 캐싱 및 삭제 로직을 처리합니다.
+
+## 관련 패키지
+
+- `@fluojs/redis`: Redis 저장소 사용 시 필요합니다.
+- `@fluojs/http`: HTTP 인터셉터 및 데코레이터 사용 시 필요합니다.
+
+## 예제 소스
+
+- `packages/cache-manager/src/module.test.ts`: 모듈 설정 및 프로바이더 테스트.
+- `packages/cache-manager/src/interceptor.test.ts`: HTTP 캐싱 및 삭제 테스트.
+- `packages/cache-manager/src/service.ts`: 코어 `CacheService` 구현.

package/README.md

@@ -0,0 +1,189 @@
+# @fluojs/cache-manager
+
+<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.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [When to Use](#when-to-use)
+- [Quick Start](#quick-start)
+  - [HTTP Response Caching](#http-response-caching)
+  - [Application-Level Caching](#application-level-caching)
+- [Common Patterns](#common-patterns)
+  - [Redis Storage](#redis-storage)
+  - [Query-Sensitive Caching](#query-sensitive-caching)
+  - [Manual Module Composition](#manual-module-composition)
+- [Public API Overview](#public-api-overview)
+- [Related Packages](#related-packages)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+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.
+
+For Redis-backed caching:
+
+```bash
+npm install @fluojs/cache-manager @fluojs/redis ioredis
+```
+
+## When to Use
+
+- When you want to cache expensive database queries or external API responses.
+- When you need to improve HTTP performance by caching GET responses.
+- When you need to share cache state across multiple instances (using Redis).
+- When you need a simple "remember" pattern (fetch if missing, then cache).
+
+## Quick Start
+
+### HTTP Response Caching
+
+Register the `CacheModule` and use the `CacheInterceptor` on your controllers.
+
+The built-in memory path is intentionally bounded by default: when you omit `ttl`, fluo applies a 300-second default TTL and keeps at most 1,000 live memory-store entries before evicting the oldest keys.
+
+```typescript
+import { Module } from '@fluojs/core';
+import { Controller, Get, UseInterceptors } from '@fluojs/http';
+import { CacheModule, CacheInterceptor, CacheTTL } from '@fluojs/cache-manager';
+
+@Controller('/products')
+class ProductController {
+  @Get('/')
+  @UseInterceptors(CacheInterceptor)
+  @CacheTTL(60) // Cache for 60 seconds
+  list() {
+    return [{ id: 1, name: 'Product A' }];
+  }
+}
+
+@Module({
+  imports: [CacheModule.forRoot({ store: 'memory' })],
+  controllers: [ProductController],
+})
+class AppModule {}
+```
+
+### Application-Level Caching
+
+Inject `CacheService` to manage cache programmatically.
+
+```typescript
+import { Inject } from '@fluojs/core';
+import { CacheService } from '@fluojs/cache-manager';
+
+class UserService {
+  constructor(@Inject(CacheService) private readonly cache: CacheService) {}
+
+  async getProfile(userId: string) {
+    return this.cache.remember(`user:${userId}`, async () => {
+      // This runs only if the key is missing from cache
+      return fetchUserProfile(userId);
+    }, 300); // 5 minutes
+  }
+}
+```
+
+## Common Patterns
+
+### Redis Storage
+
+To use Redis, ensure `@fluojs/redis` is configured and set the store to `'redis'`.
+
+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,
+})
+```
+
+If you registered multiple Redis clients, set `redis.clientName` to target a named `@fluojs/redis` connection.
+
+Leave `redis.clientName` unset to keep using the default Redis client resolved through `REDIS_CLIENT`.
+
+```typescript
+CacheModule.forRoot({
+  store: 'redis',
+  redis: { clientName: 'cache' },
+})
+```
+
+`redis.client` remains the highest-precedence override. Use it only when you need to bypass DI-based client selection entirely.
+
+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.
+
+### Query-Sensitive Caching
+
+By default, the cache key ignores query parameters. Enable `httpKeyStrategy: 'route+query'` to cache different responses for different search parameters.
+
+```typescript
+CacheModule.forRoot({
+  store: 'memory',
+  httpKeyStrategy: 'route+query',
+})
+```
+
+### Manual Module Composition
+
+Use `CacheModule.forRoot(...)` for normal application setup, including custom `defineModule(...)` composition.
+
+```typescript
+import { defineModule } from '@fluojs/runtime';
+import { CacheInterceptor, CacheModule, CacheService } from '@fluojs/cache-manager';
+
+class ManualCacheModule {}
+
+defineModule(ManualCacheModule, {
+  exports: [CacheService, CacheInterceptor],
+  imports: [CacheModule.forRoot({ store: 'memory', ttl: 60 })],
+});
+```
+
+### Memory Store Operational Limits
+
+The built-in memory store is designed for single-process, bounded caching:
+
+- If you omit `ttl` on the default memory path, `CacheModule.forRoot()` uses a 300-second TTL.
+- `ttl: 0` is still supported for no-expiry entries, but the memory store keeps only the most recent 1,000 live keys.
+- High-cardinality or multi-instance deployments should use the Redis store instead of relying on process-local memory.
+
+### Deferred eviction timing
+
+For non-GET handlers decorated with `@CacheEvict(...)`, eviction is deferred until the response successfully commits. 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.
+
+## Public API Overview
+
+### Modules
+- `CacheModule.forRoot(options)`: Configures the cache store (memory/redis), default TTL, and key strategies.
+  This is the primary package entrypoint for application modules.
+
+
+### Services
+- `CacheService`: Main API for manual cache operations (`get`, `set`, `del`, `remember`, `reset`).
+
+### 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).
+
+### Interceptors
+- `CacheInterceptor`: Handles automatic GET response caching and eviction logic.
+
+## Related Packages
+
+- `@fluojs/redis`: Required for Redis storage.
+- `@fluojs/http`: Required for HTTP interceptors and decorators.
+
+## Example Sources
+
+- `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.

package/dist/clone.d.ts

@@ -0,0 +1,2 @@
+export declare function cloneCacheValue<T>(value: T): T;
+//# sourceMappingURL=clone.d.ts.map

package/dist/clone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clone.d.ts","sourceRoot":"","sources":["../src/clone.ts"],"names":[],"mappings":"AAAA,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAE9C"}

package/dist/clone.js

@@ -0,0 +1,3 @@
+export function cloneCacheValue(value) {
+  return structuredClone(value);
+}

package/dist/decorators.d.ts

@@ -0,0 +1,70 @@
+import type { CacheEvictDecoratorValue, CacheKeyDecoratorValue } from './types.js';
+/** Shared controller metadata key used to store per-route cache metadata records. */
+export declare const cacheRouteMetadataKey: unique symbol;
+type StandardMetadataBag = Record<PropertyKey, unknown>;
+type StandardMethodDecoratorFn = (value: Function, context: ClassMethodDecoratorContext) => void;
+/**
+ * Override the computed cache key for a GET handler.
+ *
+ * @param key Static cache key or resolver invoked with the interceptor context.
+ * @returns A method decorator that stores cache-key metadata for the handler.
+ *
+ * @example
+ * ```ts
+ * @CacheKey('/products:featured')
+ * @Get('/featured')
+ * listFeatured() {}
+ * ```
+ */
+export declare function CacheKey(key: CacheKeyDecoratorValue): StandardMethodDecoratorFn;
+/**
+ * Override the cache TTL for a GET handler.
+ *
+ * @param ttlSeconds Cache lifetime in seconds. Use `0` to disable expiration.
+ * @returns A method decorator that stores per-handler TTL metadata.
+ *
+ * @example
+ * ```ts
+ * @CacheTTL(60)
+ * @Get('/')
+ * listProducts() {}
+ * ```
+ */
+export declare function CacheTTL(ttlSeconds: number): StandardMethodDecoratorFn;
+/**
+ * Evict one or more cache entries after a successful non-GET handler completes.
+ *
+ * @param value Static key list or resolver that derives eviction targets from the request/result.
+ * @returns A method decorator that stores eviction metadata for the handler.
+ *
+ * @example
+ * ```ts
+ * @CacheEvict('/products')
+ * @Post('/refresh')
+ * refresh() {}
+ * ```
+ */
+export declare function CacheEvict(value: CacheEvictDecoratorValue): StandardMethodDecoratorFn;
+/**
+ * Read `@CacheKey(...)` metadata from a method metadata bag.
+ *
+ * @param bag Route-level metadata bag captured from the controller.
+ * @returns The stored cache-key override, if present.
+ */
+export declare function getCacheKeyMetadata(bag: StandardMetadataBag): CacheKeyDecoratorValue | undefined;
+/**
+ * Read `@CacheTTL(...)` metadata from a method metadata bag.
+ *
+ * @param bag Route-level metadata bag captured from the controller.
+ * @returns The stored TTL override in seconds, if present.
+ */
+export declare function getCacheTtlMetadata(bag: StandardMetadataBag): number | undefined;
+/**
+ * Read `@CacheEvict(...)` metadata from a method metadata bag.
+ *
+ * @param bag Route-level metadata bag captured from the controller.
+ * @returns A defensive copy of the eviction metadata, if present.
+ */
+export declare function getCacheEvictMetadata(bag: StandardMetadataBag): CacheEvictDecoratorValue | undefined;
+export {};
+//# sourceMappingURL=decorators.d.ts.map

package/dist/decorators.d.ts.map

@@ -0,0 +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"}

package/dist/decorators.js

@@ -0,0 +1,120 @@
+/** 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');
+function getMetadataBag(metadata) {
+  return metadata;
+}
+function getRouteRecord(metadata, name) {
+  const bag = getMetadataBag(metadata);
+  let routeMap = bag[cacheRouteMetadataKey];
+  if (!routeMap) {
+    routeMap = new Map();
+    bag[cacheRouteMetadataKey] = routeMap;
+  }
+  let record = routeMap.get(name);
+  if (!record) {
+    record = {};
+    routeMap.set(name, record);
+  }
+  return record;
+}
+function cloneEvictValue(value) {
+  if (Array.isArray(value)) {
+    return [...value];
+  }
+  return value;
+}
+
+/**
+ * Override the computed cache key for a GET handler.
+ *
+ * @param key Static cache key or resolver invoked with the interceptor context.
+ * @returns A method decorator that stores cache-key metadata for the handler.
+ *
+ * @example
+ * ```ts
+ * @CacheKey('/products:featured')
+ * @Get('/featured')
+ * listFeatured() {}
+ * ```
+ */
+export function CacheKey(key) {
+  return (_value, context) => {
+    getRouteRecord(context.metadata, context.name)[cacheKeyMetadataKey] = key;
+  };
+}
+
+/**
+ * Override the cache TTL for a GET handler.
+ *
+ * @param ttlSeconds Cache lifetime in seconds. Use `0` to disable expiration.
+ * @returns A method decorator that stores per-handler TTL metadata.
+ *
+ * @example
+ * ```ts
+ * @CacheTTL(60)
+ * @Get('/')
+ * listProducts() {}
+ * ```
+ */
+export function CacheTTL(ttlSeconds) {
+  return (_value, context) => {
+    getRouteRecord(context.metadata, context.name)[cacheTtlMetadataKey] = ttlSeconds;
+  };
+}
+
+/**
+ * Evict one or more cache entries after a successful non-GET handler completes.
+ *
+ * @param value Static key list or resolver that derives eviction targets from the request/result.
+ * @returns A method decorator that stores eviction metadata for the handler.
+ *
+ * @example
+ * ```ts
+ * @CacheEvict('/products')
+ * @Post('/refresh')
+ * refresh() {}
+ * ```
+ */
+export function CacheEvict(value) {
+  return (_value, context) => {
+    getRouteRecord(context.metadata, context.name)[cacheEvictMetadataKey] = cloneEvictValue(value);
+  };
+}
+
+/**
+ * Read `@CacheKey(...)` metadata from a method metadata bag.
+ *
+ * @param bag Route-level metadata bag captured from the controller.
+ * @returns The stored cache-key override, if present.
+ */
+export function getCacheKeyMetadata(bag) {
+  return bag[cacheKeyMetadataKey];
+}
+
+/**
+ * Read `@CacheTTL(...)` metadata from a method metadata bag.
+ *
+ * @param bag Route-level metadata bag captured from the controller.
+ * @returns The stored TTL override in seconds, if present.
+ */
+export function getCacheTtlMetadata(bag) {
+  const ttl = bag[cacheTtlMetadataKey];
+  if (typeof ttl !== 'number') {
+    return undefined;
+  }
+  return ttl;
+}
+
+/**
+ * Read `@CacheEvict(...)` metadata from a method metadata bag.
+ *
+ * @param bag Route-level metadata bag captured from the controller.
+ * @returns A defensive copy of the eviction metadata, if present.
+ */
+export function getCacheEvictMetadata(bag) {
+  const value = bag[cacheEvictMetadataKey];
+  return value ? cloneEvictValue(value) : undefined;
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from './decorators.js';
+export * from './interceptor.js';
+export * from './stores/memory-store.js';
+export * from './module.js';
+export * from './stores/redis-store.js';
+export * from './service.js';
+export * from './status.js';
+export * from './tokens.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from './decorators.js';
+export * from './interceptor.js';
+export * from './stores/memory-store.js';
+export * from './module.js';
+export * from './stores/redis-store.js';
+export * from './service.js';
+export * from './status.js';
+export * from './tokens.js';
+export * from './types.js';

package/dist/interceptor.d.ts

@@ -0,0 +1,20 @@
+import { type CallHandler, type Interceptor, type InterceptorContext } from '@fluojs/http';
+import { CacheService } from './service.js';
+import type { NormalizedCacheModuleOptions } from './types.js';
+/**
+ * Caches GET responses and evicts related entries after successful write operations.
+ */
+export declare class CacheInterceptor implements Interceptor {
+    private readonly cache;
+    private readonly options;
+    constructor(cache: CacheService, options: NormalizedCacheModuleOptions);
+    intercept(context: InterceptorContext, next: CallHandler): Promise<unknown>;
+    private interceptGet;
+    private evictAfterWrite;
+    private resolveEvictKeys;
+    private shouldCacheValue;
+    private safeGet;
+    private safeSet;
+    private safeDel;
+}
+//# sourceMappingURL=interceptor.d.ts.map

package/dist/interceptor.d.ts.map

@@ -0,0 +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"}