mm_vars 1.0.0 → 1.1.0

package/README.md

@@ -19,12 +19,12 @@ npm install mm_vars
 const { Vars, varsAdmin } = require('mm_vars');
 
 // 直接使用存储类
-const vars = new Vars('./data/vars.json');
+const vars = new Vars({ file: './data/vars.json' });
 vars.set('step', 1).set('state', 'busy');
 vars.save();
 
 // 通过管理器按作用域获取实例（相同作用域返回同一实例）
-const scoped = varsAdmin('app', './data/app_vars.json');
+const scoped = varsAdmin('app', { file: './data/app_vars.json' });
 scoped.set('count', 10);
 ```
 
@@ -41,7 +41,7 @@ scoped.set('count', 10);
 | load | 从持久化文件加载 | - | boolean |
 
 ## 依赖
-- mm_corejs：提供 Admin 管理器
+- mm_admin：提供 Admin 管理器
 
 ## 许可证
 ISC

package/example/index.js

@@ -0,0 +1,49 @@
+/**
+ * mm_vars 变量存储示例
+ * 演示 varsAdmin() 作用域工厂，以及 Vars 类可随时修改、
+ * 删除的键值变量存取与 JSON 文件持久化（save / load）。
+ * 运行：node example/index.js
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { Vars, varsAdmin } = require('../index.js');
+
+/** 示例临时目录 */
+const TMP_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'mm-vars-example-'));
+
+/**
+ * 主流程
+ */
+function main() {
+  // 方式1：作用域工厂，获取 os 作用域的变量存储实例
+  const store = varsAdmin('os');
+  store.set('token', 'abc123');
+  console.log('工厂实例读取 token:', store.get('token'));
+
+  // 方式2：类实例 + 文件持久化
+  const file = path.join(TMP_DIR, 'vars.json');
+  const vars = new Vars({ file });
+  vars.set('name', 'demo').set('count', 1);
+  console.log('变量列表:', vars.list());
+  console.log('保存到文件:', vars.save());
+
+  // 变量可随时修改
+  vars.set('count', 2);
+  console.log('修改后 count:', vars.get('count'));
+
+  // 变量可删除
+  console.log('删除 name:', vars.del('name'));
+  console.log('删除后列表:', vars.list());
+
+  // 从文件重新加载（文件里是保存时的数据）
+  const loaded = new Vars({ file });
+  loaded.load();
+  console.log('重新加载后 name:', loaded.get('name'));
+  console.log('重新加载后 count:', loaded.get('count'));
+
+  // 清理临时目录
+  fs.rmSync(TMP_DIR, { recursive: true, force: true });
+}
+
+main();

package/index.js

@@ -1,7 +1,7 @@
-const Admin = require('mm_corejs').Admin;
+const { reg } = require('mm_admin');
 const Vars = require('./lib/vars.js');
 
-let admin = new Admin();
+const admin = reg('vars');
 admin.setClass(Vars);
 
 module.exports = {
@@ -14,9 +14,17 @@ module.exports = {
    * @returns {Vars} 变量存储实例
    */
   varsAdmin(scope, config) {
-    if (!scope) {
-      scope = 'os';
-    }
-    return admin.get(scope, config);
+    return admin.get(scope || 'os', config);
+  },
+  /**
+   * 获取缺省变量存储实例
+   * @returns {Vars} 变量存储实例
+   */
+  getVars() {
+    return admin.get('os');
   }
 };
+
+/* mm-tool-logic-export 工具能力层：其它模块可 require("<pkg>").tools.<name> 直接引用 */
+Object.defineProperty(module.exports, 'tools', { enumerable: true, configurable: true,
+  get: function () { return require('./lib/tools'); } });

package/jest.config.js

@@ -0,0 +1,18 @@
+'use strict';
+
+/**
+ * Jest 测试配置
+ */
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['<rootDir>/test/**/*.test.js'],
+  collectCoverageFrom: ['lib/**/*.js', 'index.js'],
+  coverageThreshold: {
+    global: {
+      branches: 100,
+      functions: 100,
+      lines: 100,
+      statements: 100
+    }
+  }
+};

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/lib/tools/variables/index.js

@@ -0,0 +1,73 @@
+/**
+ * 变量管理器
+ * 运行时 key-value 变量存储，支持读取/写入/删除/自增/条件判断
+ * 可作为工作流间的轻量状态共享层
+ */
+var _variables = {};
+
+async function main(params, ctx, options) {
+  var action = params.action || 'get';
+  var key = params.key;
+  var value = params.value;
+  var namespace = params.namespace || 'global';
+
+  var store = _getStore(namespace);
+
+  if (!key && action !== 'list' && action !== 'reset') {
+    ctx.output = { error: { code: 'MGR_MISSING_PARAM', message: '缺少 key 参数' } };
+    return ctx.output;
+  }
+
+  switch (action) {
+    case 'get':
+      ctx.output = { obj: store[key], key: key, namespace: namespace, exists: key in store };
+      break;
+    case 'set':
+      store[key] = value;
+      ctx.output = { msg: '变量设置成功', key: key, namespace: namespace };
+      break;
+    case 'delete':
+      delete store[key];
+      ctx.output = { msg: '变量删除成功', key: key, namespace: namespace };
+      break;
+    case 'increment':
+      if (typeof store[key] !== 'number') store[key] = 0;
+      store[key] += params.delta || 1;
+      ctx.output = { msg: '自增成功', key: key, value: store[key], namespace: namespace };
+      break;
+    case 'decrement':
+      if (typeof store[key] !== 'number') store[key] = 0;
+      store[key] -= params.delta || 1;
+      ctx.output = { msg: '自减成功', key: key, value: store[key], namespace: namespace };
+      break;
+    case 'toggle':
+      store[key] = !store[key];
+      ctx.output = { msg: '切换成功', key: key, value: store[key], namespace: namespace };
+      break;
+    case 'exists':
+      ctx.output = { obj: key in store, key: key, namespace: namespace };
+      break;
+    case 'list':
+      ctx.output = {
+        list: Object.keys(store),
+        count: Object.keys(store).length,
+        namespace: namespace
+      };
+      break;
+    case 'reset':
+      _variables[namespace] = {};
+      ctx.output = { msg: '命名空间已重置', namespace: namespace };
+      break;
+    default:
+      ctx.output = { error: { code: 'MGR_UNKNOWN_ACTION', message: '不支持的操作: ' + action } };
+  }
+
+  return ctx.output;
+}
+
+function _getStore(namespace) {
+  if (!_variables[namespace]) _variables[namespace] = {};
+  return _variables[namespace];
+}
+
+module.exports = { main };

package/lib/vars.js

@@ -1,4 +1,4 @@
-const KvStore = require('mm_corejs').KvStore;
+const KvStore = require('mm_kv_store').KvStore;
 
 /**
  * 变量存储类，可随时修改和删除

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "mm_vars",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "变量存储模块：用于存储可随时修改和删除的键值变量",
   "main": "index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/qiuwenwu91/mm_vars.git"
+  },
   "keywords": [
     "mm_mod",
     "mm_infra",
@@ -11,15 +15,16 @@
     "变量",
     "存储"
   ],
-  "layer": "infra",
-  "group": "data",
+  "layer": "infrastructure",
+  "group": "state",
   "author": "邱文武",
   "license": "ISC",
   "scripts": {
     "test": "jest --coverage"
   },
   "dependencies": {
-    "mm_corejs": "^1.1.4"
+    "mm_admin": "^1.1.0",
+    "mm_kv_store": "^1.0.0"
   },
   "devDependencies": {
     "jest": "^30.5.2"

package/test/vars.test.js

@@ -21,6 +21,10 @@ describe('mm_vars 模块入口', () => {
   it('varsAdmin 缺省作用域为 os', () => {
     expect(mod.varsAdmin()).toBeInstanceOf(Vars);
   });
+
+  it('getVars 返回 os 作用域的实例', () => {
+    expect(mod.getVars()).toBe(mod.varsAdmin());
+  });
 });
 
 describe('Vars', () => {
@@ -37,14 +41,14 @@ describe('Vars', () => {
   describe('构造', () => {
     it('默认不传文件路径时 file 为空字符串', () => {
       const vars = new Vars();
-      expect(vars._file).toBe('');
+      expect(vars.config.file).toBe('');
       expect(vars.list()).toEqual({});
     });
 
     it('传入文件路径时保存路径', () => {
       const file = path.join(tmp_dir, 'vars.json');
-      const vars = new Vars(file);
-      expect(vars._file).toBe(file);
+      const vars = new Vars({ file });
+      expect(vars.config.file).toBe(file);
     });
   });
 
@@ -141,7 +145,7 @@ describe('Vars', () => {
 
     it('save 写入文件返回 true', () => {
       const file = path.join(tmp_dir, 'vars.json');
-      const vars = new Vars(file);
+      const vars = new Vars({ file });
       vars.set('a', 1);
       expect(vars.save()).toBe(true);
       expect(JSON.parse(fs.readFileSync(file, 'utf8'))).toEqual({ a: 1 });
@@ -153,14 +157,14 @@ describe('Vars', () => {
     });
 
     it('文件不存在时 load 返回 false', () => {
-      const vars = new Vars(path.join(tmp_dir, 'nope.json'));
+      const vars = new Vars({ file: path.join(tmp_dir, 'nope.json') });
       expect(vars.load()).toBe(false);
     });
 
     it('文件存在时 load 加载数据返回 true', () => {
       const file = path.join(tmp_dir, 'vars.json');
       fs.writeFileSync(file, JSON.stringify({ a: 1, b: 'x' }));
-      const vars = new Vars(file);
+      const vars = new Vars({ file });
       expect(vars.load()).toBe(true);
       expect(vars.get('a')).toBe(1);
       expect(vars.get('b')).toBe('x');

package/tool/variables/index.js

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

package/tool/variables/tool.json

@@ -0,0 +1,68 @@
+{
+  "name": "variables",
+  "handler": "manager",
+  "title": "变量管理器",
+  "description": "运行时键值存储，支持读写、增减、切换与重置。适用场景：流程间传递状态、计数或开关时。工作流提示：action 选 get/set/delete/increment/decrement 等，namespace 隔离（默认 global），set 配 value、增减 delta，读在 obj/list、写在 msg。",
+  "type": "core",
+  "params": {
+    "type": "object",
+    "properties": {
+      "action": {
+        "type": "string",
+        "description": "操作: get/set/delete/increment/decrement/toggle/exists/list/reset",
+        "default": "get",
+        "enum": [
+          "get",
+          "set",
+          "delete",
+          "increment",
+          "decrement",
+          "toggle",
+          "exists",
+          "list",
+          "reset"
+        ]
+      },
+      "key": {
+        "type": "string",
+        "description": "变量名"
+      },
+      "value": {
+        "description": "变量值（set 模式）"
+      },
+      "namespace": {
+        "type": "string",
+        "description": "命名空间（隔离不同场景的变量）",
+        "default": "global"
+      },
+      "delta": {
+        "type": "number",
+        "description": "增量值（increment/decrement 模式）",
+        "default": 1
+      }
+    }
+  },
+  "returns": {
+    "description": "管理操作结果，读操作返回 obj 或 list+count，写操作返回 msg，异常时返回 error",
+    "type": "object",
+    "properties": {
+      "obj": {
+        "description": "读取操作的单条结果（get/exists 操作）"
+      },
+      "list": {
+        "type": "array",
+        "description": "变量名列表（list 操作）"
+      },
+      "count": {
+        "type": "number",
+        "description": "变量数量（list 操作）"
+      },
+      "msg": {
+        "type": "string",
+        "description": "写操作结果描述（set/delete/increment/decrement/toggle/reset 操作）"
+      }
+    }
+  },
+  "options": {},
+  "group": "state"
+}