@jintianxiayu/cache-decorator 0.1.2 → 1.0.0

package/test/native-cache.test.ts

@@ -1,71 +1,77 @@
-import { MemoryCacheProvider } from '../src/core/native-cache';
-
-describe('MemoryCacheProvider', () => {
-  let provider: MemoryCacheProvider;
-
-  beforeEach(() => {
-    provider = new MemoryCacheProvider();
-  });
-
-  describe('get & set', () => {
-    it('应返回已缓存的值', () => {
-      provider.set('key1', 'value1');
-      expect(provider.get('key1')).toBe('value1');
-    });
-
-    it('应返回 undefined 对不存在的键', () => {
-      expect(provider.get('nonexistent')).toBeUndefined();
-    });
-  });
-
-  describe('TTL', () => {
-    it('应在 TTL 后失效', () => {
-      jest.useFakeTimers();
-
-      provider.set('key1', 'value1', 5);
-      expect(provider.get('key1')).toBe('value1');
-
-      jest.advanceTimersByTime(5001);
-      expect(provider.get('key1')).toBeUndefined();
-
-      jest.useRealTimers();
-    });
-
-    it('无 TTL 时不应失效', () => {
-      provider.set('key1', 'value1');
-      expect(provider.get('key1')).toBe('value1');
-    });
-  });
-
-  describe('delete', () => {
-    it('应删除指定键', () => {
-      provider.set('key1', 'value1');
-      provider.delete('key1');
-      expect(provider.get('key1')).toBeUndefined();
-    });
-  });
-
-  describe('clear', () => {
-    it('应清除所有缓存', () => {
-      provider.set('key1', 'value1');
-      provider.set('key2', 'value2');
-      provider.clear();
-      expect(provider.get('key1')).toBeUndefined();
-      expect(provider.get('key2')).toBeUndefined();
-    });
-  });
-
-  describe('deleteByPattern', () => {
-    it('应删除匹配模式的键', () => {
-      provider.set('user:1', 'user1');
-      provider.set('user:2', 'user2');
-      provider.set('order:1', 'order1');
-
-      provider.deleteByPattern('user:*');
-
-      expect(provider.get('user:1')).toBeUndefined();
-      expect(provider.get('user:2')).toBeUndefined();
-      expect(provider.get('order:1')).toBe('order1');
-    });
-  });
-});
+import { MemoryCacheProvider } from '../src/core/native-cache';
+
+describe('MemoryCacheProvider', () => {
+    let provider: MemoryCacheProvider;
+
+    beforeEach(() => {
+        provider = new MemoryCacheProvider();
+    });
+
+    afterEach(() => {
+        jest.useRealTimers();
+    });
+
+    describe('get & set', () => {
+        it('应返回已缓存的值', () => {
+            provider.set('key1', 'value1');
+            expect(provider.get('key1')).toBe('value1');
+        });
+
+        it('应返回 undefined 对不存在的键', () => {
+            expect(provider.get('nonexistent')).toBeUndefined();
+        });
+    });
+
+    describe('TTL', () => {
+        it('应在 TTL 后失效', () => {
+            jest.useFakeTimers();
+
+            provider.set('key1', 'value1', 5);
+            expect(provider.get('key1')).toBe('value1');
+
+            jest.advanceTimersByTime(5001);
+            expect(provider.get('key1')).toBeUndefined();
+        });
+
+        it('无 TTL 时不应失效', () => {
+            jest.useFakeTimers();
+
+            provider.set('key1', 'value1');
+            jest.advanceTimersByTime(24 * 60 * 60 * 1000);
+
+            expect(provider.get('key1')).toBe('value1');
+        });
+    });
+
+    describe('delete', () => {
+        it('应删除指定键', () => {
+            provider.set('key1', 'value1');
+            provider.delete('key1');
+            expect(provider.get('key1')).toBeUndefined();
+        });
+    });
+
+    describe('clear', () => {
+        it('应清除所有缓存', () => {
+            provider.set('key1', 'value1');
+            provider.set('key2', 'value2');
+            provider.clear();
+            expect(provider.get('key1')).toBeUndefined();
+            expect(provider.get('key2')).toBeUndefined();
+        });
+    });
+
+    describe('deleteByPattern', () => {
+        it('cache-evict-allentries-prefix/MemoryCacheProvider 实现前缀匹配', () => {
+            provider.set('user:1', 'user1');
+            provider.set('user:2', 'user2');
+            provider.set('order:1', 'order1');
+
+            provider.deleteByPattern('user:*');
+
+            expect(provider.get('user:1')).toBeUndefined();
+            expect(provider.get('user:2')).toBeUndefined();
+            expect(provider.get('order:1')).toBe('order1');
+        });
+    });
+});

