@jintianxiayu/cache-decorator 0.1.2

package/README.md

@@ -0,0 +1,133 @@
+# @jintianxiayu/cache-decorator
+
+方法缓存装饰器，为 TypeScript 方法提供声明式缓存功能。
+
+## 安装
+
+```bash
+npm install @jintianxiayu/cache-decorator reflect-metadata
+```
+
+## 特性
+
+- `@Cache` 装饰器：方法缓存，支持 TTL 过期
+- `@CacheEvict` 装饰器：缓存清除
+- 可插拔的缓存后端（Memory / Redis / 自定义）
+- 请求合并：并发场景下返回同一个 Promise
+- 错误结果缓存：防止缓存穿透
+
+## 重要提示
+
+> ⚠️ **@Cache 和 @CacheEvict 装饰器仅适用于返回 Promise 的方法**
+>
+> 这两个装饰器都会将被装饰的方法替换为异步函数。如果装饰返回非 Promise 的同步方法，调用方会收到 Promise 对象而非期望的返回值，导致难以排查的 bug。
+>
+> ```typescript
+> // ✅ 正确：async 方法或返回 Promise 的方法
+> @Cache('data')
+> async getData() { ... }
+>
+> @CacheEvict('data')
+> async clearData() { ... }
+>
+> // ❌ 错误：返回非 Promise 的同步方法不要使用这些装饰器
+> @Cache('data')
+> getData() { return 'result'; }  // 调用方得到 Promise，不是 'result'
+> ```
+
+## 使用示例
+
+```typescript
+import 'reflect-metadata';
+import { Cache, CacheEvict, CacheProviderRegistry, MemoryCacheProvider } from '@jintianxiayu/cache-decorator';
+
+// 注册默认 Provider
+CacheProviderRegistry.register('memory', new MemoryCacheProvider());
+CacheProviderRegistry.setDefault('memory');
+
+class UserService {
+  @Cache('user-cache', { ttl: 60000 })
+  async getUser(id: number) {
+    return { id, name: 'test' };
+  }
+
+  @CacheEvict('user-cache')
+  async updateUser(id: number) {
+    return { id, updated: true };
+  }
+}
+```
+
+### 自定义缓存 Key
+
+通过 `key` 选项自定义缓存 key 生成逻辑：
+
+```typescript
+class UserService {
+  // 使用字符串作为 key，所有调用共享同一缓存
+  @Cache('config', { key: 'global-config' })
+  async getConfig() {
+    return { ... };
+  }
+
+  // 使用函数基于参数生成 key
+  @Cache('user', { key: (...args) => String(args[0]) })
+  async getUser(id: number) {
+    return { id };
+  }
+
+  // 清除时使用相同的 key 函数
+  @CacheEvict('user', { key: (...args) => String(args[0]) })
+  async deleteUser(id: number) {
+    return { id, deleted: true };
+  }
+}
+```
+
+
+
+## API
+
+### @Cache(cacheName, options?)
+
+缓存装饰器。**必须用于 async 方法**。
+
+- `cacheName`: 缓存名称
+- `options.ttl`: 过期时间（秒）
+- `options.providerName`: 指定 CacheProvider
+- `options.key`: 自定义缓存 key，支持以下形式：
+  - `undefined/null`: 使用默认逻辑，基于方法参数生成 key
+  - `string`: 直接作为 key 值，格式为 `cacheName:keyValue`
+  - `function`: 接收方法参数数组，返回自定义字符串
+
+### @CacheEvict(cacheName, options?)
+
+缓存清除装饰器。**必须用于返回 Promise 的方法**。
+
+- `cacheName`: 缓存名称
+- `options.allEntries`: 清除该缓存名称下的所有条目（而非所有缓存），默认 false
+- `options.providerName`: 指定 CacheProvider
+- `options.key`: 自定义缓存 key，与 `@Cache` 行为一致。当 `allEntries: true` 时忽略
+
+### CacheProviderRegistry
+
+全局缓存提供者注册表。
+
+```typescript
+CacheProviderRegistry.register('memory', new MemoryCacheProvider());
+CacheProviderRegistry.setDefault('memory');
+CacheProviderRegistry.get('memory');
+```
+
+### MemoryCacheProvider
+
+内存 Map 实现，适用于单机应用。
+
+### RedisCacheProvider
+
+Redis 实现，适用于分布式场景。
+
+```typescript
+import Redis from 'ioredis';
+const redisProvider = new RedisCacheProvider(new Redis());
+```

