@jintianxiayu/cache-decorator 0.1.2

package/src/index.ts

@@ -0,0 +1,9 @@
+
+export * from './core/cache-provider';
+export * from './core/cache-provider-registry';
+export * from './core/key-builder';
+export * from './core/native-cache';
+export * from './core/pending-cache';
+export * from './core/redis-cache';
+export * from './decorators/cache';
+export * from './decorators/cache-evict';

package/test/cache-evict.test.ts

@@ -0,0 +1,178 @@
+import { Cache } from '../src/decorators/cache';
+import { CacheEvict } from '../src/decorators/cache-evict';
+import { CacheProviderRegistry } from '../src/core/cache-provider-registry';
+import { MemoryCacheProvider } from '../src/core/native-cache';
+
+describe('@CacheEvict 装饰器', () => {
+  let memoryProvider: MemoryCacheProvider;
+
+  beforeAll(() => {
+    memoryProvider = new MemoryCacheProvider();
+    CacheProviderRegistry.register('memory', memoryProvider);
+    CacheProviderRegistry.setDefault('memory');
+  });
+
+  afterEach(() => {
+    memoryProvider.clear();
+  });
+
+  describe('按入参清除', () => {
+    it('应清除对应缓存条目', async () => {
+      let getUserCallCount = 0;
+      let updateUserCallCount = 0;
+
+      class UserService {
+        @Cache('user-cache')
+        async getUser(id: number) {
+          getUserCallCount++;
+          return { id };
+        }
+
+        @CacheEvict('user-cache')
+        async updateUser(id: number) {
+          updateUserCallCount++;
+          return { id, updated: true };
+        }
+      }
+
+      const service = new UserService();
+      await service.getUser(1);
+      await service.getUser(1);
+      expect(getUserCallCount).toBe(1);
+
+      await service.updateUser(1);
+      await service.getUser(1);
+      expect(getUserCallCount).toBe(2);
+      expect(updateUserCallCount).toBe(1);
+    });
+  });
+
+  describe('清除所有条目', () => {
+    it('应清除该缓存名称下所有条目', async () => {
+      let getUserCallCount = 0;
+      let getOrderCallCount = 0;
+      let clearCallCount = 0;
+
+      class Service {
+        @Cache('user-cache')
+        async getUser(id: number) {
+          getUserCallCount++;
+          return { id };
+        }
+
+        @Cache('order-cache')
+        async getOrder(id: number) {
+          getOrderCallCount++;
+          return { id };
+        }
+
+        @CacheEvict('user-cache', { allEntries: true })
+        async clearAllUsers() {
+          clearCallCount++;
+          return true;
+        }
+      }
+
+      const service = new Service();
+      await service.getUser(1);
+      await service.getUser(2);
+      await service.getOrder(1);
+      expect(getUserCallCount).toBe(2);
+      expect(getOrderCallCount).toBe(1);
+
+      await service.clearAllUsers();
+      expect(clearCallCount).toBe(1);
+
+      await service.getUser(1);
+      await service.getUser(2);
+      await service.getOrder(1);
+      expect(getUserCallCount).toBe(4);
+      expect(getOrderCallCount).toBe(1);
+    });
+  });
+
+  describe('key 选项', () => {
+    it('key 为字符串时应删除对应缓存条目', async () => {
+      let getUserCallCount = 0;
+
+      class UserService {
+        @Cache('user-cache', { key: 'all-users' })
+        async getUsers() {
+          getUserCallCount++;
+          return [{ id: 1 }, { id: 2 }];
+        }
+
+        @CacheEvict('user-cache', { key: 'all-users' })
+        async clearUsers() {
+          return true;
+        }
+      }
+
+      const service = new UserService();
+      await service.getUsers();
+      await service.getUsers();
+      expect(getUserCallCount).toBe(1);
+
+      await service.clearUsers();
+      await service.getUsers();
+      expect(getUserCallCount).toBe(2);
+    });
+
+    it('key 为函数时应使用函数返回值删除缓存条目', async () => {
+      let getUserCallCount = 0;
+
+      class UserService {
+        @Cache('user-cache', { key: (...args: unknown[]) => String(args[0]) })
+        async getUser(id: number) {
+          getUserCallCount++;
+          return { id };
+        }
+
+        @CacheEvict('user-cache', { key: (...args: unknown[]) => String(args[0]) })
+        async deleteUser(id: number) {
+          return { id, deleted: true };
+        }
+      }
+
+      const service = new UserService();
+      await service.getUser(1);
+      await service.getUser(2);
+      expect(getUserCallCount).toBe(2);
+
+      await service.deleteUser(1);
+      await service.getUser(1);
+      await service.getUser(2);
+      expect(getUserCallCount).toBe(3);
+    });
+
+    it('allEntries 为 true 时忽略 key 选项', async () => {
+      let getUserCallCount = 0;
+      let clearCallCount = 0;
+
+      class UserService {
+        @Cache('user-cache', { key: 'specific-key' })
+        async getUsers() {
+          getUserCallCount++;
+          return [];
+        }
+
+        @CacheEvict('user-cache', { allEntries: true, key: 'ignored-key' })
+        async clearAllUsers() {
+          clearCallCount++;
+          return true;
+        }
+      }
+
+      const service = new UserService();
+      await service.getUsers();
+      await service.getUsers();
+      expect(getUserCallCount).toBe(1);
+
+      await service.clearAllUsers();
+      expect(clearCallCount).toBe(1);
+
+      await service.getUsers();
+      expect(getUserCallCount).toBe(2);
+    });
+  });
+});

