@jintianxiayu/cache-decorator 0.1.2 → 1.0.0

package/test/helpers/package-consumer.ts

@@ -0,0 +1,231 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+
+export const packageRoot = resolve(__dirname, '../..');
+
+/**
+ * 从 README 指定小节提取第一个 TypeScript 示例，使文档参与真实消费项目编译。
+ * @param section README 的三级标题文本。
+ * @param headingLevel 小节使用的二级或三级标题层级。
+ * @returns 标题下第一个 TypeScript 代码块。
+ * @throws 标题或代码块不存在时抛出。
+ */
+export function readReadmeExample(section: string, headingLevel: 2 | 3 = 3): string {
+    const readme = readFileSync(join(packageRoot, 'README.md'), 'utf8').replaceAll('\r\n', '\n');
+    const heading = `${'#'.repeat(headingLevel)} ${section}\n`;
+    const sectionStart = readme.indexOf(heading);
+    if (sectionStart < 0) {
+        throw new Error(`Missing README section: ${section}`);
+    }
+    const sectionEnd = readme.indexOf('\n##', sectionStart + heading.length);
+    const content = readme.slice(sectionStart, sectionEnd < 0 ? undefined : sectionEnd);
+    const example = /```typescript\n([\s\S]*?)\n```/.exec(content)?.[1];
+    if (!example) {
+        throw new Error(`Missing TypeScript example in README section: ${section}`);
+    }
+    return example;
+}
+
+/** 临时消费项目的已安装产物；所有路径均位于当前测试拥有的临时目录。 */
+export interface PackageConsumer {
+    readonly directory: string;
+    readonly installedPackage: string;
+    readonly dependencyTree: string;
+}
+
+/**
+ * 用结构化参数运行子进程，并清除可能让临时项目继承 workspace 依赖的环境变量。
+ * @param request 可执行文件、参数及工作目录。
+ * @returns 标准输出。
+ * @throws 子进程失败、超时或无法启动时抛出带输出的错误。
+ */
+export function runCommand(request: {
+    readonly executable: string;
+    readonly args: string[];
+    readonly cwd: string;
+}): string {
+    const environment = { ...process.env };
+    delete environment.NODE_PATH;
+    delete environment.INIT_CWD;
+    delete environment.PNPM_WORKSPACE_DIR;
+    const result = spawnSync(request.executable, request.args, {
+        cwd: request.cwd,
+        env: environment,
+        encoding: 'utf8',
+        timeout: 120000,
+        windowsHide: true,
+        maxBuffer: 8 * 1024 * 1024,
+    });
+    if (result.error || result.status !== 0) {
+        throw new Error(
+            `${request.executable} failed: ${result.error?.message ?? result.status}\n${result.stdout}\n${result.stderr}`
+        );
+    }
+    return result.stdout;
+}
+
+/** 使用生命周期提供的 pnpm 路径；Windows 独立 Jest 运行兼容 Node 安装目录中的 pnpm。 */
+function runPnpm(args: string[], cwd: string): string {
+    const candidates = [
+        process.env.npm_execpath,
+        join(dirname(process.execPath), 'node_modules/pnpm/bin/pnpm.mjs'),
+        join(dirname(process.execPath), 'node_modules/pnpm/bin/pnpm.cjs'),
+    ];
+    const executable = candidates.find((candidate) => candidate && existsSync(candidate));
+    if (!executable) {
+        throw new Error('Run package consumer tests with pnpm test');
+    }
+    const isScript = ['.mjs', '.cjs', '.js'].some((extension) => executable.endsWith(extension));
+    return runCommand({
+        executable: isScript ? process.execPath : executable,
+        args: isScript ? [executable, ...args] : args,
+        cwd,
+    });
+}
+
+/**
+ * 创建与 workspace 不相交的临时测试根目录。
+ * @returns 位于系统临时目录且带专用前缀的目录。
+ */
+export function createPackageTestRoot(): string {
+    return mkdtempSync(join(tmpdir(), 'cache-consumer-'));
+}
+
+/**
+ * 构建并打包当前 cache-decorator 包。
+ * @param root 本次测试拥有的临时根目录。
+ * @returns 这次测试使用的 tarball 绝对路径。
+ * @throws 构建或打包失败时抛出。
+ */
+export function packCurrentPackage(root: string): string {
+    runCommand({
+        executable: process.execPath,
+        args: [require.resolve('typescript/bin/tsc'), '-p', join(packageRoot, 'tsconfig.json')],
+        cwd: packageRoot,
+    });
+    const archive = join(root, 'cache-decorator.tgz');
+    runPnpm(['pack', '--out', archive, '--json'], packageRoot);
+    return archive;
+}
+
+/**
+ * 构建并打包当前 workspace Logger，供外部消费 fixture 显式满足 required peer。
+ * @param root 本次测试拥有的临时根目录。
+ * @returns 这次测试使用的 Logger tarball 绝对路径。
+ * @throws 构建或打包失败时抛出。
+ */
+export function packLoggerPackage(root: string): string {
+    const loggerRoot = resolve(packageRoot, '../logger');
+    runCommand({
+        executable: process.execPath,
+        args: [require.resolve('typescript/bin/tsc'), '-p', join(loggerRoot, 'tsconfig.json')],
+        cwd: loggerRoot,
+    });
+    const archive = join(root, 'logger.tgz');
+    runPnpm(['pack', '--out', archive, '--json'], loggerRoot);
+    return archive;
+}
+
+/** 读取当前 workspace 已安装版本，避免消费测试解析无关的新版本。 */
+function installedVersion(name: string): string {
+    const localManifest = join(packageRoot, 'node_modules', name, 'package.json');
+    const manifestPath = existsSync(localManifest) ? localManifest : require.resolve(`${name}/package.json`);
+    const manifest: { readonly version: string } = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    return manifest.version;
+}
+
+/**
+ * 安装真实 tarball 和唯一指定的 Redis 客户端，严格编译并运行消费用法。
+ * @param request 临时根、归档、客户端名称及消费源码。
+ * @returns 可审计的安装路径及生产依赖树。
+ * @throws 安装、严格类型检查或运行失败时抛出。
+ */
+export function installConsumer(request: {
+    readonly root: string;
+    readonly archive: string;
+    readonly loggerArchive: string;
+    readonly client: 'none' | 'redis' | 'ioredis';
+    readonly source: string;
+    readonly readmeSource: string;
+    readonly quickStartSource: string;
+}): PackageConsumer {
+    const directory = join(request.root, request.client);
+    mkdirSync(directory);
+    const dependencies: Record<string, string> = {
+        '@jintianxiayu/cache-decorator': `file:${request.archive.replaceAll('\\', '/')}`,
+        '@jintianxiayu/logger': `file:${request.loggerArchive.replaceAll('\\', '/')}`,
+        'reflect-metadata': installedVersion('reflect-metadata'),
+    };
+    if (request.client !== 'none') {
+        dependencies[request.client] = installedVersion(request.client);
+    }
+    writeFileSync(
+        join(directory, 'package.json'),
+        JSON.stringify({
+            name: `cache-consumer-${request.client}`,
+            private: true,
+            dependencies,
+            devDependencies: {
+                typescript: installedVersion('typescript'),
+                '@types/node': installedVersion('@types/node'),
+            },
+        })
+    );
+    writeFileSync(
+        join(directory, 'tsconfig.json'),
+        JSON.stringify({
+            compilerOptions: {
+                strict: true,
+                skipLibCheck: false,
+                target: 'ES2021',
+                module: 'NodeNext',
+                moduleResolution: 'NodeNext',
+                types: ['node'],
+                outDir: 'out',
+                experimentalDecorators: true,
+                emitDecoratorMetadata: true,
+            },
+            include: ['consumer.ts', 'readme-example.ts', 'quick-start.ts'],
+        })
+    );
+    writeFileSync(join(directory, 'consumer.ts'), request.source);
+    writeFileSync(join(directory, 'readme-example.ts'), request.readmeSource);
+    writeFileSync(join(directory, 'quick-start.ts'), request.quickStartSource);
+    runPnpm(
+        [
+            'install',
+            '--ignore-scripts',
+            '--store-dir',
+            join(request.root, 'store'),
+            '--config.auto-install-peers=false',
+        ],
+        directory
+    );
+    runCommand({
+        executable: process.execPath,
+        args: [join(directory, 'node_modules/typescript/bin/tsc'), '-p', directory],
+        cwd: directory,
+    });
+    runCommand({ executable: process.execPath, args: [join(directory, 'out/consumer.js')], cwd: directory });
+    return {
+        directory,
+        installedPackage: join(directory, 'node_modules/@jintianxiayu/cache-decorator'),
+        dependencyTree: runPnpm(['list', '--prod', '--depth', '100', '--json'], directory),
+    };
+}
+
+/**
+ * 仅删除本测试通过 mkdtemp 创建且已确认位于系统临时目录内的目录。
+ * @param root 待删除的测试临时根目录。
+ * @returns 删除完成后返回。
+ * @throws 目标不在系统临时目录或前缀不匹配时拒绝删除。
+ */
+export function removePackageTestRoot(root: string): void {
+    const absolute = resolve(root);
+    if (!absolute.startsWith(resolve(tmpdir()) + sep) || !basename(absolute).startsWith('cache-consumer-')) {
+        throw new Error('Refusing to remove a path outside the package test temporary root');
+    }
+    rmSync(absolute, { recursive: true, force: true, maxRetries: 3 });
+}

