@jintianxiayu/cache-decorator 0.1.3 → 1.0.1

package/src/core/cache-error.ts

@@ -0,0 +1,233 @@
+/** 异常缓存使用的固定 envelope 类型标识。 */
+const CACHE_ERROR_KIND = '@jintianxiayu/cache-decorator/error';
+
+/** 当前异常缓存 envelope 版本。 */
+const CACHE_ERROR_VERSION = 1;
+
+/**
+ * 异常缓存编解码器，将业务异常转换为可持久化 payload，并在命中时恢复异常语义。
+ */
+export interface CacheErrorCodec {
+    /**
+     * 编码本次业务异常。
+     * @param error 被装饰业务方法抛出或拒绝的值。
+     * @returns 可 JSON 往返的 payload。
+     */
+    encode(error: unknown): unknown;
+
+    /**
+     * 解码缓存中的 payload。
+     * @param payload 当前版本 envelope 中的 JSON payload。
+     * @returns 命中时应向调用方抛出的值。
+     */
+    decode(payload: unknown): unknown;
+}
+
+/**
+ * 业务异常持久化策略；提供该对象即显式启用异常缓存。
+ */
+export interface CacheErrorPolicy {
+    /** 独立于正常结果 TTL 的正整数秒级异常 TTL。 */
+    ttl: number;
+
+    /** 返回 true 时允许缓存本次业务异常；省略时接受全部业务异常。 */
+    shouldCache?: (error: unknown) => boolean;
+
+    /** 成对提供的异常编解码器；省略时使用标准 Error/JSON 值 codec。 */
+    codec?: CacheErrorCodec;
+}
+
+/** 装饰器求值时完成校验并绑定默认 codec 的内部策略。 */
+export interface NormalizedCacheErrorPolicy {
+    readonly ttl: number;
+    readonly shouldCache: ((error: unknown) => boolean) | undefined;
+    readonly codec: CacheErrorCodec;
+}
+
+/** Provider 中异常条目的版本化内容。 */
+export interface VersionedCacheErrorPayload {
+    readonly kind: typeof CACHE_ERROR_KIND;
+    readonly version: typeof CACHE_ERROR_VERSION;
+    readonly payload: unknown;
+}
+
+interface DefaultErrorPayload {
+    readonly type: 'error';
+    readonly name: string;
+    readonly message: string;
+}
+
+interface DefaultValuePayload {
+    readonly type: 'value';
+    readonly value: unknown;
+}
+
+function isRecord(value: unknown): value is Record<PropertyKey, unknown> {
+    return typeof value === 'object' && value !== null;
+}
+
+function isPlainObject(value: object): boolean {
+    const prototype = Object.getPrototypeOf(value) as unknown;
+    return prototype === Object.prototype || prototype === null;
+}
+
+/**
+ * 递归校验值是否可以无损表示为 JSON，拒绝 JSON.stringify 会静默丢弃或改写的结构。
+ * @param value 待校验的 payload 或 envelope 节点。
+ * @param ancestors 当前递归路径上的对象，用于识别循环引用而不拒绝普通重复引用。
+ * @returns 无返回值。
+ * @throws 值包含非 JSON 类型、非有限数、稀疏数组、symbol key、特殊对象或循环引用时抛出 TypeError。
+ */
+function validateJsonValue(value: unknown, ancestors: Set<object>): void {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+        return;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new TypeError('Cache error payload numbers must be finite');
+        }
+        return;
+    }
+    if (!isRecord(value)) {
+        throw new TypeError('Cache error payload must contain only JSON-compatible values');
+    }
+    if ((!Array.isArray(value) && !isPlainObject(value)) || Object.getOwnPropertySymbols(value).length > 0) {
+        throw new TypeError('Cache error payload must use JSON objects and arrays');
+    }
+    if (ancestors.has(value)) {
+        throw new TypeError('Cache error payload must not contain circular references');
+    }
+
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            for (let index = 0; index < value.length; index += 1) {
+                if (!Object.prototype.hasOwnProperty.call(value, index)) {
+                    throw new TypeError('Cache error payload arrays must not be sparse');
+                }
+                validateJsonValue(value[index], ancestors);
+            }
+            return;
+        }
+        for (const child of Object.values(value)) {
+            validateJsonValue(child, ancestors);
+        }
+    } finally {
+        ancestors.delete(value);
+    }
+}
+
+/**
+ * 校验并执行一次 JSON stringify/parse，以统一 Memory、Redis 与自定义 Provider 得到的表示。
+ * @param value codec 产生的完整版本化 envelope。
+ * @returns JSON 往返后的独立规范化值。
+ * @throws 无法安全 JSON 往返时抛出 TypeError 或底层序列化错误。
+ */
+function normalizeJsonValue(value: unknown): unknown {
+    validateJsonValue(value, new Set<object>());
+    const serialized = JSON.stringify(value);
+    if (typeof serialized !== 'string') {
+        throw new TypeError('Cache error payload must serialize to JSON');
+    }
+    return JSON.parse(serialized) as unknown;
+}
+
+const defaultCacheErrorCodec: CacheErrorCodec = Object.freeze({
+    encode(error: unknown): DefaultErrorPayload | DefaultValuePayload {
+        if (error instanceof Error) {
+            return { type: 'error', name: error.name, message: error.message };
+        }
+        return { type: 'value', value: error };
+    },
+    decode(payload: unknown): unknown {
+        if (!isRecord(payload)) {
+            throw new TypeError('Default cache error payload must be an object');
+        }
+        if (payload.type === 'error' && typeof payload.name === 'string' && typeof payload.message === 'string') {
+            const error = new Error(payload.message);
+            error.name = payload.name;
+            return error;
+        }
+        if (payload.type === 'value' && Object.prototype.hasOwnProperty.call(payload, 'value')) {
+            return payload.value;
+        }
+        throw new TypeError('Default cache error payload has an unsupported shape');
+    },
+});
+
+/**
+ * 在 legacy decorator 求值阶段校验外部异常策略并绑定默认 codec。
+ * @param policy 调用方传入的可选异常策略。
+ * @returns 禁用状态返回 undefined；启用状态返回不可变的内部策略快照。
+ * @throws TTL 非正有限整数时抛 RangeError；筛选器或 codec 结构非法时抛 TypeError。
+ */
+export function normalizeCacheErrorPolicy(
+    policy: CacheErrorPolicy | undefined
+): NormalizedCacheErrorPolicy | undefined {
+    if (policy === undefined) {
+        return undefined;
+    }
+    if (!isRecord(policy)) {
+        throw new TypeError('Cache error policy must be an object');
+    }
+    const ttl = policy.ttl;
+    const shouldCache = policy.shouldCache;
+    const configuredCodec = policy.codec;
+    if (typeof ttl !== 'number' || !Number.isFinite(ttl) || !Number.isInteger(ttl) || ttl < 1) {
+        throw new RangeError('Cache error TTL must be a positive finite integer');
+    }
+    if (shouldCache !== undefined && typeof shouldCache !== 'function') {
+        throw new TypeError('Cache error shouldCache must be a function');
+    }
+    const codec = configuredCodec === undefined ? defaultCacheErrorCodec : configuredCodec;
+    if (!isRecord(codec) || typeof codec.encode !== 'function' || typeof codec.decode !== 'function') {
+        throw new TypeError('Cache error codec must provide encode and decode functions');
+    }
+    return Object.freeze({ ttl, shouldCache, codec });
+}
+
+/**
+ * 将业务异常编码为当前版本且已经 JSON 规范化的 envelope。
+ * @param error 本次业务方法产生的原始异常。
+ * @param policy 已在 decorator 求值阶段归一化的策略。
+ * @returns 可直接交给任意 CacheProvider 的版本化异常内容。
+ * @throws codec 或 JSON 往返失败时传播错误。
+ */
+export function encodeCacheError(error: unknown, policy: NormalizedCacheErrorPolicy): VersionedCacheErrorPayload {
+    const envelope = {
+        kind: CACHE_ERROR_KIND,
+        version: CACHE_ERROR_VERSION,
+        payload: policy.codec.encode(error),
+    };
+    return normalizeJsonValue(envelope) as VersionedCacheErrorPayload;
+}
+
+/**
+ * 判断 Provider 返回的 error 字段是否为当前版本 envelope。
+ * @param value Provider 返回的 error 字段。
+ * @returns kind、version 与 payload 完整匹配当前协议时返回 true。
+ */
+export function isCurrentCacheErrorPayload(value: unknown): value is VersionedCacheErrorPayload {
+    return (
+        isRecord(value) &&
+        value.kind === CACHE_ERROR_KIND &&
+        value.version === CACHE_ERROR_VERSION &&
+        Object.prototype.hasOwnProperty.call(value, 'payload')
+    );
+}
+
+/**
+ * 使用当前策略解码异常，并拒绝异步或不能安全表示的非 Error 结果。
+ * @param envelope 已识别为当前版本的异常内容。
+ * @param policy 当前装饰器启用的异常策略。
+ * @returns codec 产生的同一个异常结果。
+ * @throws codec 抛错或返回不受支持的结果时抛出。
+ */
+export function decodeCacheError(envelope: VersionedCacheErrorPayload, policy: NormalizedCacheErrorPolicy): unknown {
+    const decoded = policy.codec.decode(envelope.payload);
+    if (decoded instanceof Error) {
+        return decoded;
+    }
+    validateJsonValue(decoded, new Set<object>());
+    return decoded;
+}

