@jintianxiayu/cache-decorator 0.1.3 → 1.0.0

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

@@ -0,0 +1,328 @@
+import { readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import {
+    createPackageTestRoot,
+    installConsumer,
+    PackageConsumer,
+    packCurrentPackage,
+    packLoggerPackage,
+    packageRoot,
+    readReadmeExample,
+    removePackageTestRoot,
+    runCommand,
+} from './helpers/package-consumer';
+
+jest.setTimeout(180000);
+
+const sources = {
+    none: `
+        import assert from 'node:assert/strict';
+        import { LoggerFactory } from '@jintianxiayu/logger';
+        import {
+            Cache, CacheProviderRegistry, MemoryCacheProvider, RedisCacheProvider, createIoredisCacheClient,
+            createNodeRedisCacheClient, type CacheProvider, type RedisCacheClient,
+            type IoredisCacheClientSource, type NodeRedisCacheClientSource, type NodeRedisCacheClientOptions,
+        } from '@jintianxiayu/cache-decorator';
+        const values = new Map<string, string>();
+        const client: RedisCacheClient = {
+            get: async (key) => values.get(key) ?? null,
+            set: async ({ key, value }) => { values.set(key, value); },
+            deleteMany: async (keys) => { for (const key of keys) { values.delete(key); } },
+            scan: async () => ({ cursor: '0', keys: [...values.keys()] }),
+            flushDatabase: async () => { values.clear(); },
+        };
+        const custom: CacheProvider = {
+            get: async () => undefined, set: async () => undefined, delete: async () => undefined,
+            clear: async () => undefined, deleteByPattern: async () => undefined,
+        };
+        export type Sources = IoredisCacheClientSource | NodeRedisCacheClientSource;
+        export type Options = NodeRedisCacheClientOptions;
+        async function main(): Promise<void> {
+            LoggerFactory.init({
+                root: { console: { enabled: false }, file: { enabled: false } },
+                processErrors: { uncaughtException: false, unhandledRejection: false, exitOnError: false },
+            });
+            try {
+                assert.equal(typeof createIoredisCacheClient, 'function');
+                assert.equal(typeof createNodeRedisCacheClient, 'function');
+                const memory = new MemoryCacheProvider();
+                await memory.set('memory-key', { source: 'memory' });
+                assert.deepEqual(await memory.get('memory-key'), { source: 'memory' });
+                CacheProviderRegistry.register('memory', memory);
+                let calls = 0;
+                class Service {
+                    @Cache('external-memory', { providerName: 'memory' })
+                    getValue(id: number): { id: number } {
+                        calls += 1;
+                        return { id };
+                    }
+                }
+                const service = new Service();
+                assert.deepEqual(await service.getValue(1), { id: 1 });
+                assert.deepEqual(await service.getValue(1), { id: 1 });
+                assert.equal(calls, 1);
+
+                const redis = new RedisCacheProvider(client);
+                await redis.set('redis-key', { source: 'custom-client' });
+                assert.deepEqual(await redis.get('redis-key'), { source: 'custom-client' });
+                CacheProviderRegistry.register('custom', custom);
+                CacheProviderRegistry.setDefault('custom');
+                assert.equal(await CacheProviderRegistry.get().get('key'), undefined);
+            } finally {
+                CacheProviderRegistry.clear();
+                await LoggerFactory.shutdown({ timeout: 2_000 });
+            }
+        }
+        main().catch((error: unknown) => { console.error(error); process.exitCode = 1; });
+    `,
+    redis: `
+        import assert from 'node:assert/strict';
+        import { randomUUID } from 'node:crypto';
+        import { createClient } from 'redis';
+        import { RedisCacheProvider, createNodeRedisCacheClient } from '@jintianxiayu/cache-decorator';
+        const redis = createClient();
+        const provider = new RedisCacheProvider(createNodeRedisCacheClient(redis));
+        assert.ok(provider instanceof RedisCacheProvider);
+        assert.equal(redis.isOpen, false);
+        async function runCache(): Promise<void> {
+            const url = process.env.CACHE_DECORATOR_TEST_REDIS_URL;
+            assert.ok(url);
+            const connection = createClient({
+                url, disableOfflineQueue: true, socket: { connectTimeout: 1000, reconnectStrategy: false },
+            });
+            const errors: Error[] = [];
+            connection.on('error', (error: Error) => errors.push(error));
+            const key = 'cache-consumer:' + randomUUID();
+            try {
+                await connection.connect();
+                const cache = new RedisCacheProvider(createNodeRedisCacheClient(connection));
+                await cache.set(key, { source: 'node-redis' }, 30);
+                assert.deepEqual(await cache.get(key), { source: 'node-redis' });
+                await cache.delete(key);
+                assert.equal(await cache.get(key), undefined);
+                assert.equal(await connection.ping(), 'PONG');
+                assert.deepEqual(errors, []);
+            } finally {
+                if (connection.isOpen) {
+                    try { await connection.del(key); }
+                    finally { connection.destroy(); }
+                }
+            }
+        }
+        if (process.argv[2] === 'cache') {
+            runCache().catch((error: unknown) => { console.error(error); process.exitCode = 1; });
+        }
+    `,
+    ioredis: `
+        import assert from 'node:assert/strict';
+        import { randomUUID } from 'node:crypto';
+        import Redis from 'ioredis';
+        import { RedisCacheProvider, createIoredisCacheClient } from '@jintianxiayu/cache-decorator';
+        const redis = new Redis({ lazyConnect: true });
+        const provider = new RedisCacheProvider(createIoredisCacheClient(redis));
+        assert.ok(provider instanceof RedisCacheProvider);
+        assert.equal(redis.status, 'wait');
+        async function runCache(): Promise<void> {
+            const url = process.env.CACHE_DECORATOR_TEST_REDIS_URL;
+            assert.ok(url);
+            const connection = new Redis(url, {
+                lazyConnect: true, enableOfflineQueue: false, connectTimeout: 1000, commandTimeout: 1000,
+                retryStrategy: () => null,
+            });
+            const errors: Error[] = [];
+            connection.on('error', (error: Error) => errors.push(error));
+            const key = 'cache-consumer:' + randomUUID();
+            try {
+                await connection.connect();
+                const cache = new RedisCacheProvider(createIoredisCacheClient(connection));
+                await cache.set(key, { source: 'ioredis' }, 30);
+                assert.deepEqual(await cache.get(key), { source: 'ioredis' });
+                await cache.delete(key);
+                assert.equal(await cache.get(key), undefined);
+                assert.equal(await connection.ping(), 'PONG');
+                assert.deepEqual(errors, []);
+            } finally {
+                try { if (connection.status === 'ready') { await connection.del(key); } }
+                finally { connection.disconnect(); }
+            }
+        }
+        if (process.argv[2] === 'cache') {
+            runCache().catch((error: unknown) => { console.error(error); process.exitCode = 1; });
+        }
+    `,
+};
+
+let root: string;
+let consumers: Record<'none' | 'redis' | 'ioredis', PackageConsumer>;
+
+/** 在干净 Node 子进程内检查依赖解析，避免 Jest 启动脚本的 NODE_PATH 干扰。 */
+function clientResolution(consumer: PackageConsumer): Record<string, string | null> {
+    return JSON.parse(
+        runCommand({
+            executable: process.execPath,
+            cwd: consumer.directory,
+            args: [
+                '-e',
+                `
+            const results = {};
+            for (const name of ['redis', 'ioredis']) {
+                try { results[name] = require.resolve(name); }
+                catch (error) {
+                    if (error.code !== 'MODULE_NOT_FOUND') { throw error; }
+                    results[name] = null;
+                }
+            }
+            process.stdout.write(JSON.stringify(results));
+        `,
+            ],
+        })
+    );
+}
+
+beforeAll(() => {
+    root = createPackageTestRoot();
+    const archive = packCurrentPackage(root);
+    const loggerArchive = packLoggerPackage(root);
+    consumers = {
+        none: installConsumer({
+            root,
+            archive,
+            loggerArchive,
+            client: 'none',
+            source: sources.none,
+            readmeSource: readReadmeExample('自定义 RedisCacheClient'),
+            quickStartSource: readReadmeExample('快速开始', 2),
+        }),
+        redis: installConsumer({
+            root,
+            archive,
+            loggerArchive,
+            client: 'redis',
+            source: sources.redis,
+            readmeSource: readReadmeExample('node-redis'),
+            quickStartSource: readReadmeExample('快速开始', 2),
+        }),
+        ioredis: installConsumer({
+            root,
+            archive,
+            loggerArchive,
+            client: 'ioredis',
+            source: sources.ioredis,
+            readmeSource: readReadmeExample('ioredis'),
+            quickStartSource: readReadmeExample('快速开始', 2),
+        }),
+    };
+});
+
+it('cache-operation-logging/P01 外部严格消费项目显式提供并共享唯一 Logger peer', () => {
+    for (const consumer of Object.values(consumers)) {
+        const requireFromConsumer = createRequire(join(consumer.directory, 'package.json'));
+        const requireFromCache = createRequire(join(consumer.installedPackage, 'package.json'));
+        expect(realpathSync(requireFromCache.resolve('@jintianxiayu/logger'))).toBe(
+            realpathSync(requireFromConsumer.resolve('@jintianxiayu/logger'))
+        );
+        expect(consumer.dependencyTree).toContain('"@jintianxiayu/logger"');
+        expect(consumer.dependencyTree).toContain('"reflect-metadata"');
+    }
+});
+
+it('cache-operation-logging/P02 发布 manifest 将 Logger workspace peer 转为实际 semver', () => {
+    const manifest = JSON.parse(readFileSync(join(consumers.none.installedPackage, 'package.json'), 'utf8')) as {
+        readonly dependencies?: Record<string, string>;
+        readonly peerDependencies?: Record<string, string>;
+    };
+    const loggerManifest = JSON.parse(readFileSync(join(packageRoot, '../logger/package.json'), 'utf8')) as {
+        readonly version: string;
+    };
+    expect(manifest.peerDependencies?.['@jintianxiayu/logger']).toBe(`^${loggerManifest.version}`);
+    expect(manifest.peerDependencies?.['@jintianxiayu/logger']).not.toContain('workspace:');
+    expect(manifest.dependencies?.['@jintianxiayu/logger']).toBeUndefined();
+});
+
+afterAll(() => {
+    if (root) {
+        removePackageTestRoot(root);
+    }
+});
+
+it('redis-cache-client/P01 不安装 Redis 客户端也能使用非 Redis Provider', () => {
+    const consumer = consumers.none;
+    expect(clientResolution(consumer)).toEqual({ ioredis: null, redis: null });
+    expect(consumer.dependencyTree).not.toContain('"ioredis":');
+    expect(consumer.dependencyTree).not.toContain('"redis":');
+});
+
+it('redis-cache-client/P02 仅安装 node-redis 的消费项目', () => {
+    const consumer = consumers.redis;
+    const resolution = clientResolution(consumer);
+    expect(resolution.redis?.startsWith(consumer.directory)).toBe(true);
+    expect(resolution.ioredis).toBeNull();
+    expect(consumer.dependencyTree).toContain('"redis":');
+    expect(consumer.dependencyTree).not.toContain('"ioredis":');
+});
+
+it('redis-cache-client/P03 仅安装 ioredis 的消费项目', () => {
+    const consumer = consumers.ioredis;
+    const resolution = clientResolution(consumer);
+    expect(resolution.ioredis?.startsWith(consumer.directory)).toBe(true);
+    expect(resolution.redis).toBeNull();
+    expect(consumer.dependencyTree).toContain('"ioredis":');
+    expect(consumer.dependencyTree).not.toContain('"redis":');
+});
+
+const redisTest = process.env.CACHE_DECORATOR_TEST_REDIS_URL ? it : it.skip;
+
+redisTest('redis-cache-client/P02 仅 node-redis 的消费项目执行真实缓存操作', () => {
+    const consumer = consumers.redis;
+    expect(
+        runCommand({
+            executable: process.execPath,
+            args: [join(consumer.directory, 'out/consumer.js'), 'cache'],
+            cwd: consumer.directory,
+        })
+    ).toBe('');
+});
+
+redisTest('redis-cache-client/P03 仅 ioredis 的消费项目执行真实缓存操作', () => {
+    const consumer = consumers.ioredis;
+    expect(
+        runCommand({
+            executable: process.execPath,
+            args: [join(consumer.directory, 'out/consumer.js'), 'cache'],
+            cwd: consumer.directory,
+        })
+    ).toBe('');
+});
+
+it('redis-cache-client/P04 公共入口与声明不泄漏第三方客户端', () => {
+    const consumer = consumers.none;
+    const requireFromConsumer = createRequire(join(consumer.directory, 'package.json'));
+    const api: Record<string, unknown> = requireFromConsumer('@jintianxiayu/cache-decorator');
+    expect(Object.keys(api).sort()).toEqual(
+        [
+            'Cache',
+            'CacheEvict',
+            'CacheProviderRegistry',
+            'KeyBuilder',
+            'MemoryCacheProvider',
+            'PendingCache',
+            'RedisCacheProvider',
+            'createIoredisCacheClient',
+            'createNodeRedisCacheClient',
+        ].sort()
+    );
+    const manifest = JSON.parse(readFileSync(join(consumer.installedPackage, 'package.json'), 'utf8'));
+    for (const field of ['dependencies', 'peerDependencies', 'optionalDependencies']) {
+        expect(manifest[field]?.ioredis).toBeUndefined();
+        expect(manifest[field]?.redis).toBeUndefined();
+    }
+    const dist = join(consumer.installedPackage, 'dist');
+    const externalClient = /(?:from\s*|require\s*\(\s*|import\s*\(\s*)['"](?:ioredis|redis)(?:\/|['"])/;
+    for (const entry of readdirSync(dist, { recursive: true })) {
+        const name = String(entry);
+        if (name.endsWith('.js') || name.endsWith('.d.ts')) {
+            expect(readFileSync(join(dist, name), 'utf8')).not.toMatch(externalClient);
+        }
+    }
+});

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

@@ -0,0 +1,269 @@
+import { RedisCacheClient } from '../src/core/redis-cache-client';
+import { RedisCacheProvider } from '../src/core/redis-cache';
+
+function createClient(): jest.Mocked<RedisCacheClient> {
+    const client = {
+        get: jest.fn<Promise<string | null>, Parameters<RedisCacheClient['get']>>(),
+        set: jest.fn<Promise<void>, Parameters<RedisCacheClient['set']>>(),
+        deleteMany: jest.fn<Promise<void>, Parameters<RedisCacheClient['deleteMany']>>(),
+        scan: jest.fn<ReturnType<RedisCacheClient['scan']>, Parameters<RedisCacheClient['scan']>>(),
+        flushDatabase: jest.fn<Promise<void>, Parameters<RedisCacheClient['flushDatabase']>>(),
+    } satisfies jest.Mocked<RedisCacheClient>;
+    client.get.mockResolvedValue(null);
+    client.set.mockResolvedValue(undefined);
+    client.deleteMany.mockResolvedValue(undefined);
+    client.scan.mockResolvedValue({ cursor: '0', keys: [] });
+    client.flushDatabase.mockResolvedValue(undefined);
+    return client;
+}
+
+function useStringStorage(client: jest.Mocked<RedisCacheClient>): Map<string, string> {
+    const values = new Map<string, string>();
+    client.set.mockImplementation(({ key, value }): Promise<void> => {
+        values.set(key, value);
+        return Promise.resolve();
+    });
+    client.get.mockImplementation((key): Promise<string | null> => Promise.resolve(values.get(key) ?? null));
+    return values;
+}
+
+it('redis-cache-client/V01 不存在的 key 返回 cache miss', async () => {
+    const client = createClient();
+    const provider = new RedisCacheProvider(client);
+
+    await expect(provider.get('missing')).resolves.toBeUndefined();
+
+    expect(client.get).toHaveBeenCalledWith('missing');
+    expect(client.set).not.toHaveBeenCalled();
+});
+
+it('redis-cache-client/V03 非 JSON 字符串和空字符串保持原值', async () => {
+    const client = createClient();
+    const values = useStringStorage(client);
+    const provider = new RedisCacheProvider(client);
+
+    await provider.set('plain', 'not-json');
+    await provider.set('empty', '');
+
+    expect(values).toEqual(
+        new Map([
+            ['plain', 'not-json'],
+            ['empty', ''],
+        ])
+    );
+    await expect(provider.get('plain')).resolves.toBe('not-json');
+    await expect(provider.get('empty')).resolves.toBe('');
+});
+
+it('redis-cache-client/V04 JSON 文本字符串沿用解析行为', async () => {
+    const client = createClient();
+    const values = useStringStorage(client);
+    const provider = new RedisCacheProvider(client);
+    const cases: ReadonlyArray<readonly [string, unknown]> = [
+        ['123', 123],
+        ['true', true],
+        ['null', null],
+        ['[1,2]', [1, 2]],
+        ['{"status":"open"}', { status: 'open' }],
+    ];
+
+    for (const [source, expected] of cases) {
+        await provider.set(source, source);
+        expect(values.get(source)).toBe(source);
+        await expect(provider.get(source)).resolves.toEqual(expected);
+    }
+});
+
+it('redis-cache-client/V06 缺省 TTL 与零 TTL 永不过期', async () => {
+    const client = createClient();
+    const provider = new RedisCacheProvider(client);
+
+    await provider.set('default-ttl', 'value');
+    await provider.set('zero-ttl', 'value', 0);
+
+    expect(client.set).toHaveBeenNthCalledWith(1, { key: 'default-ttl', value: 'value' });
+    expect(client.set).toHaveBeenNthCalledWith(2, { key: 'zero-ttl', value: 'value' });
+});
+
+it('redis-cache-client/V07 序列化失败不写入', async () => {
+    const client = createClient();
+    const provider = new RedisCacheProvider(client);
+    const cyclic: { self?: unknown } = {};
+    cyclic.self = cyclic;
+    const values: readonly unknown[] = [cyclic, undefined, (): void => undefined, Symbol('cache')];
+
+    for (const value of values) {
+        await expect(provider.set('key', value)).rejects.toThrow(TypeError);
+    }
+    expect(client.set).not.toHaveBeenCalled();
+});
+
+it('redis-cache-client/V08 key 边界不被 Provider 改写', async () => {
+    const client = createClient();
+    const provider = new RedisCacheProvider(client);
+    const keys = ['', '订单:缓存[*]?'];
+    client.get.mockResolvedValue('value');
+
+    for (const key of keys) {
+        await provider.set(key, 'value');
+        await provider.get(key);
+        await provider.delete(key);
+    }
+
+    expect(client.set.mock.calls.map(([request]) => request.key)).toEqual(keys);
+    expect(client.get.mock.calls.map(([key]) => key)).toEqual(keys);
+    expect(client.deleteMany.mock.calls.map(([deletedKeys]) => deletedKeys)).toEqual(keys.map((key) => [key]));
+});
+
+it('redis-cache-client/E01 读取异常不是 cache miss', async () => {
+    const client = createClient();
+    const provider = new RedisCacheProvider(client);
+    const error = new Error('GET unavailable');
+    client.get.mockRejectedValue(error);
+
+    await expect(provider.get('key')).rejects.toBe(error);
+    expect(client.set).not.toHaveBeenCalled();
+});
+
+it('redis-cache-client/E02 写入异常传播', async () => {
+    const client = createClient();
+    const provider = new RedisCacheProvider(client);
+    const error = new Error('SET unavailable');
+    client.set.mockRejectedValue(error);
+
+    await expect(provider.set('key', { value: true })).rejects.toBe(error);
+    expect(client.set).toHaveBeenCalledWith({ key: 'key', value: '{"value":true}' });
+});
+
+it('redis-cache-client/E04 非法 TTL 在写入前被拒绝', async () => {
+    const client = createClient();
+    const provider = new RedisCacheProvider(client);
+    const invalidTtls = [-1, -0.5, 1.5, Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY];
+
+    for (const ttl of invalidTtls) {
+        await expect(provider.set('key', 'value', ttl)).rejects.toThrow(RangeError);
+    }
+    expect(client.set).not.toHaveBeenCalled();
+});
+
+it('redis-cache-client/R01 重复删除保持幂等', async () => {
+    const client = createClient();
+    const provider = new RedisCacheProvider(client);
+
+    await expect(provider.delete('key')).resolves.toBeUndefined();
+    await expect(provider.delete('key')).resolves.toBeUndefined();
+
+    expect(client.deleteMany).toHaveBeenCalledTimes(2);
+    expect(client.deleteMany).toHaveBeenNthCalledWith(1, ['key']);
+    expect(client.deleteMany).toHaveBeenNthCalledWith(2, ['key']);
+});
+
+it('redis-cache-client/R02 重复写入由后完成的命令覆盖', async () => {
+    const client = createClient();
+    useStringStorage(client);
+    const provider = new RedisCacheProvider(client);
+
+    await provider.set('key', { version: 1 }, 60);
+    await provider.set('key', { version: 2 }, 120);
+
+    await expect(provider.get<{ version: number }>('key')).resolves.toEqual({ version: 2 });
+    expect(client.set).toHaveBeenNthCalledWith(1, {
+        key: 'key',
+        value: '{"version":1}',
+        ttlSeconds: 60,
+    });
+    expect(client.set).toHaveBeenNthCalledWith(2, {
+        key: 'key',
+        value: '{"version":2}',
+        ttlSeconds: 120,
+    });
+});
+
+it('redis-cache-client/E03 删除或清库异常传播', async () => {
+    const deleteClient = createClient();
+    const deleteProvider = new RedisCacheProvider(deleteClient);
+    const deleteError = new Error('DEL unavailable');
+    deleteClient.deleteMany.mockRejectedValue(deleteError);
+    const clearClient = createClient();
+    const clearProvider = new RedisCacheProvider(clearClient);
+    const clearError = new Error('FLUSHDB unavailable');
+    clearClient.flushDatabase.mockRejectedValue(clearError);
+
+    await expect(deleteProvider.delete('key')).rejects.toBe(deleteError);
+    await expect(clearProvider.clear()).rejects.toBe(clearError);
+});
+
+it('cache-evict-allentries-prefix/pattern 末尾 * 作为前缀匹配', async () => {
+    const client = createClient();
+    const provider = new RedisCacheProvider(client);
+    const existingKeys = new Set(['name:1', 'name:2', 'order:1']);
+    client.scan.mockResolvedValue({ cursor: '0', keys: ['name:1', 'name:2'] });
+    client.deleteMany.mockImplementation((keys): Promise<void> => {
+        for (const key of keys) {
+            existingKeys.delete(key);
+        }
+        return Promise.resolve();
+    });
+
+    await provider.deleteByPattern('name*');
+
+    expect(client.scan).toHaveBeenCalledWith({ cursor: '0', pattern: 'name*', count: 100 });
+    expect(client.deleteMany).toHaveBeenCalledWith(['name:1', 'name:2']);
+    expect(existingKeys).toEqual(new Set(['order:1']));
+});
+
+it('cache-evict-allentries-prefix/RedisCacheProvider 使用 SCAN 迭代删除', async () => {
+    const client = createClient();
+    const provider = new RedisCacheProvider(client);
+    client.scan
+        .mockResolvedValueOnce({ cursor: '7', keys: ['name:1'] })
+        .mockResolvedValueOnce({ cursor: '0', keys: ['name:2'] });
+
+    await provider.deleteByPattern('name*');
+
+    expect(client.scan.mock.calls).toEqual([
+        [{ cursor: '0', pattern: 'name*', count: 100 }],
+        [{ cursor: '7', pattern: 'name*', count: 100 }],
+    ]);
+    expect(client.deleteMany.mock.calls).toEqual([[['name:1']], [['name:2']]]);
+});
+
+it('cache-evict-allentries-prefix/F04 多页、空页与重复 key 均能完成扫描', async () => {
+    const client = createClient();
+    const provider = new RedisCacheProvider(client);
+    client.scan
+        .mockResolvedValueOnce({ cursor: '4', keys: ['name:1'] })
+        .mockResolvedValueOnce({ cursor: '8', keys: [] })
+        .mockResolvedValueOnce({ cursor: '0', keys: ['name:1', 'name:2'] });
+
+    await provider.deleteByPattern('name*');
+
+    expect(client.scan.mock.calls).toEqual([
+        [{ cursor: '0', pattern: 'name*', count: 100 }],
+        [{ cursor: '4', pattern: 'name*', count: 100 }],
+        [{ cursor: '8', pattern: 'name*', count: 100 }],
+    ]);
+    expect(client.deleteMany.mock.calls).toEqual([[['name:1']], [['name:1', 'name:2']]]);
+});
+
+it('cache-evict-allentries-prefix/F09 扫描或批量删除失败时停止并传播', async () => {
+    const scanClient = createClient();
+    const scanProvider = new RedisCacheProvider(scanClient);
+    const scanError = new Error('SCAN unavailable');
+    scanClient.scan.mockRejectedValue(scanError);
+
+    await expect(scanProvider.deleteByPattern('name*')).rejects.toBe(scanError);
+    expect(scanClient.deleteMany).not.toHaveBeenCalled();
+
+    const deleteClient = createClient();
+    const deleteProvider = new RedisCacheProvider(deleteClient);
+    const deleteError = new Error('second page DEL unavailable');
+    deleteClient.scan
+        .mockResolvedValueOnce({ cursor: '5', keys: ['name:1'] })
+        .mockResolvedValueOnce({ cursor: '9', keys: ['name:2'] });
+    deleteClient.deleteMany.mockResolvedValueOnce(undefined).mockRejectedValueOnce(deleteError);
+
+    await expect(deleteProvider.deleteByPattern('name*')).rejects.toBe(deleteError);
+    expect(deleteClient.scan).toHaveBeenCalledTimes(2);
+    expect(deleteClient.deleteMany.mock.calls).toEqual([[['name:1']], [['name:2']]]);
+});

package/test/type-contract/contract.ts

@@ -0,0 +1,64 @@
+import {
+    Cache,
+    CacheEvict,
+    type CacheEvictOptions,
+    type CacheKeyResolver,
+    type CacheOptions,
+    type CacheProvider,
+} from '@jintianxiayu/cache-decorator';
+
+type Equal<Left, Right> =
+    (<Value>() => Value extends Left ? 1 : 2) extends <Value>() => Value extends Right ? 1 : 2 ? true : false;
+type Assert<Condition extends true> = Condition;
+type LegacyMethodDecorator = (_target: object, _propertyKey: string, descriptor: PropertyDescriptor) => void;
+
+export type CacheOptionKeysMatch = Assert<Equal<keyof CacheOptions, 'ttl' | 'providerName' | 'key'>>;
+export type CacheEvictOptionKeysMatch = Assert<Equal<keyof CacheEvictOptions, 'key' | 'allEntries' | 'providerName'>>;
+export type CacheKeyResolverMatch = Assert<Equal<CacheKeyResolver, null | string | ((...args: unknown[]) => string)>>;
+
+const provider: CacheProvider = {
+    get: <Value>(_key: string): Value | undefined => undefined,
+    set: <Value>(_key: string, _value: Value, _ttl?: number): void => {
+        return;
+    },
+    delete: (_key: string): void => {
+        return;
+    },
+    clear: (): void => {
+        return;
+    },
+    deleteByPattern: (_pattern: string): void => {
+        return;
+    },
+};
+
+const cacheDecorator: LegacyMethodDecorator = Cache('contract-cache', {
+    ttl: 60,
+    providerName: 'memory',
+    key: (...args: unknown[]) => String(args[0]),
+});
+const evictDecorator: LegacyMethodDecorator = CacheEvict('contract-cache', {
+    providerName: 'memory',
+    key: null,
+    allEntries: false,
+});
+
+const invalidLoggingOption: CacheOptions = {
+    // @ts-expect-error CacheOptions 不提供第二套日志开关。
+    logging: true,
+};
+const invalidDebugOption: CacheOptions = {
+    // @ts-expect-error CacheOptions 不提供 debug 开关。
+    debug: true,
+};
+const invalidLoggerOption: CacheEvictOptions = {
+    // @ts-expect-error CacheEvictOptions 不接受 Logger 实例或回调。
+    logger: undefined,
+};
+
+void provider;
+void cacheDecorator;
+void evictDecorator;
+void invalidLoggingOption;
+void invalidDebugOption;
+void invalidLoggerOption;

package/test/type-contract/tsconfig.json

@@ -0,0 +1,12 @@
+{
+    "extends": "../../../../tsconfig.json",
+    "compilerOptions": {
+        "noEmit": true,
+        "skipLibCheck": false,
+        "paths": {
+            "@jintianxiayu/cache-decorator": ["../../dist/index.d.ts"]
+        },
+        "types": ["node"]
+    },
+    "include": ["contract.ts"]
+}