@jintianxiayu/cache-decorator 1.0.0 → 1.0.2

package/test/cache-logger.integration.test.ts

@@ -1,129 +1,159 @@
-import { spawn } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { runCommand } from './helpers/package-consumer';
-
-jest.setTimeout(30_000);
-
-interface CacheLogMetadata {
-    readonly event: string;
-    readonly cacheName: string;
-    readonly methodName: string;
-    readonly providerName: string;
-    readonly entryType?: string;
-    readonly operation?: string;
-    readonly error?: {
-        readonly name: string;
-        readonly message: string;
-        readonly password: string;
-        readonly email: string;
-    };
-}
-
-interface JsonLogEvent {
-    readonly level: string;
-    readonly name: string;
-    readonly message: string;
-    readonly traceId: string;
-    readonly meta: CacheLogMetadata;
-}
-
-interface ChildResult {
-    readonly code: number | null;
-    readonly stdout: string;
-    readonly stderr: string;
-}
-
-const packageRoot = resolve(__dirname, '..');
-const loggerRoot = resolve(packageRoot, '../logger');
-const fixture = join(__dirname, 'fixtures', 'cache-logger-child.mjs');
-
-/**
- * 在隔离进程运行真实 Logger fixture，确保关闭流程完整刷新结构化输出。
- * @param profileLevel cache 命名 profile 的筛选级别。
- * @returns 子进程退出码和完整标准流。
- * @throws 子进程无法启动时拒绝。
- */
-function runFixture(profileLevel: 'debug' | 'error'): Promise<ChildResult> {
-    return new Promise((resolveResult, reject) => {
-        const child = spawn(process.execPath, [fixture, profileLevel], {
-            cwd: packageRoot,
-            stdio: ['ignore', 'pipe', 'pipe'],
-            windowsHide: true,
-        });
-        let stdout = '';
-        let stderr = '';
-        child.stdout.setEncoding('utf8');
-        child.stderr.setEncoding('utf8');
-        child.stdout.on('data', (chunk: string) => (stdout += chunk));
-        child.stderr.on('data', (chunk: string) => (stderr += chunk));
-        child.once('error', reject);
-        child.once('exit', (code) => resolveResult({ code, stdout, stderr }));
-    });
-}
-
-function parseEvents(output: string): JsonLogEvent[] {
-    return output
-        .split(/\r?\n/)
-        .filter(Boolean)
-        .map((line) => JSON.parse(line) as JsonLogEvent);
-}
-
-beforeAll(() => {
-    const compiler = require.resolve('typescript/bin/tsc');
-    runCommand({ executable: process.execPath, args: [compiler, '-p', loggerRoot], cwd: loggerRoot });
-    runCommand({ executable: process.execPath, args: [compiler, '-p', packageRoot], cwd: packageRoot });
-});
-
-it('cache-operation-logging/M03 cache-operation-logging/M04 使用真实命名 Logger 脱敏并关联 traceId', async () => {
-    const result = await runFixture('debug');
-    expect(result.code).toBe(0);
-    expect(result.stderr).toBe('');
-    expect(result.stdout).not.toContain('provider-password-secret');
-    expect(result.stdout).not.toContain('provider@example.com');
-    expect(result.stdout).not.toContain('business-value-secret');
-
-    const output = parseEvents(result.stdout);
-    expect(output.map(({ level, meta }) => `${level}:${meta.event}`)).toEqual([
-        'debug:cache.miss',
-        'debug:cache.write_dispatched',
-        'error:cache.operation_failed',
-    ]);
-    expect(output.every(({ name }) => name === '@jintianxiayu/cache-decorator')).toBe(true);
-    expect(output.every(({ traceId }) => traceId === 'cache-fixture-trace')).toBe(true);
-    expect(output.every(({ meta }) => !('traceId' in meta))).toBe(true);
-    expect(output[2]?.meta).toMatchObject({
-        event: 'cache.operation_failed',
-        cacheName: 'fixture-failure-users',
-        methodName: 'getUser',
-        providerName: 'failing',
-        operation: 'read',
-        error: {
-            name: 'Error',
-            message: 'redis unavailable',
-            password: '********',
-            email: 'pr***@example.com',
-        },
-    });
-});
-
-it('cache-operation-logging/Logger 配置筛选输出且复用应用提供的唯一 Logger runtime', async () => {
-    const result = await runFixture('error');
-    expect(result.code).toBe(0);
-    expect(result.stderr).toBe('');
-    const output = parseEvents(result.stdout);
-    expect(output).toHaveLength(1);
-    expect(output[0]).toMatchObject({
-        level: 'error',
-        name: '@jintianxiayu/cache-decorator',
-        traceId: 'cache-fixture-trace',
-        meta: { event: 'cache.operation_failed', operation: 'read' },
-    });
-});
-
-it('cache decorator 源码不读取或写入 LoggerContext', () => {
-    const sources = ['src/core/cache-logger.ts', 'src/decorators/cache.ts', 'src/decorators/cache-evict.ts']
-        .map((file) => readFileSync(join(packageRoot, file), 'utf8'))
-        .join('\n');
-    expect(sources).not.toContain('LoggerContext');
-});
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { runCommand } from './helpers/package-consumer';
+
+jest.setTimeout(30_000);
+
+interface CacheLogMetadata {
+    readonly event: string;
+    readonly cacheName: string;
+    readonly methodName: string;
+    readonly providerName: string;
+    readonly entryType?: string;
+    readonly operation?: string;
+    readonly error?: {
+        readonly name: string;
+        readonly message: string;
+        readonly password: string;
+        readonly email: string;
+    };
+}
+
+interface JsonLogEvent {
+    readonly level: string;
+    readonly name: string;
+    readonly message: string;
+    readonly traceId: string;
+    readonly meta: CacheLogMetadata;
+}
+
+interface ChildResult {
+    readonly code: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+
+const packageRoot = resolve(__dirname, '..');
+const loggerRoot = resolve(packageRoot, '../logger');
+const fixture = join(__dirname, 'fixtures', 'cache-logger-child.mjs');
+const providerFailureFixture = join(__dirname, 'fixtures', 'cache-provider-failure-child.mjs');
+
+/**
+ * 在隔离进程运行真实 Logger fixture，确保关闭流程完整刷新结构化输出。
+ * @param profileLevel cache 命名 profile 的筛选级别。
+ * @returns 子进程退出码和完整标准流。
+ * @throws 子进程无法启动时拒绝。
+ */
+function runFixture(profileLevel: 'debug' | 'error'): Promise<ChildResult> {
+    return new Promise((resolveResult, reject) => {
+        const child = spawn(process.execPath, [fixture, profileLevel], {
+            cwd: packageRoot,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk: string) => (stdout += chunk));
+        child.stderr.on('data', (chunk: string) => (stderr += chunk));
+        child.once('error', reject);
+        child.once('exit', (code) => resolveResult({ code, stdout, stderr }));
+    });
+}
+
+/**
+ * 在严格未处理 rejection 模式运行 Provider 异步失败 fixture。
+ * @returns 子进程退出码和完整标准流。
+ * @throws 子进程无法启动时拒绝。
+ */
+function runProviderFailureFixture(): Promise<ChildResult> {
+    return new Promise((resolveResult, reject) => {
+        const child = spawn(process.execPath, ['--unhandled-rejections=strict', providerFailureFixture], {
+            cwd: packageRoot,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk: string) => (stdout += chunk));
+        child.stderr.on('data', (chunk: string) => (stderr += chunk));
+        child.once('error', reject);
+        child.once('exit', (code) => resolveResult({ code, stdout, stderr }));
+    });
+}
+
+function parseEvents(output: string): JsonLogEvent[] {
+    return output
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .map((line) => JSON.parse(line) as JsonLogEvent);
+}
+
+beforeAll(() => {
+    const compiler = require.resolve('typescript/bin/tsc');
+    runCommand({ executable: process.execPath, args: [compiler, '-p', loggerRoot], cwd: loggerRoot });
+    runCommand({ executable: process.execPath, args: [compiler, '-p', packageRoot], cwd: packageRoot });
+});
+
+it('cache-operation-logging/M03 cache-operation-logging/M04 使用真实命名 Logger 脱敏并关联 traceId', async () => {
+    const result = await runFixture('debug');
+    expect(result.code).toBe(0);
+    expect(result.stderr).toBe('');
+    expect(result.stdout).not.toContain('provider-password-secret');
+    expect(result.stdout).not.toContain('provider@example.com');
+    expect(result.stdout).not.toContain('business-value-secret');
+
+    const output = parseEvents(result.stdout);
+    expect(output.map(({ level, meta }) => `${level}:${meta.event}`)).toEqual([
+        'debug:cache.miss',
+        'debug:cache.write_dispatched',
+        'error:cache.operation_failed',
+    ]);
+    expect(output.every(({ name }) => name === '@jintianxiayu/cache-decorator')).toBe(true);
+    expect(output.every(({ traceId }) => traceId === 'cache-fixture-trace')).toBe(true);
+    expect(output.every(({ meta }) => !('traceId' in meta))).toBe(true);
+    expect(output[2]?.meta).toMatchObject({
+        event: 'cache.operation_failed',
+        cacheName: 'fixture-failure-users',
+        methodName: 'getUser',
+        providerName: 'failing',
+        operation: 'read',
+        error: {
+            name: 'Error',
+            message: 'redis unavailable',
+            password: '********',
+            email: 'pr***@example.com',
+        },
+    });
+});
+
+it('cache-operation-logging/Logger 配置筛选输出且复用应用提供的唯一 Logger runtime', async () => {
+    const result = await runFixture('error');
+    expect(result.code).toBe(0);
+    expect(result.stderr).toBe('');
+    const output = parseEvents(result.stdout);
+    expect(output).toHaveLength(1);
+    expect(output[0]).toMatchObject({
+        level: 'error',
+        name: '@jintianxiayu/cache-decorator',
+        traceId: 'cache-fixture-trace',
+        meta: { event: 'cache.operation_failed', operation: 'read' },
+    });
+});
+
+it('异步缓存写入和单 key 删除拒绝不会触发未处理 rejection', async () => {
+    const result = await runProviderFailureFixture();
+    expect(result.code).toBe(0);
+    expect(result.stderr).toBe('');
+});
+
+it('cache decorator 源码不读取或写入 LoggerContext', () => {
+    const sources = ['src/core/cache-logger.ts', 'src/decorators/cache.ts', 'src/decorators/cache-evict.ts']
+        .map((file) => readFileSync(join(packageRoot, file), 'utf8'))
+        .join('\n');
+    expect(sources).not.toContain('LoggerContext');
+});

package/test/cache-logger.test.ts

@@ -1,153 +1,156 @@
-import type { LoggerInterface } from '@jintianxiayu/logger';
-
-type CacheLoggerModule = typeof import('../src/core/cache-logger');
-
-interface CacheLoggerHarness {
-    readonly cacheLogger: CacheLoggerModule;
-    readonly getLogger: jest.Mock<LoggerInterface, [string]>;
-    readonly logger: jest.Mocked<LoggerInterface>;
-}
-
-const logContext = {
-    cacheName: 'users',
-    methodName: 'findUser',
-    providerName: 'default',
-} as const;
-
-function createMockLogger(): jest.Mocked<LoggerInterface> {
-    return {
-        debug: jest.fn(),
-        info: jest.fn(),
-        warn: jest.fn(),
-        error: jest.fn(),
-    };
-}
-
-/**
- * 为每个用例重新加载 cache Logger 模块，隔离模块级 Logger 缓存并允许注入获取失败。
- * @param getLoggerImplementation 可选的 LoggerFactory.getLogger 替代实现。
- * @returns 独立模块、Logger 获取 mock 和四个 level 方法 mock。
- * @throws 隔离模块未能同步加载时抛出。
- */
-function loadCacheLogger(getLoggerImplementation?: (name: string) => LoggerInterface): CacheLoggerHarness {
-    jest.resetModules();
-    const logger = createMockLogger();
-    const getLogger = jest.fn<LoggerInterface, [string]>(getLoggerImplementation ?? (() => logger));
-    jest.doMock('@jintianxiayu/logger', () => ({ LoggerFactory: { getLogger } }));
-    let cacheLogger: CacheLoggerModule | undefined;
-    jest.isolateModules(() => {
-        cacheLogger = jest.requireActual<CacheLoggerModule>('../src/core/cache-logger');
-    });
-    if (!cacheLogger) {
-        throw new Error('Cache logger module was not loaded');
-    }
-    return { cacheLogger, getLogger, logger };
-}
-
-afterEach(() => {
-    jest.resetModules();
-    jest.dontMock('@jintianxiayu/logger');
-});
-
-it('cache-operation-logging/L01 导入和 decorator 求值不初始化 Logger', () => {
-    const { getLogger } = loadCacheLogger();
-    const { Cache } = jest.requireActual<typeof import('../src/decorators/cache')>('../src/decorators/cache');
-    const { CacheEvict } = jest.requireActual<typeof import('../src/decorators/cache-evict')>(
-        '../src/decorators/cache-evict'
-    );
-
-    Cache('users');
-    CacheEvict('users');
-
-    expect(getLogger).not.toHaveBeenCalled();
-});
-
-it('cache-operation-logging/L02 首次运行期事件获取并复用应用命名 Logger', () => {
-    const { cacheLogger, getLogger, logger } = loadCacheLogger();
-
-    cacheLogger.logCacheEvent('cache.miss', logContext);
-    cacheLogger.logCacheEvent('cache.hit', { ...logContext, entryType: 'value' });
-
-    expect(getLogger).toHaveBeenCalledTimes(1);
-    expect(getLogger).toHaveBeenCalledWith('@jintianxiayu/cache-decorator');
-    expect(logger.debug).toHaveBeenCalledTimes(2);
-});
-
-it('cache-operation-logging/正常缓存决策使用 debug', () => {
-    const { cacheLogger, logger } = loadCacheLogger();
-    const events = [
-        'cache.pending_hit',
-        'cache.hit',
-        'cache.miss',
-        'cache.write_dispatched',
-        'cache.evict_dispatched',
-        'cache.evict_completed',
-    ] as const;
-
-    for (const event of events) {
-        cacheLogger.logCacheEvent(event, logContext);
-    }
-
-    expect(logger.debug).toHaveBeenCalledTimes(events.length);
-    expect(logger.debug.mock.calls.map((call) => (call[1] as { event: string }).event)).toEqual(events);
-    expect(logger.info).not.toHaveBeenCalled();
-    expect(logger.warn).not.toHaveBeenCalled();
-    expect(logger.error).not.toHaveBeenCalled();
-});
-
-it('cache-operation-logging/可恢复回退与淘汰跳过使用 warn', () => {
-    const { cacheLogger, logger } = loadCacheLogger();
-
-    cacheLogger.logCacheEvent('cache.key_fallback', { ...logContext, reason: 'resolver_error' });
-    cacheLogger.logCacheEvent('cache.evict_skipped', { ...logContext, reason: 'business_error' });
-
-    expect(logger.warn).toHaveBeenCalledTimes(2);
-    expect(logger.warn.mock.calls.map((call) => (call[1] as { event: string }).event)).toEqual([
-        'cache.key_fallback',
-        'cache.evict_skipped',
-    ]);
-    expect(logger.debug).not.toHaveBeenCalled();
-    expect(logger.info).not.toHaveBeenCalled();
-    expect(logger.error).not.toHaveBeenCalled();
-});
-
-it('cache-operation-logging/缓存基础设施失败使用 error', () => {
-    const { cacheLogger, logger } = loadCacheLogger();
-    const providerError = new Error('redis unavailable');
-
-    cacheLogger.logCacheEvent('cache.operation_failed', {
-        ...logContext,
-        operation: 'read',
-        error: providerError,
-    });
-
-    expect(logger.error).toHaveBeenCalledWith(
-        'Cache operation failed',
-        expect.objectContaining({ event: 'cache.operation_failed', operation: 'read', error: providerError })
-    );
-    expect(logger.debug).not.toHaveBeenCalled();
-    expect(logger.info).not.toHaveBeenCalled();
-    expect(logger.warn).not.toHaveBeenCalled();
-});
-
-it('Logger 获取或写入同步失败时不向缓存调用方抛出', () => {
-    const getLoggerError = new Error('invalid logger config');
-    const failedGet = loadCacheLogger(() => {
-        throw getLoggerError;
-    });
-    expect(() => failedGet.cacheLogger.logCacheEvent('cache.miss', logContext)).not.toThrow();
-
-    const failedWrite = loadCacheLogger();
-    failedWrite.logger.debug.mockImplementationOnce(() => {
-        throw new Error('transport failed');
-    });
-    expect(() => failedWrite.cacheLogger.logCacheEvent('cache.miss', logContext)).not.toThrow();
-});
-
-it('Provider 日志标签将缺省和空名称稳定映射为 default', () => {
-    const { cacheLogger } = loadCacheLogger();
-
-    expect(cacheLogger.cacheProviderLabel(undefined)).toBe('default');
-    expect(cacheLogger.cacheProviderLabel('')).toBe('default');
-    expect(cacheLogger.cacheProviderLabel('redis-primary')).toBe('redis-primary');
-});
+import type { LoggerInterface } from '@jintianxiayu/logger';
+
+type CacheLoggerModule = typeof import('../src/core/cache-logger');
+
+interface CacheLoggerHarness {
+    readonly cacheLogger: CacheLoggerModule;
+    readonly getLogger: jest.Mock<LoggerInterface, [string]>;
+    readonly logger: jest.Mocked<LoggerInterface>;
+}
+
+const logContext = {
+    cacheName: 'users',
+    methodName: 'findUser',
+    providerName: 'default',
+} as const;
+
+function createMockLogger(): jest.Mocked<LoggerInterface> {
+    return {
+        debug: jest.fn(),
+        info: jest.fn(),
+        warn: jest.fn(),
+        error: jest.fn(),
+    };
+}
+
+/**
+ * 为每个用例重新加载 cache Logger 模块，隔离模块级 Logger 缓存并允许注入获取失败。
+ * @param getLoggerImplementation 可选的 LoggerFactory.getLogger 替代实现。
+ * @returns 独立模块、Logger 获取 mock 和四个 level 方法 mock。
+ * @throws 隔离模块未能同步加载时抛出。
+ */
+function loadCacheLogger(getLoggerImplementation?: (name: string) => LoggerInterface): CacheLoggerHarness {
+    jest.resetModules();
+    const logger = createMockLogger();
+    const getLogger = jest.fn<LoggerInterface, [string]>(getLoggerImplementation ?? (() => logger));
+    jest.doMock('@jintianxiayu/logger', () => ({ LoggerFactory: { getLogger } }));
+    let cacheLogger: CacheLoggerModule | undefined;
+    jest.isolateModules(() => {
+        cacheLogger = jest.requireActual<CacheLoggerModule>('../src/core/cache-logger');
+    });
+    if (!cacheLogger) {
+        throw new Error('Cache logger module was not loaded');
+    }
+    return { cacheLogger, getLogger, logger };
+}
+
+afterEach(() => {
+    jest.resetModules();
+    jest.dontMock('@jintianxiayu/logger');
+});
+
+it('cache-operation-logging/L01 导入和 decorator 求值不初始化 Logger', () => {
+    const { getLogger } = loadCacheLogger();
+    const { Cache } = jest.requireActual<typeof import('../src/decorators/cache')>('../src/decorators/cache');
+    const { CacheEvict } = jest.requireActual<typeof import('../src/decorators/cache-evict')>(
+        '../src/decorators/cache-evict'
+    );
+
+    Cache('users');
+    CacheEvict('users');
+
+    expect(getLogger).not.toHaveBeenCalled();
+});
+
+it('cache-operation-logging/L02 首次运行期事件获取并复用应用命名 Logger', () => {
+    const { cacheLogger, getLogger, logger } = loadCacheLogger();
+
+    cacheLogger.logCacheEvent('cache.miss', logContext);
+    cacheLogger.logCacheEvent('cache.hit', { ...logContext, entryType: 'value' });
+
+    expect(getLogger).toHaveBeenCalledTimes(1);
+    expect(getLogger).toHaveBeenCalledWith('@jintianxiayu/cache-decorator');
+    expect(logger.debug).toHaveBeenCalledTimes(2);
+});
+
+it('cache-operation-logging/正常缓存决策使用 debug', () => {
+    const { cacheLogger, logger } = loadCacheLogger();
+    const events = [
+        'cache.pending_hit',
+        'cache.hit',
+        'cache.miss',
+        'cache.write_dispatched',
+        'cache.error_cache_skipped',
+        'cache.evict_dispatched',
+        'cache.evict_completed',
+    ] as const;
+
+    for (const event of events) {
+        cacheLogger.logCacheEvent(event, logContext);
+    }
+
+    expect(logger.debug).toHaveBeenCalledTimes(events.length);
+    expect(logger.debug.mock.calls.map((call) => (call[1] as { event: string }).event)).toEqual(events);
+    expect(logger.info).not.toHaveBeenCalled();
+    expect(logger.warn).not.toHaveBeenCalled();
+    expect(logger.error).not.toHaveBeenCalled();
+});
+
+it('cache-operation-logging/可恢复回退与淘汰跳过使用 warn', () => {
+    const { cacheLogger, logger } = loadCacheLogger();
+
+    cacheLogger.logCacheEvent('cache.key_fallback', { ...logContext, reason: 'resolver_error' });
+    cacheLogger.logCacheEvent('cache.error_cache_failed', { ...logContext, phase: 'encode' });
+    cacheLogger.logCacheEvent('cache.evict_skipped', { ...logContext, reason: 'business_error' });
+
+    expect(logger.warn).toHaveBeenCalledTimes(3);
+    expect(logger.warn.mock.calls.map((call) => (call[1] as { event: string }).event)).toEqual([
+        'cache.key_fallback',
+        'cache.error_cache_failed',
+        'cache.evict_skipped',
+    ]);
+    expect(logger.debug).not.toHaveBeenCalled();
+    expect(logger.info).not.toHaveBeenCalled();
+    expect(logger.error).not.toHaveBeenCalled();
+});
+
+it('cache-operation-logging/缓存基础设施失败使用 error', () => {
+    const { cacheLogger, logger } = loadCacheLogger();
+    const providerError = new Error('redis unavailable');
+
+    cacheLogger.logCacheEvent('cache.operation_failed', {
+        ...logContext,
+        operation: 'read',
+        error: providerError,
+    });
+
+    expect(logger.error).toHaveBeenCalledWith(
+        'Cache operation failed',
+        expect.objectContaining({ event: 'cache.operation_failed', operation: 'read', error: providerError })
+    );
+    expect(logger.debug).not.toHaveBeenCalled();
+    expect(logger.info).not.toHaveBeenCalled();
+    expect(logger.warn).not.toHaveBeenCalled();
+});
+
+it('Logger 获取或写入同步失败时不向缓存调用方抛出', () => {
+    const getLoggerError = new Error('invalid logger config');
+    const failedGet = loadCacheLogger(() => {
+        throw getLoggerError;
+    });
+    expect(() => failedGet.cacheLogger.logCacheEvent('cache.miss', logContext)).not.toThrow();
+
+    const failedWrite = loadCacheLogger();
+    failedWrite.logger.debug.mockImplementationOnce(() => {
+        throw new Error('transport failed');
+    });
+    expect(() => failedWrite.cacheLogger.logCacheEvent('cache.miss', logContext)).not.toThrow();
+});
+
+it('Provider 日志标签将缺省和空名称稳定映射为 default', () => {
+    const { cacheLogger } = loadCacheLogger();
+
+    expect(cacheLogger.cacheProviderLabel(undefined)).toBe('default');
+    expect(cacheLogger.cacheProviderLabel('')).toBe('default');
+    expect(cacheLogger.cacheProviderLabel('redis-primary')).toBe('redis-primary');
+});