mm_dict 1.0.2 → 1.0.4

package/README.md

@@ -18,12 +18,12 @@ npm install mm_dict
 const { Dict, dictAdmin } = require('mm_dict');
 
 // 直接使用存储类
-const dict = new Dict('./data/dict.json');
+const dict = new Dict({ file: './data/dict.json' });
 dict.set('val', 'value').set('生命值', 'hp');
 dict.save();
 
 // 通过管理器按作用域获取实例（相同作用域返回同一实例）
-const scoped = dictAdmin('app', './data/app_dict.json');
+const scoped = dictAdmin('app', { file: './data/app_dict.json' });
 scoped.set('HP', 'hp');
 ```
 
@@ -40,7 +40,16 @@ scoped.set('HP', 'hp');
 | load | 从持久化文件加载 | - | boolean |
 
 ## 依赖
-- mm_corejs：提供 Admin 管理器
+- mm_admin：提供 Admin 管理器
 
 ## 许可证
 ISC
+
+## 工具契约（LLM 可调用）
+
+本模块 `tool/` 下登记以下工具契约，实现位于 `lib/tools/<name>/`，`tool/<name>/index.js` 仅为薄适配层。
+其它模块可直接 `require('<pkg>').tools.<name>` 复用实现，无需经过工具注册面。
+
+| 工具名 | 标题 | 说明 |
+| --- | --- | --- |
+| `dict` | 字符串字典 | 字符串键值字典读写 |

package/example/index.js

@@ -23,14 +23,14 @@ function main() {
 
   // 方式2：类实例 + 文件持久化
   const file = path.join(TMP_DIR, 'dict.json');
-  const dict = new Dict(file);
+  const dict = new Dict({ file });
   dict.set('zh', '中文').set('en', 'English');
   console.log('字典列表:', dict.list());
   console.log('has(zh):', dict.has('zh'));
   console.log('保存到文件:', dict.save());
 
   // 从文件重新加载
-  const loaded = new Dict(file);
+  const loaded = new Dict({ file });
   loaded.load();
   console.log('加载后读取 en:', loaded.get('en'));
 

package/index.js

@@ -1,7 +1,7 @@
-const Admin = require('mm_corejs').Admin;
+const { reg } = require('mm_admin');
 const Dict = require('./lib/dict.js');
 
-let admin = new Admin();
+const admin = reg('dict');
 admin.setClass(Dict);
 
 module.exports = {
@@ -14,12 +14,13 @@ module.exports = {
    * @returns {Dict} 字典存储实例
    */
   dictAdmin(scope, config) {
-    if (!scope) {
-      scope = 'os';
-    }
-    return admin.get(scope, config);
+    return admin.get(scope || 'os', config);
   },
   getDict() {
     return admin.get('os');
   }
 };
+
+/* mm-tool-logic-export 工具能力层：其它模块可 require("mm_dict").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/dict.js

@@ -17,14 +17,6 @@ class Dict extends KvStore {
       throw new TypeError('dict 的值必须是字符串');
     }
   }
-  
-  /**
-   * 是否允许覆盖已存在的配置项
-   * @returns {boolean} 不允许覆盖返回 false
-   */
-  _isOverwritable() {
-    return false;
-  }
 }
 
 module.exports = Dict;

package/lib/tools/dict/index.js

@@ -0,0 +1,70 @@
+'use strict';
+/**
+ * dict —— 字符串字典工具
+ * 复用模块 Dict 实例（键值字符串约束由模块强制）。
+ */
+const { dictAdmin } = require('../../../index.js');
+
+/**
+ * 落盘：未配置持久化文件时只保留内存结果
+ * @param {object} store 存储实例
+ * @returns {boolean} 是否已落盘
+ */
+function _save(store) {
+  const file = (store.config && store.config.file) || '';
+  if (!file) return false;
+  store.save();
+  return true;
+}
+
+async function main(params, ctx, options) {
+  void options;
+  const p = params || {};
+  const action = p.action || 'list';
+  const done = (data) => { ctx.output = data; return data; };
+
+  try {
+    const store = dictAdmin(p.scope || 'os');
+
+    if (action === 'set') {
+      if (!p.key) throw new TypeError('key 不能为空');
+      if (typeof p.value !== 'string') throw new TypeError('value 必须是字符串');
+      store.set(p.key, p.value);
+      _save(store);
+      return done({ code: 0, msg: '写入成功', key: p.key });
+    }
+
+    if (action === 'get') {
+      if (!p.key) throw new TypeError('key 不能为空');
+      return done({ code: 0, msg: '成功', key: p.key, value: store.get(p.key), exists: store.has(p.key) });
+    }
+
+    if (action === 'del') {
+      if (!p.key) throw new TypeError('key 不能为空');
+      const deleted = store.del(p.key);
+      _save(store);
+      return done({ code: 0, msg: deleted ? '删除成功' : '键不存在', key: p.key, deleted: !!deleted });
+    }
+
+    if (action === 'has') {
+      if (!p.key) throw new TypeError('key 不能为空');
+      return done({ code: 0, msg: '成功', key: p.key, exists: store.has(p.key) });
+    }
+
+    if (action === 'list') {
+      const list = store.list();
+      return done({ code: 0, msg: '成功', list, count: Object.keys(list || {}).length });
+    }
+
+    if (action === 'save') {
+      _save(store);
+      return done({ code: 0, msg: '已落盘', ok: true });
+    }
+
+    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,6 +1,6 @@
 {
   "name": "mm_dict",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "字典存储模块：键和值都只能是字符串，用于键值映射",
   "main": "index.js",
   "repository": {
@@ -15,15 +15,15 @@
     "字典",
     "存储"
   ],
-  "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": {

package/test/dict.test.js

@@ -21,6 +21,10 @@ describe('mm_dict 模块入口', () => {
   it('dictAdmin 缺省作用域为 os', () => {
     expect(mod.dictAdmin()).toBeInstanceOf(Dict);
   });
+
+  it('getDict 返回 os 作用域的实例', () => {
+    expect(mod.getDict()).toBeInstanceOf(Dict);
+  });
 });
 
 describe('Dict', () => {
@@ -37,14 +41,14 @@ describe('Dict', () => {
   describe('构造', () => {
     it('默认不传文件路径时 file 为空字符串', () => {
       const dict = new Dict();
-      expect(dict._file).toBe('');
+      expect(dict.config.file).toBe('');
       expect(dict.list()).toEqual({});
     });
 
     it('传入文件路径时保存路径', () => {
       const file = path.join(tmp_dir, 'dict.json');
-      const dict = new Dict(file);
-      expect(dict._file).toBe(file);
+      const dict = new Dict({ file });
+      expect(dict.config.file).toBe(file);
     });
   });
 
@@ -146,7 +150,7 @@ describe('Dict', () => {
 
     it('save 写入文件返回 true', () => {
       const file = path.join(tmp_dir, 'dict.json');
-      const dict = new Dict(file);
+      const dict = new Dict({ file });
       dict.set('val', 'value');
       expect(dict.save()).toBe(true);
       expect(JSON.parse(fs.readFileSync(file, 'utf8'))).toEqual({ val: 'value' });
@@ -158,14 +162,14 @@ describe('Dict', () => {
     });
 
     it('文件不存在时 load 返回 false', () => {
-      const dict = new Dict(path.join(tmp_dir, 'nope.json'));
+      const dict = new Dict({ file: path.join(tmp_dir, 'nope.json') });
       expect(dict.load()).toBe(false);
     });
 
     it('文件存在时 load 加载数据返回 true', () => {
       const file = path.join(tmp_dir, 'dict.json');
       fs.writeFileSync(file, JSON.stringify({ val: 'value', key: 'k' }));
-      const dict = new Dict(file);
+      const dict = new Dict({ file });
       expect(dict.load()).toBe(true);
       expect(dict.get('val')).toBe('value');
       expect(dict.get('key')).toBe('k');
@@ -174,7 +178,7 @@ describe('Dict', () => {
     it('文件含非字符串值时 load 抛 TypeError', () => {
       const file = path.join(tmp_dir, 'dict.json');
       fs.writeFileSync(file, JSON.stringify({ val: 123 }));
-      const dict = new Dict(file);
+      const dict = new Dict({ file });
       expect(() => dict.load()).toThrow('dict 的值必须是字符串');
     });
   });

package/tool/dict/index.js

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

package/tool/dict/tool.json

@@ -0,0 +1,81 @@
+{
+  "name": "dict",
+  "title": "字符串字典",
+  "description": "基于 mm_dict 的字典存储能力：写入键值均为字符串的映射、读取、删除、判断存在、列出全部并落盘。适用场景：维护枚举映射（状态码→文案）、别名表、固定键值字典。",
+  "category": "状态存储",
+  "group": "state",
+  "type": "function",
+  "main": "./index.js",
+  "params": {
+    "type": "object",
+    "properties": {
+      "action": {
+        "type": "string",
+        "description": "操作类型: set(写入字典)/get(读取)/del(删除)/has(判断存在)/list(列出全部)/save(落盘)",
+        "enum": [
+          "set",
+          "get",
+          "del",
+          "has",
+          "list",
+          "save"
+        ],
+        "default": "set"
+      },
+      "key": {
+        "type": "string",
+        "description": "字典键(get/del/has/set 必填)"
+      },
+      "value": {
+        "type": "string",
+        "description": "字典值(set 必填，必须是字符串)"
+      },
+      "scope": {
+        "type": "string",
+        "description": "实例作用域，缺省 os",
+        "default": "os"
+      }
+    },
+    "required": [
+      "action"
+    ]
+  },
+  "returns": {
+    "type": "object",
+    "properties": {
+      "code": {
+        "type": "number",
+        "description": "0 表示成功，1xxxx 表示业务/执行异常"
+      },
+      "msg": {
+        "type": "string",
+        "description": "结果描述"
+      },
+      "value": {
+        "type": "string",
+        "description": "读取到的值(get)"
+      },
+      "exists": {
+        "type": "boolean",
+        "description": "是否存在"
+      },
+      "deleted": {
+        "type": "boolean",
+        "description": "是否删除成功(del)"
+      },
+      "list": {
+        "type": "object",
+        "description": "全部字典项(list)"
+      },
+      "count": {
+        "type": "number",
+        "description": "数量"
+      },
+      "error": {
+        "type": "object",
+        "description": "异常对象 { name, message }"
+      }
+    }
+  },
+  "handler": "manager"
+}