@jintianxiayu/cache-decorator 1.0.0 → 1.0.2

package/test/helpers/redis-fixture.ts

@@ -1,142 +1,142 @@
-import { randomUUID } from 'node:crypto';
-import Redis from 'ioredis';
-import { createClient } from 'redis';
-
-/** 由测试持有的两种真实 Redis 连接及其精确清理范围。 */
-export interface RedisFixture {
-    readonly io: Redis;
-    readonly node: ReturnType<typeof createClient>;
-    readonly database: number;
-    readonly errors: Error[];
-
-    /**
-     * 分配只属于本夹具的唯一物理 key。
-     * @returns 已登记且可由 close 精确清理的 key。
-     */
-    key(): string;
-
-    /**
-     * 登记由本夹具唯一 key 派生的物理 key，供 close 精确清理。
-     * @param key 必须位于 cache-decorator-test 测试命名空间内的物理 key。
-     * @returns 原 key，便于测试在构造数据时直接使用。
-     * @throws key 不属于测试命名空间时拒绝，避免误删外部数据。
-     */
-    track(key: string): string;
-
-    /**
-     * 清理本夹具登记的 key，并关闭本夹具创建的两个连接。
-     * @returns 清理与关闭完成后结束；重复调用保持幂等。
-     * @throws Redis 清理命令失败时传播原始错误，但仍回收连接。
-     */
-    close(): Promise<void>;
-}
-
-function selectedDatabase(url: string): number {
-    const pathname = new URL(url).pathname;
-    if (pathname === '' || pathname === '/') {
-        return 0;
-    }
-    const databaseText = pathname.slice(1);
-    const database = Number(databaseText);
-    if (!Number.isSafeInteger(database) || database < 0 || String(database) !== databaseText) {
-        throw new Error('CACHE_DECORATOR_TEST_REDIS_URL must select a valid Redis database number');
-    }
-    return database;
-}
-
-async function createFixture(url: string, database: number): Promise<RedisFixture> {
-    const errors: Error[] = [];
-    const keys = new Set<string>();
-    let closed = false;
-    const io = new Redis(url, {
-        lazyConnect: true,
-        enableOfflineQueue: false,
-        connectTimeout: 1000,
-        commandTimeout: 1000,
-        maxRetriesPerRequest: 0,
-        retryStrategy: (): null => null,
-    });
-    const node = createClient({
-        url,
-        disableOfflineQueue: true,
-        socket: { connectTimeout: 1000, reconnectStrategy: false },
-    });
-    io.on('error', (error: Error) => errors.push(error));
-    node.on('error', (error: Error) => errors.push(error));
-    try {
-        await Promise.all([io.connect(), node.connect()]);
-    } catch (error) {
-        io.disconnect();
-        if (node.isOpen) {
-            node.destroy();
-        }
-        throw error;
-    }
-    return {
-        io,
-        node,
-        database,
-        errors,
-        /** @inheritdoc */
-        key(): string {
-            const key = `cache-decorator-test:${randomUUID()}`;
-            keys.add(key);
-            return key;
-        },
-        /** @inheritdoc */
-        track(key: string): string {
-            if (!key.startsWith('cache-decorator-test:')) {
-                throw new Error('Redis fixture can only track cache-decorator-test keys');
-            }
-            keys.add(key);
-            return key;
-        },
-        /** @inheritdoc */
-        async close(): Promise<void> {
-            if (closed) {
-                return;
-            }
-            closed = true;
-            try {
-                if (keys.size > 0 && node.isReady) {
-                    await node.del([...keys]);
-                } else if (keys.size > 0 && io.status === 'ready') {
-                    await io.del(...keys);
-                }
-            } finally {
-                if (io.status !== 'end') {
-                    io.disconnect();
-                }
-                if (node.isOpen) {
-                    node.destroy();
-                }
-            }
-        },
-    };
-}
-
-/**
- * 从显式测试 URL 创建两个真实客户端，不回退到默认地址或业务连接。
- * @param url `CACHE_DECORATOR_TEST_REDIS_URL` 提供的专用 Redis 地址。
- * @returns 已完成连接且由测试负责 close 的双客户端夹具。
- * @throws URL、连接或后续清理失败时传播错误。
- */
-export async function createRedisFixture(url: string): Promise<RedisFixture> {
-    return createFixture(url, selectedDatabase(url));
-}
-
-/**
- * 为会执行 FLUSHDB 的场景创建显式非零数据库夹具。
- * @param url `CACHE_DECORATOR_TEST_REDIS_URL` 提供且路径包含非零数据库号的地址。
- * @returns 已连接到明确隔离数据库的双客户端夹具。
- * @throws URL 未显式选择非零数据库时拒绝，避免清理共享或默认数据库。
- */
-export async function createIsolatedDatabaseRedisFixture(url: string): Promise<RedisFixture> {
-    const database = selectedDatabase(url);
-    if (database === 0) {
-        throw new Error(
-            'Database-level cache tests require CACHE_DECORATOR_TEST_REDIS_URL to select a non-zero database'
-        );
-    }
-    return createFixture(url, database);
-}
+import { randomUUID } from 'node:crypto';
+import Redis from 'ioredis';
+import { createClient } from 'redis';
+
+/** 由测试持有的两种真实 Redis 连接及其精确清理范围。 */
+export interface RedisFixture {
+    readonly io: Redis;
+    readonly node: ReturnType<typeof createClient>;
+    readonly database: number;
+    readonly errors: Error[];
+
+    /**
+     * 分配只属于本夹具的唯一物理 key。
+     * @returns 已登记且可由 close 精确清理的 key。
+     */
+    key(): string;
+
+    /**
+     * 登记由本夹具唯一 key 派生的物理 key，供 close 精确清理。
+     * @param key 必须位于 cache-decorator-test 测试命名空间内的物理 key。
+     * @returns 原 key，便于测试在构造数据时直接使用。
+     * @throws key 不属于测试命名空间时拒绝，避免误删外部数据。
+     */
+    track(key: string): string;
+
+    /**
+     * 清理本夹具登记的 key，并关闭本夹具创建的两个连接。
+     * @returns 清理与关闭完成后结束；重复调用保持幂等。
+     * @throws Redis 清理命令失败时传播原始错误，但仍回收连接。
+     */
+    close(): Promise<void>;
+}
+
+function selectedDatabase(url: string): number {
+    const pathname = new URL(url).pathname;
+    if (pathname === '' || pathname === '/') {
+        return 0;
+    }
+    const databaseText = pathname.slice(1);
+    const database = Number(databaseText);
+    if (!Number.isSafeInteger(database) || database < 0 || String(database) !== databaseText) {
+        throw new Error('CACHE_DECORATOR_TEST_REDIS_URL must select a valid Redis database number');
+    }
+    return database;
+}
+
+async function createFixture(url: string, database: number): Promise<RedisFixture> {
+    const errors: Error[] = [];
+    const keys = new Set<string>();
+    let closed = false;
+    const io = new Redis(url, {
+        lazyConnect: true,
+        enableOfflineQueue: false,
+        connectTimeout: 1000,
+        commandTimeout: 1000,
+        maxRetriesPerRequest: 0,
+        retryStrategy: (): null => null,
+    });
+    const node = createClient({
+        url,
+        disableOfflineQueue: true,
+        socket: { connectTimeout: 1000, reconnectStrategy: false },
+    });
+    io.on('error', (error: Error) => errors.push(error));
+    node.on('error', (error: Error) => errors.push(error));
+    try {
+        await Promise.all([io.connect(), node.connect()]);
+    } catch (error) {
+        io.disconnect();
+        if (node.isOpen) {
+            node.destroy();
+        }
+        throw error;
+    }
+    return {
+        io,
+        node,
+        database,
+        errors,
+        /** @inheritdoc */
+        key(): string {
+            const key = `cache-decorator-test:${randomUUID()}`;
+            keys.add(key);
+            return key;
+        },
+        /** @inheritdoc */
+        track(key: string): string {
+            if (!key.startsWith('cache-decorator-test:')) {
+                throw new Error('Redis fixture can only track cache-decorator-test keys');
+            }
+            keys.add(key);
+            return key;
+        },
+        /** @inheritdoc */
+        async close(): Promise<void> {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            try {
+                if (keys.size > 0 && node.isReady) {
+                    await node.del([...keys]);
+                } else if (keys.size > 0 && io.status === 'ready') {
+                    await io.del(...keys);
+                }
+            } finally {
+                if (io.status !== 'end') {
+                    io.disconnect();
+                }
+                if (node.isOpen) {
+                    node.destroy();
+                }
+            }
+        },
+    };
+}
+
+/**
+ * 从显式测试 URL 创建两个真实客户端，不回退到默认地址或业务连接。
+ * @param url `CACHE_DECORATOR_TEST_REDIS_URL` 提供的专用 Redis 地址。
+ * @returns 已完成连接且由测试负责 close 的双客户端夹具。
+ * @throws URL、连接或后续清理失败时传播错误。
+ */
+export async function createRedisFixture(url: string): Promise<RedisFixture> {
+    return createFixture(url, selectedDatabase(url));
+}
+
+/**
+ * 为会执行 FLUSHDB 的场景创建显式非零数据库夹具。
+ * @param url `CACHE_DECORATOR_TEST_REDIS_URL` 提供且路径包含非零数据库号的地址。
+ * @returns 已连接到明确隔离数据库的双客户端夹具。
+ * @throws URL 未显式选择非零数据库时拒绝，避免清理共享或默认数据库。
+ */
+export async function createIsolatedDatabaseRedisFixture(url: string): Promise<RedisFixture> {
+    const database = selectedDatabase(url);
+    if (database === 0) {
+        throw new Error(
+            'Database-level cache tests require CACHE_DECORATOR_TEST_REDIS_URL to select a non-zero database'
+        );
+    }
+    return createFixture(url, database);
+}

