@jintianxiayu/cache-decorator 1.0.0 → 1.0.2

package/src/core/pending-cache.ts

@@ -1,29 +1,29 @@
-/**
- * 请求合并缓存
- * 用于在并发场景下返回同一个 Promise，避免重复执行
- */
-export class PendingCache {
-    private pending = new Map<string, Promise<unknown>>();
-
-    get<T>(key: string): Promise<T> | undefined {
-        return this.pending.get(key) as Promise<T> | undefined;
-    }
-
-    set<T>(key: string, promise: Promise<T>): void {
-        this.pending.set(key, promise);
-        const deleteSettledPromise = (): void => {
-            if (this.pending.get(key) === promise) {
-                this.pending.delete(key);
-            }
-        };
-        void promise.then(deleteSettledPromise, deleteSettledPromise);
-    }
-
-    delete(key: string): void {
-        this.pending.delete(key);
-    }
-
-    clear(): void {
-        this.pending.clear();
-    }
-}
+/**
+ * 请求合并缓存
+ * 用于在并发场景下返回同一个 Promise，避免重复执行
+ */
+export class PendingCache {
+    private pending = new Map<string, Promise<unknown>>();
+
+    get<T>(key: string): Promise<T> | undefined {
+        return this.pending.get(key) as Promise<T> | undefined;
+    }
+
+    set<T>(key: string, promise: Promise<T>): void {
+        this.pending.set(key, promise);
+        const deleteSettledPromise = (): void => {
+            if (this.pending.get(key) === promise) {
+                this.pending.delete(key);
+            }
+        };
+        void promise.then(deleteSettledPromise, deleteSettledPromise);
+    }
+
+    delete(key: string): void {
+        this.pending.delete(key);
+    }
+
+    clear(): void {
+        this.pending.clear();
+    }
+}

package/src/core/redis-cache-client.ts

