@jintianxiayu/cache-decorator 0.1.2 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# @jintianxiayu/cache-decorator
+
+## 1.0.0
+
+### Major Changes
+
+- 本次发布包含以下变更：
+
+  - `@jintianxiayu/logger`：重构日志配置、命名 Logger、Plain/JSON 输出、轮转文件、元数据规范化与脱敏、异步 `traceId` 上下文、进程错误处理及可等待的关闭流程。BREAKING：包根不再导出 `createLogger`、`ConfigLoader` 和 `LogPosition`；`LoggerContext.set/clear/getStore` 改为通过 `withContext/get` 使用，配置结构及脱敏字段格式同步调整，运行时要求 Node.js 20.19+/22.13+/24+。
+  - `@jintianxiayu/cache-decorator`：修复并发缓存 Promise 复用及拒绝后的清理；解耦 `RedisCacheProvider` 与具体 Redis SDK，新增 `RedisCacheClient`、ioredis 和 node-redis 适配工厂，并保持 Redis key、值格式及秒级 TTL 兼容；新增缓存命中、回填、淘汰和基础设施失败的结构化日志。BREAKING：调用方必须显式包装并管理 Redis 连接、直接声明所用 Redis 客户端依赖，同时提供兼容的 `@jintianxiayu/logger` peer 并在首次缓存调用前初始化 Logger。
+  - `@jintianxiayu/lock-decorator`：解耦 `RedisLockProvider` 与 ioredis，新增 `RedisLockClient`、ioredis 和 node-redis 适配工厂，锁协议及连接所有权语义保持不变；新增锁获取、重试、续期、业务执行和释放的结构化日志。Watchdog 续期 Promise 拒绝会被记录并停止后续续期，不再形成未处理拒绝，已开始的业务仍继续执行并在结束时尝试释放锁。BREAKING：调用方必须显式包装现有 Redis 连接、直接声明客户端依赖，同时提供兼容的 `@jintianxiayu/logger` peer 并在首次锁调用前初始化 Logger。
+  - `@jintianxiayu/http-client-decorator`：同步适配 logger 0.2 的 peer 依赖与异步上下文用法；调用方应通过 `LoggerContext.withContext` 建立请求上下文，tracing 中间件继续从中读取并注入 `traceId`。
+  - 仓库开发与发布流程迁移到 pnpm 11 原生 workspace，并统一 TypeScript NodeNext、Jest、清理、构建和本地发布配置。
+
+### Patch Changes
+
+- Updated dependencies:
+  - @jintianxiayu/logger@1.0.0

package/README.md