package/dist/core/cache-provider-registry.d.ts

@@ -0,0 +1,30 @@
+import { CacheProvider } from './cache-provider';
+/**
+ * 全局缓存提供者注册表
+ * 用于注册和获取不同类型的 CacheProvider
+ */
+export declare class CacheProviderRegistry {
+    /**
+     * 注册缓存提供者
+     * @param name 提供者名称
+     * @param provider 缓存提供者实例
+     */
+    static register(name: string, provider: CacheProvider): void;
+    /**
+     * 获取缓存提供者
+     * @param name 提供者名称，不指定则使用默认提供者
+     * @returns 缓存提供者实例
+     * @throws 未注册且无默认提供者时抛出错误
+     */
+    static get(name?: string): CacheProvider;
+    /**
+     * 设置默认缓存提供者
+     * @param name 提供者名称
+     */
+    static setDefault(name: string): void;
+    /**
+     * 清空注册表
+     */
+    static clear(): void;
+}
+//# sourceMappingURL=cache-provider-registry.d.ts.map

package/dist/core/cache-provider-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-provider-registry.d.ts","sourceRoot":"","sources":["../../src/core/cache-provider-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAKjD;;;GAGG;AACH,qBAAa,qBAAqB;IAChC;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI;IAI5D;;;;;OAKG;IACH,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,aAAa;IAYxC;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIrC;;OAEG;IACH,MAAM,CAAC,KAAK,IAAI,IAAI;CAIrB"}

package/dist/core/cache-provider-registry.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheProviderRegistry = void 0;
+const providers = new Map();
+let defaultName;
+/**
+ * 全局缓存提供者注册表
+ * 用于注册和获取不同类型的 CacheProvider
+ */
+class CacheProviderRegistry {
+    /**
+     * 注册缓存提供者
+     * @param name 提供者名称
+     * @param provider 缓存提供者实例
+     */
+    static register(name, provider) {
+        providers.set(name, provider);
+    }
+    /**
+     * 获取缓存提供者
+     * @param name 提供者名称，不指定则使用默认提供者
+     * @returns 缓存提供者实例
+     * @throws 未注册且无默认提供者时抛出错误
+     */
+    static get(name) {
+        const providerName = name || defaultName;
+        if (!providerName) {
+            throw new Error('No CacheProvider registered and no default set');
+        }
+        const provider = providers.get(providerName);
+        if (!provider) {
+            throw new Error(`CacheProvider "${providerName}" not found`);
+        }
+        return provider;
+    }
+    /**
+     * 设置默认缓存提供者
+     * @param name 提供者名称
+     */
+    static setDefault(name) {
+        defaultName = name;
+    }
+    /**
+     * 清空注册表
+     */
+    static clear() {
+        providers.clear();
+        defaultName = undefined;
+    }
+}
+exports.CacheProviderRegistry = CacheProviderRegistry;
+//# sourceMappingURL=cache-provider-registry.js.map

package/dist/core/cache-provider-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-provider-registry.js","sourceRoot":"","sources":["../../src/core/cache-provider-registry.ts"],"names":[],"mappings":";;;AAEA,MAAM,SAAS,GAAG,IAAI,GAAG,EAAyB,CAAC;AACnD,IAAI,WAA+B,CAAC;AAEpC;;;GAGG;AACH,MAAa,qBAAqB;IAChC;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAY,EAAE,QAAuB;QACnD,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAChC,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,GAAG,CAAC,IAAa;QACtB,MAAM,YAAY,GAAG,IAAI,IAAI,WAAW,CAAC;QACzC,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,CAAC;QACD,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QAC7C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,kBAAkB,YAAY,aAAa,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,IAAY;QAC5B,WAAW,GAAG,IAAI,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAK;QACV,SAAS,CAAC,KAAK,EAAE,CAAC;QAClB,WAAW,GAAG,SAAS,CAAC;IAC1B,CAAC;CACF;AA3CD,sDA2CC"}

