chanjs 2.7.7 → 2.7.10

package/doc/Cache.md

@@ -1,333 +0,0 @@
-# Cache 缓存工具
-
-## 概述
-
-`Cache` 是基于单 Map 实现的 LRU + 惰性 TTL 过期清理缓存类，对齐 Redis incr 行为，专用于限流场景的内存存储。
-
-## 特性
-
-- **LRU 淘汰**：访问刷新 LRU 顺序，容量超限时自动淘汰最久未使用的条目
-- **惰性 TTL**：自增不续期，批量惰性清理过期条目
-- **容量淘汰**：达到最大容量时自动 LRU 淘汰
-- **高性能**：10w 容量，定时批量清理避免阻塞事件循环
-
-## 引入方式
-
-```javascript
-import { cache } from 'chanjs';
-
-// 或创建自定义实例
-import Cache from 'chanjs/storage/cache.js';
-const customCache = new Cache({ maxSize: 50000, defaultTTL: 60000 });
-```
-
-## 构造函数
-
-```javascript
-new Cache(opts = {})
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| opts.maxSize | number | 否 | 100000 | 缓存最大条目数 |
-| opts.defaultTTL | number | 否 | 300000 (5分钟) | 默认过期时间（毫秒） |
-
-## 核心方法
-
-### 1. set - 写入缓存
-
-```javascript
-set(key, value, ttl = this.defaultTTL)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| key | string | 是 | - | 缓存键 |
-| value | any | 是 | - | 缓存值 |
-| ttl | number | 否 | defaultTTL | 过期时间（毫秒），<=0 视为永久存储 |
-
-**示例**
-
-```javascript
-import { cache } from 'chanjs';
-
-// 设置 60 秒过期的缓存
-cache.set('user:1001', { name: '张三' }, 60000);
-
-// 永久存储（ttl <= 0）
-cache.set('config:app', { version: '1.0' }, 0);
-```
-
-### 2. get - 读取缓存
-
-```javascript
-get(key)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| key | string | 是 | 缓存键 |
-
-**返回值**
-
-- 缓存值：存在且未过期
-- `null`：不存在或已过期
-
-**示例**
-
-```javascript
-const user = cache.get('user:1001');
-if (user) {
-  console.log('用户信息：', user);
-} else {
-  console.log('缓存不存在或已过期');
-}
-```
-
-### 3. has - 检查存在
-
-```javascript
-has(key)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| key | string | 是 | 缓存键 |
-
-**返回值**
-
-- `true`：存在且未过期
-- `false`：不存在或已过期
-
-**示例**
-
-```javascript
-if (cache.has('user:1001')) {
-  console.log('缓存存在');
-}
-```
-
-### 4. del - 删除缓存
-
-```javascript
-del(key)
-```
-
-**示例**
-
-```javascript
-cache.del('user:1001');
-```
-
-### 5. clear - 清空所有
-
-```javascript
-clear()
-```
-
-**示例**
-
-```javascript
-cache.clear();
-```
-
-### 6. size - 获取数量
-
-```javascript
-size()
-```
-
-**返回值**
-
-缓存条目总数（近似值，包含未惰性清理的过期项）
-
-**示例**
-
-```javascript
-const count = cache.size();
-console.log(`缓存条目数：${count}`);
-```
-
-### 7. incr - 自增（限流专用）
-
-```javascript
-incr(key, ttlMs = 60000)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| key | string | 是 | - | 缓存键 |
-| ttlMs | number | 否 | 60000 | 新建 key 的过期时间（毫秒），存量不续期 |
-
-**返回值**
-
-自增后的值（number）
-
-**特性**
-
-- 新建 key 使用指定 TTL
-- 存量 key 不续期 TTL
-- 支持容量超限自动 LRU 淘汰
-
-**示例**
-
-```javascript
-// 限流场景：60 秒内最多 100 次请求
-const count = cache.incr('rate:192.168.1.1', 60000);
-if (count > 100) {
-  console.log('请求过于频繁');
-} else {
-  console.log(`当前第 ${count} 次请求`);
-}
-```
-
-### 8. incrAndExpire - 自增并设置过期时间
-
-```javascript
-incrAndExpire(key, ttlMs)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| key | string | 是 | 缓存键 |
-| ttlMs | number | 是 | 新建 key 的过期时间（毫秒） |
-
-**返回值**
-
-自增后的值（number）
-
-**示例**
-
-```javascript
-const count = cache.incrAndExpire('limit:api:1001', 30000);
-```
-
-### 9. expire - 刷新过期时间
-
-```javascript
-expire(key, ttlMs)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| key | string | 是 | 缓存键 |
-| ttlMs | number | 是 | 新的过期时间（毫秒） |
-
-**返回值**
-
-- `true`：刷新成功
-- `false`：key 不存在或已过期
-
-**示例**
-
-```javascript
-// 续期 30 秒
-cache.expire('session:1001', 30000);
-```
-
-## 内部机制
-
-### LRU 淘汰
-
-- 使用 Map 的插入顺序特性
-- 访问时删除再插入，刷新到最新位置
-- 容量超限时淘汰最久未使用的条目
-
-### 惰性清理
-
-- 每 10 秒触发一次批量清理
-- 单次最多清理 1000 条，避免阻塞事件循环
-- 读取时检查过期状态，过期则删除
-
-### 容量配置
-
-- 默认最大容量：100,000 条
-- 达到容量上限时自动 LRU 淘汰
-- 可通过构造函数自定义
-
-## 使用场景
-
-### 1. 接口限流
-
-```javascript
-import { cache } from 'chanjs';
-
-function rateLimitMiddleware(req, res, next) {
-  const ip = req.ip;
-  const key = `rate:${ip}`;
-  const count = cache.incr(key, 60000); // 60 秒窗口
-  
-  if (count > 100) {
-    return res.status(429).json({
-      success: false,
-      code: 1009,
-      msg: '请求过于频繁'
-    });
-  }
-  
-  next();
-}
-```
-
-### 2. 会话缓存
-
-```javascript
-// 存储用户会话
-cache.set(`session:${userId}`, {
-  userId,
-  loginTime: Date.now(),
-  role: 'admin'
-}, 3600000); // 1 小时
-
-// 读取会话
-const session = cache.get(`session:${userId}`);
-```
-
-### 3. 数据缓存
-
-```javascript
-// 缓存数据库查询结果
-async function getUserWithCache(userId) {
-  const key = `user:${userId}`;
-  let user = cache.get(key);
-  
-  if (!user) {
-    user = await db('users').where({ id: userId }).first();
-    if (user) {
-      cache.set(key, user, 300000); // 缓存 5 分钟
-    }
-  }
-  
-  return user;
-}
-```
-
-## 注意事项
-
-1. **内存占用**：缓存存储在内存中，应用重启后数据丢失
-2. **容量限制**：默认 10w 条目，超限自动 LRU 淘汰
-3. **过期精度**：惰性清理，过期时间可能有几秒误差
-4. **并发安全**：单线程环境，无需考虑并发问题
-5. **适用场景**：限流计数、临时缓存、会话存储等短 TTL 数据
-6. **不适用**：持久化存储、跨进程共享、大数据量存储
-
-## 与 Store 的关系
-
-- `Cache` 是底层内存缓存实现
-- `Store` 是统一存储适配层，封装了 `Cache` 和 Redis
-- 业务层推荐使用 `Store`，自动切换内存/Redis
-- 仅在使用纯内存场景时直接使用 `Cache`