@jintianxiayu/cache-decorator 0.1.2 → 1.0.0

package/test/cache.test.ts

@@ -1,256 +1,255 @@
-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);
-    });
-  });
-});
+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();
+    });
+
+    afterEach(() => {
+        jest.useRealTimers();
+    });
+
+    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 {
+                callCount = 0;
+
+                @Cache('user-cache', { ttl: 60 })
+                async getUser(id: number) {
+                    this.callCount++;
+                    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 });
+            expect(service.callCount).toBe(2);
+        });
+    });
+
+    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('应缓存错误结果并重新抛出原始异常', async () => {
+            const expectedError = new Error('user not found');
+
+            class UserService {
+                callCount = 0;
+
+                @Cache('user-cache')
+                async getUser(_id: number) {
+                    this.callCount++;
+                    throw expectedError;
+                }
+            }
+
+            const service = new UserService();
+
+            await expect(service.getUser(1)).rejects.toBe(expectedError);
+            await expect(service.getUser(1)).rejects.toBe(expectedError);
+            expect(service.callCount).toBe(1);
+        });
+    });
+
+    describe('请求合并', () => {
+        it('并发请求应返回同一 Promise', async () => {
+            let resolvePromise: ((value: number) => void) | undefined;
+            let callCount = 0;
+            const resultPromise = new Promise<number>((resolve) => {
+                resolvePromise = resolve;
+            });
+
+            class UserService {
+                @Cache('user-cache')
+                async getUser(_id: number): Promise<number> {
+                    callCount++;
+                    return resultPromise;
+                }
+            }
+
+            const service = new UserService();
+            const promise1 = service.getUser(1);
+            const promise2 = service.getUser(1);
+
+            await Promise.resolve();
+            resolvePromise!(42);
+
+            const [result1, result2] = await Promise.all([promise1, promise2]);
+            expect(callCount).toBe(1);
+            expect(promise1).toBe(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/fixtures/cache-logger-child.mjs

@@ -0,0 +1,108 @@
+import assert from 'node:assert/strict';
+import { realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import cachePackage from '../../dist/index.js';
+import loggerPackage from '../../../logger/dist/index.js';
+
+const { Cache, CacheProviderRegistry, MemoryCacheProvider } = cachePackage;
+const { LoggerContext, LoggerFactory } = loggerPackage;
+const CACHE_LOGGER_NAME = '@jintianxiayu/cache-decorator';
+const profileLevel = process.argv[2];
+const fixtureDirectory = dirname(fileURLToPath(import.meta.url));
+const fixtureRequire = createRequire(import.meta.url);
+if (profileLevel !== 'debug' && profileLevel !== 'error') {
+    throw new Error('Expected cache Logger profile level: debug or error');
+}
+
+/** 将 legacy method decorator 应用到 JavaScript fixture 的指定方法。 */
+function decorateMethod(target, methodName, decorator) {
+    const descriptor = Object.getOwnPropertyDescriptor(target, methodName);
+    assert.ok(descriptor);
+    decorator(target, methodName, descriptor);
+    Object.defineProperty(target, methodName, descriptor);
+}
+
+/** 在应用初始化 Logger 后执行正常缓存和 Provider 失败调用。 */
+async function main() {
+    LoggerFactory.init({
+        root: {
+            level: 'error',
+            console: { enabled: false, colors: false, format: 'json' },
+            file: { enabled: false },
+        },
+        loggers: {
+            [CACHE_LOGGER_NAME]: {
+                level: profileLevel,
+                console: { enabled: true, colors: false, format: 'json' },
+                file: { enabled: false },
+            },
+        },
+        masking: { enabled: true },
+        processErrors: {
+            uncaughtException: false,
+            unhandledRejection: false,
+            exitOnError: false,
+        },
+    });
+
+    const cachePackageRoot = resolve(fixtureDirectory, '../..');
+    const requireFromCache = createRequire(join(cachePackageRoot, 'package.json'));
+    const directLoggerEntry = fixtureRequire.resolve('@jintianxiayu/logger');
+    const cacheLoggerEntry = requireFromCache.resolve('@jintianxiayu/logger');
+    assert.equal(realpathSync(directLoggerEntry), realpathSync(cacheLoggerEntry));
+    const namedLogger = LoggerFactory.getLogger(CACHE_LOGGER_NAME);
+
+    const memoryProvider = new MemoryCacheProvider();
+    const providerError = Object.assign(new Error('redis unavailable'), {
+        password: 'provider-password-secret',
+        email: 'provider@example.com',
+    });
+    const failingProvider = {
+        get: async () => {
+            throw providerError;
+        },
+        set: () => undefined,
+        delete: () => undefined,
+        clear: () => undefined,
+        deleteByPattern: () => undefined,
+    };
+
+    class SuccessService {
+        getUser() {
+            return { id: 17, password: 'business-value-secret' };
+        }
+    }
+    decorateMethod(SuccessService.prototype, 'getUser', Cache('fixture-users', { providerName: 'memory' }));
+
+    class FailureService {
+        getUser() {
+            throw new Error('business method must not run');
+        }
+    }
+    decorateMethod(FailureService.prototype, 'getUser', Cache('fixture-failure-users', { providerName: 'failing' }));
+
+    CacheProviderRegistry.register('memory', memoryProvider);
+    CacheProviderRegistry.register('failing', failingProvider);
+    try {
+        const result = await LoggerContext.withContext({ traceId: 'cache-fixture-trace' }, () =>
+            new SuccessService().getUser()
+        );
+        assert.deepEqual(result, { id: 17, password: 'business-value-secret' });
+
+        const failure = LoggerContext.withContext({ traceId: 'cache-fixture-trace' }, () =>
+            new FailureService().getUser()
+        );
+        await assert.rejects(failure, (error) => error === providerError);
+        assert.strictEqual(LoggerFactory.getLogger(CACHE_LOGGER_NAME), namedLogger);
+    } finally {
+        CacheProviderRegistry.clear();
+        await LoggerFactory.shutdown({ timeout: 2_000 });
+    }
+}
+
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.stack : String(error)}\n`);
+    process.exitCode = 1;
+});

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

@@ -0,0 +1,22 @@
+import Redis from 'ioredis';
+
+/**
+ * 使用 0.1.3 的字符串/JSON 与秒级 TTL 协议写入兼容性数据。
+ * @param client 由测试创建并持有的 ioredis 连接。
+ * @param key 旧版本收到的原始缓存 key。
+ * @param value 旧版本支持的字符串或 JSON 可序列化值。
+ * @param ttl 可选的秒级 TTL；0 与 undefined 使用普通 SET。
+ * @returns 旧版写入命令成功后完成。
+ * @throws 无法序列化或 Redis 命令失败时传播错误。
+ */
+export async function writeLegacyRedisCache(client: Redis, key: string, value: unknown, ttl?: number): Promise<void> {
+    const serialized = typeof value === 'string' ? value : JSON.stringify(value);
+    if (typeof serialized !== 'string') {
+        throw new TypeError('Legacy cache fixture value must serialize to a string');
+    }
+    if (ttl) {
+        await client.setex(key, ttl, serialized);
+        return;
+    }
+    await client.set(key, serialized);
+}