@jintianxiayu/cache-decorator 0.1.3 → 1.0.0

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

@@ -0,0 +1,327 @@
+import { once } from 'node:events';
+import Redis from 'ioredis';
+import { createIoredisCacheClient } from '../src/adapters/ioredis-cache-client';
+import { createNodeRedisCacheClient } from '../src/adapters/node-redis-cache-client';
+import { RedisCacheProvider } from '../src/core/redis-cache';
+import { writeLegacyRedisCache } from './helpers/legacy-redis-cache';
+import { RedisFixture, createIsolatedDatabaseRedisFixture, createRedisFixture } from './helpers/redis-fixture';
+
+const redisUrl = process.env.CACHE_DECORATOR_TEST_REDIS_URL;
+const redisTests = redisUrl ? describe : describe.skip;
+
+interface TestKeyNamespace {
+    readonly keyPrefix: string;
+    physicalKey(logicalKey: string): string;
+}
+
+function createKeyNamespace(fixture: RedisFixture): TestKeyNamespace {
+    const keyPrefix = `${fixture.key()}:`;
+    return {
+        keyPrefix,
+        physicalKey(logicalKey: string): string {
+            return fixture.track(`${keyPrefix}${logicalKey}`);
+        },
+    };
+}
+
+redisTests('真实 Redis 夹具（需 CACHE_DECORATOR_TEST_REDIS_URL）', () => {
+    let fixture: RedisFixture | undefined;
+
+    beforeEach(async () => {
+        if (!redisUrl) {
+            throw new Error('CACHE_DECORATOR_TEST_REDIS_URL is required');
+        }
+        fixture = await createRedisFixture(redisUrl);
+    });
+
+    afterEach(async () => fixture?.close());
+
+    it('双客户端连接及夹具清理只影响自有唯一 key', async () => {
+        if (!redisUrl || !fixture) {
+            throw new Error('CACHE_DECORATOR_TEST_REDIS_URL is required');
+        }
+        const observer = await createRedisFixture(redisUrl);
+        const ownKey = fixture.key();
+        const otherKey = observer.key();
+        try {
+            await expect(fixture.io.ping()).resolves.toBe('PONG');
+            await expect(fixture.node.ping()).resolves.toBe('PONG');
+            await fixture.io.set(ownKey, 'owned');
+            await observer.node.set(otherKey, 'untouched');
+            await fixture.close();
+            await expect(observer.node.get(ownKey)).resolves.toBeNull();
+            await expect(observer.node.get(otherKey)).resolves.toBe('untouched');
+            expect(fixture.errors).toEqual([]);
+        } finally {
+            await observer.close();
+        }
+    });
+});
+
+redisTests('Redis 客户端数据与互操作协议', () => {
+    let fixture: RedisFixture | undefined;
+    let ioProvider: RedisCacheProvider;
+    let nodeProvider: RedisCacheProvider;
+
+    beforeEach(async () => {
+        if (!redisUrl) {
+            throw new Error('CACHE_DECORATOR_TEST_REDIS_URL is required');
+        }
+        fixture = await createRedisFixture(redisUrl);
+        ioProvider = new RedisCacheProvider(createIoredisCacheClient(fixture.io));
+        nodeProvider = new RedisCacheProvider(createNodeRedisCacheClient(fixture.node));
+    });
+
+    afterEach(async () => fixture?.close());
+
+    it('redis-cache-client/V02 JSON 值跨客户端读取', async () => {
+        if (!fixture) {
+            throw new Error('Redis fixture is required');
+        }
+        const values: readonly unknown[] = [{ status: 'open' }, [1, 'two'], true, 42, null];
+        for (const value of values) {
+            const ioKey = fixture.key();
+            const nodeKey = fixture.key();
+            await ioProvider.set(ioKey, value);
+            await expect(nodeProvider.get(ioKey)).resolves.toEqual(value);
+            await nodeProvider.set(nodeKey, value);
+            await expect(ioProvider.get(nodeKey)).resolves.toEqual(value);
+        }
+    });
+
+    it('redis-cache-client/V05 正整数 TTL 按秒传递', async () => {
+        if (!fixture) {
+            throw new Error('Redis fixture is required');
+        }
+        const ioKey = fixture.key();
+        const nodeKey = fixture.key();
+        await ioProvider.set(ioKey, 'io', 30);
+        await nodeProvider.set(nodeKey, 'node', 30);
+
+        const [ioTtl, nodeTtl] = await Promise.all([fixture.node.ttl(ioKey), fixture.io.ttl(nodeKey)]);
+        expect(ioTtl).toBeGreaterThan(20);
+        expect(ioTtl).toBeLessThanOrEqual(30);
+        expect(nodeTtl).toBeGreaterThan(20);
+        expect(nodeTtl).toBeLessThanOrEqual(30);
+    });
+
+    it('redis-cache-client/V06 缺省 TTL 与零 TTL 永不过期', async () => {
+        if (!fixture) {
+            throw new Error('Redis fixture is required');
+        }
+        const ioKey = fixture.key();
+        const nodeKey = fixture.key();
+        await ioProvider.set(ioKey, 'io');
+        await nodeProvider.set(nodeKey, 'node', 0);
+
+        await expect(fixture.node.ttl(ioKey)).resolves.toBe(-1);
+        await expect(fixture.io.ttl(nodeKey)).resolves.toBe(-1);
+    });
+
+    it('redis-cache-client/R03 并发写入不提供额外竞争控制', async () => {
+        if (!fixture) {
+            throw new Error('Redis fixture is required');
+        }
+        const key = fixture.key();
+        const ioSet = jest.spyOn(fixture.io, 'set');
+        const nodeSet = jest.spyOn(fixture.node, 'set');
+
+        await Promise.all([
+            ioProvider.set(key, { writer: 'ioredis' }),
+            nodeProvider.set(key, { writer: 'node-redis' }),
+        ]);
+
+        expect([{ writer: 'ioredis' }, { writer: 'node-redis' }]).toContainEqual(await ioProvider.get(key));
+        expect(ioSet).toHaveBeenCalledTimes(1);
+        expect(nodeSet).toHaveBeenCalledTimes(1);
+        ioSet.mockRestore();
+        nodeSet.mockRestore();
+    });
+
+    it('redis-cache-client/E05 真实连接不可用时不创建替代连接', async () => {
+        if (!redisUrl) {
+            throw new Error('CACHE_DECORATOR_TEST_REDIS_URL is required');
+        }
+        for (const kind of ['ioredis', 'node-redis'] as const) {
+            const unavailable = await createRedisFixture(redisUrl);
+            const provider = new RedisCacheProvider(
+                kind === 'ioredis'
+                    ? createIoredisCacheClient(unavailable.io)
+                    : createNodeRedisCacheClient(unavailable.node)
+            );
+            const ioConnect = jest.spyOn(unavailable.io, 'connect');
+            const nodeConnect = jest.spyOn(unavailable.node, 'connect');
+            try {
+                if (kind === 'ioredis') {
+                    const ended = once(unavailable.io, 'end');
+                    unavailable.io.disconnect();
+                    await ended;
+                } else {
+                    unavailable.node.destroy();
+                }
+                const started = Date.now();
+                await expect(provider.get(unavailable.key())).rejects.toBeInstanceOf(Error);
+                expect(Date.now() - started).toBeLessThan(1500);
+                expect(ioConnect).not.toHaveBeenCalled();
+                expect(nodeConnect).not.toHaveBeenCalled();
+            } finally {
+                ioConnect.mockRestore();
+                nodeConnect.mockRestore();
+                await unavailable.close();
+            }
+        }
+    });
+
+    it('redis-cache-client/I01 ioredis 写入后由 node-redis 读取', async () => {
+        if (!fixture) {
+            throw new Error('Redis fixture is required');
+        }
+        const key = fixture.key();
+        await ioProvider.set(key, { source: 'ioredis' }, 30);
+
+        await expect(nodeProvider.get(key)).resolves.toEqual({ source: 'ioredis' });
+        expect(await fixture.node.ttl(key)).toBeGreaterThan(20);
+    });
+
+    it('redis-cache-client/I02 node-redis 写入后由 ioredis 读取', async () => {
+        if (!fixture) {
+            throw new Error('Redis fixture is required');
+        }
+        const key = fixture.key();
+        await nodeProvider.set(key, { source: 'node-redis' }, 30);
+
+        await expect(ioProvider.get(key)).resolves.toEqual({ source: 'node-redis' });
+        expect(await fixture.io.ttl(key)).toBeGreaterThan(20);
+    });
+
+    it('cache-operation-logging/A03 redis-cache-client/I03 新版本读取旧版本缓存', async () => {
+        if (!fixture) {
+            throw new Error('Redis fixture is required');
+        }
+        const stringKey = fixture.key();
+        const objectKey = fixture.key();
+        await writeLegacyRedisCache(fixture.io, stringKey, 'legacy-string');
+        await writeLegacyRedisCache(fixture.io, objectKey, { legacy: true }, 30);
+
+        await expect(nodeProvider.get(stringKey)).resolves.toBe('legacy-string');
+        await expect(ioProvider.get(objectKey)).resolves.toEqual({ legacy: true });
+    });
+
+    it('cache-evict-allentries-prefix/RedisCacheProvider 使用 SCAN 迭代删除', async () => {
+        if (!fixture) {
+            throw new Error('Redis fixture is required');
+        }
+        const namespace = createKeyNamespace(fixture);
+        const provider = new RedisCacheProvider(
+            createNodeRedisCacheClient(fixture.node, { keyPrefix: namespace.keyPrefix })
+        );
+        const matchingKeys = Array.from({ length: 150 }, (_, index) => `name:${index}`);
+        const physicalMatchingKeys = matchingKeys.map((key) => namespace.physicalKey(key));
+        const otherKey = namespace.physicalKey('order:1');
+        await Promise.all([
+            ...physicalMatchingKeys.map((key) => fixture.node.set(key, 'value')),
+            fixture.node.set(otherKey, 'other'),
+        ]);
+        const scan = jest.spyOn(fixture.node, 'scan');
+
+        await provider.deleteByPattern('name*');
+
+        expect(scan).toHaveBeenCalled();
+        for (const call of scan.mock.calls) {
+            expect(call[1]).toEqual({ MATCH: `${namespace.keyPrefix}name*`, COUNT: 100 });
+        }
+        expect((await fixture.node.mGet(physicalMatchingKeys)).every((value) => value === null)).toBe(true);
+        await expect(fixture.node.get(otherKey)).resolves.toBe('other');
+        scan.mockRestore();
+    });
+
+    it('cache-evict-allentries-prefix/F05 ioredis keyPrefix 下删除逻辑 pattern', async () => {
+        if (!fixture) {
+            throw new Error('Redis fixture is required');
+        }
+        const namespace = createKeyNamespace(fixture);
+        const first = namespace.physicalKey('name:1');
+        const second = namespace.physicalKey('name:2');
+        const other = namespace.physicalKey('order:1');
+        const prefixed = new Redis({ ...fixture.io.options, keyPrefix: namespace.keyPrefix, lazyConnect: true });
+        prefixed.on('error', (error: Error) => fixture.errors.push(error));
+        try {
+            await prefixed.connect();
+            await fixture.node.mSet({ [first]: 'one', [second]: 'two', [other]: 'other' });
+            const provider = new RedisCacheProvider(createIoredisCacheClient(prefixed));
+
+            await provider.deleteByPattern('name*');
+
+            await expect(fixture.node.mGet([first, second])).resolves.toEqual([null, null]);
+            await expect(fixture.node.get(other)).resolves.toBe('other');
+        } finally {
+            if (prefixed.status !== 'end') {
+                const ended = once(prefixed, 'end');
+                prefixed.disconnect();
+                await ended;
+            }
+        }
+    });
+
+    it('cache-evict-allentries-prefix/F07 node-redis 缺省前缀不改写 key', async () => {
+        if (!fixture) {
+            throw new Error('Redis fixture is required');
+        }
+        const namespace = createKeyNamespace(fixture);
+        const first = namespace.physicalKey('name:1');
+        const second = namespace.physicalKey('name:2');
+        const other = namespace.physicalKey('order:1');
+        await fixture.node.mSet({ [first]: 'one', [second]: 'two', [other]: 'other' });
+
+        await nodeProvider.deleteByPattern(`${namespace.keyPrefix}name*`);
+
+        await expect(fixture.node.mGet([first, second])).resolves.toEqual([null, null]);
+        await expect(fixture.node.get(other)).resolves.toBe('other');
+    });
+
+    it('cache-evict-allentries-prefix/F08 node-redis 显式前缀访问同一命名空间', async () => {
+        if (!fixture) {
+            throw new Error('Redis fixture is required');
+        }
+        const namespace = createKeyNamespace(fixture);
+        const physicalKey = namespace.physicalKey('name:1');
+        const provider = new RedisCacheProvider(
+            createNodeRedisCacheClient(fixture.node, { keyPrefix: namespace.keyPrefix })
+        );
+
+        await provider.set('name:1', { prefixed: true });
+        await expect(fixture.io.get(physicalKey)).resolves.toBe('{"prefixed":true}');
+        await expect(provider.get('name:1')).resolves.toEqual({ prefixed: true });
+        await provider.deleteByPattern('name*');
+        await expect(fixture.io.get(physicalKey)).resolves.toBeNull();
+    });
+});
+
+redisTests('Redis 数据库级清理（要求 URL 显式选择非零数据库）', () => {
+    let fixture: RedisFixture | undefined;
+
+    beforeEach(async () => {
+        if (!redisUrl) {
+            throw new Error('CACHE_DECORATOR_TEST_REDIS_URL is required');
+        }
+        fixture = await createIsolatedDatabaseRedisFixture(redisUrl);
+    });
+
+    afterEach(async () => fixture?.close());
+
+    it('redis-cache-client/R04 重复清库保持数据库级语义', async () => {
+        if (!fixture) {
+            throw new Error('Redis fixture is required');
+        }
+        const cacheKey = fixture.key();
+        const businessKey = fixture.key();
+        const provider = new RedisCacheProvider(createNodeRedisCacheClient(fixture.node, { keyPrefix: 'ignored:' }));
+        await fixture.node.mSet({ [cacheKey]: 'cache', [businessKey]: 'business' });
+
+        await expect(provider.clear()).resolves.toBeUndefined();
+        await expect(provider.clear()).resolves.toBeUndefined();
+
+        await expect(fixture.node.mGet([cacheKey, businessKey])).resolves.toEqual([null, null]);
+        await expect(fixture.node.dbSize()).resolves.toBe(0);
+    });
+});

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

