mm_cachebase 2.0.6 → 2.0.7

package/README.md

@@ -267,3 +267,12 @@ async function pubsubExample() {
 - 发布订阅为进程内实现（mm_redis 支持跨进程）
 - 集合/有序集合用 JS 原生 `Set`/`Map` 实现，无 Redis 的 O(log N) 复杂度保证
 - 构造函数自动初始化（内存缓存特性），mm_redis 需显式 `open()`
+
+## 工具契约（LLM 可调用）
+
+本模块 `tool/` 下登记以下工具契约，实现位于 `lib/tools/<name>/`，`tool/<name>/index.js` 仅为薄适配层。
+其它模块可直接 `require('<pkg>').tools.<name>` 复用实现，无需经过工具注册面。
+
+| 工具名 | 标题 | 说明 |
+| --- | --- | --- |
+| `cachebase` | 进程内缓存 | 带过期的键值缓存与计数 |

package/cache/test_open_close.json

@@ -1 +1 @@
-{data:{},expires:{},types:{},timestamp:1793313151555}
+{data:{},expires:{},types:{},timestamp:1794643219183}

package/cache/test_set_get.json

@@ -1 +1 @@
-{data:{},expires:{},types:{},timestamp:1793313151543}
+{data:{},expires:{},types:{},timestamp:1794643219158}

package/index.js

@@ -1,28 +1,27 @@
 const CacheBase = require('./lib/cachebase');
-const Admin = require('mm_corejs').Admin;
+const { reg } = require('mm_admin');
 
 /**
  * 缓存管理器实例（Admin 工厂）
  */
-const admin = new Admin();
+const admin = reg('mm_cachebase');
 admin.setClass(CacheBase);
 
-/**
- * @description CacheBase管理器，用于创建缓存
- * @param {String} scope 作用域
- * @param {Object} config 配置参数
- * @return {Object} 返回一个CacheBase类实例
- */
-function cachebaseAdmin(scope, config) {
-	if (!scope) {
-		scope = 'os';
-	}
-	return admin.get(scope, config);
-}
-
 // 导出类
 module.exports = {
 	CacheBase,
 	admin,
-	cachebaseAdmin
-};
+	/**
+	 * @description CacheBase管理器，用于创建缓存
+	 * @param {String} scope 作用域
+	 * @param {Object} config 配置参数
+	 * @return {Object} 返回一个CacheBase类实例
+	 */
+	cachebaseAdmin(scope, config) {
+		return admin.get(scope || 'os', config);
+	}
+};
+
+/* mm-tool-logic-export 工具能力层：其它模块可 require("mm_cachebase").tools.<name> 直接引用 */
+Object.defineProperty(module.exports, 'tools', { enumerable: true, configurable: true,
+  get: function () { return require('./lib/tools'); } });

package/lib/tools/cachebase/index.js

