mm_cachebase 1.4.4 → 1.4.6

package/README.md

@@ -1,6 +1,6 @@
 # mm_cachebase
 
-一个轻量级的本地缓存类库，提供了丰富的缓存操作接口，支持过期时间设置、数组操作等功能。
+一个轻量级的本地缓存类库，提供了丰富的缓存操作接口，支持过期时间设置、数组操作、哈希表、集合、有序集合等功能，以及完整的事件通知系统。
 
 ## 安装
 
@@ -126,21 +126,90 @@ await cache.setrange(key, index, value)
 ```
 - 从指定位置替换字符串
 
-### 数组操作
+### 哈希表操作
 
-#### 设置数组
+#### 设置哈希表字段
+```javascript
+await cache.hset(key, field, value)
+```
+- `key`: 哈希表的键名
+- `field`: 字段名
+- `value`: 字段值
+- 返回: 成功返回1，失败返回0
+
+#### 获取哈希表字段
+```javascript
+await cache.hget(key, field)
+```
+- 返回: 字段值，不存在则返回null
+
+#### 删除哈希表字段
+```javascript
+await cache.hdel(key, field)
+```
+- 返回: 成功返回1，失败返回0
+
+#### 获取哈希表所有键名
+```javascript
+await cache.hkeys(key)
+```
+- 返回: 键名数组
+
+#### 获取哈希表所有值
+```javascript
+await cache.hvals(key)
+```
+- 返回: 值数组
+
+### 列表操作
+
+#### 设置列表
 ```javascript
 await cache.list_set(key, value, maxAge)
 ```
 - 设置一个数组类型的缓存
 
-#### 添加数组元素
+#### 添加列表元素
 ```javascript
 await cache.list_add(key, value)
 ```
 - 向数组末尾添加元素
 - 返回: 成功返回1，失败返回-1
 
+#### 从左侧推入元素
+```javascript
+await cache.lpush(key, ...values)
+```
+- 从列表左侧添加一个或多个元素
+- 返回: 操作后的列表长度
+
+#### 从左侧弹出元素
+```javascript
+await cache.lpop(key)
+```
+- 从列表左侧移除并返回一个元素
+- 返回: 弹出的元素，列表为空返回null
+
+#### 从右侧推入元素
+```javascript
+await cache.rpush(key, ...values)
+```
+- 从列表右侧添加一个或多个元素
+- 返回: 操作后的列表长度
+
+#### 从右侧弹出元素
+```javascript
+await cache.rpop(key)
+```
+- 从列表右侧移除并返回一个元素
+- 返回: 弹出的元素，列表为空返回null
+
+#### 获取列表长度
+```javascript
+await cache.llen(key)
+```
+- 返回: 列表长度，键不存在返回0
+
 #### 判断数组元素是否存在
 ```javascript
 await cache.list_has(key, value)
@@ -159,6 +228,70 @@ await cache.list_clear(key, value)
 ```
 - 清空数组或用新数组替换
 
+### 集合操作
+
+#### 添加集合成员
+```javascript
+await cache.sadd(key, member)
+```
+- 向集合添加一个成员
+- 返回: 成功返回1，成员已存在返回0
+
+#### 删除集合成员
+```javascript
+await cache.srem(key, member)
+```
+- 从集合移除一个成员
+- 返回: 成功返回1，成员不存在返回0
+
+#### 获取集合所有成员
+```javascript
+await cache.smembers(key)
+```
+- 返回: 成员数组，键不存在返回空数组
+
+#### 判断成员是否存在
+```javascript
+await cache.sismember(key, member)
+```
+- 返回: 存在返回1，不存在返回0
+
+#### 获取集合大小
+```javascript
+await cache.scard(key)
+```
+- 返回: 集合大小，键不存在返回0
+
+### 有序集合操作
+
+#### 添加有序集合成员
+```javascript
+await cache.zadd(key, score, member)
+```
+- 向有序集合添加一个成员
+- 返回: 成功返回1，成员已存在返回0
+
+#### 获取有序集合范围
+```javascript
+await cache.zrange(key, start, stop, withScores)
+```
+- `start`/`stop`: 范围索引
+- `withScores`: 是否返回分数
+- 返回: 成员数组或[成员, 分数]数组
+
+#### 删除有序集合成员
+```javascript
+await cache.zrem(key, member)
+```
+- 从有序集合移除一个成员
+- 返回: 成功返回1，成员不存在返回0
+
+#### 获取成员分数
+```javascript
+await cache.zscore(key, member)
+```
+- 返回: 成员分数，成员不存在返回null
+
 ### 其他操作
 
 #### 排序
@@ -182,6 +315,12 @@ await cache.clear(pattern)
 - `pattern`: 可选，支持*通配符，清空匹配的键
 - 不传则清空所有缓存
 
+#### 销毁缓存实例
+```javascript
+await cache.dispose()
+```
+- 清理所有资源，移除所有监听器
+
 ## 使用示例
 
 ### 基本缓存操作
@@ -205,21 +344,119 @@ async function example() {
 }
 ```
 
