mm_cachebase 1.4.5 → 1.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 邱文武
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,14 @@
 # mm_cachebase
 
-一个轻量级的本地缓存类库，提供了丰富的缓存操作接口，支持过期时间设置、数组操作等功能。
+一个轻量级的本地缓存类库，提供了与Redis兼容的缓存操作接口，支持过期时间设置、哈希表操作、数值操作、字符串操作等功能，以及完整的事件通知系统。
+
+## 特点
+
+- **Redis兼容API**：实现了与npm redis模块相似的接口，便于无缝切换
+- **轻量级设计**：纯JavaScript实现，无外部依赖
+- **完整的事件系统**：支持前置/后置/错误事件，便于日志记录和访问控制
+- **过期时间管理**：支持设置和查询键的过期时间
+- **丰富的数据类型支持**：支持字符串、哈希表等Redis常见数据类型
 
 ## 安装
 
@@ -38,9 +46,7 @@ async function example() {
 const cache = new CacheBase();
 ```
 
-创建一个新的缓存实例。缓存实例包含以下属性：
-- `list`: 存储缓存数据的数组
-- `func`: 到期通知函数（可选）
+创建一个新的缓存实例。缓存实例基于EventEmitter，支持完整的事件系统。
 
 ### 基本操作
 
@@ -51,14 +57,14 @@ await cache.set(key, value, maxAge)
 - `key`: 缓存键名
 - `value`: 缓存的值
 - `maxAge`: 过期时间（秒），-1表示永不过期
-- 返回: 设置的值
+- 返回: 'OK'
 
 #### 获取缓存
 ```javascript
 await cache.get(key)
 ```
 - `key`: 缓存键名
-- 返回: 缓存值，不存在则返回undefined
+- 返回: 缓存值，不存在则返回null
 
 #### 删除缓存
 ```javascript
@@ -67,120 +73,291 @@ await cache.del(key)
 - `key`: 缓存键名
 - 返回: 成功返回1，失败返回0
 
-#### 添加缓存
+#### 设置并获取旧值
 ```javascript
-await cache.add(key, value, maxAge)
+await cache.getset(key, value, maxAge)
 ```
-- 只在键不存在时添加缓存
-- 返回: 添加成功返回值，已存在返回0
+- 先获取旧值，然后设置新值
+- 返回: 旧值，不存在则返回null
+
+#### 批量设置缓存
+```javascript
+await cache.mset(keys, values, maxAge)
+```
+- `keys`: 键名数组
+- `values`: 值数组
+- 返回: 'OK'
+
+#### 批量获取缓存
+```javascript
+await cache.mget(...keys)
+```
+- `keys`: 一个或多个键名
+- 返回: 值数组
 
 #### 判断键是否存在
 ```javascript
-await cache.has(key)
+await cache.exists(...keys)
 ```
-- 返回: 存在返回1，不存在返回0
+- `keys`: 一个或多个键名
+- 返回: 存在的键数量
 
 ### 过期时间操作
 
-#### 设置/查询过期时间
+#### 设置过期时间
 ```javascript
-await cache.ttl(key, maxAge)
+await cache.expire(key, maxAge)
 ```
-- `maxAge`: 不传则查询剩余时间，传入则设置新的过期时间
-- 返回: 查询时返回剩余秒数，设置时返回1
+- `maxAge`: 过期时间（秒）
+- 返回: 成功返回1，失败返回0
+
+#### 查询剩余过期时间
+```javascript
+await cache.ttl(key)
+```
+- 返回: 剩余秒数，不存在或永不过期返回-1
+
+#### 移除过期时间
+```javascript
+await cache.persist(key)
+```
+- 返回: 成功返回1，失败返回0
 
 ### 数值操作
 
 #### 增加整数
 ```javascript
-await cache.addInt(key, num)
+await cache.incr(key)
 ```
-- `num`: 要增加的数值，可以为负数
-- 返回: 计算后的结果
+- 将键的值加1
+- 返回: 增加后的值
+
+#### 增加指定整数
+```javascript
+await cache.incrby(key, increment)
+```
+- `increment`: 要增加的整数
+- 返回: 增加后的值
+
+#### 减少整数
+```javascript
+await cache.decr(key)
+```
+- 将键的值减1
+- 返回: 减少后的值
+
+#### 减少指定整数
+```javascript
+await cache.decrby(key, decrement)
+```
+- `decrement`: 要减少的整数
+- 返回: 减少后的值
 
 #### 增加浮点数
 ```javascript
-await cache.addFloat(key, num)
+await cache.incrbyfloat(key, increment)
 ```
-- 用法同addInt，支持浮点数
+- `increment`: 要增加的浮点数
+- 返回: 增加后的值
 
 ### 字符串操作
 
 #### 追加字符串
 ```javascript
-await cache.addStr(key, str)
+await cache.append(key, value)
 ```
 - 在已有字符串后追加新字符串
-- 返回: 追加后的完整字符串
+- 返回: 追加后的字符串长度
+
+#### 获取字符串长度
+```javascript
+await cache.strlen(key)
+```
+- 返回: 字符串长度
+
+### 哈希表操作
 
-#### 获取子字符串
+#### 设置哈希表字段
 ```javascript
-await cache.getrange(key, start, end)
+await cache.hset(key, field, value)
 ```
-- 获取缓存字符串的指定范围
-- 返回: 截取的字符串
+- `key`: 哈希表的键名
+- `field`: 字段名
+- `value`: 字段值
+- 返回: 成功返回1，失败返回0
+
+#### 获取哈希表字段
+```javascript
+await cache.hget(key, field)
+```
+- 返回: 字段值，不存在则返回null
+
+#### 获取哈希表所有字段和值
+```javascript
+await cache.hgetall(key)
+```
+- 返回: 包含所有字段和值的对象
 
-#### 替换字符串
+#### 删除哈希表字段
 ```javascript
-await cache.setrange(key, index, value)
+await cache.hdel(key, field)
 ```
-- 从指定位置替换字符串
+- 返回: 成功返回1，失败返回0
 
-### 数组操作
+### 键操作
 
-#### 设置数组
+#### 获取所有键名
 ```javascript
-await cache.list_set(key, value, maxAge)
+await cache.keys(pattern)
 ```
-- 设置一个数组类型的缓存
+- `pattern`: 支持*通配符的匹配模式
+- 返回: 匹配的键名数组
 
-#### 添加数组元素
+#### 获取键数量
 ```javascript
-await cache.list_add(key, value)
+await cache.dbsize()
 ```
-- 向数组末尾添加元素
-- 返回: 成功返回1，失败返回-1
+- 返回: 缓存中的键数量
 
-#### 判断数组元素是否存在
+#### 清空缓存
 ```javascript
-await cache.list_has(key, value)
+await cache.flushdb()
 ```
-- 检查数组中是否包含指定元素
+- 清空所有缓存
+- 返回: 'OK'
 
-#### 获取数组片段
+#### 销毁缓存实例
 ```javascript
-await cache.list_get(key, start, end)
+await cache.dispose()
 ```
-- 获取数组的指定范围元素
+- 清理所有资源，移除所有监听器
+
+### 兼容方法（保持向后兼容）
 
-#### 清空/重置数组
+#### 添加缓存（仅当键不存在时）
 ```javascript
-await cache.list_clear(key, value)
+await cache.add(key, value, maxAge)
 ```
-- 清空数组或用新数组替换
+- 返回: 添加成功返回值，已存在返回0
 
-### 其他操作
+#### 检查键是否存在
+```javascript
+await cache.has(key)
+```
+- 返回: 存在返回1，不存在返回0
 
-#### 排序
+#### 增加浮点数（兼容方法）
 ```javascript
-await cache.sort(key, way, obj_key)
+await cache.addFloat(key, num)
 ```
-- `way`: 'asc'升序或'desc'降序
-- `obj_key`: 如果数组元素是对象，指定排序的键
+- `num`: 要增加的浮点数
+- 返回: 计算后的结果
 
-#### 获取所有键名
+#### 追加字符串（兼容方法）
 ```javascript
-await cache.keys(pattern)
+await cache.addStr(key, str)
 ```
-- `pattern`: 支持*通配符的匹配模式
-- 返回: 匹配的键名数组
+- 返回: 追加后的完整字符串
 
-#### 清空缓存
+#### 清空匹配缓存（兼容方法）
 ```javascript
 await cache.clear(pattern)
 ```
-- `pattern`: 可选，支持*通配符，清空匹配的键
-- 不传则清空所有缓存
+- `pattern`: 可选，支持*通配符
+
+## 事件系统
+
+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`
+- `mset_before`, `mset_after`, `mset_error`
+- `mget_before`, `mget_after`, `mget_error`
+
+#### 过期时间操作事件
+- `expire_before`, `expire_after`, `expire_error`
+- `ttl_before`, `ttl_after`, `ttl_error`
+
+#### 数值操作事件
+- `incr_before`, `incr_after`, `incr_error`
+- `decr_before`, `decr_after`, `decr_error`
+- `incrby_before`, `incrby_after`, `incrby_error`
+- `decrby_before`, `decrby_after`, `decrby_error`
+- `incrbyfloat_before`, `incrbyfloat_after`, `incrbyfloat_error`
+
+#### 字符串操作事件
+- `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`
+
+### 事件使用示例
+
+```javascript
+const cache = new CacheBase();
+
+// 监听设置操作的前置事件
+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_after', (data) => {
+    console.log(`获取键 ${data.key} 的结果: ${data.result}`);
+});
+
+// 错误事件监听
+cache.on('get_error', (data) => {
+    console.error(`获取键 ${data.key} 时出错: ${data.error.message}`);
+});
+```
 
 ## 使用示例
 
@@ -197,7 +374,7 @@ async function example() {
     console.log(user); // 输出: 张三
     
     // 检查是否存在
-    const exists = await cache.has("user");
+    const exists = await cache.exists("user");
     console.log(exists); // 输出: 1
     
     // 删除缓存
@@ -205,53 +382,72 @@ 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 user = await cache.hgetall("user:123");
+    console.log(user); // 输出: { name: "张三", age: 30, email: "zhangsan@example.com" }
     
-    // 排序
-    await cache.sort("users", "asc");
+    // 删除字段
+    await cache.hdel("user:123", "email");
 }
 ```
 
