@jintianxiayu/cache-decorator 0.1.2 → 1.0.0

package/dist/adapters/redis-key-prefix.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeRedisGlobLiteral = escapeRedisGlobLiteral;
+exports.createRedisScanPattern = createRedisScanPattern;
+exports.stripRedisKeyPrefix = stripRedisKeyPrefix;
+const REDIS_GLOB_META_CHARACTERS = new Set(['\\', '*', '?', '[', ']']);
+/**
+ * 将普通字符串转换为 Redis glob pattern 中的字面量片段。
+ * @param value 仅作为字面前缀使用的字符串。
+ * @returns 对反斜杠、星号、问号和方括号增加反斜杠转义后的片段。
+ */
+function escapeRedisGlobLiteral(value) {
+    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。
+ */
+function createRedisScanPattern(keyPrefix, pattern) {
+    return `${escapeRedisGlobLiteral(keyPrefix)}${pattern}`;
+}
+/**
+ * 验证扫描结果属于指定物理命名空间并恢复逻辑 key。
+ * @param keyPrefix 调用方配置的物理 key 前缀。
+ * @param physicalKey Redis SCAN 返回的物理 key。
+ * @returns 只剥离一次字面前缀后的逻辑 key。
+ * @throws 扫描结果不属于指定前缀时抛出 TypeError，避免扩大后续删除范围。
+ */
+function stripRedisKeyPrefix(keyPrefix, physicalKey) {
+    if (!physicalKey.startsWith(keyPrefix)) {
+        throw new TypeError('Redis SCAN returned a key outside the configured key prefix');
+    }
+    return physicalKey.slice(keyPrefix.length);
+}
+//# sourceMappingURL=redis-key-prefix.js.map

package/dist/adapters/redis-key-prefix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-key-prefix.js","sourceRoot":"","sources":["../../src/adapters/redis-key-prefix.ts"],"names":[],"mappings":";;AAOA,wDAMC;AAQD,wDAEC;AASD,kDAKC;AArCD,MAAM,0BAA0B,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAEvE;;;;GAIG;AACH,SAAgB,sBAAsB,CAAC,KAAa;IAChD,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,KAAK,MAAM,SAAS,IAAI,KAAK,EAAE,CAAC;QAC5B,OAAO,IAAI,0BAA0B,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACxF,CAAC;IACD,OAAO,OAAO,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,sBAAsB,CAAC,SAAiB,EAAE,OAAe;IACrE,OAAO,GAAG,sBAAsB,CAAC,SAAS,CAAC,GAAG,OAAO,EAAE,CAAC;AAC5D,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,mBAAmB,CAAC,SAAiB,EAAE,WAAmB;IACtE,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,SAAS,CAAC,6DAA6D,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAC/C,CAAC"}

package/dist/core/cache-logger.d.ts

@@ -0,0 +1,28 @@
+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';
+/** 缓存日志只接受与决策相关的稳定字段，避免业务数据和 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;
+}
+/**
+ * 提交一条不会影响缓存或业务结果的结构化日志。
+ * @param event 决定固定 message 与 level 的缓存事件。
+ * @param context 不包含参数、值或 key 的缓存决策上下文。
+ * @returns 无返回值；Logger 获取或同步写入失败时静默结束。
+ * @throws 不主动抛出异常。
+ */
+export declare function logCacheEvent(event: CacheLogEvent, context: CacheLogContext): void;
+/**
+ * 将 decorator 配置中的 Provider 名称转换为稳定日志标签。
+ * @param providerName 用户显式配置的 Provider 名称。
+ * @returns 非空显式名称；缺省或空字符串返回 `default`。
+ * @throws 不主动抛出异常。
+ */
+export declare function cacheProviderLabel(providerName: string | undefined): string;
+//# sourceMappingURL=cache-logger.d.ts.map

package/dist/core/cache-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-logger.d.ts","sourceRoot":"","sources":["../../src/core/cache-logger.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,aAAa,GACnB,mBAAmB,GACnB,WAAW,GACX,YAAY,GACZ,wBAAwB,GACxB,wBAAwB,GACxB,uBAAuB,GACvB,oBAAoB,GACpB,qBAAqB,GACrB,wBAAwB,CAAC;AAS/B,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,YAAY,CAAC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,CAAC;IACtD,QAAQ,CAAC,SAAS,CAAC,EAAE,qBAAqB,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC5B;AA8CD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAMlF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAK3E"}

package/dist/core/cache-logger.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logCacheEvent = logCacheEvent;
+exports.cacheProviderLabel = cacheProviderLabel;
+const logger_1 = require("@jintianxiayu/logger");
+const CACHE_LOGGER_NAME = '@jintianxiayu/cache-decorator';
+/** 日志定义映射中 K 为稳定事件名，V 为固定的日志级别与无业务数据消息。 */
+const CACHE_LOG_DEFINITIONS = {
+    '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;
+function getCacheLogger() {
+    cacheLogger ??= logger_1.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, definition, metadata) {
+    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 不主动抛出异常。
+ */
+function logCacheEvent(event, context) {
+    try {
+        writeCacheLog(getCacheLogger(), CACHE_LOG_DEFINITIONS[event], { event, ...context });
+    }
+    catch (_error) {
+        return;
+    }
+}
+/**
+ * 将 decorator 配置中的 Provider 名称转换为稳定日志标签。
+ * @param providerName 用户显式配置的 Provider 名称。
+ * @returns 非空显式名称；缺省或空字符串返回 `default`。
+ * @throws 不主动抛出异常。
+ */
+function cacheProviderLabel(providerName) {
+    if (providerName === undefined || providerName.length === 0) {
+        return 'default';
+    }
+    return providerName;
+}
+//# sourceMappingURL=cache-logger.js.map

package/dist/core/cache-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-logger.js","sourceRoot":"","sources":["../../src/core/cache-logger.ts"],"names":[],"mappings":";;AAqFA,sCAMC;AAQD,gDAKC;AAxGD,iDAA2E;AAE3E,MAAM,iBAAiB,GAAG,+BAA+B,CAAC;AAgC1D,2CAA2C;AAC3C,MAAM,qBAAqB,GAAwD;IAC/E,mBAAmB,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,8BAA8B,EAAE;IAChF,WAAW,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE;IAC3D,YAAY,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE;IAC/D,wBAAwB,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,wBAAwB,EAAE;IAC/E,wBAAwB,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,2BAA2B,EAAE;IAClF,uBAAuB,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,0BAA0B,EAAE;IAChF,oBAAoB,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,8CAA8C,EAAE;IAChG,qBAAqB,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,+CAA+C,EAAE;IAClG,wBAAwB,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,wBAAwB,EAAE;CAClF,CAAC;AAEF,IAAI,WAAwC,CAAC;AAE7C,SAAS,cAAc;IACnB,WAAW,KAAK,sBAAa,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;IAC3D,OAAO,WAAW,CAAC;AACvB,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,aAAa,CAClB,MAAuB,EACvB,UAA8B,EAC9B,QAA6D;IAE7D,IAAI,UAAU,CAAC,KAAK,KAAK,OAAO,EAAE,CAAC;QAC/B,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC3C,OAAO;IACX,CAAC;IACD,IAAI,UAAU,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC1C,OAAO;IACX,CAAC;IACD,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,aAAa,CAAC,KAAoB,EAAE,OAAwB;IACxE,IAAI,CAAC;QACD,aAAa,CAAC,cAAc,EAAE,EAAE,qBAAqB,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACzF,CAAC;IAAC,OAAO,MAAM,EAAE,CAAC;QACd,OAAO;IACX,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,SAAgB,kBAAkB,CAAC,YAAgC;IAC/D,IAAI,YAAY,KAAK,SAAS,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1D,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,OAAO,YAAY,CAAC;AACxB,CAAC"}

package/dist/core/cache-provider-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache-provider-registry.d.ts","sourceRoot":"","sources":["../../src/core/cache-provider-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAKjD;;;GAGG;AACH,qBAAa,qBAAqB;IAChC;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI;IAI5D;;;;;OAKG;IACH,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,aAAa;IAYxC;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIrC;;OAEG;IACH,MAAM,CAAC,KAAK,IAAI,IAAI;CAIrB"}
+{"version":3,"file":"cache-provider-registry.d.ts","sourceRoot":"","sources":["../../src/core/cache-provider-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAKjD;;;GAGG;AACH,qBAAa,qBAAqB;IAC9B;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI;IAI5D;;;;;OAKG;IACH,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,aAAa;IAYxC;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIrC;;OAEG;IACH,MAAM,CAAC,KAAK,IAAI,IAAI;CAIvB"}

package/dist/core/cache-provider-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache-provider-registry.js","sourceRoot":"","sources":["../../src/core/cache-provider-registry.ts"],"names":[],"mappings":";;;AAEA,MAAM,SAAS,GAAG,IAAI,GAAG,EAAyB,CAAC;AACnD,IAAI,WAA+B,CAAC;AAEpC;;;GAGG;AACH,MAAa,qBAAqB;IAChC;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAY,EAAE,QAAuB;QACnD,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAChC,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,GAAG,CAAC,IAAa;QACtB,MAAM,YAAY,GAAG,IAAI,IAAI,WAAW,CAAC;QACzC,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,CAAC;QACD,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QAC7C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,kBAAkB,YAAY,aAAa,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,IAAY;QAC5B,WAAW,GAAG,IAAI,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAK;QACV,SAAS,CAAC,KAAK,EAAE,CAAC;QAClB,WAAW,GAAG,SAAS,CAAC;IAC1B,CAAC;CACF;AA3CD,sDA2CC"}
+{"version":3,"file":"cache-provider-registry.js","sourceRoot":"","sources":["../../src/core/cache-provider-registry.ts"],"names":[],"mappings":";;;AAEA,MAAM,SAAS,GAAG,IAAI,GAAG,EAAyB,CAAC;AACnD,IAAI,WAA+B,CAAC;AAEpC;;;GAGG;AACH,MAAa,qBAAqB;IAC9B;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAY,EAAE,QAAuB;QACjD,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAClC,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,GAAG,CAAC,IAAa;QACpB,MAAM,YAAY,GAAG,IAAI,IAAI,WAAW,CAAC;QACzC,IAAI,CAAC,YAAY,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACtE,CAAC;QACD,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QAC7C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,kBAAkB,YAAY,aAAa,CAAC,CAAC;QACjE,CAAC;QACD,OAAO,QAAQ,CAAC;IACpB,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,IAAY;QAC1B,WAAW,GAAG,IAAI,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAK;QACR,SAAS,CAAC,KAAK,EAAE,CAAC;QAClB,WAAW,GAAG,SAAS,CAAC;IAC5B,CAAC;CACJ;AA3CD,sDA2CC"}

package/dist/core/cache-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache-provider.d.ts","sourceRoot":"","sources":["../../src/core/cache-provider.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAE5D;;;;;OAKG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElE;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C;;OAEG;IACH,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9B;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD"}
+{"version":3,"file":"cache-provider.d.ts","sourceRoot":"","sources":["../../src/core/cache-provider.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC1B;;;;OAIG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAE5D;;;;;OAKG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElE;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C;;OAEG;IACH,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9B;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D"}

package/dist/core/key-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"key-builder.d.ts","sourceRoot":"","sources":["../../src/core/key-builder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,UAAU;IACrB;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM;CAmBzD"}
+{"version":3,"file":"key-builder.d.ts","sourceRoot":"","sources":["../../src/core/key-builder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,UAAU;IACnB;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM;CAqB3D"}

package/dist/core/key-builder.js

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

package/dist/core/key-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"key-builder.js","sourceRoot":"","sources":["../../src/core/key-builder.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,MAAa,UAAU;IACrB;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,SAAiB,EAAE,IAAe;QAC7C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,cAAc,GAAG,IAAI;aACxB,GAAG,CAAC,GAAG,CAAC,EAAE;YACT,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS;gBAAE,OAAO,MAAM,CAAC;YACrD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAC5B,IAAI,CAAC;oBACH,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;gBAC7B,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;gBACrB,CAAC;YACH,CAAC;YACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC,CAAC;aACD,IAAI,CAAC,GAAG,CAAC,CAAC;QACb,OAAO,GAAG,SAAS,IAAI,cAAc,EAAE,CAAC;IAC1C,CAAC;CACF;AA1BD,gCA0BC"}
+{"version":3,"file":"key-builder.js","sourceRoot":"","sources":["../../src/core/key-builder.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,MAAa,UAAU;IACnB;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,SAAiB,EAAE,IAAe;QAC3C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpB,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,MAAM,cAAc,GAAG,IAAI;aACtB,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;YACT,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;gBACpC,OAAO,MAAM,CAAC;YAClB,CAAC;YACD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAC1B,IAAI,CAAC;oBACD,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;gBAC/B,CAAC;gBAAC,MAAM,CAAC;oBACL,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;gBACvB,CAAC;YACL,CAAC;YACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC,CAAC;aACD,IAAI,CAAC,GAAG,CAAC,CAAC;QACf,OAAO,GAAG,SAAS,IAAI,cAAc,EAAE,CAAC;IAC5C,CAAC;CACJ;AA5BD,gCA4BC"}

package/dist/core/native-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-cache.d.ts","sourceRoot":"","sources":["../../src/core/native-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAUjD;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IACvD,OAAO,CAAC,KAAK,CAA0C;IAEvD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAUlC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAKjD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,KAAK,IAAI,IAAI;IAIb;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAQvC"}
+{"version":3,"file":"native-cache.d.ts","sourceRoot":"","sources":["../../src/core/native-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAUjD;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IACrD,OAAO,CAAC,KAAK,CAA0C;IAEvD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAYlC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAKjD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,KAAK,IAAI,IAAI;IAIb;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAQzC"}

package/dist/core/native-cache.js

@@ -11,8 +11,9 @@ class MemoryCacheProvider {
     }
     get(key) {
         const entry = this.cache.get(key);
-        if (!entry)
+        if (!entry) {
             return undefined;
+        }
         if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
             this.cache.delete(key);
             return undefined;

package/dist/core/native-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"native-cache.js","sourceRoot":"","sources":["../../src/core/native-cache.ts"],"names":[],"mappings":";;;AAUA;;;GAGG;AACH,MAAa,mBAAmB;IAAhC;QACU,UAAK,GAAG,IAAI,GAAG,EAA+B,CAAC;IAqCzD,CAAC;IAnCC,GAAG,CAAI,GAAW;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC7B,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YAC7D,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,KAAK,CAAC,KAAU,CAAC;IAC1B,CAAC;IAED,GAAG,CAAI,GAAW,EAAE,KAAQ,EAAE,GAAY;QACxC,MAAM,SAAS,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QACvD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,OAAe;QAC7B,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC1C,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YACpC,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC3B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAtCD,kDAsCC"}
+{"version":3,"file":"native-cache.js","sourceRoot":"","sources":["../../src/core/native-cache.ts"],"names":[],"mappings":";;;AAUA;;;GAGG;AACH,MAAa,mBAAmB;IAAhC;QACY,UAAK,GAAG,IAAI,GAAG,EAA+B,CAAC;IAuC3D,CAAC;IArCG,GAAG,CAAI,GAAW;QACd,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YAC3D,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,OAAO,KAAK,CAAC,KAAU,CAAC;IAC5B,CAAC;IAED,GAAG,CAAI,GAAW,EAAE,KAAQ,EAAE,GAAY;QACtC,MAAM,SAAS,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QACvD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,MAAM,CAAC,GAAW;QACd,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,KAAK;QACD,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,OAAe;QAC3B,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC1C,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YAClC,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBACzB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC3B,CAAC;QACL,CAAC;IACL,CAAC;CACJ;AAxCD,kDAwCC"}

package/dist/core/pending-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pending-cache.d.ts","sourceRoot":"","sources":["../../src/core/pending-cache.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAuC;IAEtD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS;IAI3C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;IAO9C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,KAAK,IAAI,IAAI;CAGd"}
+{"version":3,"file":"pending-cache.d.ts","sourceRoot":"","sources":["../../src/core/pending-cache.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,YAAY;IACrB,OAAO,CAAC,OAAO,CAAuC;IAEtD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS;IAI3C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;IAU9C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,KAAK,IAAI,IAAI;CAGhB"}

package/dist/core/pending-cache.js

@@ -14,9 +14,12 @@ class PendingCache {
     }
     set(key, promise) {
         this.pending.set(key, promise);
-        promise.finally(() => {
-            this.pending.delete(key);
-        });
+        const deleteSettledPromise = () => {
+            if (this.pending.get(key) === promise) {
+                this.pending.delete(key);
+            }
+        };
+        void promise.then(deleteSettledPromise, deleteSettledPromise);
     }
     delete(key) {
         this.pending.delete(key);

package/dist/core/pending-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"pending-cache.js","sourceRoot":"","sources":["../../src/core/pending-cache.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,MAAa,YAAY;IAAzB;QACU,YAAO,GAAG,IAAI,GAAG,EAA4B,CAAC;IAoBxD,CAAC;IAlBC,GAAG,CAAI,GAAW;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAA2B,CAAC;IACzD,CAAC;IAED,GAAG,CAAI,GAAW,EAAE,OAAmB;QACrC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC/B,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE;YACnB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;CACF;AArBD,oCAqBC"}
+{"version":3,"file":"pending-cache.js","sourceRoot":"","sources":["../../src/core/pending-cache.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,MAAa,YAAY;IAAzB;QACY,YAAO,GAAG,IAAI,GAAG,EAA4B,CAAC;IAuB1D,CAAC;IArBG,GAAG,CAAI,GAAW;QACd,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAA2B,CAAC;IAC3D,CAAC;IAED,GAAG,CAAI,GAAW,EAAE,OAAmB;QACnC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC/B,MAAM,oBAAoB,GAAG,GAAS,EAAE;YACpC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,OAAO,EAAE,CAAC;gBACpC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7B,CAAC;QACL,CAAC,CAAC;QACF,KAAK,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE,oBAAoB,CAAC,CAAC;IAClE,CAAC;IAED,MAAM,CAAC,GAAW;QACd,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED,KAAK;QACD,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;CACJ;AAxBD,oCAwBC"}

package/dist/core/redis-cache-client.d.ts

@@ -0,0 +1,156 @@
+/** 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;
+}
+//# sourceMappingURL=redis-cache-client.d.ts.map

package/dist/core/redis-cache-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-cache-client.d.ts","sourceRoot":"","sources":["../../src/core/redis-cache-client.ts"],"names":[],"mappings":"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"}

package/dist/core/redis-cache-client.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=redis-cache-client.js.map

package/dist/core/redis-cache-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-cache-client.js","sourceRoot":"","sources":["../../src/core/redis-cache-client.ts"],"names":[],"mappings":""}

package/dist/core/redis-cache.d.ts

@@ -1,20 +1,52 @@
 import { CacheProvider } from './cache-provider';
-import Redis from 'ioredis';
+import { RedisCacheClient } from './redis-cache-client';
 /**
- * Redis 缓存提供者，基于 ioredis 实现
- * 适用于分布式场景，支持跨进程共享缓存
+ * Redis 缓存提供者，在客户端无关的字符串命令之上维护统一缓存协议。
+ * 适用于分布式场景，支持跨进程及跨客户端共享缓存。
  */
 export declare class RedisCacheProvider implements CacheProvider {
-    private redis;
-    constructor(redis?: Redis);
+    private readonly client;
+    /**
+     * 创建复用调用方 Redis 连接的缓存提供者。
+     * @param client 已适配的最小 Redis 缓存客户端。
+     */
+    constructor(client: RedisCacheClient);
+    /**
+     * 按既有协议读取并反序列化缓存值。
+     * @param key 未经 Provider 改写的逻辑缓存键。
+     * @returns 解析后的业务值；Redis miss 时返回 undefined。
+     * @throws GET 命令失败时传播客户端原始错误。
+     */
     get<T>(key: string): Promise<T | undefined>;
+    /**
+     * 按既有字符串或 JSON 协议写入缓存值。
+     * @param key 未经 Provider 改写的逻辑缓存键。
+     * @param value 需要缓存的业务值。
+     * @param ttl 可选的正整数秒级 TTL；undefined 或 0 表示永不过期。
+     * @returns 写入命令成功后完成。
+     * @throws 值不能序列化时抛 TypeError，TTL 非法时抛 RangeError，命令失败时传播原始错误。
+     */
     set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    /**
+     * 幂等删除一个逻辑缓存键。
+     * @param key 未经 Provider 改写的逻辑缓存键。
+     * @returns 删除命令成功后完成。
+     * @throws DEL 命令失败时传播客户端原始错误。
+     */
     delete(key: string): Promise<void>;
+    /**
+     * 清空客户端当前选择的整个 Redis 数据库。
+     * @returns FLUSHDB 命令成功后完成。
+     * @throws 清库命令失败时传播客户端原始错误。
+     */
     clear(): Promise<void>;
     /**
-     * 根据模式删除匹配的缓存键
-     * @param pattern glob模式字符串（如 user:*），使用 SCAN 游标迭代避免阻塞 Redis
+     * 使用游标扫描并按页删除匹配的逻辑缓存键，避免阻塞 Redis。
+     * @param pattern 保留 glob 语义的逻辑 pattern，例如 user:*。
+     * @returns 游标归零且所有已扫描页面删除成功后完成。
+     * @throws SCAN 或任一页 DEL 失败时传播客户端原始错误，并停止后续页面。
      */
     deleteByPattern(pattern: string): Promise<void>;
+    private normalizeTtl;
 }
 //# sourceMappingURL=redis-cache.d.ts.map

package/dist/core/redis-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"redis-cache.d.ts","sourceRoot":"","sources":["../../src/core/redis-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,MAAM,SAAS,CAAC;AAE5B;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,aAAa;IACtD,OAAO,CAAC,KAAK,CAAQ;gBAET,KAAK,CAAC,EAAE,KAAK;IAInB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAU3C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS1D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;OAGG;IACG,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAgBtD"}
+{"version":3,"file":"redis-cache.d.ts","sourceRoot":"","sources":["../../src/core/redis-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,aAAa;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAE1C;;;OAGG;gBACS,MAAM,EAAE,gBAAgB;IAIpC;;;;;OAKG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAajD;;;;;;;OAOG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAahE;;;;;OAKG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;;OAKG;IACG,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWrD,OAAO,CAAC,YAAY;CASvB"}

package/dist/core/redis-cache.js

@@ -1,58 +1,99 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RedisCacheProvider = void 0;
-const ioredis_1 = __importDefault(require("ioredis"));
 /**
- * Redis 缓存提供者，基于 ioredis 实现
- * 适用于分布式场景，支持跨进程共享缓存
+ * Redis 缓存提供者，在客户端无关的字符串命令之上维护统一缓存协议。
+ * 适用于分布式场景，支持跨进程及跨客户端共享缓存。
  */
 class RedisCacheProvider {
-    constructor(redis) {
-        this.redis = redis ?? new ioredis_1.default();
+    /**
+     * 创建复用调用方 Redis 连接的缓存提供者。
+     * @param client 已适配的最小 Redis 缓存客户端。
+     */
+    constructor(client) {
+        this.client = client;
     }
+    /**
+     * 按既有协议读取并反序列化缓存值。
+     * @param key 未经 Provider 改写的逻辑缓存键。
+     * @returns 解析后的业务值；Redis miss 时返回 undefined。
+     * @throws GET 命令失败时传播客户端原始错误。
+     */
     async get(key) {
-        const value = await this.redis.get(key);
-        if (value === null)
+        const value = await this.client.get(key);
+        if (value === null) {
             return undefined;
+        }
         try {
             return JSON.parse(value);
         }
         catch {
+            // 兼容既有协议：不是合法 JSON 的字符串按原值返回。
             return value;
         }
     }
+    /**
+     * 按既有字符串或 JSON 协议写入缓存值。
+     * @param key 未经 Provider 改写的逻辑缓存键。
+     * @param value 需要缓存的业务值。
+     * @param ttl 可选的正整数秒级 TTL；undefined 或 0 表示永不过期。
+     * @returns 写入命令成功后完成。
+     * @throws 值不能序列化时抛 TypeError，TTL 非法时抛 RangeError，命令失败时传播原始错误。
+     */
     async set(key, value, ttl) {
+        const ttlSeconds = this.normalizeTtl(ttl);
         const serialized = typeof value === 'string' ? value : JSON.stringify(value);
-        if (ttl) {
-            await this.redis.setex(key, ttl, serialized);
+        if (typeof serialized !== 'string') {
+            throw new TypeError('Cache value must serialize to a string');
         }
-        else {
-            await this.redis.set(key, serialized);
+        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) {
-        await this.redis.del(key);
+        await this.client.deleteMany([key]);
     }
+    /**
+     * 清空客户端当前选择的整个 Redis 数据库。
+     * @returns FLUSHDB 命令成功后完成。
+     * @throws 清库命令失败时传播客户端原始错误。
+     */
     async clear() {
-        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) {
         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');
     }
+    normalizeTtl(ttl) {
+        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;
+    }
 }
 exports.RedisCacheProvider = RedisCacheProvider;
 //# sourceMappingURL=redis-cache.js.map