@@ -1,160 +1,160 @@
-/** Redis 缓存使用的最小字符串命令边界，连接及其生命周期由调用方持有。 */
-export interface RedisCacheClient {
-    /**
-     * 读取逻辑缓存键对应的字符串值。
-     * @param key 未经 Provider 改写的逻辑缓存键。
-     * @returns 缓存字符串；键不存在时返回 null。
-     * @throws 客户端命令失败时传播原始错误。
-     */
-    get(key: string): Promise<string | null>;
-
-    /**
-     * 写入已经由 Provider 序列化的缓存字符串。
-     * @param request 逻辑缓存键、字符串值及可选的秒级 TTL。
-     * @returns 命令成功后完成。
-     * @throws 客户端命令失败时传播原始错误。
-     */
-    set(request: { readonly key: string; readonly value: string; readonly ttlSeconds?: number }): Promise<void>;
-
-    /**
-     * 批量删除逻辑缓存键；空数组不得发送无参数 DEL。
-     * @param keys 保持调用顺序的逻辑缓存键集合。
-     * @returns 删除命令成功后完成。
-     * @throws 客户端命令失败时传播原始错误。
-     */
-    deleteMany(keys: readonly string[]): Promise<void>;
-
-    /**
-     * 按逻辑 glob pattern 扫描一页缓存键。
-     * @param request 当前游标、逻辑 pattern 和本页数量提示。
-     * @returns 下一游标及已经恢复为逻辑形式的缓存键。
-     * @throws 客户端命令失败或响应不受支持时传播错误。
-     */
-    scan(request: { readonly cursor: string; readonly pattern: string; readonly count: number }): Promise<{
-        readonly cursor: string;
-        readonly keys: readonly string[];
-    }>;
-
-    /**
-     * 清空客户端当前选择的整个 Redis 数据库。
-     * @returns 清库命令成功后完成。
-     * @throws 客户端命令失败时传播原始错误。
-     */
-    flushDatabase(): Promise<void>;
-}
-
-/** ioredis 适配器实际使用的命令形状，避免公共声明依赖完整客户端类型。 */
-export interface IoredisCacheClientSource {
-    /** 调用方连接的现有选项；适配器只读取 keyPrefix。 */
-    readonly options: { readonly keyPrefix?: string };
-
-    /**
-     * 读取由 ioredis 自行应用 keyPrefix 的逻辑键。
-     * @param key 逻辑缓存键。
-     * @returns ioredis 原始 GET 响应。
-     * @throws 客户端命令错误。
-     */
-    get(key: string): Promise<unknown>;
-
-    /**
-     * 不带过期时间写入由 ioredis 自行应用 keyPrefix 的逻辑键。
-     * @param key 逻辑缓存键。
-     * @param value 已序列化的缓存字符串。
-     * @returns ioredis 原始 SET 响应。
-     * @throws 客户端命令错误。
-     */
-    set(key: string, value: string): Promise<unknown>;
-
-    /**
-     * 使用秒级 TTL 写入由 ioredis 自行应用 keyPrefix 的逻辑键。
-     * @param key 逻辑缓存键。
-     * @param ttlSeconds 正整数秒级 TTL。
-     * @param value 已序列化的缓存字符串。
-     * @returns ioredis 原始 SETEX 响应。
-     * @throws 客户端命令错误。
-     */
-    setex(key: string, ttlSeconds: number, value: string): Promise<unknown>;
-
-    /**
-     * 删除由 ioredis 自行应用 keyPrefix 的逻辑键。
-     * @param keys 保持调用顺序的逻辑缓存键。
-     * @returns ioredis 原始 DEL 响应。
-     * @throws 客户端命令错误。
-     */
-    del(...keys: string[]): Promise<unknown>;
-
-    /**
-     * 使用 ioredis 的五段 SCAN 参数形状扫描物理键。
-     * @param args 游标、MATCH、物理 pattern、COUNT 和数量提示。
-     * @returns ioredis 原始 tuple SCAN 响应。
-     * @throws 客户端命令错误。
-     */
-    scan(...args: [cursor: string, match: 'MATCH', pattern: string, count: 'COUNT', limit: number]): Promise<unknown>;
-
-    /**
-     * 清空连接当前选择的 Redis 数据库。
-     * @returns ioredis 原始 FLUSHDB 响应。
-     * @throws 客户端命令错误。
-     */
-    flushdb(): Promise<unknown>;
-}
-
-/** node-redis 适配器实际使用的命令形状，避免公共声明依赖完整客户端类型。 */
-export interface NodeRedisCacheClientSource {
-    /**
-     * 读取已经应用适配器前缀的物理键。
-     * @param key 物理缓存键。
-     * @returns node-redis 原始 GET 响应。
-     * @throws 客户端命令错误。
-     */
-    get(key: string): Promise<unknown>;
-
-    /**
-     * 不带过期时间写入已经应用适配器前缀的物理键。
-     * @param key 物理缓存键。
-     * @param value 已序列化的缓存字符串。
-     * @returns node-redis 原始 SET 响应。
-     * @throws 客户端命令错误。
-     */
-    set(key: string, value: string): Promise<unknown>;
-
-    /**
-     * 使用秒级 TTL 写入已经应用适配器前缀的物理键。
-     * @param key 物理缓存键。
-     * @param ttlSeconds 正整数秒级 TTL。
-     * @param value 已序列化的缓存字符串。
-     * @returns node-redis 原始 SETEX 响应。
-     * @throws 客户端命令错误。
-     */
-    setEx(key: string, ttlSeconds: number, value: string): Promise<unknown>;
-
-    /**
-     * 删除一个或多个已经应用适配器前缀的物理键。
-     * @param keys 单个物理键或保持调用顺序的物理键数组。
-     * @returns node-redis 原始 DEL 响应。
-     * @throws 客户端命令错误。
-     */
-    del(keys: string | string[]): Promise<unknown>;
-
-    /**
-     * 使用 node-redis 的对象选项扫描物理键。
-     * @param cursor 当前 Redis 游标。
-     * @param options 物理 MATCH pattern 和本页数量提示。
-     * @returns node-redis 原始对象 SCAN 响应。
-     * @throws 客户端命令错误。
-     */
-    scan(cursor: string, options: { MATCH: string; COUNT: number }): Promise<unknown>;
-
-    /**
-     * 清空连接当前选择的 Redis 数据库。
-     * @returns node-redis 原始 FLUSHDB 响应。
-     * @throws 客户端命令错误。
-     */
-    flushDb(): Promise<unknown>;
-}
-
-/** node-redis 没有透明 keyPrefix，通过适配器显式保持逻辑命名空间。 */
-export interface NodeRedisCacheClientOptions {
-    /** 拼接到每个逻辑 key 前的字面字符串，缺省为空字符串。 */
-    readonly keyPrefix?: string;
-}
+/** Redis 缓存使用的最小字符串命令边界，连接及其生命周期由调用方持有。 */
+export interface RedisCacheClient {
+    /**
+     * 读取逻辑缓存键对应的字符串值。
+     * @param key 未经 Provider 改写的逻辑缓存键。
+     * @returns 缓存字符串；键不存在时返回 null。
+     * @throws 客户端命令失败时传播原始错误。
+     */
+    get(key: string): Promise<string | null>;
+
+    /**
+     * 写入已经由 Provider 序列化的缓存字符串。
+     * @param request 逻辑缓存键、字符串值及可选的秒级 TTL。
+     * @returns 命令成功后完成。
+     * @throws 客户端命令失败时传播原始错误。
+     */
+    set(request: { readonly key: string; readonly value: string; readonly ttlSeconds?: number }): Promise<void>;
+
+    /**
+     * 批量删除逻辑缓存键；空数组不得发送无参数 DEL。
+     * @param keys 保持调用顺序的逻辑缓存键集合。
+     * @returns 删除命令成功后完成。
+     * @throws 客户端命令失败时传播原始错误。
+     */
+    deleteMany(keys: readonly string[]): Promise<void>;
+
+    /**
+     * 按逻辑 glob pattern 扫描一页缓存键。
+     * @param request 当前游标、逻辑 pattern 和本页数量提示。
+     * @returns 下一游标及已经恢复为逻辑形式的缓存键。
+     * @throws 客户端命令失败或响应不受支持时传播错误。
+     */
+    scan(request: { readonly cursor: string; readonly pattern: string; readonly count: number }): Promise<{
+        readonly cursor: string;
+        readonly keys: readonly string[];
+    }>;
+
+    /**
+     * 清空客户端当前选择的整个 Redis 数据库。
+     * @returns 清库命令成功后完成。
+     * @throws 客户端命令失败时传播原始错误。
+     */
+    flushDatabase(): Promise<void>;
+}
+
+/** ioredis 适配器实际使用的命令形状，避免公共声明依赖完整客户端类型。 */
+export interface IoredisCacheClientSource {
+    /** 调用方连接的现有选项；适配器只读取 keyPrefix。 */
+    readonly options: { readonly keyPrefix?: string };
+
+    /**
+     * 读取由 ioredis 自行应用 keyPrefix 的逻辑键。
+     * @param key 逻辑缓存键。
+     * @returns ioredis 原始 GET 响应。
+     * @throws 客户端命令错误。
+     */
+    get(key: string): Promise<unknown>;
+
+    /**
+     * 不带过期时间写入由 ioredis 自行应用 keyPrefix 的逻辑键。
+     * @param key 逻辑缓存键。
+     * @param value 已序列化的缓存字符串。
+     * @returns ioredis 原始 SET 响应。
+     * @throws 客户端命令错误。
+     */
+    set(key: string, value: string): Promise<unknown>;
+
+    /**
+     * 使用秒级 TTL 写入由 ioredis 自行应用 keyPrefix 的逻辑键。
+     * @param key 逻辑缓存键。
+     * @param ttlSeconds 正整数秒级 TTL。
+     * @param value 已序列化的缓存字符串。
+     * @returns ioredis 原始 SETEX 响应。
+     * @throws 客户端命令错误。
+     */
+    setex(key: string, ttlSeconds: number, value: string): Promise<unknown>;
+
+    /**
+     * 删除由 ioredis 自行应用 keyPrefix 的逻辑键。
+     * @param keys 保持调用顺序的逻辑缓存键。
+     * @returns ioredis 原始 DEL 响应。
+     * @throws 客户端命令错误。
+     */
+    del(...keys: string[]): Promise<unknown>;
+
+    /**
+     * 使用 ioredis 的五段 SCAN 参数形状扫描物理键。
+     * @param args 游标、MATCH、物理 pattern、COUNT 和数量提示。
+     * @returns ioredis 原始 tuple SCAN 响应。
+     * @throws 客户端命令错误。
+     */
+    scan(...args: [cursor: string, match: 'MATCH', pattern: string, count: 'COUNT', limit: number]): Promise<unknown>;
+
+    /**
+     * 清空连接当前选择的 Redis 数据库。
+     * @returns ioredis 原始 FLUSHDB 响应。
+     * @throws 客户端命令错误。
+     */
+    flushdb(): Promise<unknown>;
+}
+
+/** node-redis 适配器实际使用的命令形状，避免公共声明依赖完整客户端类型。 */
+export interface NodeRedisCacheClientSource {
+    /**
+     * 读取已经应用适配器前缀的物理键。
+     * @param key 物理缓存键。
+     * @returns node-redis 原始 GET 响应。
+     * @throws 客户端命令错误。
+     */
+    get(key: string): Promise<unknown>;
+
+    /**
+     * 不带过期时间写入已经应用适配器前缀的物理键。
+     * @param key 物理缓存键。
+     * @param value 已序列化的缓存字符串。
+     * @returns node-redis 原始 SET 响应。
+     * @throws 客户端命令错误。
+     */
+    set(key: string, value: string): Promise<unknown>;
+
+    /**
+     * 使用秒级 TTL 写入已经应用适配器前缀的物理键。
+     * @param key 物理缓存键。
+     * @param ttlSeconds 正整数秒级 TTL。
+     * @param value 已序列化的缓存字符串。
+     * @returns node-redis 原始 SETEX 响应。
+     * @throws 客户端命令错误。
+     */
+    setEx(key: string, ttlSeconds: number, value: string): Promise<unknown>;
+
+    /**
+     * 删除一个或多个已经应用适配器前缀的物理键。
+     * @param keys 单个物理键或保持调用顺序的物理键数组。
+     * @returns node-redis 原始 DEL 响应。
+     * @throws 客户端命令错误。
+     */
+    del(keys: string | string[]): Promise<unknown>;
+
+    /**
+     * 使用 node-redis 的对象选项扫描物理键。
+     * @param cursor 当前 Redis 游标。
+     * @param options 物理 MATCH pattern 和本页数量提示。
+     * @returns node-redis 原始对象 SCAN 响应。
+     * @throws 客户端命令错误。
+     */
+    scan(cursor: string, options: { MATCH: string; COUNT: number }): Promise<unknown>;
+
+    /**
+     * 清空连接当前选择的 Redis 数据库。
+     * @returns node-redis 原始 FLUSHDB 响应。
+     * @throws 客户端命令错误。
+     */
+    flushDb(): Promise<unknown>;
+}
+
+/** node-redis 没有透明 keyPrefix，通过适配器显式保持逻辑命名空间。 */
+export interface NodeRedisCacheClientOptions {
+    /** 拼接到每个逻辑 key 前的字面字符串，缺省为空字符串。 */
+    readonly keyPrefix?: string;
+}

