@jintianxiayu/cache-decorator 0.1.3 → 1.0.1

package/dist/decorators/cache.js

@@ -3,29 +3,150 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CacheProviderRegistry = void 0;
 exports.Cache = Cache;
 require("reflect-metadata");
+const cache_error_1 = require("../core/cache-error");
+const cache_logger_1 = require("../core/cache-logger");
 const cache_provider_registry_1 = require("../core/cache-provider-registry");
 const key_builder_1 = require("../core/key-builder");
 const pending_cache_1 = require("../core/pending-cache");
 const pendingCache = new pending_cache_1.PendingCache();
+/**
+ * 获取配置指向的缓存 Provider，并在解析失败时记录原始错误。
+ * @param providerName decorator 配置中的 Provider 名称。
+ * @param logContext 当前方法的稳定日志上下文。
+ * @returns 已注册的缓存 Provider。
+ * @throws Provider 注册表抛出的原始错误。
+ */
+function resolveCacheProvider(providerName, logContext) {
+    try {
+        return cache_provider_registry_1.CacheProviderRegistry.get(providerName);
+    }
+    catch (error) {
+        (0, cache_logger_1.logCacheEvent)('cache.operation_failed', { ...logContext, operation: 'provider_resolution', error });
+        throw error;
+    }
+}
+/**
+ * 保持 fire-and-forget 语义提交缓存写入，仅捕获调用当下可观察的同步失败。
+ * @param request 写入所需 Provider、entry 和无业务数据日志上下文。
+ * @returns 无返回值；异步写入 Promise 不会被等待或消费。
+ * @throws Provider set 同步抛出的原始错误。
+ */
+function dispatchCacheWrite(request) {
+    try {
+        request.provider.set(request.cacheKey, request.entry, request.ttl);
+    }
+    catch (error) {
+        (0, cache_logger_1.logCacheEvent)('cache.operation_failed', { ...request.logContext, operation: 'write', error });
+        throw error;
+    }
+    (0, cache_logger_1.logCacheEvent)('cache.write_dispatched', { ...request.logContext, entryType: request.entryType });
+}
+/**
+ * 提交异常条目写入；同步 Provider 失败只记录基础设施错误，不遮蔽已经发生的业务异常。
+ * @param request 异常写入所需 Provider、entry、TTL 和稳定日志上下文。
+ * @returns 无返回值；异步写入 Promise 保持既有 fire-and-forget 边界。
+ */
+function dispatchCacheErrorWrite(request) {
+    try {
+        request.provider.set(request.cacheKey, request.entry, request.ttl);
+    }
+    catch (error) {
+        (0, cache_logger_1.logCacheEvent)('cache.operation_failed', { ...request.logContext, operation: 'write', error });
+        return;
+    }
+    (0, cache_logger_1.logCacheEvent)('cache.write_dispatched', { ...request.logContext, entryType: 'error' });
+}
+function isErrorCacheEntry(entry) {
+    return typeof entry === 'object' && entry !== null && 'error' in entry;
+}
+/**
+ * 按当前异常策略分类 Provider 条目，并只把可成功解码的当前版本异常视为命中。
+ * @param entry Provider 返回的缓存联合条目。
+ * @param errorPolicy 当前装饰器归一化后的异常策略。
+ * @param logContext 当前方法的稳定日志上下文。
+ * @returns value/error 命中结果，或需要继续业务流程的 miss。
+ */
+function resolveCachedEntry(entry, errorPolicy, logContext) {
+    if (!isErrorCacheEntry(entry)) {
+        (0, cache_logger_1.logCacheEvent)('cache.hit', { ...logContext, entryType: 'value' });
+        return { type: 'value', value: entry.value };
+    }
+    if (!(0, cache_error_1.isCurrentCacheErrorPayload)(entry.error)) {
+        (0, cache_logger_1.logCacheEvent)('cache.error_cache_skipped', { ...logContext, reason: 'legacy_entry' });
+        return { type: 'miss' };
+    }
+    if (errorPolicy === undefined) {
+        (0, cache_logger_1.logCacheEvent)('cache.error_cache_skipped', { ...logContext, reason: 'disabled_entry' });
+        return { type: 'miss' };
+    }
+    try {
+        const error = (0, cache_error_1.decodeCacheError)(entry.error, errorPolicy);
+        (0, cache_logger_1.logCacheEvent)('cache.hit', { ...logContext, entryType: 'error' });
+        return { type: 'error', error };
+    }
+    catch (_error) {
+        (0, cache_logger_1.logCacheEvent)('cache.error_cache_failed', { ...logContext, phase: 'decode' });
+        return { type: 'miss' };
+    }
+}
+/**
+ * 按固定顺序评估筛选器、编码异常并发起独立 TTL 写入，任何策略失败都保留原业务异常。
+ * @param request 本次业务异常、当前策略、Provider、完整 key 与稳定日志上下文。
+ * @returns 无返回值。
+ */
+function handleBusinessError(request) {
+    const { error, errorPolicy, provider, cacheKey, logContext } = request;
+    if (errorPolicy === undefined) {
+        (0, cache_logger_1.logCacheEvent)('cache.error_cache_skipped', { ...logContext, reason: 'disabled' });
+        return;
+    }
+    if (errorPolicy.shouldCache !== undefined) {
+        let accepted;
+        try {
+            accepted = errorPolicy.shouldCache(error);
+            if (typeof accepted !== 'boolean') {
+                throw new TypeError('Cache error shouldCache must return a boolean');
+            }
+        }
+        catch (_error) {
+            (0, cache_logger_1.logCacheEvent)('cache.error_cache_failed', { ...logContext, phase: 'predicate' });
+            return;
+        }
+        if (!accepted) {
+            (0, cache_logger_1.logCacheEvent)('cache.error_cache_skipped', { ...logContext, reason: 'predicate_rejected' });
+            return;
+        }
+    }
+    let entry;
+    try {
+        entry = { error: (0, cache_error_1.encodeCacheError)(error, errorPolicy) };
+    }
+    catch (_error) {
+        (0, cache_logger_1.logCacheEvent)('cache.error_cache_failed', { ...logContext, phase: 'encode' });
+        return;
+    }
+    dispatchCacheErrorWrite({ provider, cacheKey, entry, entryType: 'error', ttl: errorPolicy.ttl, logContext });
+}
 /**
  * 解析缓存 key
- * @param cacheName 缓存名称
  * @param keyResolver key 解析器
  * @param args 方法参数数组
+ * @param logContext 不包含业务参数和值的日志上下文
  * @returns 解析后的缓存 key
  */
