@zenweb/cache/dist/types.d.ts

Zenweb Cache module

import { Redis, RedisOptions } from "ioredis";
/**
 * 缓存选项
 */
export interface SetOption {
    /**
     * 缓存有效时长 (秒)
     * - `0` 永久有效
     * @default 60
     */
    ttl?: number;
    /**
     * 压缩内容最少长度(字节)
     * - `0` 不压缩
     * - 是否压缩判断:
     *   - 原始内容长度大于配置值
     *   - 压缩完成后的长度小于配置值
     * @default 1024
     */
    compressMinLength?: number;
    /**
     * 压缩存储比率
     * - 压缩完成后的长度对比压缩之前的长度所缩减的比率
     * - 压缩率不满足要求则不存储压缩数据
     * - 相对于低比率的压缩数据再解压节省的空间十分有限又浪费计算资源
     * - 默认 0.95, 至少压缩率达到 95% 才有价值
     * @default 0.95
     */
    compressStoreRatio?: number;
    /**
     * 压缩级别
     * @default 1
     */
    compressLevel?: number;
}
/**
 * 对象序列化
 */
export interface ObjectSerializer {
    serialize(data: object): Buffer;
    deserialize(data: Buffer): object;
}
export interface SetupOption {
    /**
     * Redis 实例或 Redis 选项
     */
    redis?: Redis | RedisOptions;
    /**
     * 默认缓存设置选项
     */
    set?: SetOption;
    /**
     * 默认锁缓存选项
     */
    lockGet?: LockGetOption;
    /**
     * 自定义序列化器
     * - 默认为 JSON 序列化
     */
    serializer?: ObjectSerializer;
}
/**
 * 取得缓存选项
 */
export interface GetOption {
    /**
     * 是否反序列化数据为对象
     * @default true
     */
    parse?: boolean;
    /**
     * 如果数据被压缩，是否需要解压
     * - `parse: false` 时有效
     * @default true
     */
    decompress?: boolean;
}
/**
 * 设置缓存结果
 */
export interface SetResult {
    /**
     * 未经过压缩的数据
     */
    data: string | Buffer;
    /**
     * 经过压缩的数据
     */
    compressed?: Buffer;
}
/**
 * 锁选项
 */
export interface LockOption {
    /**
     * 锁超时 (毫秒)
     * - 取得锁后多久没有释放则自动释放
     * @default 10000
     */
    lockTimeout?: number;
    /**
     * 数据获取重试超时 (毫秒)
     * - 0 不进行重试
     * - lockGet 默认为 5000
     * - singleRunner 默认为 0
     */
    retryTimeout?: number;
    /**
     * 数据获取重试间隔 (毫秒)
     * @default 500
     */
    retryDelay?: number;
}
/**
 * 取得或使用锁设置新缓存
 */
export interface LockGetOption extends GetOption, SetOption, LockOption {
    /**
     * 预刷新（秒）
     * - `0` 无效
     * - 缓存剩余时间小于值时主动刷新，不影响当前数据获取
     * @default 0
     */
    preRefresh?: number;
    /**
     * 刷新数据
     * - 不从 Redis 获取数据，直接调用 fetch 设置新的数据
     * @default false
     */
    refresh?: boolean;
    /**
     * 本地存储
     * - 如果指定一个对象，则尝试先从对象中存取
     * - 防止在同一次请求中重复从 Redis 获取
     * - 一般情况下在 Context 中设置一个空对象并指定
     */
    localStore?: {
        [key: string]: any;
    };
    /**
     * 不等待
     * - 当缓存不存在时直接返回 `undefined`，之后使用 `fetch` 取得数据并设置缓存
     * - 应用场景: 某些数据并不参与业务逻辑又比较耗时，当 `fetch` 处理时间过长的情况下可能会造成请求超时，使用 `wait: false` 可以跳过等待
     * @default false
     */
    noWait?: boolean;
}
export type CacheKeyType = string | number | object | undefined | null | boolean;
export type CacheHelperOption = Omit<LockGetOption, 'parse' | 'noWait'>;
export type CacheHelperKey<P extends CacheKeyType[]> = string | ((...param: P) => string | Promise<string>);