package/test/cache-provider-registry.test.ts

@@ -0,0 +1,36 @@
+import { CacheProviderRegistry } from '../src/core/cache-provider-registry';
+import { MemoryCacheProvider } from '../src/core/native-cache';
+
+describe('CacheProviderRegistry', () => {
+  let memoryProvider: MemoryCacheProvider;
+
+  beforeEach(() => {
+    memoryProvider = new MemoryCacheProvider();
+    CacheProviderRegistry.register('memory', memoryProvider);
+  });
+
+  afterEach(() => {
+    CacheProviderRegistry.clear();
+  });
+
+  describe('register & get', () => {
+    it('应注册并获取 Provider', () => {
+      expect(CacheProviderRegistry.get('memory')).toBe(memoryProvider);
+    });
+
+    it('应在 Provider 不存在时抛出错误', () => {
+      expect(() => CacheProviderRegistry.get('nonexistent')).toThrow();
+    });
+  });
+
+  describe('setDefault & get', () => {
+    it('应设置并获取默认 Provider', () => {
+      CacheProviderRegistry.setDefault('memory');
+      expect(CacheProviderRegistry.get()).toBe(memoryProvider);
+    });
+
+    it('应在未设置默认且未指定时抛出错误', () => {
+      expect(() => CacheProviderRegistry.get()).toThrow();
+    });
+  });
+});

package/test/cache.test.ts