@@ -0,0 +1,82 @@
+'use strict';
+/**
+ * cachebase —— 进程内缓存工具
+ * 复用模块 CacheBase 实例的 Redis 对齐 API，不另建缓存表。
+ */
+const { cachebaseAdmin } = require('../../../index.js');
+
+async function _ready(scope) {
+  const cache = cachebaseAdmin(scope || 'os');
+  if (typeof cache.isConnected === 'function' && !cache.isConnected()) {
+    await cache.init();
+  }
+  return cache;
+}
+
+async function main(params, ctx, options) {
+  void options;
+  const p = params || {};
+  const action = p.action || 'get';
+  const done = (data) => { ctx.output = data; return data; };
+
+  try {
+    const cache = await _ready(p.scope);
+
+    if (action === 'set') {
+      if (!p.key) throw new TypeError('key 不能为空');
+      if (Number(p.ttl) > 0) {
+        await cache.set(p.key, p.value, { ttl: Number(p.ttl) });
+      } else {
+        await cache.set(p.key, p.value);
+      }
+      return done({ code: 0, msg: '写入成功', key: p.key });
+    }
+
+    if (action === 'get') {
+      if (!p.key) throw new TypeError('key 不能为空');
+      const value = await cache.get(p.key);
+      return done({ code: 0, msg: '成功', key: p.key, value, exists: value !== null && value !== undefined });
+    }
+
+    if (action === 'del') {
+      if (!p.key) throw new TypeError('key 不能为空');
+      const deleted = await cache.del(p.key);
+      return done({ code: 0, msg: '删除完成', key: p.key, deleted: Number(deleted) || 0 });
+    }
+
+    if (action === 'has') {
+      if (!p.key) throw new TypeError('key 不能为空');
+      const exists = await cache.has(p.key);
+      return done({ code: 0, msg: '成功', key: p.key, exists: !!exists });
+    }
+
+    if (action === 'keys') {
+      const keys = await cache.keys(p.pattern || '*');
+      const list = Array.isArray(keys) ? keys : Object.keys(keys || {});
+      return done({ code: 0, msg: '成功', count: list.length, keys: list });
+    }
+
+    if (action === 'incr') {
+      if (!p.key) throw new TypeError('key 不能为空');
+      const value = await cache.incrby(p.key, Number(p.delta || 1));
+      return done({ code: 0, msg: '成功', key: p.key, value });
+    }
+
+    if (action === 'ttl') {
+      if (!p.key) throw new TypeError('key 不能为空');
+      const ttl = await cache.ttl(p.key);
+      return done({ code: 0, msg: '成功', key: p.key, ttl });
+    }
+
+    if (action === 'clear') {
+      await cache.clear();
+      return done({ code: 0, msg: '已清库' });
+    }
+
+    return done({ code: 10001, msg: '不支持的操作: ' + action });
+  } catch (error) {
+    return done({ code: 10000, msg: '执行失败：' + error.message, error: { name: error.name, message: error.message } });
+  }
+}
+
+module.exports = { main };

package/lib/tools/index.js

@@ -0,0 +1,16 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+/** 模块能力层：懒加载工具实现，避免模块入口被 require 时加载全部实现 */
+module.exports = new Proxy({}, {
+  get(_t, key) {
+    if (typeof key !== 'string') return undefined;
+    if (!fs.existsSync(path.join(__dirname, key, 'index.js'))) return undefined;
+    return require('./' + key);
+  },
+  has(_t, key) {
+    return typeof key === 'string' && fs.existsSync(path.join(__dirname, key, 'index.js'));
+  },
+  ownKeys() { return fs.readdirSync(__dirname, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name); },
+  getOwnPropertyDescriptor(_t, key) { return this.has(_t, key) ? { enumerable: true, configurable: true } : undefined; }
+});

package/package.json

@@ -1,54 +1,55 @@
 {
-    "name": "mm_cachebase",
-    "version": "2.0.6",
-    "description": "一个轻量级的本地缓存类库，接口与 mm_redis 完全对齐：全异步API、冒号风格事件、统一签名与返回值，支持字符串、哈希、列表、集合、有序集合、发布订阅。",
-    "main": "index.js",
-    "scripts": {
-        "test": "node test.js"
-    },
-    "repository": {
-        "type": "git",
-        "url": "git+https://gitee.com/qiuwenwu91/mm_cachebase.git"
-    },
-    "keywords": [
-        "mm_mod",
-        "mm_port",
-        "mm_cache",
-        "cachebase",
-        "redis",
-        "cache",
-        "memory-cache",
-        "local-cache",
-        "async",
-        "await",
-        "promise",
-        "set",
-        "get",
-        "del",
-        "hash",
-        "event",
-        "ttl",
-        "expire",
-        "incr",
-        "decr",
-        "persistence",
-        "persist",
-        "scope"
-    ],
-    "layer": "adapter",
-    "group": "cache",
-    "author": "邱文武",
-    "license": "MIT",
-    "bugs": {
-        "url": "https://gitee.com/qiuwenwu91/mm_cachebase/issues"
-    },
-    "homepage": "https://gitee.com/qiuwenwu91/mm_cachebase#readme",
-    "dependencies": {
-        "mm_corejs": "^1.1.5",
-        "mm_mod": "^1.0.1",
-        "mm_helper": "^1.0.1"
-    },
-    "devDependencies": {
-        "mm_eslint": "^1.7.7"
-    }
+  "name": "mm_cachebase",
+  "version": "2.0.7",
+  "description": "一个轻量级的本地缓存类库，接口与 mm_redis 完全对齐：全异步API、冒号风格事件、统一签名与返回值，支持字符串、哈希、列表、集合、有序集合、发布订阅。",
+  "main": "index.js",
+  "scripts": {
+    "test": "node test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/qiuwenwu91/mm_cachebase.git"
+  },
+  "keywords": [
+    "mm_mod",
+    "mm_port",
+    "mm_cache",
+    "cachebase",
+    "redis",
+    "cache",
+    "memory-cache",
+    "local-cache",
+    "async",
+    "await",
+    "promise",
+    "set",
+    "get",
+    "del",
+    "hash",
+    "event",
+    "ttl",
+    "expire",
+    "incr",
+    "decr",
+    "persistence",
+    "persist",
+    "scope"
+  ],
+  "layer": "infrastructure",
+  "group": "cache",
+  "author": "邱文武",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://gitee.com/qiuwenwu91/mm_cachebase/issues"
+  },
+  "homepage": "https://gitee.com/qiuwenwu91/mm_cachebase#readme",
+  "dependencies": {
+    "mm_admin": "^1.1.0",
+    "mm_eslint": "^1.0.0",
+    "mm_helper": "^1.0.1",
+    "mm_mod": "^1.0.1"
+  },
+  "devDependencies": {
+    "mm_eslint": "^1.7.7"
+  }
 }