-### 数组操作示例
+### 哈希表操作示例
 ```javascript
-async function arrayExample() {
-    // 设置数组
-    await cache.list_set("users", ["张三", "李四"], 300);
+async function hashExample() {
+    // 设置哈希表字段
+    await cache.hset("user:123", "name", "张三");
+    await cache.hset("user:123", "age", 30);
+    await cache.hset("user:123", "email", "zhangsan@example.com");
     
-    // 添加元素
-    await cache.list_add("users", "王五");
+    // 获取哈希表字段
+    const name = await cache.hget("user:123", "name");
+    console.log(name); // 输出: 张三
     
-    // 获取数组
-    const users = await cache.list_get("users");
-    console.log(users); // 输出: ["张三", "李四", "王五"]
+    // 获取所有键名
+    const keys = await cache.hkeys("user:123");
+    console.log(keys); // 输出: ["name", "age", "email"]
+    
+    // 获取所有值
+    const values = await cache.hvals("user:123");
+    console.log(values); // 输出: ["张三", 30, "zhangsan@example.com"]
+    
+    // 删除字段
+    await cache.hdel("user:123", "email");
+}
+```
+
+### 列表操作示例
+```javascript
+async function listExample() {
+    // 设置列表
+    await cache.list_set("tasks", ["任务1", "任务2"], 300);
+    
+    // 添加元素到末尾
+    await cache.list_add("tasks", "任务3");
+    
+    // 从左侧推入元素
+    await cache.lpush("tasks", "任务0");
+    
+    // 从右侧推入元素
+    await cache.rpush("tasks", "任务4");
+    
+    // 从左侧弹出元素
+    const task0 = await cache.lpop("tasks");
+    console.log("弹出任务:", task0); // 输出: 任务0
+    
+    // 从右侧弹出元素
+    const task4 = await cache.rpop("tasks");
+    console.log("弹出任务:", task4); // 输出: 任务4
+    
+    // 获取列表长度
+    const length = await cache.llen("tasks");
+    console.log("任务数量:", length); // 输出: 3
+    
+    // 获取列表
+    const tasks = await cache.list_get("tasks");
+    console.log("任务列表:", tasks); // 输出: ["任务1", "任务2", "任务3"]
     
     // 排序
-    await cache.sort("users", "asc");
+    await cache.sort("tasks", "asc");
+}
+```
+
+### 集合操作示例
+```javascript
+async function setExample() {
+    // 添加集合成员
+    await cache.sadd("users", "张三");
+    await cache.sadd("users", "李四");
+    await cache.sadd("users", "王五");
+    
+    // 尝试添加重复成员
+    const result = await cache.sadd("users", "张三");
+    console.log("添加重复成员结果:", result); // 输出: 0
+    
+    // 判断成员是否存在
+    const exists = await cache.sismember("users", "张三");
+    console.log("张三是否在用户集合中:", exists); // 输出: 1
+    
+    // 获取集合所有成员
+    const members = await cache.smembers("users");
+    console.log("用户集合:", members); // 输出: ["张三", "李四", "王五"]
+    
+    // 获取集合大小
+    const size = await cache.scard("users");
+    console.log("集合大小:", size); // 输出: 3
+    
+    // 删除成员
+    await cache.srem("users", "李四");
+}
+```
+
+### 有序集合操作示例
+```javascript
+async function sortedSetExample() {
+    // 添加有序集合成员
+    await cache.zadd("scores", 95, "张三");
+    await cache.zadd("scores", 88, "李四");
+    await cache.zadd("scores", 92, "王五");
+    
+    // 获取有序集合范围（升序）
+    const ascendingScores = await cache.zrange("scores", 0, -1, true);
+    console.log("分数排序(升序):", ascendingScores);
+    // 输出: ["李四", 88, "王五", 92, "张三", 95]
+    
+    // 获取指定成员分数
+    const zhangScore = await cache.zscore("scores", "张三");
+    console.log("张三的分数:", zhangScore); // 输出: 95
+    
+    // 删除成员
+    await cache.zrem("scores", "李四");
+    
+    // 再次获取有序集合
+    const remainingScores = await cache.zrange("scores", 0, -1);
+    console.log("剩余成员:", remainingScores); // 输出: ["王五", "张三"]
 }
 ```
 