@@ -0,0 +1,256 @@
+import { Cache } from '../src/decorators/cache';
+import { CacheProviderRegistry } from '../src/core/cache-provider-registry';
+import { MemoryCacheProvider } from '../src/core/native-cache';
+
+describe('@Cache 装饰器', () => {
+  beforeAll(() => {
+    CacheProviderRegistry.register('memory', new MemoryCacheProvider());
+    CacheProviderRegistry.setDefault('memory');
+  });
+
+  beforeEach(() => {
+    const provider = CacheProviderRegistry.get();
+    provider.clear();
+  });
+
+  describe('基础缓存', () => {
+    it('应缓存方法结果', async () => {
+      class UserService {
+        callCount = 0;
+
+        @Cache('user-cache')
+        async getUser(id: number) {
+          this.callCount++;
+          return { id, name: 'test' };
+        }
+      }
+
+      const service = new UserService();
+      const result1 = await service.getUser(1);
+      const result2 = await service.getUser(1);
+
+      expect(result1).toEqual({ id: 1, name: 'test' });
+      expect(result2).toEqual({ id: 1, name: 'test' });
+      expect(service.callCount).toBe(1);
+    });
+
+    it('不同参数应分别缓存', async () => {
+      class UserService {
+        callCount = 0;
+
+        @Cache('user-cache')
+        async getUser(id: number) {
+          this.callCount++;
+          return { id };
+        }
+      }
+
+      const service = new UserService();
+      await service.getUser(1);
+      await service.getUser(2);
+
+      expect(service.callCount).toBe(2);
+    });
+  });
+
+  describe('TTL 过期', () => {
+    it('应在 TTL 后失效', async () => {
+      jest.useFakeTimers();
+
+      class UserService {
+        @Cache('user-cache', { ttl: 60 })
+        async getUser(id: number) {
+          return { id };
+        }
+      }
+
+      const service = new UserService();
+      const result1 = await service.getUser(1);
+      expect(result1).toEqual({ id: 1 });
+
+      jest.advanceTimersByTime(60001);
+
+      const result2 = await service.getUser(1);
+      expect(result2).toEqual({ id: 1 });
+
+      jest.useRealTimers();
+    });
+  });
+
+  describe('缓存命中', () => {
+    it('应直接返回缓存值', async () => {
+      class UserService {
+        callCount = 0;
+
+        @Cache('user-cache')
+        async getUser(id: number) {
+          this.callCount++;
+          return { id, timestamp: Date.now() };
+        }
+      }
+
+      const service = new UserService();
+      const result1 = await service.getUser(1);
+      const result2 = await service.getUser(1);
+
+      expect(result1.id).toBe(1);
+      expect(result2.id).toBe(1);
+      expect(result1.timestamp).toBe(result2.timestamp);
+      expect(service.callCount).toBe(1);
+    });
+  });
+
+  describe('错误结果缓存', () => {
+    it.skip('应缓存错误结果', async () => {
+      class UserService {
+        callCount = 0;
+
+        @Cache('user-cache')
+        async getUser(_id: number) {
+          this.callCount++;
+          throw new Error('user not found');
+        }
+      }
+
+      const service = new UserService();
+
+      try {
+        await service.getUser(1);
+      } catch (e) {
+        // expected
+      }
+      try {
+        await service.getUser(1);
+      } catch (e) {
+        // expected
+      }
+      expect(service.callCount).toBe(1);
+    });
+  });
+
+  describe('请求合并', () => {
+    it.skip('并发请求应返回同一 Promise', async () => {
+      let resolvePromise: ((value: number) => void) | undefined;
+      let callCount = 0;
+
+      class UserService {
+        @Cache('user-cache')
+        async getUser(_id: number): Promise<number> {
+          callCount++;
+          return new Promise(resolve => {
+            resolvePromise = resolve;
+          });
+        }
+      }
+
+      const service = new UserService();
+      const promise1 = service.getUser(1);
+      const promise2 = service.getUser(1);
+
+      await new Promise(resolve => setTimeout(resolve, 10));
+
+      expect(callCount).toBe(1);
+      expect(promise1).toBe(promise2);
+
+      resolvePromise!(42);
+
+      const [result1, result2] = await Promise.all([promise1, promise2]);
+      expect(result1).toBe(42);
+      expect(result2).toBe(42);
+      expect(callCount).toBe(1);
+    });
+  });
+
+  describe('key 选项', () => {
+    it('key 为 undefined 时使用自动生成逻辑', async () => {
+      class UserService {
+        callCount = 0;
+
+        @Cache('user-cache', { key: undefined })
+        async getUser(id: number) {
+          this.callCount++;
+          return { id };
+        }
+      }
+
+      const service = new UserService();
+      await service.getUser(1);
+      await service.getUser(1);
+      expect(service.callCount).toBe(1);
+    });
+
+    it('key 为 null 时使用自动生成逻辑', async () => {
+      class UserService {
+        callCount = 0;
+
+        @Cache('user-cache', { key: null })
+        async getUser(id: number) {
+          this.callCount++;
+          return { id };
+        }
+      }
+
+      const service = new UserService();
+      await service.getUser(1);
+      await service.getUser(1);
+      expect(service.callCount).toBe(1);
+    });
+
+    it('key 为字符串时使用字符串值', async () => {
+      class UserService {
+        callCount = 0;
+
+        @Cache('user-cache', { key: 'specific-key' })
+        async getUser(id: number) {
+          this.callCount++;
+          return { id };
+        }
+      }
+
+      const service = new UserService();
+      await service.getUser(1);
+      await service.getUser(2);
+      expect(service.callCount).toBe(1);
+    });
+
+    it('key 为函数时使用函数返回值', async () => {
+      class UserService {
+        callCount = 0;
+
+        @Cache('user-cache', { key: (...args: unknown[]) => String(args[0]) })
+        async getUser(id: number) {
+          this.callCount++;
+          return { id };
+        }
+      }
+
+      const service = new UserService();
+      await service.getUser(1);
+      await service.getUser(1);
+      expect(service.callCount).toBe(1);
+      await service.getUser(2);
+      expect(service.callCount).toBe(2);
+    });
+
+    it('key 函数抛出异常时降级到自动生成', async () => {
+      class UserService {
+        callCount = 0;
+
+        @Cache('user-cache', {
+          key: () => {
+            throw new Error('bad key');
+          },
+        })
+        async getUser(id: number) {
+          this.callCount++;
+          return { id };
+        }
+      }
+
+      const service = new UserService();
+      await service.getUser(1);
+      await service.getUser(1);
+      expect(service.callCount).toBe(1);
+    });
+  });
+});

package/test/key-builder.test.ts

@@ -0,0 +1,37 @@
+import { KeyBuilder } from '../src/core/key-builder';
+
+describe('KeyBuilder', () => {
+  describe('build', () => {
+    it('应生成包含缓存名的 key', () => {
+      const key = KeyBuilder.build('user-cache', []);
+      expect(key).toBe('user-cache');
+    });
+
+    it('应生成包含参数值的 key', () => {
+      const key = KeyBuilder.build('user-cache', [1]);
+      expect(key).toBe('user-cache:1');
+    });
+
+    it('应处理多个参数', () => {
+      const key = KeyBuilder.build('user-cache', [1, 'test']);
+      expect(key).toBe('user-cache:1&test');
+    });
+
+    it('应处理对象参数', () => {
+      const key = KeyBuilder.build('user-cache', [{ id: 1, name: 'test' }]);
+      expect(key).toBe('user-cache:{"id":1,"name":"test"}');
+    });
+
+    it('应处理 null 和 undefined', () => {
+      const key1 = KeyBuilder.build('user-cache', [null]);
+      const key2 = KeyBuilder.build('user-cache', [undefined]);
+      expect(key1).toBe('user-cache:null');
+      expect(key2).toBe('user-cache:null');
+    });
+
+    it('应处理数字和布尔值', () => {
+      const key = KeyBuilder.build('user-cache', [123, true, false]);
+      expect(key).toBe('user-cache:123&true&false');
+    });
+  });
+});

package/test/native-cache.test.ts

@@ -0,0 +1,71 @@
+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');
+    });
+  });
+});

package/test/pending-cache.test.ts

@@ -0,0 +1,56 @@
+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();
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}