@@ -0,0 +1,201 @@
+import { createIoredisCacheClient } from '../src/adapters/ioredis-cache-client';
+import { CacheProviderRegistry } from '../src/core/cache-provider-registry';
+import { IoredisCacheClientSource } from '../src/core/redis-cache-client';
+import { KeyBuilder } from '../src/core/key-builder';
+import { MemoryCacheProvider } from '../src/core/native-cache';
+import { RedisCacheProvider } from '../src/core/redis-cache';
+import { CacheEvict } from '../src/decorators/cache-evict';
+import { Cache } from '../src/decorators/cache';
+
+class FakeIoredisCacheClientSource implements IoredisCacheClientSource {
+    readonly options = Object.freeze({ keyPrefix: '' });
+    readonly writes: Array<{
+        readonly key: string;
+        readonly value: string;
+        readonly ttlSeconds: number | undefined;
+    }> = [];
+    private readonly values = new Map<string, string>();
+
+    constructor(private readonly events: string[]) {}
+
+    get(key: string): Promise<unknown> {
+        this.events.push(`get:${key}`);
+        return Promise.resolve(this.values.get(key) ?? null);
+    }
+
+    set(key: string, value: string): Promise<unknown> {
+        this.events.push(`set:${key}`);
+        this.writes.push({ key, value, ttlSeconds: undefined });
+        this.values.set(key, value);
+        return Promise.resolve('OK');
+    }
+
+    setex(key: string, ttlSeconds: number, value: string): Promise<unknown> {
+        this.events.push(`setex:${key}`);
+        this.writes.push({ key, value, ttlSeconds });
+        this.values.set(key, value);
+        return Promise.resolve('OK');
+    }
+
+    del(...keys: string[]): Promise<unknown> {
+        this.events.push(`del:${keys.join(',')}`);
+        let deleted = 0;
+        for (const key of keys) {
+            if (this.values.delete(key)) {
+                deleted += 1;
+            }
+        }
+        return Promise.resolve(deleted);
+    }
+
+    scan(..._args: Parameters<IoredisCacheClientSource['scan']>): Promise<unknown> {
+        return Promise.resolve(['0', []]);
+    }
+
+    flushdb(): Promise<unknown> {
+        this.values.clear();
+        return Promise.resolve('OK');
+    }
+
+    seed(key: string, value: string): void {
+        this.values.set(key, value);
+    }
+
+    raw(key: string): string | undefined {
+        return this.values.get(key);
+    }
+}
+
+beforeEach(() => CacheProviderRegistry.clear());
+afterEach(() => CacheProviderRegistry.clear());
+
+it('redis-cache-client/D01 默认 Redis Provider 保持装饰器调用方式', async () => {
+    const events: string[] = [];
+    const source = new FakeIoredisCacheClientSource(events);
+    const provider = new RedisCacheProvider(createIoredisCacheClient(source));
+    CacheProviderRegistry.register('redis', provider);
+    CacheProviderRegistry.setDefault('redis');
+    const cacheKey = KeyBuilder.build('d01-users', [1]);
+
+    class UserService {
+        @Cache('d01-users')
+        async getUser(id: number): Promise<{ id: number; version: number }> {
+            events.push(`business:get:${id}`);
+            return { id, version: events.filter((event) => event === `business:get:${id}`).length };
+        }
+
+        @CacheEvict('d01-users')
+        async updateUser(id: number): Promise<{ id: number; updated: boolean }> {
+            events.push(`business:update:${id}`);
+            return { id, updated: true };
+        }
+    }
+
+    const service = new UserService();
+    await expect(service.getUser(1)).resolves.toEqual({ id: 1, version: 1 });
+    await expect(service.getUser(1)).resolves.toEqual({ id: 1, version: 1 });
+    await expect(service.updateUser(1)).resolves.toEqual({ id: 1, updated: true });
+    await expect(service.getUser(1)).resolves.toEqual({ id: 1, version: 2 });
+
+    expect(events).toEqual([
+        `get:${cacheKey}`,
+        'business:get:1',
+        `set:${cacheKey}`,
+        `get:${cacheKey}`,
+        'business:update:1',
+        `del:${cacheKey}`,
+        `get:${cacheKey}`,
+        'business:get:1',
+        `set:${cacheKey}`,
+    ]);
+});
+
+it('redis-cache-client/D02 指定 Provider 名称保持原行为', async () => {
+    const events: string[] = [];
+    const redisProvider = new RedisCacheProvider(createIoredisCacheClient(new FakeIoredisCacheClientSource(events)));
+    const memoryProvider = new MemoryCacheProvider();
+    CacheProviderRegistry.register('redis', redisProvider);
+    CacheProviderRegistry.register('memory', memoryProvider);
+    CacheProviderRegistry.setDefault('memory');
+    const redisKey = KeyBuilder.build('d02-orders', ['active']);
+
+    class OrderService {
+        redisCalls = 0;
+        memoryCalls = 0;
+
+        @Cache('d02-orders', { providerName: 'redis', key: 'active' })
+        async getRedisOrder(id: number): Promise<{ id: number; source: string }> {
+            this.redisCalls += 1;
+            return { id, source: 'redis' };
+        }
+
+        @Cache('d02-orders', { providerName: 'memory', key: 'active' })
+        async getMemoryOrder(id: number): Promise<{ id: number; source: string }> {
+            this.memoryCalls += 1;
+            return { id, source: 'memory' };
+        }
+
+        @CacheEvict('d02-orders', { providerName: 'redis', key: 'active' })
+        async evictRedisOrder(): Promise<string> {
+            return 'evicted';
+        }
+    }
+
+    const service = new OrderService();
+    await expect(service.getRedisOrder(1)).resolves.toEqual({ id: 1, source: 'redis' });
+    await expect(service.getRedisOrder(2)).resolves.toEqual({ id: 1, source: 'redis' });
+    await expect(service.getMemoryOrder(3)).resolves.toEqual({ id: 3, source: 'memory' });
+    await expect(service.getMemoryOrder(4)).resolves.toEqual({ id: 3, source: 'memory' });
+    await expect(service.evictRedisOrder()).resolves.toBe('evicted');
+    await expect(service.getRedisOrder(5)).resolves.toEqual({ id: 5, source: 'redis' });
+    await expect(service.getMemoryOrder(6)).resolves.toEqual({ id: 3, source: 'memory' });
+
+    expect(service.redisCalls).toBe(2);
+    expect(service.memoryCalls).toBe(1);
+    expect(events.filter((event) => event === `get:${redisKey}`)).toHaveLength(3);
+    expect(events).toContain(`del:${redisKey}`);
+});
+
+it('cache-operation-logging/A03 日志改造保持旧版 Redis key、entry、TTL 与淘汰 pattern', async () => {
+    const events: string[] = [];
+    const source = new FakeIoredisCacheClientSource(events);
+    const scan = jest.spyOn(source, 'scan');
+    const provider = new RedisCacheProvider(createIoredisCacheClient(source));
+    CacheProviderRegistry.register('compat-redis', provider);
+    const legacyKey = KeyBuilder.build('compat-users', ['legacy']);
+    const freshKey = KeyBuilder.build('compat-users', ['fresh']);
+    source.seed(legacyKey, '{"value":{"id":18,"source":"legacy-0.1.3"}}');
+    let legacyBusinessCalls = 0;
+
+    class UserService {
+        @Cache('compat-users', { providerName: 'compat-redis', key: 'legacy' })
+        async getLegacyUser(): Promise<{ id: number; source: string }> {
+            legacyBusinessCalls += 1;
+            return { id: 0, source: 'business' };
+        }
+
+        @Cache('compat-users', { providerName: 'compat-redis', key: 'fresh', ttl: 45 })
+        async getFreshUser(): Promise<{ id: number; source: string }> {
+            return { id: 19, source: 'current' };
+        }
+
+        @CacheEvict('compat-users', { providerName: 'compat-redis', allEntries: true })
+        async clearUsers(): Promise<boolean> {
+            return true;
+        }
+    }
+
+    const service = new UserService();
+    await expect(service.getLegacyUser()).resolves.toEqual({ id: 18, source: 'legacy-0.1.3' });
+    expect(legacyBusinessCalls).toBe(0);
+    await expect(service.getFreshUser()).resolves.toEqual({ id: 19, source: 'current' });
+    expect(source.raw(freshKey)).toBe('{"value":{"id":19,"source":"current"}}');
+    expect(source.writes).toContainEqual({
+        key: freshKey,
+        value: '{"value":{"id":19,"source":"current"}}',
+        ttlSeconds: 45,
+    });
+
+    await expect(service.clearUsers()).resolves.toBe(true);
+    expect(scan).toHaveBeenCalledWith('0', 'MATCH', 'compat-users*', 'COUNT', 100);
+});