package/dist/core/cache-provider.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 缓存提供者接口，定义缓存存储后端的统一契约
+ * 支持可插拔的缓存实现（Memory、Redis、自定义）
+ */
+export interface CacheProvider {
+    /**
+     * 获取缓存值
+     * @param key 缓存键
+     * @returns 缓存值，不存在或已过期返回 undefined
+     */
+    get<T>(key: string): T | undefined | Promise<T | undefined>;
+    /**
+     * 设置缓存值
+     * @param key 缓存键
+     * @param value 缓存值
+     * @param ttl 过期时间（秒），不设置则永不过期
+     */
+    set<T>(key: string, value: T, ttl?: number): void | Promise<void>;
+    /**
+     * 删除指定缓存
+     * @param key 缓存键
+     */
+    delete(key: string): void | Promise<void>;
+    /**
+     * 清除所有缓存
+     */
+    clear(): void | Promise<void>;
+    /**
+     * 根据模式删除匹配的缓存键
+     * @param pattern glob模式字符串（如 user:*），末尾的 * 作为前缀匹配
+     */
+    deleteByPattern(pattern: string): void | Promise<void>;
+}
+//# sourceMappingURL=cache-provider.d.ts.map

package/dist/core/cache-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-provider.d.ts","sourceRoot":"","sources":["../../src/core/cache-provider.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAE5D;;;;;OAKG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElE;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C;;OAEG;IACH,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9B;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD"}

package/dist/core/cache-provider.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=cache-provider.js.map

package/dist/core/cache-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-provider.js","sourceRoot":"","sources":["../../src/core/cache-provider.ts"],"names":[],"mappings":""}

package/dist/core/key-builder.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 缓存 Key 构建器
+ * 负责将缓存名称和参数转换为统一的 key 字符串
+ */
+export declare class KeyBuilder {
+    /**
+     * 构建缓存 key
+     * @param cacheName 缓存名称
+     * @param args 方法参数列表
+     * @returns 格式为 {cacheName}:{serializedArgs} 的 key 字符串
+     */
+    static build(cacheName: string, args: unknown[]): string;
+}
+//# sourceMappingURL=key-builder.d.ts.map

package/dist/core/key-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-builder.d.ts","sourceRoot":"","sources":["../../src/core/key-builder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,UAAU;IACrB;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM;CAmBzD"}

package/dist/core/key-builder.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyBuilder = void 0;
+/**
+ * 缓存 Key 构建器
+ * 负责将缓存名称和参数转换为统一的 key 字符串
+ */
+class KeyBuilder {
+    /**
+     * 构建缓存 key
+     * @param cacheName 缓存名称
+     * @param args 方法参数列表
+     * @returns 格式为 {cacheName}:{serializedArgs} 的 key 字符串
+     */
+    static build(cacheName, args) {
+        if (args.length === 0) {
+            return cacheName;
+        }
+        const serializedArgs = args
+            .map(arg => {
+            if (arg === null || arg === undefined)
+                return 'null';
+            if (typeof arg === 'object') {
+                try {
+                    return JSON.stringify(arg);
+                }
+                catch {
+                    return String(arg);
+                }
+            }
+            return String(arg);
+        })
+            .join('&');
+        return `${cacheName}:${serializedArgs}`;
+    }
+}
+exports.KeyBuilder = KeyBuilder;
+//# sourceMappingURL=key-builder.js.map

package/dist/core/key-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-builder.js","sourceRoot":"","sources":["../../src/core/key-builder.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,MAAa,UAAU;IACrB;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,SAAiB,EAAE,IAAe;QAC7C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,cAAc,GAAG,IAAI;aACxB,GAAG,CAAC,GAAG,CAAC,EAAE;YACT,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS;gBAAE,OAAO,MAAM,CAAC;YACrD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAC5B,IAAI,CAAC;oBACH,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;gBAC7B,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;gBACrB,CAAC;YACH,CAAC;YACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC,CAAC;aACD,IAAI,CAAC,GAAG,CAAC,CAAC;QACb,OAAO,GAAG,SAAS,IAAI,cAAc,EAAE,CAAC;IAC1C,CAAC;CACF;AA1BD,gCA0BC"}

package/dist/core/native-cache.d.ts

@@ -0,0 +1,18 @@
+import { CacheProvider } from './cache-provider';
+/**
+ * 内存缓存提供者，基于 Map 实现
+ * 适用于单机应用，缓存随进程重启清除
+ */
+export declare class MemoryCacheProvider implements CacheProvider {
+    private cache;
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T, ttl?: number): void;
+    delete(key: string): void;
+    clear(): void;
+    /**
+     * 根据模式删除匹配的缓存键
+     * @param pattern glob模式字符串（如 user:*），末尾的 * 作为前缀匹配
+     */
+    deleteByPattern(pattern: string): void;
+}
+//# sourceMappingURL=native-cache.d.ts.map