-function resolveCacheKey(cacheName, keyResolver, args) {
+function resolveCacheKey(keyResolver, args, logContext) {
     if (keyResolver === undefined || keyResolver === null) {
-        return key_builder_1.KeyBuilder.build(cacheName, args);
+        return key_builder_1.KeyBuilder.build(logContext.cacheName, args);
     }
     if (typeof keyResolver === 'string') {
-        return key_builder_1.KeyBuilder.build(cacheName, [keyResolver]);
+        return key_builder_1.KeyBuilder.build(logContext.cacheName, [keyResolver]);
     }
     try {
-        return key_builder_1.KeyBuilder.build(cacheName, [keyResolver(...args)]);
+        return key_builder_1.KeyBuilder.build(logContext.cacheName, [keyResolver(...args)]);
     }
-    catch {
-        return key_builder_1.KeyBuilder.build(cacheName, args);
+    catch (_error) {
+        (0, cache_logger_1.logCacheEvent)('cache.key_fallback', { ...logContext, reason: 'resolver_error' });
+        return key_builder_1.KeyBuilder.build(logContext.cacheName, args);
     }
 }
 /**
@@ -35,34 +156,58 @@ function resolveCacheKey(cacheName, keyResolver, args) {
  * @param options 配置项
  */
 function Cache(cacheName, options) {
-    return function (_target, _propertyKey, descriptor) {
+    const errorPolicy = (0, cache_error_1.normalizeCacheErrorPolicy)(options?.errorCache);
+    return function (_target, propertyKey, descriptor) {
         const originalMethod = descriptor.value;
-        descriptor.value = async function (...args) {
-            const cacheKey = resolveCacheKey(cacheName, options?.key, args);
-            const providerName = options?.providerName;
-            const provider = cache_provider_registry_1.CacheProviderRegistry.get(providerName);
-            const cached = await provider.get(cacheKey);
-            if (cached !== undefined) {
-                const entry = cached;
-                if ('error' in entry) {
-                    throw entry.error;
-                }
-                return entry.value;
-            }
+        const logContext = {
+            cacheName,
+            methodName: propertyKey,
+            providerName: (0, cache_logger_1.cacheProviderLabel)(options?.providerName),
+        };
+        descriptor.value = function (...args) {
+            const cacheKey = resolveCacheKey(options?.key, args, logContext);
             const pending = pendingCache.get(cacheKey);
             if (pending) {
+                (0, cache_logger_1.logCacheEvent)('cache.pending_hit', logContext);
                 return pending;
             }
             const promise = (async () => {
+                const provider = resolveCacheProvider(options?.providerName, logContext);
+                let cached;
+                try {
+                    cached = await provider.get(cacheKey);
+                }
+                catch (error) {
+                    (0, cache_logger_1.logCacheEvent)('cache.operation_failed', { ...logContext, operation: 'read', error });
+                    throw error;
+                }
+                if (cached !== undefined) {
+                    const cachedResult = resolveCachedEntry(cached, errorPolicy, logContext);
+                    if (cachedResult.type === 'value') {
+                        return cachedResult.value;
+                    }
+                    if (cachedResult.type === 'error') {
+                        throw cachedResult.error;
+                    }
+                }
+                (0, cache_logger_1.logCacheEvent)('cache.miss', logContext);
+                let result;
                 try {
-                    const result = await originalMethod.apply(this, args);
-                    provider.set(cacheKey, { value: result }, options?.ttl);
-                    return result;
+                    result = (await originalMethod.apply(this, args));
                 }
                 catch (error) {
-                    provider.set(cacheKey, { error }, options?.ttl);
+                    handleBusinessError({ error, errorPolicy, provider, cacheKey, logContext });
                     throw error;
                 }
+                dispatchCacheWrite({
+                    provider,
+                    cacheKey,
+                    entry: { value: result },
+                    entryType: 'value',
+                    ttl: options?.ttl,
+                    logContext,
+                });
+                return result;
             })();
             pendingCache.set(cacheKey, promise);
             return promise;

package/dist/decorators/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/decorators/cache.ts"],"names":[],"mappings":";;;AAoFA,sBA0CC;AA9HD,4BAA0B;AAC1B,6EAAwE;AACxE,qDAAiD;AACjD,yDAAqD;AAoDrD,MAAM,YAAY,GAAG,IAAI,4BAAY,EAAE,CAAC;AAExC;;;;;;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,KAAK,CAAC,SAAiB,EAAE,OAAsB;IAC7D,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,QAAQ,GAAG,eAAe,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;YAChE,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,CAAC;YAC3C,MAAM,QAAQ,GAAG,+CAAqB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YAEzD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC5C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,KAAK,GAAG,MAAuB,CAAC;gBACtC,IAAI,OAAO,IAAI,KAAK,EAAE,CAAC;oBACrB,MAAM,KAAK,CAAC,KAAK,CAAC;gBACpB,CAAC;gBACD,OAAO,KAAK,CAAC,KAAK,CAAC;YACrB,CAAC;YAED,MAAM,OAAO,GAAG,YAAY,CAAC,GAAG,CAAI,QAAQ,CAAC,CAAC;YAC9C,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,OAAO,CAAC;YACjB,CAAC;YAED,MAAM,OAAO,GAAG,CAAC,KAAK,IAAI,EAAE;gBAC1B,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;oBACtD,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,MAAM,EAAmB,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;oBACzE,OAAO,MAAM,CAAC;gBAChB,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAmB,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;oBACjE,MAAM,KAAK,CAAC;gBACd,CAAC;YACH,CAAC,CAAC,EAAE,CAAC;YAEL,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACpC,OAAO,OAAO,CAAC;QACjB,CAAC,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED,2EAAwE;AAA/D,gIAAA,qBAAqB,OAAA"}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/decorators/cache.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,8 +1,11 @@
+export { createIoredisCacheClient } from './adapters/ioredis-cache-client';
+export { createNodeRedisCacheClient } from './adapters/node-redis-cache-client';
 export * from './core/cache-provider';
 export * from './core/cache-provider-registry';
 export * from './core/key-builder';
 export * from './core/native-cache';
 export * from './core/pending-cache';
+export * from './core/redis-cache-client';
 export * from './core/redis-cache';
 export * from './decorators/cache';
 export * from './decorators/cache-evict';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,uBAAuB,CAAC;AACtC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAChF,cAAc,uBAAuB,CAAC;AACtC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -14,11 +14,17 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNodeRedisCacheClient = exports.createIoredisCacheClient = void 0;
+var ioredis_cache_client_1 = require("./adapters/ioredis-cache-client");
+Object.defineProperty(exports, "createIoredisCacheClient", { enumerable: true, get: function () { return ioredis_cache_client_1.createIoredisCacheClient; } });
+var node_redis_cache_client_1 = require("./adapters/node-redis-cache-client");
+Object.defineProperty(exports, "createNodeRedisCacheClient", { enumerable: true, get: function () { return node_redis_cache_client_1.createNodeRedisCacheClient; } });
 __exportStar(require("./core/cache-provider"), exports);
 __exportStar(require("./core/cache-provider-registry"), exports);
 __exportStar(require("./core/key-builder"), exports);
 __exportStar(require("./core/native-cache"), exports);
 __exportStar(require("./core/pending-cache"), exports);
+__exportStar(require("./core/redis-cache-client"), exports);
 __exportStar(require("./core/redis-cache"), exports);
 __exportStar(require("./decorators/cache"), exports);
 __exportStar(require("./decorators/cache-evict"), exports);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AACA,wDAAsC;AACtC,iEAA+C;AAC/C,qDAAmC;AACnC,sDAAoC;AACpC,uDAAqC;AACrC,qDAAmC;AACnC,qDAAmC;AACnC,2DAAyC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,wEAA2E;AAAlE,gIAAA,wBAAwB,OAAA;AACjC,8EAAgF;AAAvE,qIAAA,0BAA0B,OAAA;AACnC,wDAAsC;AACtC,iEAA+C;AAC/C,qDAAmC;AACnC,sDAAoC;AACpC,uDAAqC;AACrC,4DAA0C;AAC1C,qDAAmC;AACnC,qDAAmC;AACnC,2DAAyC"}

package/jest.config.js

@@ -6,6 +6,6 @@ module.exports = {
     moduleFileExtensions: ['ts', 'js', 'json'],
     collectCoverageFrom: ['src/**/*.ts', '!src/**/*.d.ts'],
     transform: {
-        '^.+\\.ts$': 'ts-jest',
+        '^.+\\.ts$': ['ts-jest', { tsconfig: '<rootDir>/../../tsconfig.test.json' }],
     },
 };

package/package.json

@@ -1,30 +1,27 @@
 {
-    "name": "@jintianxiayu/cache-decorator",
-    "version": "0.1.3",
-    "description": "Method caching decorators for TypeScript",
-    "main": "dist/index.js",
-    "types": "dist/index.d.ts",
-    "scripts": {
-        "build": "tsc",
-        "test": "jest",
-        "typecheck": "tsc --noEmit"
-    },
-    "dependencies": {
-        "reflect-metadata": "^0.2.2"
-    },
-    "devDependencies": {
-        "@types/ioredis": "^4.28.10",
-        "@types/node": "^22.10.0",
-        "ioredis": "^5.10.1",
-        "jest": "^29.7.0",
-        "ts-jest": "^29.2.0",
-        "typescript": "^5.7.0"
-    },
-    "peerDependencies": {
-        "reflect-metadata": "^0.2.2"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "gitHead": "0518a4e3649799cc6c176dabfebeb86bd0891085"
-}
+  "name": "@jintianxiayu/cache-decorator",
+  "version": "1.0.1",
+  "description": "Method caching decorators for TypeScript",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "reflect-metadata": "^0.2.2"
+  },
+  "peerDependencies": {
+    "@jintianxiayu/logger": "^1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "ioredis": "^5.10.1",
+    "redis": "^5.12.1",
+    "@jintianxiayu/logger": "^1.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "clean": "rimraf dist",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/adapters/ioredis-cache-client.ts

@@ -0,0 +1,89 @@
+import { IoredisCacheClientSource, 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 normalizeScanResponse(
+    response: unknown,
+    keyPrefix: string
+): { readonly cursor: string; readonly keys: readonly string[] } {
+    if (
+        !Array.isArray(response) ||
+        response.length !== 2 ||
+        typeof response[0] !== 'string' ||
+        !Array.isArray(response[1]) ||
+        !response[1].every((key: unknown) => typeof key === 'string')
+    ) {
+        throw new TypeError('Expected ioredis SCAN to return a [cursor, keys] tuple');
+    }
+    return {
+        cursor: response[0],
+        keys: response[1].map((key: string) => stripRedisKeyPrefix(keyPrefix, key)),
+    };
+}
+
+/**
+ * 将调用方的 ioredis 连接适配为客户端无关的缓存命令，不创建或关闭连接。
+ * @param client 使用默认字符串响应映射的 ioredis 普通客户端。
+ * @returns 复用该连接并恢复逻辑 key 的 Redis 缓存客户端。
+ * @throws 返回对象的命令方法传播客户端错误；非标准响应拒绝为 TypeError。
+ */
+export function createIoredisCacheClient(client: IoredisCacheClientSource): RedisCacheClient {
+    const keyPrefix = client.options.keyPrefix ?? '';
+    return {
+        /** @inheritdoc */
+        async get(key: string): Promise<string | null> {
+            return normalizeGetResponse(await client.get(key));
+        },
+        /** @inheritdoc */
+        async set({ key, value, ttlSeconds }): Promise<void> {
+            if (ttlSeconds === undefined) {
+                validateOkResponse('SET', await client.set(key, value));
+                return;
+            }
+            validateOkResponse('SETEX', await client.setex(key, ttlSeconds, value));
+        },
+        /** @inheritdoc */
+        async deleteMany(keys: readonly string[]): Promise<void> {
+            if (keys.length === 0) {
+                return;
+            }
+            validateDeleteResponse(await client.del(...keys));
+        },
+        /** @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/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);
+}