package/test/node-redis-cache-client.test.ts

@@ -0,0 +1,149 @@
+import { createNodeRedisCacheClient } from '../src/adapters/node-redis-cache-client';
+import { NodeRedisCacheClientSource } from '../src/core/redis-cache-client';
+
+function createSource(): jest.Mocked<NodeRedisCacheClientSource> {
+    const source = {
+        get: jest.fn<Promise<unknown>, Parameters<NodeRedisCacheClientSource['get']>>(),
+        set: jest.fn<Promise<unknown>, Parameters<NodeRedisCacheClientSource['set']>>(),
+        setEx: jest.fn<Promise<unknown>, Parameters<NodeRedisCacheClientSource['setEx']>>(),
+        del: jest.fn<Promise<unknown>, Parameters<NodeRedisCacheClientSource['del']>>(),
+        scan: jest.fn<Promise<unknown>, Parameters<NodeRedisCacheClientSource['scan']>>(),
+        flushDb: jest.fn<Promise<unknown>, Parameters<NodeRedisCacheClientSource['flushDb']>>(),
+    } satisfies jest.Mocked<NodeRedisCacheClientSource>;
+    return source;
+}
+
+it('redis-cache-client/A03 node-redis 无 TTL 写入成功', async () => {
+    const source = createSource();
+    const client = createNodeRedisCacheClient(source, { keyPrefix: 'cache:' });
+    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('cache:order:1', request.value);
+    expect(source.setEx).not.toHaveBeenCalled();
+});
+
+it('redis-cache-client/A04 node-redis 带 TTL 写入成功', async () => {
+    const source = createSource();
+    const client = createNodeRedisCacheClient(source, { keyPrefix: 'cache:' });
+    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('cache:order:2', request.ttlSeconds, request.value);
+    expect(source.set).not.toHaveBeenCalled();
+});
+
+it('redis-cache-client/A05 GET 响应规范化', async () => {
+    const source = createSource();
+    const client = createNodeRedisCacheClient(source, { keyPrefix: 'cache:' });
+    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, 'cache:present');
+    expect(source.get).toHaveBeenNthCalledWith(2, 'cache:missing');
+});
+
+it('redis-cache-client/A06 删除和清库响应规范化', async () => {
+    const source = createSource();
+    const client = createNodeRedisCacheClient(source, { keyPrefix: 'cache:' });
+    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, ['cache:first', 'cache:second']);
+    expect(source.del).toHaveBeenNthCalledWith(2, ['cache:missing']);
+    expect(source.flushDb).toHaveBeenCalledTimes(1);
+});
+
+it('redis-cache-client/A07 调用上下文与请求保持不变', async () => {
+    const source = createSource();
+    const options = Object.freeze({ keyPrefix: 'scope:' });
+    const client = createNodeRedisCacheClient(source, options);
+    source.set.mockImplementation(function (this: NodeRedisCacheClientSource): Promise<unknown> {
+        expect(this).toBe(source);
+        return Promise.resolve('OK');
+    });
+    source.del.mockImplementation(function (this: NodeRedisCacheClientSource): Promise<unknown> {
+        expect(this).toBe(source);
+        return Promise.resolve(2);
+    });
+    source.scan.mockImplementation(function (this: NodeRedisCacheClientSource): Promise<unknown> {
+        expect(this).toBe(source);
+        return Promise.resolve({ cursor: '0', keys: ['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(options).toEqual({ keyPrefix: 'scope:' });
+    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 = createNodeRedisCacheClient(source);
+    source.get.mockResolvedValue(Buffer.from('value'));
+    source.set.mockResolvedValue(true);
+    source.setEx.mockResolvedValue(undefined);
+    source.del.mockResolvedValue(1.5);
+    source.scan.mockResolvedValue(['0', []]);
+    source.flushDb.mockResolvedValue(null);
+
+    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/F07 node-redis 缺省前缀不改写 key', async () => {
+    const source = createSource();
+    const client = createNodeRedisCacheClient(source);
+    source.scan.mockResolvedValue({ cursor: '0', keys: ['name:1'] });
+    source.del.mockResolvedValue(1);
+
+    const page = await client.scan({ cursor: '0', pattern: 'name*', count: 100 });
+    await client.deleteMany(page.keys);
+
+    expect(source.scan).toHaveBeenCalledWith('0', { MATCH: 'name*', COUNT: 100 });
+    expect(page).toEqual({ cursor: '0', keys: ['name:1'] });
+    expect(source.del).toHaveBeenCalledWith(['name:1']);
+});
+
+it('cache-evict-allentries-prefix/F08 node-redis 显式前缀访问同一命名空间', async () => {
+    const source = createSource();
+    const client = createNodeRedisCacheClient(source, { keyPrefix: 'cache:' });
+    source.get.mockResolvedValue('value');
+    source.set.mockResolvedValue('OK');
+    source.scan.mockResolvedValue({ cursor: '0', keys: ['cache:name:1'] });
+    source.del.mockResolvedValue(1);
+
+    await expect(client.get('name:1')).resolves.toBe('value');
+    await client.set({ key: 'name:1', value: 'updated' });
+    const page = await client.scan({ cursor: '0', pattern: 'name*', count: 100 });
+    await client.deleteMany(page.keys);
+
+    expect(source.get).toHaveBeenCalledWith('cache:name:1');
+    expect(source.set).toHaveBeenCalledWith('cache:name:1', 'updated');
+    expect(source.scan).toHaveBeenCalledWith('0', { MATCH: 'cache:name*', COUNT: 100 });
+    expect(page).toEqual({ cursor: '0', keys: ['name:1'] });
+    expect(source.del).toHaveBeenCalledWith(['cache:name:1']);
+});

package/test/pending-cache.test.ts

@@ -1,56 +1,69 @@
-import { PendingCache } from '../src/core/pending-cache';
-
-describe('PendingCache', () => {
-  let pendingCache: PendingCache;
-
-  beforeEach(() => {
-    pendingCache = new PendingCache();
-  });
-
-  describe('get & set', () => {
-    it('应返回已存储的 Promise', async () => {
-      const promise = Promise.resolve('value');
-      pendingCache.set('key1', promise);
-      expect(await pendingCache.get('key1')).toBe('value');
-    });
-
-    it('应返回 undefined 对不存在的键', () => {
-      expect(pendingCache.get('nonexistent')).toBeUndefined();
-    });
-  });
-
-  describe('请求合并', () => {
-    it('应在 Promise 完成时自动删除', async () => {
-      let resolve: (value: string) => void;
-      const promise = new Promise<string>(r => { resolve = r; });
-
-      pendingCache.set('key1', promise);
-      expect(pendingCache.get('key1')).toBeDefined();
-
-      resolve!('value');
-      await promise;
-      await new Promise(resolve => setTimeout(resolve, 0));
-
-      expect(pendingCache.get('key1')).toBeUndefined();
-    });
-  });
-
-  describe('delete', () => {
-    it('应删除指定键', async () => {
-      const promise = Promise.resolve('value');
-      pendingCache.set('key1', promise);
-      pendingCache.delete('key1');
-      expect(pendingCache.get('key1')).toBeUndefined();
-    });
-  });
-
-  describe('clear', () => {
-    it('应清除所有 pending 请求', async () => {
-      pendingCache.set('key1', Promise.resolve('v1'));
-      pendingCache.set('key2', Promise.resolve('v2'));
-      pendingCache.clear();
-      expect(pendingCache.get('key1')).toBeUndefined();
-      expect(pendingCache.get('key2')).toBeUndefined();
-    });
-  });
-});
+import { PendingCache } from '../src/core/pending-cache';
+
+describe('PendingCache', () => {
+    let pendingCache: PendingCache;
+
+    beforeEach(() => {
+        pendingCache = new PendingCache();
+    });
+
+    describe('get & set', () => {
+        it('应返回已存储的 Promise', async () => {
+            const promise = Promise.resolve('value');
+            pendingCache.set('key1', promise);
+            expect(await pendingCache.get('key1')).toBe('value');
+        });
+
+        it('应返回 undefined 对不存在的键', () => {
+            expect(pendingCache.get('nonexistent')).toBeUndefined();
+        });
+    });
+
+    describe('请求合并', () => {
+        it('应在 Promise 完成时自动删除', async () => {
+            let resolve: (value: string) => void;
+            const promise = new Promise<string>((r) => {
+                resolve = r;
+            });
+
+            pendingCache.set('key1', promise);
+            expect(pendingCache.get('key1')).toBeDefined();
+
+            resolve!('value');
+            await promise;
+            await new Promise((resolve) => setTimeout(resolve, 0));
+
+            expect(pendingCache.get('key1')).toBeUndefined();
+        });
+
+        it('应在 Promise 拒绝时自动删除且保留原始异常', async () => {
+            const expectedError = new Error('request failed');
+            const promise = Promise.reject(expectedError);
+
+            pendingCache.set('key1', promise);
+
+            await expect(promise).rejects.toBe(expectedError);
+            await Promise.resolve();
+            expect(pendingCache.get('key1')).toBeUndefined();
+        });
+    });
+
+    describe('delete', () => {
+        it('应删除指定键', async () => {
+            const promise = Promise.resolve('value');
+            pendingCache.set('key1', promise);
+            pendingCache.delete('key1');
+            expect(pendingCache.get('key1')).toBeUndefined();
+        });
+    });
+
+    describe('clear', () => {
+        it('应清除所有 pending 请求', async () => {
+            pendingCache.set('key1', Promise.resolve('v1'));
+            pendingCache.set('key2', Promise.resolve('v2'));
+            pendingCache.clear();
+            expect(pendingCache.get('key1')).toBeUndefined();
+            expect(pendingCache.get('key2')).toBeUndefined();
+        });
+    });
+});

package/test/redis-cache-client-lifecycle.test.ts

@@ -0,0 +1,112 @@
+import { EventEmitter } from 'node:events';
+import { createIoredisCacheClient } from '../src/adapters/ioredis-cache-client';
+import { createNodeRedisCacheClient } from '../src/adapters/node-redis-cache-client';
+import { CacheProviderRegistry } from '../src/core/cache-provider-registry';
+import { RedisCacheClient } from '../src/core/redis-cache-client';
+import { RedisCacheProvider } from '../src/core/redis-cache';
+
+/** 创建由测试持有的连接探针，记录库是否越过连接所有权边界。 */
+function createConnectionProbe() {
+    const connection = Object.assign(new EventEmitter(), {
+        options: Object.freeze({ connectionName: 'application', keyPrefix: 'tenant:' }),
+        get: jest.fn((_key: string): Promise<unknown> => Promise.resolve(null)),
+        set: jest.fn((_key: string, _value: string): Promise<unknown> => Promise.resolve('OK')),
+        setex: jest.fn((_key: string, _ttlSeconds: number, _value: string): Promise<unknown> => Promise.resolve('OK')),
+        setEx: jest.fn((_key: string, _ttlSeconds: number, _value: string): Promise<unknown> => Promise.resolve('OK')),
+        del: jest.fn((..._keys: Array<string | string[]>): Promise<unknown> => Promise.resolve(1)),
+        scan: jest.fn((...args: unknown[]): Promise<unknown> => {
+            return Promise.resolve(typeof args[1] === 'string' ? ['0', []] : { cursor: '0', keys: [] });
+        }),
+        flushdb: jest.fn((): Promise<unknown> => Promise.resolve('OK')),
+        flushDb: jest.fn((): Promise<unknown> => Promise.resolve('OK')),
+        connect: jest.fn(),
+        quit: jest.fn(),
+        disconnect: jest.fn(),
+        close: jest.fn(),
+        destroy: jest.fn(),
+    });
+    const errors: Error[] = [];
+    connection.on('error', (error: Error) => errors.push(error));
+    return connection;
+}
+
+/** 断言库未更改连接配置、监听器或建立/关闭连接。 */
+function expectCallerOwnership(connection: ReturnType<typeof createConnectionProbe>): void {
+    expect(connection.options).toEqual({ connectionName: 'application', keyPrefix: 'tenant:' });
+    expect(connection.eventNames()).toEqual(['error']);
+    expect(connection.listenerCount('error')).toBe(1);
+    for (const operation of [
+        connection.connect,
+        connection.quit,
+        connection.disconnect,
+        connection.close,
+        connection.destroy,
+    ]) {
+        expect(operation).not.toHaveBeenCalled();
+    }
+}
+
+interface AdapterCase {
+    readonly name: string;
+    adapt(connection: ReturnType<typeof createConnectionProbe>): RedisCacheClient;
+}
+
+const adapterCases: readonly AdapterCase[] = [
+    {
+        name: 'ioredis',
+        adapt: (connection) => createIoredisCacheClient(connection),
+    },
+    {
+        name: 'node-redis',
+        adapt: (connection) => createNodeRedisCacheClient(connection, { keyPrefix: connection.options.keyPrefix }),
+    },
+];
+
+afterEach(() => CacheProviderRegistry.clear());
+
+describe.each(adapterCases)('$name 连接所有权', ({ adapt }) => {
+    it('redis-cache-client/O01 构造与注册不操作连接', () => {
+        const connection = createConnectionProbe();
+        const options = connection.options;
+        const listeners = connection.listeners('error');
+        const provider = new RedisCacheProvider(adapt(connection));
+        CacheProviderRegistry.register('shared', provider);
+        CacheProviderRegistry.setDefault('shared');
+
+        expect(CacheProviderRegistry.get()).toBe(provider);
+        expect(connection.options).toBe(options);
+        expect(connection.listeners('error')).toEqual(listeners);
+        expectCallerOwnership(connection);
+        for (const command of [
+            connection.get,
+            connection.set,
+            connection.setex,
+            connection.setEx,
+            connection.del,
+            connection.scan,
+            connection.flushdb,
+            connection.flushDb,
+        ]) {
+            expect(command).not.toHaveBeenCalled();
+        }
+    });
+
+    it('redis-cache-client/O02 多个 Provider 共享连接', async () => {
+        const connection = createConnectionProbe();
+        const first = new RedisCacheProvider(adapt(connection));
+        const second = new RedisCacheProvider(adapt(connection));
+
+        await first.set('first', { value: 1 });
+        await second.get('first');
+        await first.delete('first');
+        await second.deleteByPattern('shared*');
+        await first.clear();
+
+        const error = new Error('connection failure');
+        connection.get.mockRejectedValueOnce(error);
+        await expect(second.get('failed')).rejects.toBe(error);
+        await expect(connection.get('application-key')).resolves.toBeNull();
+        await expect(connection.set('application-key', 'application-value')).resolves.toBe('OK');
+        expectCallerOwnership(connection);
+    });
+});