-### 过期时间管理
+### 数值操作示例
 ```javascript
-async function ttlExample() {
-    // 设置缓存
-    await cache.set("token", "abc123", 30);
+async function numberExample() {
+    // 设置初始值
+    await cache.set("counter", 10);
+    
+    // 增加1
+    const incr = await cache.incr("counter");
+    console.log("增加后:", incr); // 输出: 11
     
-    // 查询剩余时间
-    const ttl = await cache.ttl("token");
-    console.log(`剩余${ttl}秒`);
+    // 增加指定值
+    const incrby = await cache.incrby("counter", 5);
+    console.log("增加5后:", incrby); // 输出: 16
     
-    // 延长过期时间
-    await cache.ttl("token", 60);
+    // 减少1
+    const decr = await cache.decr("counter");
+    console.log("减少后:", decr); // 输出: 15
     
-    // 设置永不过期
-    await cache.ttl("token", -1);
+    // 浮点数操作
+    await cache.set("price", 99.99);
+    const incrFloat = await cache.incrbyfloat("price", 0.01);
+    console.log("浮点数增加后:", incrFloat); // 输出: 100
 }
 ```
 
-### 批量操作
+### 批量操作示例
 ```javascript
 async function batchExample() {
-    // 获取所有以user开头的键
-    const keys = await cache.keys("user*");
+    // 批量设置
+    await cache.mset(["key1", "key2", "key3"], ["value1", "value2", "value3"]);
+    
+    // 批量获取
+    const values = await cache.mget("key1", "key2", "key3");
+    console.log("批量获取:", values); // 输出: ["value1", "value2", "value3"]
     
-    // 清空所有以temp开头的缓存
-    await cache.clear("temp*");
+    // 检查多个键是否存在
+    const existsCount = await cache.exists("key1", "key2", "nonexistent");
+    console.log("存在的键数量:", existsCount); // 输出: 2
+    
+    // 获取键数量
+    const count = await cache.dbsize();
+    console.log("键总数:", count);
     
     // 清空所有缓存
-    await cache.clear();
+    await cache.flushdb();
 }
 ```
 