package/test/helpers/redis-fixture.ts

@@ -0,0 +1,142 @@
+import { randomUUID } from 'node:crypto';
+import Redis from 'ioredis';
+import { createClient } from 'redis';
+
+/** 由测试持有的两种真实 Redis 连接及其精确清理范围。 */
+export interface RedisFixture {
+    readonly io: Redis;
+    readonly node: ReturnType<typeof createClient>;
+    readonly database: number;
+    readonly errors: Error[];
+
+    /**
+     * 分配只属于本夹具的唯一物理 key。
+     * @returns 已登记且可由 close 精确清理的 key。
+     */
+    key(): string;
+
+    /**
+     * 登记由本夹具唯一 key 派生的物理 key，供 close 精确清理。
+     * @param key 必须位于 cache-decorator-test 测试命名空间内的物理 key。
+     * @returns 原 key，便于测试在构造数据时直接使用。
+     * @throws key 不属于测试命名空间时拒绝，避免误删外部数据。
+     */
+    track(key: string): string;
+
+    /**
+     * 清理本夹具登记的 key，并关闭本夹具创建的两个连接。
+     * @returns 清理与关闭完成后结束；重复调用保持幂等。
+     * @throws Redis 清理命令失败时传播原始错误，但仍回收连接。
+     */
+    close(): Promise<void>;
+}
+
+function selectedDatabase(url: string): number {
+    const pathname = new URL(url).pathname;
+    if (pathname === '' || pathname === '/') {
+        return 0;
+    }
+    const databaseText = pathname.slice(1);
+    const database = Number(databaseText);
+    if (!Number.isSafeInteger(database) || database < 0 || String(database) !== databaseText) {
+        throw new Error('CACHE_DECORATOR_TEST_REDIS_URL must select a valid Redis database number');
+    }
+    return database;
+}
+
+async function createFixture(url: string, database: number): Promise<RedisFixture> {
+    const errors: Error[] = [];
+    const keys = new Set<string>();
+    let closed = false;
+    const io = new Redis(url, {
+        lazyConnect: true,
+        enableOfflineQueue: false,
+        connectTimeout: 1000,
+        commandTimeout: 1000,
+        maxRetriesPerRequest: 0,
+        retryStrategy: (): null => null,
+    });
+    const node = createClient({
+        url,
+        disableOfflineQueue: true,
+        socket: { connectTimeout: 1000, reconnectStrategy: false },
+    });
+    io.on('error', (error: Error) => errors.push(error));
+    node.on('error', (error: Error) => errors.push(error));
+    try {
+        await Promise.all([io.connect(), node.connect()]);
+    } catch (error) {
+        io.disconnect();
+        if (node.isOpen) {
+            node.destroy();
+        }
+        throw error;
+    }
+    return {
+        io,
+        node,
+        database,
+        errors,
+        /** @inheritdoc */
+        key(): string {
+            const key = `cache-decorator-test:${randomUUID()}`;
+            keys.add(key);
+            return key;
+        },
+        /** @inheritdoc */
+        track(key: string): string {
+            if (!key.startsWith('cache-decorator-test:')) {
+                throw new Error('Redis fixture can only track cache-decorator-test keys');
+            }
+            keys.add(key);
+            return key;
+        },
+        /** @inheritdoc */
+        async close(): Promise<void> {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            try {
+                if (keys.size > 0 && node.isReady) {
+                    await node.del([...keys]);
+                } else if (keys.size > 0 && io.status === 'ready') {
+                    await io.del(...keys);
+                }
+            } finally {
+                if (io.status !== 'end') {
+                    io.disconnect();
+                }
+                if (node.isOpen) {
+                    node.destroy();
+                }
+            }
+        },
+    };
+}
+
+/**
+ * 从显式测试 URL 创建两个真实客户端，不回退到默认地址或业务连接。
+ * @param url `CACHE_DECORATOR_TEST_REDIS_URL` 提供的专用 Redis 地址。
+ * @returns 已完成连接且由测试负责 close 的双客户端夹具。
+ * @throws URL、连接或后续清理失败时传播错误。
+ */
+export async function createRedisFixture(url: string): Promise<RedisFixture> {
+    return createFixture(url, selectedDatabase(url));
+}
+
+/**
+ * 为会执行 FLUSHDB 的场景创建显式非零数据库夹具。
+ * @param url `CACHE_DECORATOR_TEST_REDIS_URL` 提供且路径包含非零数据库号的地址。
+ * @returns 已连接到明确隔离数据库的双客户端夹具。
+ * @throws URL 未显式选择非零数据库时拒绝，避免清理共享或默认数据库。
+ */
+export async function createIsolatedDatabaseRedisFixture(url: string): Promise<RedisFixture> {
+    const database = selectedDatabase(url);
+    if (database === 0) {
+        throw new Error(
+            'Database-level cache tests require CACHE_DECORATOR_TEST_REDIS_URL to select a non-zero database'
+        );
+    }
+    return createFixture(url, database);
+}