package/dist/core/native-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-cache.d.ts","sourceRoot":"","sources":["../../src/core/native-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAUjD;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IACvD,OAAO,CAAC,KAAK,CAA0C;IAEvD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAUlC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAKjD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,KAAK,IAAI,IAAI;IAIb;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAQvC"}

package/dist/core/native-cache.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryCacheProvider = void 0;
+/**
+ * 内存缓存提供者，基于 Map 实现
+ * 适用于单机应用，缓存随进程重启清除
+ */
+class MemoryCacheProvider {
+    constructor() {
+        this.cache = new Map();
+    }
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value, ttl) {
+        const expiresAt = ttl ? Date.now() + ttl * 1000 : null;
+        this.cache.set(key, { value, expiresAt });
+    }
+    delete(key) {
+        this.cache.delete(key);
+    }
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * 根据模式删除匹配的缓存键
+     * @param pattern glob模式字符串（如 user:*），末尾的 * 作为前缀匹配
+     */
+    deleteByPattern(pattern) {
+        const prefix = pattern.replace(/\*$/, '');
+        for (const key of this.cache.keys()) {
+            if (key.startsWith(prefix)) {
+                this.cache.delete(key);
+            }
+        }
+    }
+}
+exports.MemoryCacheProvider = MemoryCacheProvider;
+//# sourceMappingURL=native-cache.js.map

package/dist/core/native-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-cache.js","sourceRoot":"","sources":["../../src/core/native-cache.ts"],"names":[],"mappings":";;;AAUA;;;GAGG;AACH,MAAa,mBAAmB;IAAhC;QACU,UAAK,GAAG,IAAI,GAAG,EAA+B,CAAC;IAqCzD,CAAC;IAnCC,GAAG,CAAI,GAAW;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC7B,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YAC7D,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,KAAK,CAAC,KAAU,CAAC;IAC1B,CAAC;IAED,GAAG,CAAI,GAAW,EAAE,KAAQ,EAAE,GAAY;QACxC,MAAM,SAAS,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QACvD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,OAAe;QAC7B,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC1C,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YACpC,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC3B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAtCD,kDAsCC"}

package/dist/core/pending-cache.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 请求合并缓存
+ * 用于在并发场景下返回同一个 Promise，避免重复执行
+ */
+export declare class PendingCache {
+    private pending;
+    get<T>(key: string): Promise<T> | undefined;
+    set<T>(key: string, promise: Promise<T>): void;
+    delete(key: string): void;
+    clear(): void;
+}
+//# sourceMappingURL=pending-cache.d.ts.map

package/dist/core/pending-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-cache.d.ts","sourceRoot":"","sources":["../../src/core/pending-cache.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAuC;IAEtD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS;IAI3C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;IAO9C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,KAAK,IAAI,IAAI;CAGd"}

package/dist/core/pending-cache.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PendingCache = void 0;
+/**
+ * 请求合并缓存
+ * 用于在并发场景下返回同一个 Promise，避免重复执行
+ */
+class PendingCache {
+    constructor() {
+        this.pending = new Map();
+    }
+    get(key) {
+        return this.pending.get(key);
+    }
+    set(key, promise) {
+        this.pending.set(key, promise);
+        promise.finally(() => {
+            this.pending.delete(key);
+        });
+    }
+    delete(key) {
+        this.pending.delete(key);
+    }
+    clear() {
+        this.pending.clear();
+    }
+}
+exports.PendingCache = PendingCache;
+//# sourceMappingURL=pending-cache.js.map

package/dist/core/pending-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-cache.js","sourceRoot":"","sources":["../../src/core/pending-cache.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,MAAa,YAAY;IAAzB;QACU,YAAO,GAAG,IAAI,GAAG,EAA4B,CAAC;IAoBxD,CAAC;IAlBC,GAAG,CAAI,GAAW;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAA2B,CAAC;IACzD,CAAC;IAED,GAAG,CAAI,GAAW,EAAE,OAAmB;QACrC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC/B,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE;YACnB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;CACF;AArBD,oCAqBC"}

package/dist/core/redis-cache.d.ts