package/src/core/redis-cache.ts

@@ -1,104 +1,104 @@
-import { CacheProvider } from './cache-provider';
-import { RedisCacheClient } from './redis-cache-client';
-
-/**
- * Redis 缓存提供者，在客户端无关的字符串命令之上维护统一缓存协议。
- * 适用于分布式场景，支持跨进程及跨客户端共享缓存。
- */
-export class RedisCacheProvider implements CacheProvider {
-    private readonly client: RedisCacheClient;
-
-    /**
-     * 创建复用调用方 Redis 连接的缓存提供者。
-     * @param client 已适配的最小 Redis 缓存客户端。
-     */
-    constructor(client: RedisCacheClient) {
-        this.client = client;
-    }
-
-    /**
-     * 按既有协议读取并反序列化缓存值。
-     * @param key 未经 Provider 改写的逻辑缓存键。
-     * @returns 解析后的业务值；Redis miss 时返回 undefined。
-     * @throws GET 命令失败时传播客户端原始错误。
-     */
-    async get<T>(key: string): Promise<T | undefined> {
-        const value = await this.client.get(key);
-        if (value === null) {
-            return undefined;
-        }
-        try {
-            return JSON.parse(value) as T;
-        } catch {
-            // 兼容既有协议：不是合法 JSON 的字符串按原值返回。
-            return value as unknown as T;
-        }
-    }
-
-    /**
-     * 按既有字符串或 JSON 协议写入缓存值。
-     * @param key 未经 Provider 改写的逻辑缓存键。
-     * @param value 需要缓存的业务值。
-     * @param ttl 可选的正整数秒级 TTL；undefined 或 0 表示永不过期。
-     * @returns 写入命令成功后完成。
-     * @throws 值不能序列化时抛 TypeError，TTL 非法时抛 RangeError，命令失败时传播原始错误。
-     */
-    async set<T>(key: string, value: T, ttl?: number): Promise<void> {
-        const ttlSeconds = this.normalizeTtl(ttl);
-        const serialized = typeof value === 'string' ? value : JSON.stringify(value);
-        if (typeof serialized !== 'string') {
-            throw new TypeError('Cache value must serialize to a string');
-        }
-        if (ttlSeconds === undefined) {
-            await this.client.set({ key, value: serialized });
-            return;
-        }
-        await this.client.set({ key, value: serialized, ttlSeconds });
-    }
-
-    /**
-     * 幂等删除一个逻辑缓存键。
-     * @param key 未经 Provider 改写的逻辑缓存键。
-     * @returns 删除命令成功后完成。
-     * @throws DEL 命令失败时传播客户端原始错误。
-     */
-    async delete(key: string): Promise<void> {
-        await this.client.deleteMany([key]);
-    }
-
-    /**
-     * 清空客户端当前选择的整个 Redis 数据库。
-     * @returns FLUSHDB 命令成功后完成。
-     * @throws 清库命令失败时传播客户端原始错误。
-     */
-    async clear(): Promise<void> {
-        await this.client.flushDatabase();
-    }
-
-    /**
-     * 使用游标扫描并按页删除匹配的逻辑缓存键，避免阻塞 Redis。
-     * @param pattern 保留 glob 语义的逻辑 pattern，例如 user:*。
-     * @returns 游标归零且所有已扫描页面删除成功后完成。
-     * @throws SCAN 或任一页 DEL 失败时传播客户端原始错误，并停止后续页面。
-     */
-    async deleteByPattern(pattern: string): Promise<void> {
-        let cursor = '0';
-        do {
-            const page = await this.client.scan({ cursor, pattern, count: 100 });
-            cursor = page.cursor;
-            if (page.keys.length > 0) {
-                await this.client.deleteMany(page.keys);
-            }
-        } while (cursor !== '0');
-    }
-
-    private normalizeTtl(ttl: number | undefined): number | undefined {
-        if (ttl === undefined || ttl === 0) {
-            return undefined;
-        }
-        if (!Number.isFinite(ttl) || !Number.isInteger(ttl) || ttl < 1) {
-            throw new RangeError('Redis cache TTL must be a positive finite integer or zero');
-        }
-        return ttl;
-    }
-}
+import { CacheProvider } from './cache-provider';
+import { RedisCacheClient } from './redis-cache-client';
+
+/**
+ * Redis 缓存提供者，在客户端无关的字符串命令之上维护统一缓存协议。
+ * 适用于分布式场景，支持跨进程及跨客户端共享缓存。
+ */
+export class RedisCacheProvider implements CacheProvider {
+    private readonly client: RedisCacheClient;
+
+    /**
+     * 创建复用调用方 Redis 连接的缓存提供者。
+     * @param client 已适配的最小 Redis 缓存客户端。
+     */
+    constructor(client: RedisCacheClient) {
+        this.client = client;
+    }
+
+    /**
+     * 按既有协议读取并反序列化缓存值。
+     * @param key 未经 Provider 改写的逻辑缓存键。
+     * @returns 解析后的业务值；Redis miss 时返回 undefined。
+     * @throws GET 命令失败时传播客户端原始错误。
+     */
+    async get<T>(key: string): Promise<T | undefined> {
+        const value = await this.client.get(key);
+        if (value === null) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(value) as T;
+        } catch {
+            // 兼容既有协议：不是合法 JSON 的字符串按原值返回。
+            return value as unknown as T;
+        }
+    }
+
+    /**
+     * 按既有字符串或 JSON 协议写入缓存值。
+     * @param key 未经 Provider 改写的逻辑缓存键。
+     * @param value 需要缓存的业务值。
+     * @param ttl 可选的正整数秒级 TTL；undefined 或 0 表示永不过期。
+     * @returns 写入命令成功后完成。
+     * @throws 值不能序列化时抛 TypeError，TTL 非法时抛 RangeError，命令失败时传播原始错误。
+     */
+    async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+        const ttlSeconds = this.normalizeTtl(ttl);
+        const serialized = typeof value === 'string' ? value : JSON.stringify(value);
+        if (typeof serialized !== 'string') {
+            throw new TypeError('Cache value must serialize to a string');
+        }
+        if (ttlSeconds === undefined) {
+            await this.client.set({ key, value: serialized });
+            return;
+        }
+        await this.client.set({ key, value: serialized, ttlSeconds });
+    }
+
+    /**
+     * 幂等删除一个逻辑缓存键。
+     * @param key 未经 Provider 改写的逻辑缓存键。
+     * @returns 删除命令成功后完成。
+     * @throws DEL 命令失败时传播客户端原始错误。
+     */
+    async delete(key: string): Promise<void> {
+        await this.client.deleteMany([key]);
+    }
+
+    /**
+     * 清空客户端当前选择的整个 Redis 数据库。
+     * @returns FLUSHDB 命令成功后完成。
+     * @throws 清库命令失败时传播客户端原始错误。
+     */
+    async clear(): Promise<void> {
+        await this.client.flushDatabase();
+    }
+
+    /**
+     * 使用游标扫描并按页删除匹配的逻辑缓存键，避免阻塞 Redis。
+     * @param pattern 保留 glob 语义的逻辑 pattern，例如 user:*。
+     * @returns 游标归零且所有已扫描页面删除成功后完成。
+     * @throws SCAN 或任一页 DEL 失败时传播客户端原始错误，并停止后续页面。
+     */
+    async deleteByPattern(pattern: string): Promise<void> {
+        let cursor = '0';
+        do {
+            const page = await this.client.scan({ cursor, pattern, count: 100 });
+            cursor = page.cursor;
+            if (page.keys.length > 0) {
+                await this.client.deleteMany(page.keys);
+            }
+        } while (cursor !== '0');
+    }
+
+    private normalizeTtl(ttl: number | undefined): number | undefined {
+        if (ttl === undefined || ttl === 0) {
+            return undefined;
+        }
+        if (!Number.isFinite(ttl) || !Number.isInteger(ttl) || ttl < 1) {
+            throw new RangeError('Redis cache TTL must be a positive finite integer or zero');
+        }
+        return ttl;
+    }
+}