package/src/core/cache-logger.ts

@@ -0,0 +1,116 @@
+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.error_cache_skipped'
+    | 'cache.error_cache_failed'
+    | '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'
+        | 'disabled'
+        | 'predicate_rejected'
+        | 'legacy_entry'
+        | 'disabled_entry';
+    readonly phase?: 'predicate' | 'encode' | 'decode';
+    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.error_cache_skipped': { level: 'debug', message: 'Cache error entry skipped' },
+    'cache.error_cache_failed': { level: 'warn', message: 'Cache error policy failed' },
+    '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

@@ -15,7 +15,9 @@ export class KeyBuilder {
         }
         const serializedArgs = args
             .map((arg) => {
-                if (arg === null || arg === undefined) return 'null';
+                if (arg === null || arg === undefined) {
+                    return 'null';
+                }
                 if (typeof arg === 'object') {
                     try {
                         return JSON.stringify(arg);

package/src/core/native-cache.ts

@@ -17,7 +17,9 @@ export class MemoryCacheProvider implements CacheProvider {
 
     get<T>(key: string): T | undefined {
         const entry = this.cache.get(key);
-        if (!entry) return undefined;
+        if (!entry) {
+            return undefined;
+        }
         if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
             this.cache.delete(key);
             return undefined;

package/src/core/pending-cache.ts

@@ -11,9 +11,12 @@ export class PendingCache {
 
     set<T>(key: string, promise: Promise<T>): void {
         this.pending.set(key, promise);
-        promise.finally(() => {
-            this.pending.delete(key);
-        });
+        const deleteSettledPromise = (): void => {
+            if (this.pending.get(key) === promise) {
+                this.pending.delete(key);
+            }
+        };
+        void promise.then(deleteSettledPromise, deleteSettledPromise);
     }
 
     delete(key: string): void {

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;
+}

package/src/core/redis-cache.ts

@@ -1,56 +1,104 @@
 import { CacheProvider } from './cache-provider';
-import Redis from 'ioredis';
+import { RedisCacheClient } from './redis-cache-client';
 
 /**
- * Redis 缓存提供者，基于 ioredis 实现
- * 适用于分布式场景，支持跨进程共享缓存
+ * Redis 缓存提供者，在客户端无关的字符串命令之上维护统一缓存协议。
+ * 适用于分布式场景，支持跨进程及跨客户端共享缓存。
  */
 export class RedisCacheProvider implements CacheProvider {
-    private redis: Redis;
+    private readonly client: RedisCacheClient;
 
-    constructor(redis?: Redis) {
-        this.redis = redis ?? new Redis();
+    /**
+     * 创建复用调用方 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.redis.get(key);
-        if (value === null) return 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 (ttl) {
-            await this.redis.setex(key, ttl, serialized);
-        } else {
-            await this.redis.set(key, serialized);
+        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.redis.del(key);
+        await this.client.deleteMany([key]);
     }
 
+    /**
+     * 清空客户端当前选择的整个 Redis 数据库。
+     * @returns FLUSHDB 命令成功后完成。
+     * @throws 清库命令失败时传播客户端原始错误。
+     */
     async clear(): Promise<void> {
-        await this.redis.flushdb();
+        await this.client.flushDatabase();
     }
 
     /**
-     * 根据模式删除匹配的缓存键
-     * @param pattern glob模式字符串（如 user:*），使用 SCAN 游标迭代避免阻塞 Redis
+     * 使用游标扫描并按页删除匹配的逻辑缓存键，避免阻塞 Redis。
+     * @param pattern 保留 glob 语义的逻辑 pattern，例如 user:*。
+     * @returns 游标归零且所有已扫描页面删除成功后完成。
+     * @throws SCAN 或任一页 DEL 失败时传播客户端原始错误，并停止后续页面。
      */
     async deleteByPattern(pattern: string): Promise<void> {
         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);
+            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;
+    }
 }