@@ -0,0 +1,20 @@
+import { CacheProvider } from './cache-provider';
+import Redis from 'ioredis';
+/**
+ * Redis 缓存提供者，基于 ioredis 实现
+ * 适用于分布式场景，支持跨进程共享缓存
+ */
+export declare class RedisCacheProvider implements CacheProvider {
+    private redis;
+    constructor(redis?: Redis);
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    /**
+     * 根据模式删除匹配的缓存键
+     * @param pattern glob模式字符串（如 user:*），使用 SCAN 游标迭代避免阻塞 Redis
+     */
+    deleteByPattern(pattern: string): Promise<void>;
+}
+//# sourceMappingURL=redis-cache.d.ts.map

package/dist/core/redis-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-cache.d.ts","sourceRoot":"","sources":["../../src/core/redis-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,MAAM,SAAS,CAAC;AAE5B;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,aAAa;IACtD,OAAO,CAAC,KAAK,CAAQ;gBAET,KAAK,CAAC,EAAE,KAAK;IAInB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAU3C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS1D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;OAGG;IACG,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAgBtD"}

package/dist/core/redis-cache.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisCacheProvider = void 0;
+const ioredis_1 = __importDefault(require("ioredis"));
+/**
+ * Redis 缓存提供者，基于 ioredis 实现
+ * 适用于分布式场景，支持跨进程共享缓存
+ */
+class RedisCacheProvider {
+    constructor(redis) {
+        this.redis = redis ?? new ioredis_1.default();
+    }
+    async get(key) {
+        const value = await this.redis.get(key);
+        if (value === null)
+            return undefined;
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return value;
+        }
+    }
+    async set(key, value, ttl) {
+        const serialized = typeof value === 'string' ? value : JSON.stringify(value);
+        if (ttl) {
+            await this.redis.setex(key, ttl, serialized);
+        }
+        else {
+            await this.redis.set(key, serialized);
+        }
+    }
+    async delete(key) {
+        await this.redis.del(key);
+    }
+    async clear() {
+        await this.redis.flushdb();
+    }
+    /**
+     * 根据模式删除匹配的缓存键
+     * @param pattern glob模式字符串（如 user:*），使用 SCAN 游标迭代避免阻塞 Redis
+     */
+    async deleteByPattern(pattern) {
+        let cursor = '0';
+        do {
+            const [nextCursor, keys] = await this.redis.scan(cursor, 'MATCH', pattern, 'COUNT', 100);
+            cursor = nextCursor;
+            if (keys.length > 0) {
+                await this.redis.del(...keys);
+            }
+        } while (cursor !== '0');
+    }
+}
+exports.RedisCacheProvider = RedisCacheProvider;
+//# sourceMappingURL=redis-cache.js.map

package/dist/core/redis-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-cache.js","sourceRoot":"","sources":["../../src/core/redis-cache.ts"],"names":[],"mappings":";;;;;;AACA,sDAA4B;AAE5B;;;GAGG;AACH,MAAa,kBAAkB;IAG7B,YAAY,KAAa;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,IAAI,IAAI,iBAAK,EAAE,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,GAAG,CAAI,GAAW;QACtB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,SAAS,CAAC;QACrC,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAM,CAAC;QAChC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAqB,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,KAAK,CAAC,GAAG,CAAI,GAAW,EAAE,KAAQ,EAAE,GAAY;QAC9C,MAAM,UAAU,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC7E,IAAI,GAAG,EAAE,CAAC;YACR,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;QAC/C,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;IAC7B,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,eAAe,CAAC,OAAe;QACnC,IAAI,MAAM,GAAG,GAAG,CAAC;QACjB,GAAG,CAAC;YACF,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAC9C,MAAM,EACN,OAAO,EACP,OAAO,EACP,OAAO,EACP,GAAG,CACJ,CAAC;YACF,MAAM,GAAG,UAAU,CAAC;YACpB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpB,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;YAChC,CAAC;QACH,CAAC,QAAQ,MAAM,KAAK,GAAG,EAAE;IAC3B,CAAC;CACF;AAtDD,gDAsDC"}

package/dist/decorators/cache-evict.d.ts

@@ -0,0 +1,23 @@
+import { CacheOptions } from './cache';
+/**
+ * @CacheEvict 装饰器配置项
+ */
+export interface CacheEvictOptions extends Pick<CacheOptions, 'key'> {
+    /**
+     * 是否清除所有条目，默认为 false
+     */
+    allEntries?: boolean;
+    /**
+     * 指定 CacheProvider 名称
+     */
+    providerName?: string;
+}
+/**
+ * 缓存清除装饰器
+ * 在方法执行后清除对应的缓存条目
+ * @param cacheName 缓存名称
+ * @param options 配置项
+ */
+export declare function CacheEvict(cacheName: string, options?: CacheEvictOptions): (_target: object, _propertyKey: string, descriptor: PropertyDescriptor) => void;
+export { CacheProviderRegistry } from '../core/cache-provider-registry';
+//# sourceMappingURL=cache-evict.d.ts.map

