@jintianxiayu/cache-decorator 0.1.2 → 1.0.0

package/src/adapters/node-redis-cache-client.ts

@@ -0,0 +1,95 @@
+import { NodeRedisCacheClientOptions, NodeRedisCacheClientSource, RedisCacheClient } from '../core/redis-cache-client';
+import { createRedisScanPattern, stripRedisKeyPrefix } from './redis-key-prefix';
+
+function normalizeGetResponse(response: unknown): string | null {
+    if (typeof response === 'string' || response === null) {
+        return response;
+    }
+    throw new TypeError('Expected Redis GET to return a string or null');
+}
+
+function validateOkResponse(command: string, response: unknown): void {
+    if (response !== 'OK') {
+        throw new TypeError(`Expected Redis ${command} to return "OK"`);
+    }
+}
+
+function validateDeleteResponse(response: unknown): void {
+    if (typeof response !== 'number' || !Number.isInteger(response) || response < 0) {
+        throw new TypeError('Expected Redis DEL to return a non-negative integer');
+    }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function normalizeScanResponse(
+    response: unknown,
+    keyPrefix: string
+): { readonly cursor: string; readonly keys: readonly string[] } {
+    if (
+        !isRecord(response) ||
+        typeof response.cursor !== 'string' ||
+        !Array.isArray(response.keys) ||
+        !response.keys.every((key: unknown) => typeof key === 'string')
+    ) {
+        throw new TypeError('Expected node-redis SCAN to return a { cursor, keys } object');
+    }
+    return {
+        cursor: response.cursor,
+        keys: response.keys.map((key: string) => stripRedisKeyPrefix(keyPrefix, key)),
+    };
+}
+
+/**
+ * 将调用方的 node-redis 连接适配为客户端无关的缓存命令，不创建或关闭连接。
+ * @param client 使用默认字符串响应映射的 node-redis 普通客户端。
+ * @param options 可选的字面 key 前缀；缺省时不改写逻辑 key。
+ * @returns 复用该连接并统一物理 key 前缀的 Redis 缓存客户端。
+ * @throws 返回对象的命令方法传播客户端错误；非标准响应拒绝为 TypeError。
+ */
+export function createNodeRedisCacheClient(
+    client: NodeRedisCacheClientSource,
+    options?: NodeRedisCacheClientOptions
+): RedisCacheClient {
+    const keyPrefix = options?.keyPrefix ?? '';
+    const createPhysicalKey = (key: string): string => `${keyPrefix}${key}`;
+    return {
+        /** @inheritdoc */
+        async get(key: string): Promise<string | null> {
+            return normalizeGetResponse(await client.get(createPhysicalKey(key)));
+        },
+        /** @inheritdoc */
+        async set({ key, value, ttlSeconds }): Promise<void> {
+            const physicalKey = createPhysicalKey(key);
+            if (ttlSeconds === undefined) {
+                validateOkResponse('SET', await client.set(physicalKey, value));
+                return;
+            }
+            validateOkResponse('SETEX', await client.setEx(physicalKey, ttlSeconds, value));
+        },
+        /** @inheritdoc */
+        async deleteMany(keys: readonly string[]): Promise<void> {
+            if (keys.length === 0) {
+                return;
+            }
+            validateDeleteResponse(await client.del(keys.map(createPhysicalKey)));
+        },
+        /** @inheritdoc */
+        async scan({ cursor, pattern, count }): Promise<{
+            readonly cursor: string;
+            readonly keys: readonly string[];
+        }> {
+            const response = await client.scan(cursor, {
+                MATCH: createRedisScanPattern(keyPrefix, pattern),
+                COUNT: count,
+            });
+            return normalizeScanResponse(response, keyPrefix);
+        },
+        /** @inheritdoc */
+        async flushDatabase(): Promise<void> {
+            validateOkResponse('FLUSHDB', await client.flushDb());
+        },
+    };
+}

package/src/adapters/redis-key-prefix.ts

@@ -0,0 +1,38 @@
+const REDIS_GLOB_META_CHARACTERS = new Set(['\\', '*', '?', '[', ']']);
+
+/**
+ * 将普通字符串转换为 Redis glob pattern 中的字面量片段。
+ * @param value 仅作为字面前缀使用的字符串。
+ * @returns 对反斜杠、星号、问号和方括号增加反斜杠转义后的片段。
+ */
+export function escapeRedisGlobLiteral(value: string): string {
+    let escaped = '';
+    for (const character of value) {
+        escaped += REDIS_GLOB_META_CHARACTERS.has(character) ? `\\${character}` : character;
+    }
+    return escaped;
+}
+
+/**
+ * 为逻辑 glob pattern 增加按字面量解释的 Redis key 前缀。
+ * @param keyPrefix 调用方配置的物理 key 前缀。
+ * @param pattern Provider 传入且需要保留 glob 语义的逻辑 pattern。
+ * @returns 可直接交给 Redis SCAN MATCH 的物理 pattern。
+ */
+export function createRedisScanPattern(keyPrefix: string, pattern: string): string {
+    return `${escapeRedisGlobLiteral(keyPrefix)}${pattern}`;
+}
+
+/**
+ * 验证扫描结果属于指定物理命名空间并恢复逻辑 key。
+ * @param keyPrefix 调用方配置的物理 key 前缀。
+ * @param physicalKey Redis SCAN 返回的物理 key。
+ * @returns 只剥离一次字面前缀后的逻辑 key。
+ * @throws 扫描结果不属于指定前缀时抛出 TypeError，避免扩大后续删除范围。
+ */
+export function stripRedisKeyPrefix(keyPrefix: string, physicalKey: string): string {
+    if (!physicalKey.startsWith(keyPrefix)) {
+        throw new TypeError('Redis SCAN returned a key outside the configured key prefix');
+    }
+    return physicalKey.slice(keyPrefix.length);
+}

package/src/core/cache-logger.ts

@@ -0,0 +1,105 @@
+import { LoggerFactory, type LoggerInterface } from '@jintianxiayu/logger';
+
+const CACHE_LOGGER_NAME = '@jintianxiayu/cache-decorator';
+
+export type CacheLogEvent =
+    | 'cache.pending_hit'
+    | 'cache.hit'
+    | 'cache.miss'
+    | 'cache.write_dispatched'
+    | 'cache.evict_dispatched'
+    | 'cache.evict_completed'
+    | 'cache.key_fallback'
+    | 'cache.evict_skipped'
+    | 'cache.operation_failed';
+
+type CacheLogLevel = 'debug' | 'warn' | 'error';
+
+interface CacheLogDefinition {
+    readonly level: CacheLogLevel;
+    readonly message: string;
+}
+
+/** 缓存日志只接受与决策相关的稳定字段，避免业务数据和 cache key 被意外带入输出。 */
+export interface CacheLogContext {
+    readonly cacheName: string;
+    readonly methodName: string;
+    readonly providerName: string;
+    readonly entryType?: 'value' | 'error';
+    readonly scope?: 'key' | 'allEntries';
+    readonly reason?: 'resolver_error' | 'business_error';
+    readonly operation?: 'provider_resolution' | 'read' | 'write' | 'evict';
+    readonly error?: unknown;
+}
+
+/** 日志定义映射中 K 为稳定事件名，V 为固定的日志级别与无业务数据消息。 */
+const CACHE_LOG_DEFINITIONS: Readonly<Record<CacheLogEvent, CacheLogDefinition>> = {
+    'cache.pending_hit': { level: 'debug', message: 'Cache pending request reused' },
+    'cache.hit': { level: 'debug', message: 'Cache entry hit' },
+    'cache.miss': { level: 'debug', message: 'Cache entry missed' },
+    'cache.write_dispatched': { level: 'debug', message: 'Cache write dispatched' },
+    'cache.evict_dispatched': { level: 'debug', message: 'Cache eviction dispatched' },
+    'cache.evict_completed': { level: 'debug', message: 'Cache eviction completed' },
+    'cache.key_fallback': { level: 'warn', message: 'Cache key resolver failed; using default key' },
+    'cache.evict_skipped': { level: 'warn', message: 'Cache eviction skipped after business failure' },
+    'cache.operation_failed': { level: 'error', message: 'Cache operation failed' },
+};
+
+let cacheLogger: LoggerInterface | undefined;
+
+function getCacheLogger(): LoggerInterface {
+    cacheLogger ??= LoggerFactory.getLogger(CACHE_LOGGER_NAME);
+    return cacheLogger;
+}
+
+/**
+ * 按稳定事件定义调用对应 Logger level，不提供 info 分支以防高频缓存事件误入 info。
+ * @param logger 应用共享的 cache 命名 Logger。
+ * @param definition 当前事件固定的 level 与 message。
+ * @param metadata 只包含缓存决策白名单字段的结构化元数据。
+ * @returns 无返回值。
+ * @throws Logger 同步写入失败时透传给外层安全边界处理。
+ */
+function writeCacheLog(
+    logger: LoggerInterface,
+    definition: CacheLogDefinition,
+    metadata: CacheLogContext & { readonly event: CacheLogEvent }
+): void {
+    if (definition.level === 'debug') {
+        logger.debug(definition.message, metadata);
+        return;
+    }
+    if (definition.level === 'warn') {
+        logger.warn(definition.message, metadata);
+        return;
+    }
+    logger.error(definition.message, metadata);
+}
+
+/**
+ * 提交一条不会影响缓存或业务结果的结构化日志。
+ * @param event 决定固定 message 与 level 的缓存事件。
+ * @param context 不包含参数、值或 key 的缓存决策上下文。
+ * @returns 无返回值；Logger 获取或同步写入失败时静默结束。
+ * @throws 不主动抛出异常。
+ */
+export function logCacheEvent(event: CacheLogEvent, context: CacheLogContext): void {
+    try {
+        writeCacheLog(getCacheLogger(), CACHE_LOG_DEFINITIONS[event], { event, ...context });
+    } catch (_error) {
+        return;
+    }
+}
+
+/**
+ * 将 decorator 配置中的 Provider 名称转换为稳定日志标签。
+ * @param providerName 用户显式配置的 Provider 名称。
+ * @returns 非空显式名称；缺省或空字符串返回 `default`。
+ * @throws 不主动抛出异常。
+ */
+export function cacheProviderLabel(providerName: string | undefined): string {
+    if (providerName === undefined || providerName.length === 0) {
+        return 'default';
+    }
+    return providerName;
+}

package/src/core/cache-provider-registry.ts

@@ -8,46 +8,46 @@ let defaultName: string | undefined;
  * 用于注册和获取不同类型的 CacheProvider
  */
 export class CacheProviderRegistry {
-  /**
-   * 注册缓存提供者
-   * @param name 提供者名称
-   * @param provider 缓存提供者实例
-   */
-  static register(name: string, provider: CacheProvider): void {
-    providers.set(name, provider);
-  }
-
-  /**
-   * 获取缓存提供者
-   * @param name 提供者名称，不指定则使用默认提供者
-   * @returns 缓存提供者实例
-   * @throws 未注册且无默认提供者时抛出错误
-   */
-  static get(name?: string): CacheProvider {
-    const providerName = name || defaultName;
-    if (!providerName) {
-      throw new Error('No CacheProvider registered and no default set');
+    /**
+     * 注册缓存提供者
+     * @param name 提供者名称
+     * @param provider 缓存提供者实例
+     */
+    static register(name: string, provider: CacheProvider): void {
+        providers.set(name, provider);
     }
-    const provider = providers.get(providerName);
-    if (!provider) {
-      throw new Error(`CacheProvider "${providerName}" not found`);
+
+    /**
+     * 获取缓存提供者
+     * @param name 提供者名称，不指定则使用默认提供者
+     * @returns 缓存提供者实例
+     * @throws 未注册且无默认提供者时抛出错误
+     */
+    static get(name?: string): CacheProvider {
+        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;
     }
-    return provider;
-  }
 
-  /**
-   * 设置默认缓存提供者
-   * @param name 提供者名称
-   */
-  static setDefault(name: string): void {
-    defaultName = name;
-  }
+    /**
+     * 设置默认缓存提供者
+     * @param name 提供者名称
+     */
+    static setDefault(name: string): void {
+        defaultName = name;
+    }
 
-  /**
-   * 清空注册表
-   */
-  static clear(): void {
-    providers.clear();
-    defaultName = undefined;
-  }
-}
+    /**
+     * 清空注册表
+     */
+    static clear(): void {
+        providers.clear();
+        defaultName = undefined;
+    }
+}

package/src/core/cache-provider.ts

@@ -3,35 +3,35 @@
  * 支持可插拔的缓存实现（Memory、Redis、自定义）
  */
 export interface CacheProvider {
-  /**
-   * 获取缓存值
-   * @param key 缓存键
-   * @returns 缓存值，不存在或已过期返回 undefined
-   */
-  get<T>(key: string): T | undefined | Promise<T | undefined>;
+    /**
+     * 获取缓存值
+     * @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 缓存键
+     * @param value 缓存值
+     * @param ttl 过期时间（秒），不设置则永不过期
+     */
+    set<T>(key: string, value: T, ttl?: number): void | Promise<void>;
 
-  /**
-   * 删除指定缓存
-   * @param key 缓存键
-   */
-  delete(key: string): void | Promise<void>;
+    /**
+     * 删除指定缓存
+     * @param key 缓存键
+     */
+    delete(key: string): void | Promise<void>;
 
-  /**
-   * 清除所有缓存
-   */
-  clear(): void | Promise<void>;
+    /**
+     * 清除所有缓存
+     */
+    clear(): void | Promise<void>;
 
-  /**
-   * 根据模式删除匹配的缓存键
-   * @param pattern glob模式字符串（如 user:*），末尾的 * 作为前缀匹配
-   */
-  deleteByPattern(pattern: string): void | Promise<void>;
-}
+    /**
+     * 根据模式删除匹配的缓存键
+     * @param pattern glob模式字符串（如 user:*），末尾的 * 作为前缀匹配
+     */
+    deleteByPattern(pattern: string): void | Promise<void>;
+}

package/src/core/key-builder.ts

@@ -1,31 +1,33 @@
-/**
- * 缓存 Key 构建器
- * 负责将缓存名称和参数转换为统一的 key 字符串
- */
-export class KeyBuilder {
-  /**
-   * 构建缓存 key
-   * @param cacheName 缓存名称
-   * @param args 方法参数列表
-   * @returns 格式为 {cacheName}:{serializedArgs} 的 key 字符串
-   */
-  static build(cacheName: string, args: unknown[]): string {
-    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}`;
-  }
-}
+/**
+ * 缓存 Key 构建器
+ * 负责将缓存名称和参数转换为统一的 key 字符串
+ */
+export class KeyBuilder {
+    /**
+     * 构建缓存 key
+     * @param cacheName 缓存名称
+     * @param args 方法参数列表
+     * @returns 格式为 {cacheName}:{serializedArgs} 的 key 字符串
+     */
+    static build(cacheName: string, args: unknown[]): string {
+        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}`;
+    }
+}

