mm_cachebase 1.5.0 → 1.7.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
+
 ### 兼容方法（保持向后兼容）
 
 #### 添加缓存（仅当键不存在时）
@@ -269,6 +294,8 @@ await cache.clear(pattern)
 
 CacheBase 提供了完整的事件系统，允许你监听各种缓存操作的前后事件，以便进行日志记录、数据验证或操作取消等功能。
 
+> **性能优化说明**：从版本 1.6.0 开始，查询类方法（如 get、hget、mget、exists、ttl 等）不再触发事件，以提高高频查询操作的性能。
+
 ### 事件监听方法
 
 ```javascript
@@ -299,15 +326,12 @@ cache.off('event_name', callback);
 
 #### 基本操作事件
 - `set_before`, `set_after`, `set_error`
-- `get_before`, `get_after`, `get_error`
 - `del_before`, `del_after`, `del_error`
-- `exists_before`, `exists_after`, `exists_error`
 - `mset_before`, `mset_after`, `mset_error`
-- `mget_before`, `mget_after`, `mget_error`
 
 #### 过期时间操作事件
 - `expire_before`, `expire_after`, `expire_error`
-- `ttl_before`, `ttl_after`, `ttl_error`
+- `persist_before`, `persist_after`, `persist_error`
 
 #### 数值操作事件
 - `incr_before`, `incr_after`, `incr_error`
@@ -318,17 +342,12 @@ cache.off('event_name', callback);
 
 #### 字符串操作事件
 - `append_before`, `append_after`, `append_error`
-- `strlen_before`, `strlen_after`, `strlen_error`
 
 #### 哈希表操作事件
 - `hset_before`, `hset_after`, `hset_error`
-- `hget_before`, `hget_after`, `hget_error`
-- `hgetall_before`, `hgetall_after`, `hgetall_error`
 - `hdel_before`, `hdel_after`, `hdel_error`
 
 #### 键操作事件
-- `keys_before`, `keys_after`, `keys_error`
-- `dbsize_before`, `dbsize_after`, `dbsize_error`
 - `flushdb_before`, `flushdb_after`, `flushdb_error`
 - `dispose_before`, `dispose_after`, `dispose_error`
 
@@ -348,14 +367,9 @@ cache.on('set_before', (data) => {
     }
 });
 
-// 监听获取操作的后置事件
-cache.on('get_after', (data) => {
-    console.log(`获取键 ${data.key} 的结果: ${data.result}`);
-});
-
 // 错误事件监听
-cache.on('get_error', (data) => {
-    console.error(`获取键 ${data.key} 时出错: ${data.error.message}`);
+cache.on('mset_error', (data) => {
+    console.error(`批量设置出错: ${data.error.message}`);
 });
 ```
 
@@ -428,6 +442,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() {
@@ -455,9 +512,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等字段
 
 ## 许可证