package/dist/decorators/cache-evict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-evict.d.ts","sourceRoot":"","sources":["../../src/decorators/cache-evict.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAoB,MAAM,SAAS,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC;IAClE;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAuBD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,IAErE,SAAS,MAAM,EACf,cAAc,MAAM,EACpB,YAAY,kBAAkB,UAoBjC;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/decorators/cache-evict.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheProviderRegistry = void 0;
+exports.CacheEvict = CacheEvict;
+const cache_provider_registry_1 = require("../core/cache-provider-registry");
+const key_builder_1 = require("../core/key-builder");
+/**
+ * 解析缓存 key
+ * @param cacheName 缓存名称
+ * @param keyResolver key 解析器
+ * @param args 方法参数数组
+ * @returns 解析后的缓存 key
+ */
+function resolveCacheKey(cacheName, keyResolver, args) {
+    if (keyResolver === undefined || keyResolver === null) {
+        return key_builder_1.KeyBuilder.build(cacheName, args);
+    }
+    if (typeof keyResolver === 'string') {
+        return key_builder_1.KeyBuilder.build(cacheName, [keyResolver]);
+    }
+    try {
+        return key_builder_1.KeyBuilder.build(cacheName, [keyResolver(...args)]);
+    }
+    catch {
+        return key_builder_1.KeyBuilder.build(cacheName, args);
+    }
+}
+/**
+ * 缓存清除装饰器
+ * 在方法执行后清除对应的缓存条目
+ * @param cacheName 缓存名称
+ * @param options 配置项
+ */
+function CacheEvict(cacheName, options) {
+    return function (_target, _propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (...args) {
+            const result = await originalMethod.apply(this, args);
+            const providerName = options?.providerName;
+            const provider = cache_provider_registry_1.CacheProviderRegistry.get(providerName);
+            if (options?.allEntries) {
+                await provider.deleteByPattern(cacheName + '*');
+            }
+            else {
+                const cacheKey = resolveCacheKey(cacheName, options?.key, args);
+                provider.delete(cacheKey);
+            }
+            return result;
+        };
+    };
+}
+var cache_provider_registry_2 = require("../core/cache-provider-registry");
+Object.defineProperty(exports, "CacheProviderRegistry", { enumerable: true, get: function () { return cache_provider_registry_2.CacheProviderRegistry; } });
+//# sourceMappingURL=cache-evict.js.map

package/dist/decorators/cache-evict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-evict.js","sourceRoot":"","sources":["../../src/decorators/cache-evict.ts"],"names":[],"mappings":";;;AA8CA,gCAwBC;AAtED,6EAAwE;AACxE,qDAAiD;AAkBjD;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,SAAiB,EAAE,WAAyC,EAAE,IAAe;IACpG,IAAI,WAAW,KAAK,SAAS,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;QACtD,OAAO,wBAAU,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC3C,CAAC;IACD,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;QACpC,OAAO,wBAAU,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,CAAC;QACH,OAAO,wBAAU,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,wBAAU,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC3C,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAgB,UAAU,CAAC,SAAiB,EAAE,OAA2B;IACvE,OAAO,UACL,OAAe,EACf,YAAoB,EACpB,UAA8B;QAE9B,MAAM,cAAc,GAAG,UAAU,CAAC,KAAK,CAAC;QAExC,UAAU,CAAC,KAAK,GAAG,KAAK,WAAW,GAAG,IAAe;YACnD,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAEtD,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,CAAC;YAC3C,MAAM,QAAQ,GAAG,+CAAqB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YAEzD,IAAI,OAAO,EAAE,UAAU,EAAE,CAAC;gBACxB,MAAM,QAAQ,CAAC,eAAe,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC;YAClD,CAAC;iBAAM,CAAC;gBACN,MAAM,QAAQ,GAAG,eAAe,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;gBAChE,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC5B,CAAC;YAED,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED,2EAAwE;AAA/D,gIAAA,qBAAqB,OAAA"}