@seepine/cache

轻量缓存工具，支持：

• 纯内存缓存（基于 LRU Cache）
• 通过 Adapter 接入外部缓存（如 Redis）
• 内存 + 外部多级缓存
• 分布式锁（无 Adapter 时自动退化为进程内锁）

一、安装

npm install @seepine/cache

二、快速开始

2.1 内存缓存

无需任何配置，开箱即用：

import { Cache } from '@seepine/cache'

const cache = new Cache()

await cache.set('k1', 'v1', '30s')
const value = await cache.get('k1') // 'v1'

2.2 使用 Adapter（以 Bun Redis 为例）

通过 adapter 参数传入实现了 CacheAdapter 的实例：

import { Cache } from '@seepine/cache'
import { BunRedisAdapter } from '@seepine/cache/adapt/bun'

const cache = new Cache({
  adapter: new BunRedisAdapter('redis://localhost:6379'),
  namespace: 'my-app',
})

2.3 自定义 Adapter

实现 CacheAdapter 抽象类即可接入任意缓存后端：

import { Cache, CacheAdapter } from '@seepine/cache'

class MyRedisClient extends CacheAdapter {
  async set<T>(key: string, value: T, expireSeconds?: number) {
    /* ... */
  }
  async setnx<T>(key: string, value: T, expireSeconds?: number) {
    /* ... */
  }
  async get<T>(key: string): Promise<T | undefined> {
    /* ... */
  }
  async del(key: string) {
    /* ... */
  }
  async expire(key: string, expireSeconds: number) {
    /* ... */
  }
  async clear(namespace: string) {
    /* ... */
  }
  async close() {
    /* ... */
  }
}

const cache = new Cache({
  adapter: new MyRedisClient(),
})

2.4 开启多级缓存（内存 + Adapter）

需要传入 adapter 才可启用多级缓存：

import { Cache } from '@seepine/cache'
import { BunRedisAdapter } from '@seepine/cache/adapt/bun'

const cache = new Cache({
  adapter: new BunRedisAdapter(),
  multiLevelEnabled: true,
  multiLevelTtl: 1000, // 内存层 TTL，单位毫秒
})

三、API

3.1 Constructor Options

| 参数 | 类型 | 默认值 | 说明 | | ----------------------- | -------------- | --------- | --------------------------------------------------- | | adapter | CacheAdapter | — | 外部缓存客户端，不传则使用纯内存模式 | | namespace | string | 'cache' | 命名空间，键前缀，避免不同应用键冲突 | | multiLevelEnabled | boolean | false | 是否启用多级缓存（需要传入 adapter） | | multiLevelTtl | number | 1000 | 多级缓存中内存层 TTL（毫秒） | | lockTimeoutSeconds | number | 0 | 锁等待超时（秒），0 为无限等待 | | lockAcquireIntervalMs | number | 100 | 尝试获取锁的时间间隔（毫秒） | | lockWatchDogSeconds | number | 20 | 看门狗续期间隔（秒），实际锁过期时间为此值 × 2 + 5s |

3.2 方法

| 方法 | 说明 | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | set<T>(key, value, ttl?) | 写入缓存。ttl 支持秒数（如 60）或字符串（"10s" / "5m" / "2h" / "3d" / "1y"） | | get<T>(key) | 读取缓存，不存在返回 undefined | | getOrSet<T>(key, getFn, ttl?) | 若 key 有值直接返回；否则加锁后执行 getFn 获取并写入缓存后返回 | | del(key) | 删除缓存 | | clear() | 清空当前命名空间缓存 | | lock<T>(key, fn, timeoutSeconds?) | 获取锁后执行 fn，结束后自动释放。有 Adapter 时使用分布式锁（含自动续约 watchdog），无 Adapter 时使用进程内锁。timeoutSeconds < 0 会抛错 | | close() | 关闭连接，建议在应用退出前调用 |

3.3 TTL 格式

| 格式 | 含义 | 示例 | | ---- | ---- | ------------ | | 数字 | 秒 | 60 → 60 秒 | | Ns | 秒 | "30s" | | Nm | 分钟 | "5m" | | Nh | 小时 | "2h" | | Nd | 天 | "7d" | | Ny | 年 | "1y" |

四、示例：防止缓存击穿

import { Cache } from '@seepine/cache'
import { BunRedisAdapter } from '@seepine/cache/adapt/bun'

const cache = new Cache({
  adapter: new BunRedisAdapter(),
  multiLevelEnabled: true,
  multiLevelTtl: 1000,
})

async function getUser(userId: string) {
  // 首次走 DB，之后命中内存缓存，内存过期后走 Adapter 缓存
  return cache.getOrSet(
    `user:${userId}`,
    async () => {
      return await db.user.findById(userId)
    },
    '30s',
  )
}

五、内置 Adapter

Bun Redis

基于 Bun 内置的 Bun.RedisClient，无需额外依赖：

import { BunRedisAdapter } from '@seepine/cache/adapt/bun'

// 默认连接 localhost:6379，也支持 REDIS_URL / VALKEY_URL 环境变量
const client = new BunRedisAdapter()

// 或指定地址
const client = new BunRedisAdapter('redis://localhost:6379')