package/test/ioredis-cache-client.test.ts

@@ -1,143 +1,143 @@
-import { createIoredisCacheClient } from '../src/adapters/ioredis-cache-client';
-import { IoredisCacheClientSource } from '../src/core/redis-cache-client';
-
-function createSource(keyPrefix?: string): jest.Mocked<IoredisCacheClientSource> {
-    const source = {
-        options: Object.freeze({ keyPrefix }),
-        get: jest.fn<Promise<unknown>, Parameters<IoredisCacheClientSource['get']>>(),
-        set: jest.fn<Promise<unknown>, Parameters<IoredisCacheClientSource['set']>>(),
-        setex: jest.fn<Promise<unknown>, Parameters<IoredisCacheClientSource['setex']>>(),
-        del: jest.fn<Promise<unknown>, Parameters<IoredisCacheClientSource['del']>>(),
-        scan: jest.fn<Promise<unknown>, Parameters<IoredisCacheClientSource['scan']>>(),
-        flushdb: jest.fn<Promise<unknown>, Parameters<IoredisCacheClientSource['flushdb']>>(),
-    } satisfies jest.Mocked<IoredisCacheClientSource>;
-    return source;
-}
-
-it('redis-cache-client/A01 ioredis 无 TTL 写入成功', async () => {
-    const source = createSource();
-    const client = createIoredisCacheClient(source);
-    const request = Object.freeze({ key: 'order:1', value: '{"status":"open"}' });
-    source.set.mockResolvedValue('OK');
-
-    await expect(client.set(request)).resolves.toBeUndefined();
-
-    expect(source.set).toHaveBeenCalledWith(request.key, request.value);
-    expect(source.setex).not.toHaveBeenCalled();
-});
-
-it('redis-cache-client/A02 ioredis 带 TTL 写入成功', async () => {
-    const source = createSource();
-    const client = createIoredisCacheClient(source);
-    const request = Object.freeze({ key: 'order:2', value: 'paid', ttlSeconds: 60 });
-    source.setex.mockResolvedValue('OK');
-
-    await expect(client.set(request)).resolves.toBeUndefined();
-
-    expect(source.setex).toHaveBeenCalledWith(request.key, request.ttlSeconds, request.value);
-    expect(source.set).not.toHaveBeenCalled();
-});
-
-it('redis-cache-client/A05 GET 响应规范化', async () => {
-    const source = createSource();
-    const client = createIoredisCacheClient(source);
-    source.get.mockResolvedValueOnce('cached').mockResolvedValueOnce(null);
-
-    await expect(client.get('present')).resolves.toBe('cached');
-    await expect(client.get('missing')).resolves.toBeNull();
-
-    expect(source.get).toHaveBeenNthCalledWith(1, 'present');
-    expect(source.get).toHaveBeenNthCalledWith(2, 'missing');
-});
-
-it('redis-cache-client/A06 删除和清库响应规范化', async () => {
-    const source = createSource();
-    const client = createIoredisCacheClient(source);
-    source.del.mockResolvedValueOnce(2).mockResolvedValueOnce(0);
-    source.flushdb.mockResolvedValue('OK');
-
-    await expect(client.deleteMany(['first', 'second'])).resolves.toBeUndefined();
-    await expect(client.deleteMany(['missing'])).resolves.toBeUndefined();
-    await expect(client.deleteMany([])).resolves.toBeUndefined();
-    await expect(client.flushDatabase()).resolves.toBeUndefined();
-
-    expect(source.del).toHaveBeenCalledTimes(2);
-    expect(source.del).toHaveBeenNthCalledWith(1, 'first', 'second');
-    expect(source.del).toHaveBeenNthCalledWith(2, 'missing');
-    expect(source.flushdb).toHaveBeenCalledTimes(1);
-});
-
-it('redis-cache-client/A07 调用上下文与请求保持不变', async () => {
-    const source = createSource('scope:');
-    const client = createIoredisCacheClient(source);
-    source.set.mockImplementation(function (this: IoredisCacheClientSource): Promise<unknown> {
-        expect(this).toBe(source);
-        return Promise.resolve('OK');
-    });
-    source.del.mockImplementation(function (this: IoredisCacheClientSource): Promise<unknown> {
-        expect(this).toBe(source);
-        return Promise.resolve(2);
-    });
-    source.scan.mockImplementation(function (this: IoredisCacheClientSource): Promise<unknown> {
-        expect(this).toBe(source);
-        return Promise.resolve(['0', ['scope:first', 'scope:second']]);
-    });
-    const writeRequest = Object.freeze({ key: 'first', value: 'value' });
-    const keys = Object.freeze(['first', 'second']);
-    const scanRequest = Object.freeze({ cursor: '0', pattern: 'first*', count: 100 });
-
-    await client.set(writeRequest);
-    await client.deleteMany(keys);
-    await client.scan(scanRequest);
-
-    expect(writeRequest).toEqual({ key: 'first', value: 'value' });
-    expect(keys).toEqual(['first', 'second']);
-    expect(scanRequest).toEqual({ cursor: '0', pattern: 'first*', count: 100 });
-});
-
-it('redis-cache-client/A08 非标准响应明确失败', async () => {
-    const source = createSource();
-    const client = createIoredisCacheClient(source);
-    source.get.mockResolvedValue(false);
-    source.set.mockResolvedValue(null);
-    source.setex.mockResolvedValue(Buffer.from('OK'));
-    source.del.mockResolvedValue(-1);
-    source.scan.mockResolvedValue({ cursor: '0', keys: [] });
-    source.flushdb.mockResolvedValue('PONG');
-
-    await expect(client.get('key')).rejects.toThrow(TypeError);
-    await expect(client.set({ key: 'key', value: 'value' })).rejects.toThrow(TypeError);
-    await expect(client.set({ key: 'key', value: 'value', ttlSeconds: 1 })).rejects.toThrow(TypeError);
-    await expect(client.deleteMany(['key'])).rejects.toThrow(TypeError);
-    await expect(client.scan({ cursor: '0', pattern: '*', count: 100 })).rejects.toThrow(TypeError);
-    await expect(client.flushDatabase()).rejects.toThrow(TypeError);
-});
-
-it('cache-evict-allentries-prefix/F05 ioredis keyPrefix 下删除逻辑 pattern', async () => {
-    const source = createSource('cache:');
-    const client = createIoredisCacheClient(source);
-    source.scan.mockResolvedValue(['0', ['cache:name:1', 'cache:name:2']]);
-    source.del.mockResolvedValue(2);
-
-    const page = await client.scan({ cursor: '0', pattern: 'name*', count: 100 });
-    await client.deleteMany(page.keys);
-
-    expect(source.scan).toHaveBeenCalledWith('0', 'MATCH', 'cache:name*', 'COUNT', 100);
-    expect(page).toEqual({ cursor: '0', keys: ['name:1', 'name:2'] });
-    expect(source.del).toHaveBeenCalledWith('name:1', 'name:2');
-});
-
-it('cache-evict-allentries-prefix/F06 ioredis 特殊字符 keyPrefix 被按字面量匹配', async () => {
-    const keyPrefix = 'scope\\*?[]:';
-    const source = createSource(keyPrefix);
-    const client = createIoredisCacheClient(source);
-    source.scan.mockResolvedValue(['0', [`${keyPrefix}name:1`]]);
-    const expectedPattern = ['scope', '\\\\', '\\*', '\\?', '\\[', '\\]', ':name*'].join('');
-
-    await expect(client.scan({ cursor: '0', pattern: 'name*', count: 100 })).resolves.toEqual({
-        cursor: '0',
-        keys: ['name:1'],
-    });
-
-    expect(source.scan).toHaveBeenCalledWith('0', 'MATCH', expectedPattern, 'COUNT', 100);
-});
+import { createIoredisCacheClient } from '../src/adapters/ioredis-cache-client';
+import { IoredisCacheClientSource } from '../src/core/redis-cache-client';
+
+function createSource(keyPrefix?: string): jest.Mocked<IoredisCacheClientSource> {
+    const source = {
+        options: Object.freeze({ keyPrefix }),
+        get: jest.fn<Promise<unknown>, Parameters<IoredisCacheClientSource['get']>>(),
+        set: jest.fn<Promise<unknown>, Parameters<IoredisCacheClientSource['set']>>(),
+        setex: jest.fn<Promise<unknown>, Parameters<IoredisCacheClientSource['setex']>>(),
+        del: jest.fn<Promise<unknown>, Parameters<IoredisCacheClientSource['del']>>(),
+        scan: jest.fn<Promise<unknown>, Parameters<IoredisCacheClientSource['scan']>>(),
+        flushdb: jest.fn<Promise<unknown>, Parameters<IoredisCacheClientSource['flushdb']>>(),
+    } satisfies jest.Mocked<IoredisCacheClientSource>;
+    return source;
+}
+
+it('redis-cache-client/A01 ioredis 无 TTL 写入成功', async () => {
+    const source = createSource();
+    const client = createIoredisCacheClient(source);
+    const request = Object.freeze({ key: 'order:1', value: '{"status":"open"}' });
+    source.set.mockResolvedValue('OK');
+
+    await expect(client.set(request)).resolves.toBeUndefined();
+
+    expect(source.set).toHaveBeenCalledWith(request.key, request.value);
+    expect(source.setex).not.toHaveBeenCalled();
+});
+
+it('redis-cache-client/A02 ioredis 带 TTL 写入成功', async () => {
+    const source = createSource();
+    const client = createIoredisCacheClient(source);
+    const request = Object.freeze({ key: 'order:2', value: 'paid', ttlSeconds: 60 });
+    source.setex.mockResolvedValue('OK');
+
+    await expect(client.set(request)).resolves.toBeUndefined();
+
+    expect(source.setex).toHaveBeenCalledWith(request.key, request.ttlSeconds, request.value);
+    expect(source.set).not.toHaveBeenCalled();
+});
+
+it('redis-cache-client/A05 GET 响应规范化', async () => {
+    const source = createSource();
+    const client = createIoredisCacheClient(source);
+    source.get.mockResolvedValueOnce('cached').mockResolvedValueOnce(null);
+
+    await expect(client.get('present')).resolves.toBe('cached');
+    await expect(client.get('missing')).resolves.toBeNull();
+
+    expect(source.get).toHaveBeenNthCalledWith(1, 'present');
+    expect(source.get).toHaveBeenNthCalledWith(2, 'missing');
+});
+
+it('redis-cache-client/A06 删除和清库响应规范化', async () => {
+    const source = createSource();
+    const client = createIoredisCacheClient(source);
+    source.del.mockResolvedValueOnce(2).mockResolvedValueOnce(0);
+    source.flushdb.mockResolvedValue('OK');
+
+    await expect(client.deleteMany(['first', 'second'])).resolves.toBeUndefined();
+    await expect(client.deleteMany(['missing'])).resolves.toBeUndefined();
+    await expect(client.deleteMany([])).resolves.toBeUndefined();
+    await expect(client.flushDatabase()).resolves.toBeUndefined();
+
+    expect(source.del).toHaveBeenCalledTimes(2);
+    expect(source.del).toHaveBeenNthCalledWith(1, 'first', 'second');
+    expect(source.del).toHaveBeenNthCalledWith(2, 'missing');
+    expect(source.flushdb).toHaveBeenCalledTimes(1);
+});
+
+it('redis-cache-client/A07 调用上下文与请求保持不变', async () => {
+    const source = createSource('scope:');
+    const client = createIoredisCacheClient(source);
+    source.set.mockImplementation(function (this: IoredisCacheClientSource): Promise<unknown> {
+        expect(this).toBe(source);
+        return Promise.resolve('OK');
+    });
+    source.del.mockImplementation(function (this: IoredisCacheClientSource): Promise<unknown> {
+        expect(this).toBe(source);
+        return Promise.resolve(2);
+    });
+    source.scan.mockImplementation(function (this: IoredisCacheClientSource): Promise<unknown> {
+        expect(this).toBe(source);
+        return Promise.resolve(['0', ['scope:first', 'scope:second']]);
+    });
+    const writeRequest = Object.freeze({ key: 'first', value: 'value' });
+    const keys = Object.freeze(['first', 'second']);
+    const scanRequest = Object.freeze({ cursor: '0', pattern: 'first*', count: 100 });
+
+    await client.set(writeRequest);
+    await client.deleteMany(keys);
+    await client.scan(scanRequest);
+
+    expect(writeRequest).toEqual({ key: 'first', value: 'value' });
+    expect(keys).toEqual(['first', 'second']);
+    expect(scanRequest).toEqual({ cursor: '0', pattern: 'first*', count: 100 });
+});
+
+it('redis-cache-client/A08 非标准响应明确失败', async () => {
+    const source = createSource();
+    const client = createIoredisCacheClient(source);
+    source.get.mockResolvedValue(false);
+    source.set.mockResolvedValue(null);
+    source.setex.mockResolvedValue(Buffer.from('OK'));
+    source.del.mockResolvedValue(-1);
+    source.scan.mockResolvedValue({ cursor: '0', keys: [] });
+    source.flushdb.mockResolvedValue('PONG');
+
+    await expect(client.get('key')).rejects.toThrow(TypeError);
+    await expect(client.set({ key: 'key', value: 'value' })).rejects.toThrow(TypeError);
+    await expect(client.set({ key: 'key', value: 'value', ttlSeconds: 1 })).rejects.toThrow(TypeError);
+    await expect(client.deleteMany(['key'])).rejects.toThrow(TypeError);
+    await expect(client.scan({ cursor: '0', pattern: '*', count: 100 })).rejects.toThrow(TypeError);
+    await expect(client.flushDatabase()).rejects.toThrow(TypeError);
+});
+
+it('cache-evict-allentries-prefix/F05 ioredis keyPrefix 下删除逻辑 pattern', async () => {
+    const source = createSource('cache:');
+    const client = createIoredisCacheClient(source);
+    source.scan.mockResolvedValue(['0', ['cache:name:1', 'cache:name:2']]);
+    source.del.mockResolvedValue(2);
+
+    const page = await client.scan({ cursor: '0', pattern: 'name*', count: 100 });
+    await client.deleteMany(page.keys);
+
+    expect(source.scan).toHaveBeenCalledWith('0', 'MATCH', 'cache:name*', 'COUNT', 100);
+    expect(page).toEqual({ cursor: '0', keys: ['name:1', 'name:2'] });
+    expect(source.del).toHaveBeenCalledWith('name:1', 'name:2');
+});
+
+it('cache-evict-allentries-prefix/F06 ioredis 特殊字符 keyPrefix 被按字面量匹配', async () => {
+    const keyPrefix = 'scope\\*?[]:';
+    const source = createSource(keyPrefix);
+    const client = createIoredisCacheClient(source);
+    source.scan.mockResolvedValue(['0', [`${keyPrefix}name:1`]]);
+    const expectedPattern = ['scope', '\\\\', '\\*', '\\?', '\\[', '\\]', ':name*'].join('');
+
+    await expect(client.scan({ cursor: '0', pattern: 'name*', count: 100 })).resolves.toEqual({
+        cursor: '0',
+        keys: ['name:1'],
+    });
+
+    expect(source.scan).toHaveBeenCalledWith('0', 'MATCH', expectedPattern, 'COUNT', 100);
+});