package/src/core/native-cache.ts

@@ -1,53 +1,55 @@
-import { CacheProvider } from './cache-provider';
-
-/**
- * 缓存条目结构
- */
-interface CacheEntry<T> {
-  value: T;
-  expiresAt: number | null;
-}
-
-/**
- * 内存缓存提供者，基于 Map 实现
- * 适用于单机应用，缓存随进程重启清除
- */
-export class MemoryCacheProvider implements CacheProvider {
-  private cache = new Map<string, CacheEntry<unknown>>();
-
-  get<T>(key: string): T | undefined {
-    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 as T;
-  }
-
-  set<T>(key: string, value: T, ttl?: number): void {
-    const expiresAt = ttl ? Date.now() + ttl * 1000 : null;
-    this.cache.set(key, { value, expiresAt });
-  }
-
-  delete(key: string): void {
-    this.cache.delete(key);
-  }
-
-  clear(): void {
-    this.cache.clear();
-  }
-
-  /**
-   * 根据模式删除匹配的缓存键
-   * @param pattern glob模式字符串（如 user:*），末尾的 * 作为前缀匹配
-   */
-  deleteByPattern(pattern: string): void {
-    const prefix = pattern.replace(/\*$/, '');
-    for (const key of this.cache.keys()) {
-      if (key.startsWith(prefix)) {
-        this.cache.delete(key);
-      }
-    }
-  }
-}
+import { CacheProvider } from './cache-provider';
+
+/**
+ * 缓存条目结构
+ */
+interface CacheEntry<T> {
+    value: T;
+    expiresAt: number | null;
+}
+
+/**
+ * 内存缓存提供者，基于 Map 实现
+ * 适用于单机应用，缓存随进程重启清除
+ */
+export class MemoryCacheProvider implements CacheProvider {
+    private cache = new Map<string, CacheEntry<unknown>>();
+
+    get<T>(key: string): T | undefined {
+        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 as T;
+    }
+
+    set<T>(key: string, value: T, ttl?: number): void {
+        const expiresAt = ttl ? Date.now() + ttl * 1000 : null;
+        this.cache.set(key, { value, expiresAt });
+    }
+
+    delete(key: string): void {
+        this.cache.delete(key);
+    }
+
+    clear(): void {
+        this.cache.clear();
+    }
+
+    /**
+     * 根据模式删除匹配的缓存键
+     * @param pattern glob模式字符串（如 user:*），末尾的 * 作为前缀匹配
+     */
+    deleteByPattern(pattern: string): void {
+        const prefix = pattern.replace(/\*$/, '');
+        for (const key of this.cache.keys()) {
+            if (key.startsWith(prefix)) {
+                this.cache.delete(key);
+            }
+        }
+    }
+}

package/src/core/pending-cache.ts

@@ -1,26 +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);
-    promise.finally(() => {
-      this.pending.delete(key);
-    });
-  }
-
-  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();
+    }
+}