mm_cachebase 1.6.0 → 1.8.0

package/README.md

@@ -9,6 +9,7 @@
 - **完整的事件系统**：支持前置/后置/错误事件，便于日志记录和访问控制
 - **过期时间管理**：支持设置和查询键的过期时间
 - **丰富的数据类型支持**：支持字符串、哈希表等Redis常见数据类型
+- **多文件持久化**：支持数据持久化到文件，通过scope参数实现多实例数据隔离
 
 ## 安装
 
@@ -43,11 +44,19 @@ async function example() {
 ### 构造函数
 
 ```javascript
-const cache = new CacheBase();
+const cache = new CacheBase(scope, config);
 ```
 
 创建一个新的缓存实例。缓存实例基于EventEmitter，支持完整的事件系统。
 
+- `scope`: 缓存作用域名称（默认'sys'），用于多文件持久化时的数据隔离
+- `config`: 配置选项对象，支持以下属性：
+  - `dir`: 缓存文件存储目录（默认'./cache/'）
+  - `expire`: 默认过期时间（秒）（默认0，表示永不过期）
+  - `max`: 最大缓存键数量（默认0，表示无限制）
+  - `persist`: 是否启用持久化（默认false）
+  - `saveInterval`: 定时保存间隔（毫秒）（默认60000）
+
 ### 基本操作
 
 #### 设置缓存
@@ -232,6 +241,22 @@ await cache.dispose()
 ```
 - 清理所有资源，移除所有监听器
 
+### 持久化操作
+
+#### 连接并启动定时保存
+```javascript
+await cache.connect()
+```
+- 启用持久化时启动定时保存功能
+- 返回: 连接成功返回true，失败返回false
+
+#### 手动保存数据
+```javascript
+await cache.save()
+```
+- 手动将缓存数据保存到文件
+- 返回: 保存成功返回true，失败返回false
+
 ### 兼容方法（保持向后兼容）
 
 #### 添加缓存（仅当键不存在时）
@@ -248,15 +273,17 @@ await cache.has(key)
 
 #### 增加浮点数（兼容方法）
 ```javascript
-await cache.addFloat(key, num)
+await cache.addFloat(key, num, maxAge)
 ```
 - `num`: 要增加的浮点数
+- `maxAge`: 过期时间（秒），默认0表示永不过期
 - 返回: 计算后的结果
 
 #### 追加字符串（兼容方法）
 ```javascript
-await cache.addStr(key, str)
+await cache.addStr(key, str, maxAge)
 ```
+- `maxAge`: 过期时间（秒），默认0表示永不过期
 - 返回: 追加后的完整字符串
 
 #### 清空匹配缓存（兼容方法）
@@ -417,6 +444,49 @@ async function numberExample() {
 }
 ```
 
+### 多文件持久化示例
+```javascript
+const CacheBase = require('mm_cachebase');
+
+async function persistenceExample() {
+    // 创建启用持久化的缓存实例，指定不同的scope
+    const userCache = new CacheBase('users', { 
+        persist: true, 
+        saveInterval: 30000, // 30秒保存一次
+        dir: './test_cache/' // 自定义缓存目录
+    });
+    
+    const productCache = new CacheBase('products', { 
+        persist: true, 
+        saveInterval: 30000, 
+        dir: './test_cache/' 
+    });
+    
+    // 启动定时保存
+    await userCache.connect();
+    await productCache.connect();
+    
+    // 向不同scope添加数据
+    await userCache.set('user1', { name: '张三', age: 30 }, 3600);
+    await productCache.set('product1', { id: 1, name: '商品A', price: 99.99 }, 3600);
+    
+    // 数据会分别保存到 users.cache.json 和 products.cache.json
+    console.log('数据已保存，不同scope的数据完全隔离');
+    
+    // 手动保存（可选）
+    await userCache.save();
+    
+    // 应用重启后，可通过相同的scope加载对应的数据
+    const loadedUserCache = new CacheBase('users', { persist: true, dir: './test_cache/' });
+    const loadedUser = await loadedUserCache.get('user1');
+    console.log('加载的用户数据:', loadedUser);
+    
+    // 销毁实例时，会自动保存数据
+    await userCache.dispose();
+    await productCache.dispose();
+}
+```
+
 ### 批量操作示例
 ```javascript
 async function batchExample() {
@@ -444,9 +514,11 @@ async function batchExample() {
 
 1. 所有操作方法都是异步的，需要使用async/await或Promise处理
 2. 过期时间单位为秒，-1表示永不过期
-3. 缓存数据存储在内存中，重启后数据会丢失
-4. 事件回调函数中的 `cancel` 标志只在前置事件中有效，后置事件中修改不会产生效果
-5. 所有事件参数都遵循统一的格式，包含key、value、result、error和cancel等字段
+3. 缓存数据默认存储在内存中，重启后数据会丢失
+4. 启用持久化时，数据将保存到`{scope}.cache.json`文件，不同scope的数据存储在不同文件中，实现数据隔离
+5. 缓存目录会在第一次使用时自动创建，无需手动创建
+6. 事件回调函数中的 `cancel` 标志只在前置事件中有效，后置事件中修改不会产生效果
+7. 所有事件参数都遵循统一的格式，包含key、value、result、error和cancel等字段
 
 ## 许可证
 

package/compatibility_table.md

@@ -12,6 +12,7 @@
 | clear | ❌ | ✅ | ✅ | Redis无此方法，CacheBase保持兼容 |
 | keys | ✅ | ✅ | ✅ | 完全兼容 |
 | ttl | ✅ | ❌ | ✅ | Redis原生支持，CacheBase模拟实现 |
+| persist | ✅ | ❌ | ✅ | Redis原生支持，CacheBase模拟实现 |
 | add | ❌ | ✅ | ✅ | Redis无此方法，CacheBase保持兼容 |
 | addInt | ❌ | ✅ | ✅ | Redis无此方法，CacheBase保持兼容 |
 | addStr | ❌ | ✅ | ✅ | Redis无此方法，CacheBase保持兼容 |