@jintianxiayu/cache-decorator 0.1.3 → 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/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();
+    }
+}

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

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