@ happyvertical/ cache (笑) (笑) (掌声)
统一缓存接口支持内存,文件,Redis,以及带有TTL的S3后端,驱逐政策,批量操作,并压缩. 所有供应商执行相同的 CacheProvider 接口,因此可以在不更改应用程序代码的情况下互换后端.
安装
pnpm add @happyvertical/cache
# Requires @happyvertical/utils as a peer
# redis and @aws-sdk/client-s3 are bundled
快速启动
import { getCache } from '@happyvertical/cache';
const cache = await getCache({
provider: 'memory',
maxSize: 100 * 1024 * 1024,
evictionPolicy: 'lru',
});
await cache.set('user:123', { name: 'Alice' }, 3600); // TTL in seconds
const user = await cache.get('user:123');
await cache.delete('user:123');
await cache.close();
供应商
内存
进行中 Map- 基于缓存。 无外相依. 重新启动时丢失数据 .
const cache = await getCache({
provider: 'memory',
namespace: 'app',
defaultTTL: 3600, // seconds
maxSize: 100 * 1024 * 1024, // bytes (default 100MB)
maxEntries: 10000, // default 10k
evictionPolicy: 'lru', // 'lru' | 'lfu' | 'fifo'
checkPeriod: 60000, // expiration sweep interval in ms
});
文件
以可选的 gzip 压缩将条目存储为磁盘上的文件 。 坚持到重启为止.
const cache = await getCache({
provider: 'file',
cacheDir: './cache', // required
compression: true, // gzip (default false)
maxSize: 500 * 1024 * 1024, // bytes (default 500MB)
fileExtension: '.cache',
checkPeriod: 300000, // cleanup interval in ms
});
重写
使用 redis npm客户端. 支持大值的可选gzip压缩.
const cache = await getCache({
provider: 'redis',
host: 'localhost',
port: 6379,
password: 'secret',
db: 0,
namespace: 'app',
enableCompression: true,
compressionThreshold: 1024, // bytes — only compress values larger than this
connectTimeout: 5000, // ms
});
第3条
将条目存储为 S3 对象 。 对运行之间必须持续的 CI 缓存有用 。 默认启用了压缩以减少相继成本 .
const cache = await getCache({
provider: 's3',
bucket: 'my-cache-bucket',
prefix: 'cache/',
region: 'us-east-1',
compression: true, // default true
compressionThreshold: 1024, // bytes
});
API 密码
所有提供者执行 CacheProvider数字 :
interface CacheProvider {
get<T>(key: string): Promise<T | undefined>;
set<T>(key: string, value: T, ttl?: number): Promise<void>;
has(key: string): Promise<boolean>;
delete(key: string): Promise<boolean>;
clear(namespace?: string): Promise<void>;
keys(pattern?: string): Promise<string[]>;
getMany<T>(keys: string[]): Promise<Map<string, T>>;
setMany<T>(entries: Array<{ key: string; value: T; ttl?: number }>): Promise<void>;
deleteMany(keys: string[]): Promise<number>;
touch(key: string, ttl: number): Promise<boolean>;
getStats(): Promise<CacheStats>;
close(): Promise<void>;
}
- TTL 电话 总是数秒。 关闭不过期.
keys()接受 glob 模式 (user:*, (中文(简体) ),report:2024*) (中文(简体) ).touch()更新 TTL 不修改值。 回返false如果钥匙不存在的话.- 批量操作 (单位:千美元)
getMany, (中文(简体) ),setMany, (中文(简体) ),deleteMany)减少来回行走,尤其是为Redis.
环境变量
配置可以从 HAVE_CACHE_* 环境变量通过 @happyvertical/utils/loadEnvConfig方案选项总是优先.
| 变量 | 地图到 | 页:1 |
|---|---|---|
HAVE_CACHE_PROVIDER | provider | memory, (中文(简体) ), file, (中文(简体) ), redis, (中文(简体) ), s3 |
HAVE_CACHE_NAMESPACE | namespace | |
HAVE_CACHE_DEFAULT_TTL | defaultTTL | 秒数 |
HAVE_CACHE_MAX_SIZE | maxSize | 字节( 记忆/ 文件) |
HAVE_CACHE_MAX_ENTRIES | maxEntries | 仅包含 |
HAVE_CACHE_EVICTION_POLICY | evictionPolicy | 仅包含 |
HAVE_CACHE_CACHE_DIR | cacheDir | 仅文件 |
HAVE_CACHE_COMPRESSION | compression | 文件/s3 |
HAVE_CACHE_HOST | host | 仅重新编号 |
HAVE_CACHE_PORT | port | 仅重新编号 |
HAVE_CACHE_PASSWORD | password | 仅重新编号 |
HAVE_CACHE_BUCKET | bucket | s3 仅限 |
HAVE_CACHE_PREFIX | prefix | s3 仅限 |
HAVE_CACHE_REGION | region | s3 仅限 |
错误分类
所有错误延伸 CacheError(message, code, provider)数字 :
CacheKeyError— 无效的密钥( 空或 > 250字符)CacheConnectionError——后端无法接通(Redis)CacheSizeError- 输入将超过maxSizeCacheSerializationError- JSON 序列化/去序列化失败
出口公用事业
低级帮助者从 shared/utils数字 :
isValidKey(key)检查密钥长度限制calculateSize(value)大约JSON字节大小matchesPattern(pattern, str)- 格布比对formatKey(namespace, key)编号 :extractKey(namespace, fullKey)命名空间前缀isExpired(expiresAt)编号 :calculateExpiration(ttl)- TTL 数学serialize(value)编号 :deserialize(json)- JSON包装器