package/tool/cachebase/index.js

@@ -0,0 +1,7 @@
+'use strict';
+/**
+ * cachebase —— 工具契约适配层
+ * 业务实现归位于模块 lib/tools/cachebase/，本文件只把模块能力暴露给加载器。
+ * 其它模块可直接 require('mm_cachebase').tools.cachebase 复用。
+ */
+module.exports = require('../../lib/tools/cachebase');

package/tool/cachebase/tool.json

@@ -0,0 +1,99 @@
+{
+  "name": "cachebase",
+  "title": "进程内缓存",
+  "description": "基于 mm_cachebase 的本地缓存能力（接口与 Redis 对齐）：写入带过期时间的键、读取、删除、列键、自增、查剩余 TTL、清库。适用场景：缓存接口结果、做去重计数、临时限流状态。工作流提示：set 传 key/value/ttl(秒)，incr 用于计数。",
+  "category": "缓存",
+  "group": "cache",
+  "type": "function",
+  "main": "./index.js",
+  "params": {
+    "type": "object",
+    "properties": {
+      "action": {
+        "type": "string",
+        "description": "操作类型: set(写入缓存)/get(读取)/del(删除)/has(判断存在)/keys(列键)/incr(自增)/ttl(剩余过期)/clear(清库)",
+        "enum": [
+          "set",
+          "get",
+          "del",
+          "has",
+          "keys",
+          "incr",
+          "ttl",
+          "clear"
+        ],
+        "default": "set"
+      },
+      "key": {
+        "type": "string",
+        "description": "缓存键(get/del/has/incr/ttl/set 必填)"
+      },
+      "value": {
+        "description": "缓存值(set 必填)"
+      },
+      "ttl": {
+        "type": "number",
+        "description": "过期秒数(set 可选)，0 表示不过期"
+      },
+      "delta": {
+        "type": "number",
+        "description": "自增步长(incr 可选)，缺省 1",
+        "default": 1
+      },
+      "pattern": {
+        "type": "string",
+        "description": "键匹配模式(keys 可选)，缺省 *",
+        "default": "*"
+      },
+      "scope": {
+        "type": "string",
+        "description": "实例作用域，缺省 os",
+        "default": "os"
+      }
+    },
+    "required": [
+      "action"
+    ]
+  },
+  "returns": {
+    "type": "object",
+    "properties": {
+      "code": {
+        "type": "number",
+        "description": "0 表示成功，1xxxx 表示业务/执行异常"
+      },
+      "msg": {
+        "type": "string",
+        "description": "结果描述"
+      },
+      "value": {
+        "description": "缓存值(get)"
+      },
+      "exists": {
+        "type": "boolean",
+        "description": "是否存在"
+      },
+      "keys": {
+        "type": "array",
+        "description": "键列表(keys)"
+      },
+      "count": {
+        "type": "number",
+        "description": "数量"
+      },
+      "ttl": {
+        "type": "number",
+        "description": "剩余过期秒数，-1 永久，-2 不存在(ttl)"
+      },
+      "deleted": {
+        "type": "number",
+        "description": "删除的键数(del)"
+      },
+      "error": {
+        "type": "object",
+        "description": "异常对象 { name, message }"
+      }
+    }
+  },
+  "handler": "manager"
+}