package/test/ioredis-cache-client.test.ts

@@ -0,0 +1,143 @@
+import { createIoredisCacheClient } from '../src/adapters/ioredis-cache-client';
+import { IoredisCacheClientSource } from '../src/core/redis-cache-client';
+
+function createSource(keyPrefix?: string): jest.Mocked<IoredisCacheClientSource> {
+    const source = {
+        options: Object.freeze({ keyPrefix }),
+        get: jest.fn<Promise<unknown>, Parameters<IoredisCacheClientSource['get']>>(),
+        set: jest.fn<Promise<unknown>, Parameters<IoredisCacheClientSource['set']>>(),
+        setex: jest.fn<Promise<unknown>, Parameters<IoredisCacheClientSource['setex']>>(),
+        del: jest.fn<Promise<unknown>, Parameters<IoredisCacheClientSource['del']>>(),
+        scan: jest.fn<Promise<unknown>, Parameters<IoredisCacheClientSource['scan']>>(),
+        flushdb: jest.fn<Promise<unknown>, Parameters<IoredisCacheClientSource['flushdb']>>(),
+    } satisfies jest.Mocked<IoredisCacheClientSource>;
+    return source;
+}
+
+it('redis-cache-client/A01 ioredis 无 TTL 写入成功', async () => {
+    const source = createSource();
+    const client = createIoredisCacheClient(source);
+    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(request.key, request.value);
+    expect(source.setex).not.toHaveBeenCalled();
+});
+
+it('redis-cache-client/A02 ioredis 带 TTL 写入成功', async () => {
+    const source = createSource();
+    const client = createIoredisCacheClient(source);
+    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(request.key, request.ttlSeconds, request.value);
+    expect(source.set).not.toHaveBeenCalled();
+});
+
+it('redis-cache-client/A05 GET 响应规范化', async () => {
+    const source = createSource();
+    const client = createIoredisCacheClient(source);
+    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, 'present');
+    expect(source.get).toHaveBeenNthCalledWith(2, 'missing');
+});
+
+it('redis-cache-client/A06 删除和清库响应规范化', async () => {
+    const source = createSource();
+    const client = createIoredisCacheClient(source);
+    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, 'first', 'second');
+    expect(source.del).toHaveBeenNthCalledWith(2, 'missing');
+    expect(source.flushdb).toHaveBeenCalledTimes(1);
+});
+
+it('redis-cache-client/A07 调用上下文与请求保持不变', async () => {
+    const source = createSource('scope:');
+    const client = createIoredisCacheClient(source);
+    source.set.mockImplementation(function (this: IoredisCacheClientSource): Promise<unknown> {
+        expect(this).toBe(source);
+        return Promise.resolve('OK');
+    });
+    source.del.mockImplementation(function (this: IoredisCacheClientSource): Promise<unknown> {
+        expect(this).toBe(source);
+        return Promise.resolve(2);
+    });
+    source.scan.mockImplementation(function (this: IoredisCacheClientSource): Promise<unknown> {
+        expect(this).toBe(source);
+        return Promise.resolve(['0', ['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(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 = createIoredisCacheClient(source);
+    source.get.mockResolvedValue(false);
+    source.set.mockResolvedValue(null);
+    source.setex.mockResolvedValue(Buffer.from('OK'));
+    source.del.mockResolvedValue(-1);
+    source.scan.mockResolvedValue({ cursor: '0', keys: [] });
+    source.flushdb.mockResolvedValue('PONG');
+
+    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/F05 ioredis keyPrefix 下删除逻辑 pattern', async () => {
+    const source = createSource('cache:');
+    const client = createIoredisCacheClient(source);
+    source.scan.mockResolvedValue(['0', ['cache:name:1', 'cache:name:2']]);
+    source.del.mockResolvedValue(2);
+
+    const page = await client.scan({ cursor: '0', pattern: 'name*', count: 100 });
+    await client.deleteMany(page.keys);
+
+    expect(source.scan).toHaveBeenCalledWith('0', 'MATCH', 'cache:name*', 'COUNT', 100);
+    expect(page).toEqual({ cursor: '0', keys: ['name:1', 'name:2'] });
+    expect(source.del).toHaveBeenCalledWith('name:1', 'name:2');
+});
+
+it('cache-evict-allentries-prefix/F06 ioredis 特殊字符 keyPrefix 被按字面量匹配', async () => {
+    const keyPrefix = 'scope\\*?[]:';
+    const source = createSource(keyPrefix);
+    const client = createIoredisCacheClient(source);
+    source.scan.mockResolvedValue(['0', [`${keyPrefix}name:1`]]);
+    const expectedPattern = ['scope', '\\\\', '\\*', '\\?', '\\[', '\\]', ':name*'].join('');
+
+    await expect(client.scan({ cursor: '0', pattern: 'name*', count: 100 })).resolves.toEqual({
+        cursor: '0',
+        keys: ['name:1'],
+    });
+
+    expect(source.scan).toHaveBeenCalledWith('0', 'MATCH', expectedPattern, 'COUNT', 100);
+});

package/test/key-builder.test.ts

@@ -1,37 +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');
-    });
+    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('应生成包含参数值的 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', [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('应处理对象参数', () => {
+            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('应处理 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');
+        it('应处理数字和布尔值', () => {
+            const key = KeyBuilder.build('user-cache', [123, true, false]);
+            expect(key).toBe('user-cache:123&true&false');
+        });
     });
-  });
-});
+});