@jintianxiayu/cache-decorator 0.1.3 → 1.0.0

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,58 +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);
+    });
+});

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

@@ -0,0 +1,184 @@
+import { resolve } from 'node:path';
+import {
+    createCompilerHost,
+    createProgram,
+    createSourceFile,
+    getPreEmitDiagnostics,
+    ModuleKind,
+    ModuleResolutionKind,
+    ScriptTarget,
+} from 'typescript';
+
+/**
+ * 在包内虚拟文件位置严格检查消费方源码，不构造客户端或建立连接。
+ * @param source 消费方 TypeScript 源码。
+ * @returns 编译器产生的全部预发射诊断；空数组表示类型检查通过。
+ * @throws 编译器或文件系统读取失败时传播原始错误。
+ */
+function checkTypes(source: string): readonly unknown[] {
+    const file = resolve(__dirname, 'type-consumer.ts');
+    const options = {
+        strict: true,
+        noEmit: true,
+        skipLibCheck: false,
+        target: ScriptTarget.ES2021,
+        module: ModuleKind.NodeNext,
+        moduleResolution: ModuleResolutionKind.NodeNext,
+        types: ['node'],
+        experimentalDecorators: true,
+        emitDecoratorMetadata: true,
+    };
+    const host = createCompilerHost(options);
+    const originalGetSourceFile = host.getSourceFile.bind(host);
+    host.getSourceFile = (name, languageVersion, onError, shouldCreateNewSourceFile) => {
+        if (resolve(name) === file) {
+            return createSourceFile(name, source, languageVersion, true);
+        }
+        return originalGetSourceFile(name, languageVersion, onError, shouldCreateNewSourceFile);
+    };
+    return getPreEmitDiagnostics(createProgram([file], options, host)).map((diagnostic) => diagnostic.messageText);
+}
+
+it('redis-cache-client/C01 自定义客户端接入统一 Provider', () => {
+    expect(
+        checkTypes(`
+        import { RedisCacheClient, RedisCacheProvider } from '../src';
+
+        const client: RedisCacheClient = {
+            get(_key: string): Promise<string | null> {
+                return Promise.resolve(null);
+            },
+            set(_request): Promise<void> {
+                return Promise.resolve();
+            },
+            deleteMany(_keys): Promise<void> {
+                return Promise.resolve();
+            },
+            scan(_request): Promise<{ readonly cursor: string; readonly keys: readonly string[] }> {
+                return Promise.resolve({ cursor: '0', keys: [] });
+            },
+            flushDatabase(): Promise<void> {
+                return Promise.resolve();
+            },
+        };
+
+        export const provider = new RedisCacheProvider(client);
+    `)
+    ).toEqual([]);
+});
+
+it('redis-cache-client/C02 ioredis 实例通过真实类型检查', () => {
+    expect(
+        checkTypes(`
+        import type Redis from 'ioredis';
+        import {
+            createIoredisCacheClient,
+            IoredisCacheClientSource,
+            RedisCacheProvider,
+        } from '../src';
+
+        declare const client: Redis;
+        export const accepted: IoredisCacheClientSource = client;
+        export const provider = new RedisCacheProvider(createIoredisCacheClient(client));
+    `)
+    ).toEqual([]);
+});
+
+it('redis-cache-client/C03 node-redis 实例通过真实类型检查', () => {
+    expect(
+        checkTypes(`
+        import { createClient } from 'redis';
+        import {
+            createNodeRedisCacheClient,
+            NodeRedisCacheClientSource,
+            RedisCacheProvider,
+        } from '../src';
+
+        declare const client: ReturnType<typeof createClient>;
+        export const accepted: NodeRedisCacheClientSource = client;
+        export const provider = new RedisCacheProvider(createNodeRedisCacheClient(client));
+    `)
+    ).toEqual([]);
+});
+
+const invalidCalls = [
+    'new RedisCacheProvider();',
+    'new RedisCacheProvider(ioredis);',
+    'new RedisCacheProvider(nodeRedis);',
+    'new RedisCacheProvider(null);',
+    'new RedisCacheProvider(undefined);',
+    "cacheClient.set({ value: 'value' });",
+    "cacheClient.set({ key: 'key' });",
+    "cacheClient.scan({ pattern: '*', count: 100 });",
+    "cacheClient.scan({ cursor: '0', count: 100 });",
+    "cacheClient.scan({ cursor: '0', pattern: '*' });",
+    'cacheClient.set(null);',
+    'cacheClient.scan(undefined);',
+    'createIoredisCacheClient();',
+    'createIoredisCacheClient(null);',
+    'createIoredisCacheClient(undefined);',
+    'createNodeRedisCacheClient();',
+    'createNodeRedisCacheClient(null);',
+    'createNodeRedisCacheClient(undefined);',
+    'createIoredisCacheClient(nodeRedis);',
+    'createNodeRedisCacheClient(ioredis);',
+];
+
+it('redis-cache-client/C04 不完整或错误配对的类型被拒绝', () => {
+    const negativeFixture = invalidCalls.map((call) => `// @ts-expect-error 必须拒绝此无效调用\n${call}`).join('\n');
+    expect(
+        checkTypes(`
+        import type Redis from 'ioredis';
+        import { createClient } from 'redis';
+        import {
+            createIoredisCacheClient,
+            createNodeRedisCacheClient,
+            RedisCacheClient,
+            RedisCacheProvider,
+        } from '../src';
+
+        declare const cacheClient: RedisCacheClient;
+        declare const ioredis: Redis;
+        declare const nodeRedis: ReturnType<typeof createClient>;
+        ${negativeFixture}
+    `)
+    ).toEqual([]);
+});
+
+it('cache-operation-logging/A01 既有 decorator 与 Provider 公共类型不需要日志选项', () => {
+    expect(
+        checkTypes(`
+        import {
+            Cache,
+            CacheEvict,
+            type CacheEvictOptions,
+            type CacheOptions,
+            type CacheProvider,
+        } from '../src';
+
+        const provider: CacheProvider = {
+            get: <Value>(_key: string): Value | undefined => undefined,
+            set: <Value>(_key: string, _value: Value, _ttl?: number): void => undefined,
+            delete: (_key: string): void => undefined,
+            clear: (): void => undefined,
+            deleteByPattern: (_pattern: string): void => undefined,
+        };
+        const cache = Cache('contract-cache', { ttl: 60, providerName: 'memory', key: null });
+        const evict = CacheEvict('contract-cache', { providerName: 'memory', allEntries: true });
+        const invalidCacheOptions: CacheOptions = {
+            // @ts-expect-error CacheOptions 不接受第二套日志配置。
+            logging: true,
+        };
+        const invalidEvictOptions: CacheEvictOptions = {
+            // @ts-expect-error CacheEvictOptions 不接受 Logger 实例。
+            logger: undefined,
+        };
+
+        void provider;
+        void cache;
+        void evict;
+        void invalidCacheOptions;
+        void invalidEvictOptions;
+    `)
+    ).toEqual([]);
+});