@@ -253,6 +490,449 @@ async function batchExample() {
     // 清空所有缓存
     await cache.clear();
 }
+
+### 事件系统使用示例
+```javascript
+async function eventExample() {
+    // 设置操作的前置事件
+    cache.on('set_before', (data) => {
+        console.log(`即将设置键: ${data.key}`);
+        
+        // 示例：进行数据验证
+        if (typeof data.value === 'string' && data.value.length > 100) {
+            console.log('值长度过长，取消设置');
+            data.cancel = true; // 取消操作
+        }
+    });
+    
+    // 获取操作的后置事件
+    cache.on('get_after', (data) => {
+        console.log(`获取键 ${data.key} 的结果: ${data.result}`);
+    });
+    
+    // 尝试设置缓存
+    await cache.set("test", "这是一个测试值");
+    
+    // 获取缓存
+    const value = await cache.get("test");
+    
+    // 错误事件监听
+    cache.on('get_error', (data) => {
+        console.error(`获取键 ${data.key} 时出错: ${data.error.message}`);
+    });
+}
+```
+
+## 事件系统
+
+CacheBase 提供了完整的事件系统，允许你监听各种缓存操作的前后事件，以便进行日志记录、数据验证或操作取消等功能。
+
+### 事件监听方法
+
+```javascript
+// 监听事件
+cache.on('event_name', callback);
+
+// 监听一次性事件
+cache.once('event_name', callback);
+
+// 移除事件监听
+cache.off('event_name', callback);
+```
+
+### 事件参数格式
+
+所有事件的回调函数都会接收一个标准化的事件数据对象，包含以下属性：
+
+- `key`: 操作的缓存键名（如果适用）
+- `value`: 操作的值，可以是基本类型或包含多个属性的对象
+- `result`: 操作的结果
+- `error`: 错误信息（仅错误事件）
+- `cancel`: 用于取消操作的标志（仅前置事件）
+- `ttl`: 过期时间（秒）（仅过期时间相关操作）
+
+### 支持的事件类型
+
+每个缓存操作都有对应的前置事件（`_before`）、后置事件（`_after`）和错误事件（`_error`）。以下是主要支持的事件类型：
+
+#### 基本操作事件
+- `set_before`, `set_after`, `set_error`
+- `get_before`, `get_after`, `get_error`
+- `del_before`, `del_after`, `del_error`
+- `exists_before`, `exists_after`, `exists_error`
+- `dispose_before`, `dispose_after`, `dispose_error`
+
+#### 哈希表操作事件
+- `hset_before`, `hset_after`, `hset_error`
+- `hget_before`, `hget_after`, `hget_error`
+- `hdel_before`, `hdel_after`, `hdel_error`
+- `hkeys_before`, `hkeys_after`, `hkeys_error`
+- `hvals_before`, `hvals_after`, `hvals_error`
+
+#### 列表操作事件
+- `lpush_before`, `lpush_after`, `lpush_error`
+- `lpop_before`, `lpop_after`, `lpop_error`
+- `rpush_before`, `rpush_after`, `rpush_error`
+- `rpop_before`, `rpop_after`, `rpop_error`
+- `llen_before`, `llen_after`, `llen_error`
+- `list_set_before`, `list_set_after`, `list_set_error`
+- `list_add_before`, `list_add_after`, `list_add_error`
+- `list_clear_before`, `list_clear_after`, `list_clear_error`
+
+#### 集合操作事件
+- `sadd_before`, `sadd_after`, `sadd_error`
+- `srem_before`, `srem_after`, `srem_error`
+- `smembers_before`, `smembers_after`, `smembers_error`
+- `sismember_before`, `sismember_after`, `sismember_error`
+- `scard_before`, `scard_after`, `scard_error`
+
+#### 有序集合操作事件
+- `zadd_before`, `zadd_after`, `zadd_error`
+- `zrange_before`, `zrange_after`, `zrange_error`
+- `zrem_before`, `zrem_after`, `zrem_error`
+- `zscore_before`, `zscore_after`, `zscore_error`
+
+#### 其他操作事件
+- `mset_before`, `mset_after`, `mset_error`
+- `setex_before`, `setex_after`, `setex_error`
+- `setnx_before`, `setnx_after`, `setnx_error`
+- `add_before`, `add_after`, `add_error`
+- `addFloat_before`, `addFloat_after`, `addFloat_error`
+- `addStr_before`, `addStr_after`, `addStr_error`
+- `setrange_before`, `setrange_after`, `setrange_error`
+
+### 取消操作示例
+
+在前置事件中，你可以通过设置 `cancel` 标志为 `true` 来取消操作：
+
+```javascript
+// 监听设置操作的前置事件
+cache.on('set_before', (data) => {
+    console.log('即将设置键:', data.key, '值:', data.value);
+    
+    // 检查值是否合法
+    if (typeof data.value !== 'string' || data.value.length > 100) {
+        console.log('值不合法，取消设置操作');
+        data.cancel = true; // 取消操作
+    }
+});
+
+// 监听获取操作的前置事件 - 实现访问控制
+cache.on('get_before', (data) => {
+    console.log('尝试获取键:', data.key);
+    
+    // 实现简单的访问控制
+    const restrictedKeys = ['admin_data', 'sensitive_info'];
+    if (restrictedKeys.includes(data.key) && !userHasPermission()) {
+        console.log('无权限访问此键，取消获取操作');
+        data.cancel = true; // 取消操作
+    }
+});
+
+// 监听集合删除操作的前置事件
+cache.on('srem_before', (data) => {
+    console.log('尝试从集合', data.key, '中删除成员:', data.value.member);
+    
+    // 防止删除特定成员
+    if (data.value.member === 'protected_member') {
+        console.log('保护成员不能删除，取消操作');
+        data.cancel = true;
+    }
+});
+
+// 监听删除键操作的前置事件
+cache.on('del_before', (data) => {
+    console.log('尝试删除键:', data.key);
+    
+    // 防止删除系统键
+    if (data.key.startsWith('system:')) {
+        console.log('系统键不能删除，取消操作');
+        data.cancel = true;
+    }
+});
+```
+
+### 完整事件系统示例
+
+以下是一个完整的示例，展示如何使用事件系统进行缓存操作的全面监控、日志记录和访问控制：
+
+```javascript
+const CacheBase = require('./index.js');
+
+async function eventSystemExample() {
+    const cache = new CacheBase();
+    
+    // 1. 实现统一的操作日志记录
+    const operations = ['get', 'set', 'del', 'exists', 'hget', 'hset', 
+                       'lpush', 'lpop', 'rpush', 'rpop', 'sadd', 'srem', 
+                       'smembers', 'zadd', 'zrange'];
+    
+    // 为所有操作添加日志记录
+    operations.forEach(op => {
+        // 记录操作开始
+        cache.on(`${op}_before`, (data) => {
+            console.log(`[CACHE] 开始 ${op} 操作`, {
+                key: data.key,
+                value: data.value,
+                timestamp: new Date().toISOString()
+            });
+        });
+        
+        // 记录操作成功完成
+        cache.on(`${op}_after`, (data) => {
+            console.log(`[CACHE] ${op} 操作成功`, {
+                key: data.key,
+                result: data.result,
+                timestamp: new Date().toISOString()
+            });
+        });
+        
+        // 记录操作失败
+        cache.on(`${op}_error`, (data) => {
+            console.error(`[CACHE] ${op} 操作失败`, {
+                key: data.key,
+                error: data.error.message,
+                timestamp: new Date().toISOString()
+            });
+        });
+    });
+    
+    // 2. 实现缓存操作统计
+    const stats = {
+        totalOperations: 0,
+        successfulOperations: 0,
+        failedOperations: 0,
+        canceledOperations: 0,
+        operationTypes: {}
+    };
+    
+    // 更新统计信息
+    operations.forEach(op => {
+        cache.on(`${op}_before`, () => {
+            stats.totalOperations++;
+            stats.operationTypes[op] = (stats.operationTypes[op] || 0) + 1;
+        });
+        
+        cache.on(`${op}_after`, (data) => {
+            if (op === 'get' && data.result === null) {
+                // 可以特殊处理缓存未命中的情况
+                console.log(`[CACHE] 缓存未命中: ${data.key}`);
+            }
+            stats.successfulOperations++;
+        });
+        
+        cache.on(`${op}_error`, () => {
+            stats.failedOperations++;
+        });
+    });
+    
+    // 3. 实现复杂的访问控制
+    const accessControl = {
+        // 定义哪些用户角色可以访问哪些键模式
+        permissions: {
+            'admin': ['*'],
+            'user': ['user:*', 'public:*'],
+            'guest': ['public:*']
+        },
+        
+        // 当前用户角色
+        currentRole: 'user'
+    };
+    
+    // 为敏感操作添加访问控制
+    ['get', 'del', 'hget', 'hdel'].forEach(op => {
+        cache.on(`${op}_before`, (data) => {
+            const hasPermission = accessControl.permissions[accessControl.currentRole].some(pattern => {
+                // 简单的通配符匹配实现
+                if (pattern === '*') return true;
+                const regexPattern = pattern.replace(/\*/g, '.*');
+                const regex = new RegExp(`^${regexPattern}$`);
+                return regex.test(data.key);
+            });
+            
+            if (!hasPermission) {
+                console.warn(`[SECURITY] 拒绝访问: 用户 ${accessControl.currentRole} 尝试访问键 ${data.key}`);
+                data.cancel = true;
+                stats.canceledOperations++;
+            }
+        });
+    });
+    
+    // 4. 执行一些测试操作
+    console.log('执行测试操作...');
+    
+    // 应该成功的操作
+    await cache.set('user:123:name', '张三');
+    await cache.hset('user:123:profile', 'email', 'zhangsan@example.com');
+    await cache.sadd('user:123:tags', 'vip');
+    
+    // 尝试访问无权限的键
+    const restrictedData = await cache.get('admin:settings');
+    console.log('受限访问结果:', restrictedData); // 应该是 null
+    
+    // 正常访问有权限的键
+    const userName = await cache.get('user:123:name');
+    console.log('用户名:', userName);
+    
+    // 5. 显示操作统计
+    console.log('\n操作统计:');
+    console.log(stats);
+    
+    // 6. 清理资源
+    await cache.dispose();
+}
+
+// 运行示例
+eventSystemExample().catch(console.error);
+```
+
+### 事件参数格式示例
+
+#### 基本操作事件数据
+```javascript
+// set_before 事件数据
+{
+  key: 'test_key',
+  value: 'test_value',
+  cancel: false
+}
+
+// set_after 事件数据
+{
+  key: 'test_key', 
+  value: 'test_value', 
+  result: 1
+}
+
+// get_before 事件数据
+{
+  key: 'test_key',
+  cancel: false
+}
+
+// get_after 事件数据
+{
+  key: 'test_key',
+  result: 'test_value'
+}
+
+// exists_before 事件数据
+{
+  key: 'test_key',
+  cancel: false
+}
+
+// exists_after 事件数据
+{
+  key: 'test_key',
+  result: 1 // 1表示存在，0表示不存在
+}
+
+// dispose_before 事件数据
+{
+  cancel: false
+}
+
+// dispose_after 事件无参数
+```
+
+#### 复合操作事件数据
+```javascript
+// hset_before 事件数据
+{
+  key: 'hash_key',
+  value: { field: 'field1', value: 'value1' },
+  cancel: false
+}
+
+// hget_before 事件数据
+{
+  key: 'hash_key',
+  value: { field: 'field1' },
+  cancel: false
+}
+
+// lpush_before 事件数据
+{
+  key: 'list_key',
+  value: { values: ['item1', 'item2'] },
+  cancel: false
+}
+
+// lpop_before/lpop_after 事件数据
+{
+  key: 'list_key',
+  cancel: false // lpop_after 中包含 result
+}
+
+// rpop_before/rpop_after 事件数据
+{
+  key: 'list_key',
+  cancel: false // rpop_after 中包含 result
+}
+
+// llen_before/llen_after 事件数据
+{
+  key: 'list_key',
+  cancel: false // llen_after 中包含 result
+}
+
+// srem_before 事件数据
+{
+  key: 'set_key',
+  value: { member: 'member1' },
+  cancel: false
+}
+
+// smembers_before/smembers_after 事件数据
+{
+  key: 'set_key',
+  cancel: false // smembers_after 中包含 result 数组
+}
+
+// sismember_before 事件数据
+{
+  key: 'set_key',
+  value: { member: 'member1' },
+  cancel: false
+}
+
+// scard_before/scard_after 事件数据
+{
+  key: 'set_key',
+  cancel: false // scard_after 中包含 result
+}
+
+// zrange_before 事件数据
+{
+  key: 'zset_key',
+  value: { start: 0, stop: -1, withScores: false },
+  cancel: false
+}
+
+// zrem_before 事件数据
+{
+  key: 'zset_key',
+  value: { member: 'zmember1' },
+  cancel: false
+}
+
+// zscore_before 事件数据
+{
+  key: 'zset_key',
+  value: { member: 'zmember1' },
+  cancel: false
+}
+
+#### 过期时间操作事件数据
+```javascript
+// setex_before 事件数据
+{
+  key: 'setex_key',
+  value: 'setex_value',
+  ttl: 60,
+  cancel: false
+}
 ```
 
 ## 注意事项
@@ -261,4 +941,8 @@ async function batchExample() {
 2. 过期时间单位为秒，-1表示永不过期
 3. 数组操作方法只能用于数组类型的缓存值
 4. 键名支持*通配符匹配，可用于批量操作
-5. 缓存数据存储在内存中，重启后数据会丢失
+5. 缓存数据存储在内存中，重启后数据会丢失
+6. 事件回调函数中的 `cancel` 标志只在前置事件中有效，后置事件中修改不会产生效果
+7. 当List、Set或Sorted Set类型的缓存变为空时，对应的键会被自动删除
+8. 所有事件参数都遵循统一的格式，包含key、value、result、error和cancel等字段
+9. 错误日志都添加了`[cachebase]`前缀，便于日志识别和过滤