@@ -1,133 +1,270 @@
-# @jintianxiayu/cache-decorator
-
-方法缓存装饰器，为 TypeScript 方法提供声明式缓存功能。
-
-## 安装
-
-```bash
-npm install @jintianxiayu/cache-decorator reflect-metadata
-```
-
-## 特性
-
-- `@Cache` 装饰器：方法缓存，支持 TTL 过期
-- `@CacheEvict` 装饰器：缓存清除
-- 可插拔的缓存后端（Memory / Redis / 自定义）
-- 请求合并：并发场景下返回同一个 Promise
-- 错误结果缓存：防止缓存穿透
-
-## 重要提示
-
-> ⚠️ **@Cache 和 @CacheEvict 装饰器仅适用于返回 Promise 的方法**
->
-> 这两个装饰器都会将被装饰的方法替换为异步函数。如果装饰返回非 Promise 的同步方法，调用方会收到 Promise 对象而非期望的返回值，导致难以排查的 bug。
->
-> ```typescript
-> // ✅ 正确：async 方法或返回 Promise 的方法
-> @Cache('data')
-> async getData() { ... }
->
-> @CacheEvict('data')
-> async clearData() { ... }
->
-> // ❌ 错误：返回非 Promise 的同步方法不要使用这些装饰器
-> @Cache('data')
-> getData() { return 'result'; }  // 调用方得到 Promise，不是 'result'
-> ```
-
-## 使用示例
-
-```typescript
-import 'reflect-metadata';
-import { Cache, CacheEvict, CacheProviderRegistry, MemoryCacheProvider } from '@jintianxiayu/cache-decorator';
-
-// 注册默认 Provider
-CacheProviderRegistry.register('memory', new MemoryCacheProvider());
-CacheProviderRegistry.setDefault('memory');
-
-class UserService {
-  @Cache('user-cache', { ttl: 60000 })
-  async getUser(id: number) {
-    return { id, name: 'test' };
-  }
-
-  @CacheEvict('user-cache')
-  async updateUser(id: number) {
-    return { id, updated: true };
-  }
-}
-```
-
-### 自定义缓存 Key
-
-通过 `key` 选项自定义缓存 key 生成逻辑：
-
-```typescript
-class UserService {
-  // 使用字符串作为 key，所有调用共享同一缓存
-  @Cache('config', { key: 'global-config' })
-  async getConfig() {
-    return { ... };
-  }
-
-  // 使用函数基于参数生成 key
-  @Cache('user', { key: (...args) => String(args[0]) })
-  async getUser(id: number) {
-    return { id };
-  }
-
-  // 清除时使用相同的 key 函数
-  @CacheEvict('user', { key: (...args) => String(args[0]) })
-  async deleteUser(id: number) {
-    return { id, deleted: true };
-  }
-}
-```
-
-
-
-## API
-
-### @Cache(cacheName, options?)
-
-缓存装饰器。**必须用于 async 方法**。
-
-- `cacheName`: 缓存名称
-- `options.ttl`: 过期时间（秒）
-- `options.providerName`: 指定 CacheProvider
-- `options.key`: 自定义缓存 key，支持以下形式：
-  - `undefined/null`: 使用默认逻辑，基于方法参数生成 key
-  - `string`: 直接作为 key 值，格式为 `cacheName:keyValue`
-  - `function`: 接收方法参数数组，返回自定义字符串
-
-### @CacheEvict(cacheName, options?)
-
-缓存清除装饰器。**必须用于返回 Promise 的方法**。
-
-- `cacheName`: 缓存名称
-- `options.allEntries`: 清除该缓存名称下的所有条目（而非所有缓存），默认 false
-- `options.providerName`: 指定 CacheProvider
-- `options.key`: 自定义缓存 key，与 `@Cache` 行为一致。当 `allEntries: true` 时忽略
-
-### CacheProviderRegistry
-
-全局缓存提供者注册表。
-
-```typescript
-CacheProviderRegistry.register('memory', new MemoryCacheProvider());
-CacheProviderRegistry.setDefault('memory');
-CacheProviderRegistry.get('memory');
-```
-
-### MemoryCacheProvider
-
-内存 Map 实现，适用于单机应用。
-
-### RedisCacheProvider
-
-Redis 实现，适用于分布式场景。
-
-```typescript
-import Redis from 'ioredis';
-const redisProvider = new RedisCacheProvider(new Redis());
-```
+# @jintianxiayu/cache-decorator
+
+为 TypeScript 异步方法提供声明式缓存、缓存清除、请求合并，以及 Memory、Redis 和自定义缓存后端。
+
+## 目录
+
+- [安装](#安装)
+- [快速开始](#快速开始)
+- [缓存日志](#缓存日志)
+- [Redis](#redis)
+- [API](#api)
+
+## 安装
+
+Logger 是必需的 peer dependency；基础包不绑定任何 Redis SDK：
+
+```bash
+pnpm add @jintianxiayu/cache-decorator @jintianxiayu/logger reflect-metadata
+```
+
+需要 Redis 时，只安装应用实际使用的客户端：
+
+```bash
+pnpm add redis
+# 或
+pnpm add ioredis
+```
+
+## 快速开始
+
+```typescript
+import 'reflect-metadata';
+import { Cache, CacheEvict, CacheProviderRegistry, MemoryCacheProvider } from '@jintianxiayu/cache-decorator';
+import { LoggerFactory } from '@jintianxiayu/logger';
+
+LoggerFactory.init({
+    root: {
+        level: 'info',
+        console: { enabled: true },
+        file: { enabled: false },
+    },
+    loggers: {
+        '@jintianxiayu/cache-decorator': {
+            level: 'debug',
+            console: { enabled: true, format: 'json' },
+        },
+    },
+});
+
+CacheProviderRegistry.register('memory', new MemoryCacheProvider());
+CacheProviderRegistry.setDefault('memory');
+
+class UserService {
+    @Cache('user-cache', { ttl: 60 })
+    async getUser(id: number): Promise<{ id: number; name: string }> {
+        return { id, name: 'test' };
+    }
+
+    @CacheEvict('user-cache')
+    async updateUser(id: number): Promise<{ id: number; updated: boolean }> {
+        return { id, updated: true };
+    }
+}
+```
+
+`ttl` 的单位是秒；`undefined` 或 `0` 表示不设置过期时间。
+
+> `@Cache` 和 `@CacheEvict` 仅适用于返回 Promise 的方法。装饰同步方法会让调用方收到 Promise，而不是原返回值。
+
+### 自定义缓存 Key
+
+`key` 可以是固定字符串或根据方法参数计算的函数：
+
+```typescript
+class UserService {
+    @Cache('config', { key: 'global-config' })
+    async getConfig(): Promise<{ enabled: boolean }> {
+        return { enabled: true };
+    }
+
+    @Cache('user', { key: (...args: unknown[]) => String(args[0]) })
+    async getUser(id: number): Promise<{ id: number }> {
+        return { id };
+    }
+
+    @CacheEvict('user', { key: (...args: unknown[]) => String(args[0]) })
+    async deleteUser(id: number): Promise<{ id: number; deleted: boolean }> {
+        return { id, deleted: true };
+    }
+}
+```
+
+## 缓存日志
+
+缓存装饰器使用名称固定为 `@jintianxiayu/cache-decorator` 的 Logger。应用必须安装兼容版本的
+`@jintianxiayu/logger`，并在第一次调用被装饰方法前完成 `LoggerFactory.init()`；应用退出时仍由应用统一调用
+`LoggerFactory.shutdown()`。仅导入包、声明 decorator 或定义 class 不会提前获取 Logger，cache 包也不会自行初始化或关闭
+Logger。
+
+日志的 level、console/file transport、格式和脱敏只由同名 Logger profile 控制，不需要也不支持
+`CacheOptions.logging`、`debug` 或 Logger 回调。高频正常决策默认使用 `debug`，可恢复回退使用 `warn`，缓存基础设施失败使用
+`error`；逐调用事件不使用 `info`。
+
+| level   | event                    | 含义                                                   |
+| ------- | ------------------------ | ------------------------------------------------------ |
+| `debug` | `cache.pending_hit`      | 复用相同 key 的执行中 Promise                          |
+| `debug` | `cache.hit`              | 命中 value 或 error 缓存条目                           |
+| `debug` | `cache.miss`             | Provider 正常返回未命中                                |
+| `debug` | `cache.write_dispatched` | `set()` 已同步返回控制权，不表示异步写入成功           |
+| `debug` | `cache.evict_dispatched` | 单 key `delete()` 已同步返回控制权，不表示异步删除成功 |
+| `debug` | `cache.evict_completed`  | 已等待的 `deleteByPattern()` 正常完成                  |
+| `warn`  | `cache.key_fallback`     | 自定义 key resolver 失败，已回退默认 key               |
+| `warn`  | `cache.evict_skipped`    | 业务方法失败，淘汰被跳过                               |
+| `error` | `cache.operation_failed` | Provider 解析或可观察的读取、写入、淘汰操作失败        |
+
+`write_dispatched` 和 `evict_dispatched` 只描述调用已发起。为保持既有时序，decorator 不等待 `set()` 或单 key
+`delete()` 返回的 Promise，也不为日志附加 rejection handler；异步失败不会被描述为成功或完成。只有本来就会等待的全量淘汰可记录
+`evict_completed`。
+
+每条日志只包含 `event`、`cacheName`、`methodName`、`providerName`，并按事件增加 `entryType`、`scope`、
+`reason`、`operation` 或基础设施 `error`。日志不会包含方法参数、业务返回值、缓存值、业务异常内容或完整逻辑/物理 cache
+key，也不会为日志额外序列化这些值。Provider 错误和现有 `LoggerContext` 的 `traceId` 继续由 Logger 统一规范化、脱敏和关联；
+cache 包不直接读写 LoggerContext。Logger 自身同步失败会被隔离，不会替换缓存结果、业务结果或原始 Provider 错误。
+
+## Redis
+
+`RedisCacheProvider` 从 0.2.0 起必须接收已经适配的 `RedisCacheClient`。库不会创建、连接、重连或关闭 Redis
+连接，也不会修改连接选项与错误监听器；这些生命周期操作始终由应用负责。
+
+### node-redis
+
+```typescript
+import { createClient } from 'redis';
+import { CacheProviderRegistry, RedisCacheProvider, createNodeRedisCacheClient } from '@jintianxiayu/cache-decorator';
+
+const redis = createClient({ url: process.env.REDIS_URL });
+
+export async function startCache(): Promise<void> {
+    redis.on('error', (error: Error) => console.error('Redis error', error));
+    await redis.connect();
+    const client = createNodeRedisCacheClient(redis, { keyPrefix: 'my-app:' });
+    CacheProviderRegistry.register('redis', new RedisCacheProvider(client));
+    CacheProviderRegistry.setDefault('redis');
+}
+
+export async function stopCache(): Promise<void> {
+    if (redis.isOpen) {
+        await redis.quit();
+    }
+}
+```
+
+### ioredis
+
+```typescript
+import Redis from 'ioredis';
+import { CacheProviderRegistry, RedisCacheProvider, createIoredisCacheClient } from '@jintianxiayu/cache-decorator';
+
+const redis = new Redis(process.env.REDIS_URL ?? 'redis://127.0.0.1:6379', {
+    lazyConnect: true,
+    keyPrefix: 'my-app:',
+});
+
+export async function startCache(): Promise<void> {
+    redis.on('error', (error: Error) => console.error('Redis error', error));
+    await redis.connect();
+    CacheProviderRegistry.register('redis', new RedisCacheProvider(createIoredisCacheClient(redis)));
+    CacheProviderRegistry.setDefault('redis');
+}
+
+export function stopCache(): void {
+    redis.disconnect();
+}
+```
+
+### 自定义 RedisCacheClient
+
+其他 Redis SDK 或封装只需实现最小字符串命令接口，不必继承内置适配器：
+
+```typescript
+import { CacheProviderRegistry, RedisCacheProvider, type RedisCacheClient } from '@jintianxiayu/cache-decorator';
+
+interface StorageCommands {
+    read(key: string): Promise<string | null>;
+    write(key: string, value: string, ttlSeconds?: number): Promise<void>;
+    remove(keys: readonly string[]): Promise<void>;
+    scan(cursor: string, pattern: string, count: number): Promise<{ cursor: string; keys: readonly string[] }>;
+    clearDatabase(): Promise<void>;
+}
+
+declare const storage: StorageCommands;
+
+const client: RedisCacheClient = {
+    get: (key) => storage.read(key),
+    set: ({ key, value, ttlSeconds }) => storage.write(key, value, ttlSeconds),
+    deleteMany: (keys) => storage.remove(keys),
+    scan: ({ cursor, pattern, count }) => storage.scan(cursor, pattern, count),
+    flushDatabase: () => storage.clearDatabase(),
+};
+
+CacheProviderRegistry.register('redis', new RedisCacheProvider(client));
+```
+
+### 前缀与数据兼容
+
+- ioredis 继续使用连接的 `keyPrefix`；适配器会补齐 `SCAN` 不自动处理前缀的差异。
+- node-redis 没有透明 `keyPrefix`，应在 `createNodeRedisCacheClient(client, { keyPrefix })` 中传入等价的字面前缀。
+- 两种客户端连接同一 database、使用相同最终物理 key 时，可以互读既有缓存。字符串、JSON、miss 映射和秒级 TTL
+  格式均与 0.1.3 保持一致，无需重写或清空数据。
+- 原始字符串读取时仍会优先尝试 `JSON.parse`；例如缓存文本 `"true"` 会读为布尔值 `true`，这是既有兼容行为。
+
+`deleteByPattern()` 使用 `SCAN COUNT 100` 分页删除。它不是原子快照；并发写入时不承诺一次删除全部匹配项，命令中途失败后可幂等重试。
+
+> **危险：`RedisCacheProvider.clear()` 会执行 `FLUSHDB`，清空连接当前选择的整个 Redis database。**
+> `keyPrefix` 不会缩小其范围；共享 database 时不要调用它。
+
+### 异常与支持范围
+
+- Redis 命令拒绝会保留原始错误；不受支持的返回结构会抛出 `TypeError`。
+- TTL 必须是正有限整数秒，或使用 `0`/`undefined` 表示永不过期；其他值会在发送命令前抛出 `RangeError`。
+- 0.2.x 首版验证 ioredis 5 和 node-redis 5 的普通单实例连接及默认字符串/数字响应。
+- Cluster 跨分片扫描、Sentinel 专项切换、自定义 RESP Buffer 映射、自动故障切换和连接管理不在首版支持范围。
+
+### 从 0.1.3 迁移
+
+旧构造方式：
+
+```typescript
+const provider = new RedisCacheProvider(redis);
+```
+
+新构造方式：
+
+```typescript
+const provider = new RedisCacheProvider(createIoredisCacheClient(redis));
+```
+
+升级时保留原 database 和物理前缀，并由应用直接声明客户端依赖、先连接、最后自行关闭连接。需要回退时锁定
+`@jintianxiayu/cache-decorator@0.1.3` 并恢复旧构造方式；数据格式未改变，不需要清理 Redis。
+
+## API
+
+### @Cache(cacheName, options?)
+
+缓存装饰器，必须用于异步方法。
+
+- `cacheName`：缓存名称。
+- `options.ttl`：过期时间，单位为秒。
+- `options.providerName`：指定已注册的 `CacheProvider`。
+- `options.key`：`undefined`/`null` 使用默认参数 key；字符串使用固定 key；函数根据方法参数返回 key。
+
+### @CacheEvict(cacheName, options?)
+
+缓存清除装饰器，必须用于异步方法。
+
+- `options.allEntries`：为 `true` 时删除该缓存名称下的匹配项，而不是执行数据库级 `clear()`。
+- `options.providerName`：指定已注册的 `CacheProvider`。
+- `options.key`：行为与 `@Cache` 一致；`allEntries: true` 时忽略。
+
+### CacheProviderRegistry
+
+全局 Provider 注册表，使用 `register(name, provider)` 注册，并通过 `setDefault(name)` 选择默认 Provider。
+
+### MemoryCacheProvider
+
+基于进程内 Map 的实现，适用于单进程缓存。
+
+### RedisCacheProvider
+
+维护字符串/JSON、miss、TTL 和扫描删除协议；必须传入 `RedisCacheClient`，可使用内置适配工厂或自定义实现。

package/dist/adapters/ioredis-cache-client.d.ts

@@ -0,0 +1,9 @@
+import { IoredisCacheClientSource, RedisCacheClient } from '../core/redis-cache-client';
+/**
+ * 将调用方的 ioredis 连接适配为客户端无关的缓存命令，不创建或关闭连接。
+ * @param client 使用默认字符串响应映射的 ioredis 普通客户端。
+ * @returns 复用该连接并恢复逻辑 key 的 Redis 缓存客户端。
+ * @throws 返回对象的命令方法传播客户端错误；非标准响应拒绝为 TypeError。
+ */
+export declare function createIoredisCacheClient(client: IoredisCacheClientSource): RedisCacheClient;
+//# sourceMappingURL=ioredis-cache-client.d.ts.map

package/dist/adapters/ioredis-cache-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ioredis-cache-client.d.ts","sourceRoot":"","sources":["../../src/adapters/ioredis-cache-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAyCxF;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,wBAAwB,GAAG,gBAAgB,CAyC3F"}

package/dist/adapters/ioredis-cache-client.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createIoredisCacheClient = createIoredisCacheClient;
+const redis_key_prefix_1 = require("./redis-key-prefix");
+function normalizeGetResponse(response) {
+    if (typeof response === 'string' || response === null) {
+        return response;
+    }
+    throw new TypeError('Expected Redis GET to return a string or null');
+}
+function validateOkResponse(command, response) {
+    if (response !== 'OK') {
+        throw new TypeError(`Expected Redis ${command} to return "OK"`);
+    }
+}
+function validateDeleteResponse(response) {
+    if (typeof response !== 'number' || !Number.isInteger(response) || response < 0) {
+        throw new TypeError('Expected Redis DEL to return a non-negative integer');
+    }
+}
+function normalizeScanResponse(response, keyPrefix) {
+    if (!Array.isArray(response) ||
+        response.length !== 2 ||
+        typeof response[0] !== 'string' ||
+        !Array.isArray(response[1]) ||
+        !response[1].every((key) => typeof key === 'string')) {
+        throw new TypeError('Expected ioredis SCAN to return a [cursor, keys] tuple');
+    }
+    return {
+        cursor: response[0],
+        keys: response[1].map((key) => (0, redis_key_prefix_1.stripRedisKeyPrefix)(keyPrefix, key)),
+    };
+}
+/**
+ * 将调用方的 ioredis 连接适配为客户端无关的缓存命令，不创建或关闭连接。
+ * @param client 使用默认字符串响应映射的 ioredis 普通客户端。
+ * @returns 复用该连接并恢复逻辑 key 的 Redis 缓存客户端。
+ * @throws 返回对象的命令方法传播客户端错误；非标准响应拒绝为 TypeError。
+ */
+function createIoredisCacheClient(client) {
+    const keyPrefix = client.options.keyPrefix ?? '';
+    return {
+        /** @inheritdoc */
+        async get(key) {
+            return normalizeGetResponse(await client.get(key));
+        },
+        /** @inheritdoc */
+        async set({ key, value, ttlSeconds }) {
+            if (ttlSeconds === undefined) {
+                validateOkResponse('SET', await client.set(key, value));
+                return;
+            }
+            validateOkResponse('SETEX', await client.setex(key, ttlSeconds, value));
+        },
+        /** @inheritdoc */
+        async deleteMany(keys) {
+            if (keys.length === 0) {
+                return;
+            }
+            validateDeleteResponse(await client.del(...keys));
+        },
+        /** @inheritdoc */
+        async scan({ cursor, pattern, count }) {
+            const response = await client.scan(cursor, 'MATCH', (0, redis_key_prefix_1.createRedisScanPattern)(keyPrefix, pattern), 'COUNT', count);
+            return normalizeScanResponse(response, keyPrefix);
+        },
+        /** @inheritdoc */
+        async flushDatabase() {
+            validateOkResponse('FLUSHDB', await client.flushdb());
+        },
+    };
+}
+//# sourceMappingURL=ioredis-cache-client.js.map

package/dist/adapters/ioredis-cache-client.js.map

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

package/dist/adapters/node-redis-cache-client.d.ts

@@ -0,0 +1,10 @@
+import { NodeRedisCacheClientOptions, NodeRedisCacheClientSource, RedisCacheClient } from '../core/redis-cache-client';
+/**
+ * 将调用方的 node-redis 连接适配为客户端无关的缓存命令，不创建或关闭连接。
+ * @param client 使用默认字符串响应映射的 node-redis 普通客户端。
+ * @param options 可选的字面 key 前缀；缺省时不改写逻辑 key。
+ * @returns 复用该连接并统一物理 key 前缀的 Redis 缓存客户端。
+ * @throws 返回对象的命令方法传播客户端错误；非标准响应拒绝为 TypeError。
+ */
+export declare function createNodeRedisCacheClient(client: NodeRedisCacheClientSource, options?: NodeRedisCacheClientOptions): RedisCacheClient;
+//# sourceMappingURL=node-redis-cache-client.d.ts.map

package/dist/adapters/node-redis-cache-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-redis-cache-client.d.ts","sourceRoot":"","sources":["../../src/adapters/node-redis-cache-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,0BAA0B,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AA4CvH;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACtC,MAAM,EAAE,0BAA0B,EAClC,OAAO,CAAC,EAAE,2BAA2B,GACtC,gBAAgB,CAwClB"}

package/dist/adapters/node-redis-cache-client.js

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

package/dist/adapters/node-redis-cache-client.js.map

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

package/dist/adapters/redis-key-prefix.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 将普通字符串转换为 Redis glob pattern 中的字面量片段。
+ * @param value 仅作为字面前缀使用的字符串。
+ * @returns 对反斜杠、星号、问号和方括号增加反斜杠转义后的片段。
+ */
+export declare function escapeRedisGlobLiteral(value: string): string;
+/**
+ * 为逻辑 glob pattern 增加按字面量解释的 Redis key 前缀。
+ * @param keyPrefix 调用方配置的物理 key 前缀。
+ * @param pattern Provider 传入且需要保留 glob 语义的逻辑 pattern。
+ * @returns 可直接交给 Redis SCAN MATCH 的物理 pattern。
+ */
+export declare function createRedisScanPattern(keyPrefix: string, pattern: string): string;
+/**
+ * 验证扫描结果属于指定物理命名空间并恢复逻辑 key。
+ * @param keyPrefix 调用方配置的物理 key 前缀。
+ * @param physicalKey Redis SCAN 返回的物理 key。
+ * @returns 只剥离一次字面前缀后的逻辑 key。
+ * @throws 扫描结果不属于指定前缀时抛出 TypeError，避免扩大后续删除范围。
+ */
+export declare function stripRedisKeyPrefix(keyPrefix: string, physicalKey: string): string;
+//# sourceMappingURL=redis-key-prefix.d.ts.map

package/dist/adapters/redis-key-prefix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-key-prefix.d.ts","sourceRoot":"","sources":["../../src/adapters/redis-key-prefix.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM5D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAKlF"}