package/test/legacy-redis-cache.test.ts

@@ -0,0 +1,51 @@
+import type Redis from 'ioredis';
+import { readLegacyRedisCache, writeLegacyRedisCache } from './helpers/legacy-redis-cache';
+
+interface LegacyRedisHarness {
+    readonly client: Redis;
+    readonly get: jest.Mock<Promise<string | null>, [string]>;
+    readonly set: jest.Mock<Promise<unknown>, [string, string]>;
+    readonly setex: jest.Mock<Promise<unknown>, [string, number, string]>;
+}
+
+/** 创建只实现 legacy helper 所需命令的 Redis 测试替身。 */
+function createLegacyRedisHarness(): LegacyRedisHarness {
+    const get = jest.fn<Promise<string | null>, [string]>();
+    const set = jest.fn<Promise<unknown>, [string, string]>().mockResolvedValue('OK');
+    const setex = jest.fn<Promise<unknown>, [string, number, string]>().mockResolvedValue('OK');
+    return { client: { get, set, setex } as unknown as Redis, get, set, setex };
+}
+
+it('旧读取方可 JSON 解析新 envelope，但按旧异常分支抛出未解码对象', async () => {
+    const harness = createLegacyRedisHarness();
+    const envelope = {
+        kind: '@jintianxiayu/cache-decorator/error',
+        version: 1,
+        payload: { type: 'error', name: 'Error', message: 'not found' },
+    };
+    harness.get.mockResolvedValue(JSON.stringify({ error: envelope }));
+
+    const legacyEntry = await readLegacyRedisCache(harness.client, 'users:1');
+    let legacyThrown: unknown;
+    try {
+        if (typeof legacyEntry === 'object' && legacyEntry !== null && 'error' in legacyEntry) {
+            throw legacyEntry.error;
+        }
+    } catch (error) {
+        legacyThrown = error;
+    }
+
+    expect(harness.get).toHaveBeenCalledWith('users:1');
+    expect(legacyThrown).toEqual(envelope);
+    expect(legacyThrown).not.toBeInstanceOf(Error);
+});
+
+it('旧写入 helper 保持原 key、JSON 内容与秒级 TTL 请求', async () => {
+    const harness = createLegacyRedisHarness();
+
+    await writeLegacyRedisCache(harness.client, 'users:1', { value: { id: 1 } }, 30);
+    await writeLegacyRedisCache(harness.client, 'users:2', { value: { id: 2 } });
+
+    expect(harness.setex).toHaveBeenCalledWith('users:1', 30, '{"value":{"id":1}}');
+    expect(harness.set).toHaveBeenCalledWith('users:2', '{"value":{"id":2}}');
+});