@@ -259,6 +455,10 @@ async function batchExample() {
 
 1. 所有操作方法都是异步的，需要使用async/await或Promise处理
 2. 过期时间单位为秒，-1表示永不过期
-3. 数组操作方法只能用于数组类型的缓存值
-4. 键名支持*通配符匹配，可用于批量操作
-5. 缓存数据存储在内存中，重启后数据会丢失
+3. 缓存数据存储在内存中，重启后数据会丢失
+4. 事件回调函数中的 `cancel` 标志只在前置事件中有效，后置事件中修改不会产生效果
+5. 所有事件参数都遵循统一的格式，包含key、value、result、error和cancel等字段
+
+## 许可证
+
+MIT

package/compatibility_table.md

@@ -0,0 +1,63 @@
+```markdown
+# 三种缓存方式方法兼容性对比表格
+
+## 核心缓存方法
+
+| 方法名 | Redis | MongoDB | CacheBase | 状态说明 |
+|-------|-------|---------|-----------|----------|
+| set | ✅ | ✅ | ✅ | 完全兼容 |
+| get | ✅ | ✅ | ✅ | 完全兼容 |
+| del | ✅ | ✅ | ✅ | 完全兼容 |
+| has | ❌ | ✅ | ✅ | Redis无此方法，CacheBase保持兼容 |
+| clear | ❌ | ✅ | ✅ | Redis无此方法，CacheBase保持兼容 |
+| keys | ✅ | ✅ | ✅ | 完全兼容 |
+| ttl | ✅ | ❌ | ✅ | Redis原生支持，CacheBase模拟实现 |
+| add | ❌ | ✅ | ✅ | Redis无此方法，CacheBase保持兼容 |
+| addInt | ❌ | ✅ | ✅ | Redis无此方法，CacheBase保持兼容 |
+| addStr | ❌ | ✅ | ✅ | Redis无此方法，CacheBase保持兼容 |
+| sort | ✅ | ❌ | ✅ | Redis原生支持，CacheBase模拟实现 |
+
+## Redis兼容方法 - 哈希表操作
+
+| 方法名 | Redis | MongoDB | CacheBase | 状态说明 |
+|-------|-------|---------|-----------|----------|
+| hset | ✅ | ✅ | ✅ | 模拟实现，通过set对象方式 |
+| hget | ✅ | ✅ | ✅ | 模拟实现，通过get对象方式 |
+| hgetall | ✅ | ✅ | ✅ | 模拟实现，返回完整对象 |
+| hdel | ✅ | ✅ | ✅ | 模拟实现，删除对象属性 |
+| hexists | ✅ | ❌ | ❌ | Redis原生支持，CacheBase未实现 |
+| hkeys | ✅ | ❌ | ❌ | Redis原生支持，CacheBase未实现 |
+| hvals | ✅ | ❌ | ❌ | Redis原生支持，CacheBase未实现 |
+
+## Redis兼容方法 - 集合操作
+
+| 方法名 | Redis | MongoDB | CacheBase | 状态说明 |
+|-------|-------|---------|-----------|----------|
+| sadd | ✅ | ❌ | ❌ | Redis原生支持，CacheBase未实现 |
+| srem | ✅ | ❌ | ❌ | Redis原生支持，CacheBase未实现 |
+| sismember | ✅ | ❌ | ❌ | Redis原生支持，CacheBase未实现 |
+| smembers | ✅ | ❌ | ❌ | Redis原生支持，CacheBase未实现 |
+| scard | ✅ | ❌ | ❌ | Redis原生支持，CacheBase未实现 |
+
+## Redis兼容方法 - 有序集合操作
+
+| 方法名 | Redis | MongoDB | CacheBase | 状态说明 |
+|-------|-------|---------|-----------|----------|
+| zadd | ✅ | ❌ | ❌ | Redis原生支持，CacheBase未实现 |
+| zrem | ✅ | ❌ | ❌ | Redis原生支持，CacheBase未实现 |
+| zrange | ✅ | ❌ | ❌ | Redis原生支持，CacheBase未实现 |
+| zscore | ✅ | ❌ | ❌ | Redis原生支持，CacheBase未实现 |
+
+## Redis兼容方法 - 其他常用命令
+
+| 方法名 | Redis | MongoDB | CacheBase | 状态说明 |
+|-------|-------|---------|-----------|----------|
+| expire | ✅ | ❌ | ✅ | Redis原生支持，CacheBase通过ttl模拟 |
+| incr | ✅ | ⚠️ | ✅ | Redis原生支持，MongoDB返回undefined，CacheBase通过addInt模拟 |
+| decr | ✅ | ⚠️ | ✅ | Redis原生支持，MongoDB返回undefined，CacheBase通过addInt模拟 |
+| exists | ✅ | ✅ | ✅ | 兼容，Redis原生支持 |
+| mget | ✅ | ⚠️ | ✅ | Redis原生支持，CacheBase实现兼容 |
+| mset | ✅ | ✅ | ✅ | Redis原生支持，CacheBase实现兼容 |
+
+注：✅ 完全兼容/功能正常 | ⚠️ 部分兼容/有异常 | ❌ 不兼容/未实现
+```