mm_dict 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# 字典管理器（mm_dict）
+## 说明
+mm_dict 是字典存储模块，用于存储和查询键值映射，键和值都只能是字符串。
+例如：val → value，生命值 → hp，HP → hp。
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## 功能
+- 键名称为非空字符串，值只能为字符串
+- 支持覆盖已有值、删除、判断存在、获取副本、清空
+- 支持保存到 JSON 文件与从 JSON 文件加载（加载时校验值类型）
+
+## 安装
+```bash
+npm install mm_dict
+```
+
+## 快速开始
+```javascript
+const { Dict, dictAdmin } = require('mm_dict');
+
+// 直接使用存储类
+const dict = new Dict('./data/dict.json');
+dict.set('val', 'value').set('生命值', 'hp');
+dict.save();
+
+// 通过管理器按作用域获取实例（相同作用域返回同一实例）
+const scoped = dictAdmin('app', './data/app_dict.json');
+scoped.set('HP', 'hp');
+```
+
+## API
+| 方法 | 说明 | 参数 | 返回值 |
+|---|---|---|---|
+| set | 设置字典项（字符串） | key, value | Dict |
+| get | 获取字典项 | key | string\|undefined |
+| del | 删除字典项 | key | boolean |
+| has | 判断字典项是否存在 | key | boolean |
+| list | 获取字典表副本 | - | object |
+| clear | 清空所有字典项 | - | Dict |
+| save | 保存到持久化文件 | - | boolean |
+| load | 从持久化文件加载 | - | boolean |
+
+## 依赖
+- mm_corejs：提供 Admin 管理器
+
+## 许可证
+ISC

package/index.js

@@ -0,0 +1,25 @@
+const Admin = require('mm_corejs').Admin;
+const Dict = require('./lib/dict.js');
+
+let admin = new Admin();
+admin.setClass(Dict);
+
+module.exports = {
+  Dict,
+  admin,
+  /**
+   * 获取指定作用域的字典存储实例，不存在时创建
+   * @param {string} [scope] 作用域名称，缺省时使用 os
+   * @param {string} [config] 持久化文件路径
+   * @returns {Dict} 字典存储实例
+   */
+  dictAdmin(scope, config) {
+    if (!scope) {
+      scope = 'os';
+    }
+    return admin.get(scope, config);
+  },
+  getDict() {
+    return admin.get('os');
+  }
+};

package/lib/dict.js

@@ -0,0 +1,22 @@
+const KvStore = require('mm_corejs').KvStore;
+
+/**
+ * 字典存储类，值只能是字符串
+ * @class
+ * @augments {KvStore}
+ */
+class Dict extends KvStore {
+  /**
+   * 校验值是否为字符串
+   * @param {*} value 值
+   * @returns {void}
+   * @throws {TypeError} 值不是字符串时抛出
+   */
+  _checkValue(value) {
+    if (typeof value !== 'string') {
+      throw new TypeError('dict 的值必须是字符串');
+    }
+  }
+}
+
+module.exports = Dict;

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "mm_dict",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "字典存储模块：键和值都只能是字符串，用于键值映射",
+  "main": "index.js",
+  "keywords": [
+    "mm_mod",
+    "mm_infra",
+    "mm_data",
+    "dict",
+    "字典",
+    "存储"
+  ],
+  "layer": "infra",
+  "group": "data",
+  "author": "邱文武",
+  "license": "ISC",
+  "scripts": {
+    "test": "jest --coverage"
+  },
+  "dependencies": {
+    "mm_corejs": "^1.1.4"
+  },
+  "devDependencies": {
+    "jest": "^30.5.2"
+  }
+}

package/test/dict.test.js

@@ -0,0 +1,181 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const mod = require('../index');
+const Dict = require('../lib/dict');
+
+describe('mm_dict 模块入口', () => {
+  it('导出 Dict 类与管理器', () => {
+    expect(mod.Dict).toBe(Dict);
+    expect(mod.admin).toBeDefined();
+  });
+
+  it('dictAdmin 按作用域缓存并返回实例', () => {
+    const first = mod.dictAdmin('dict_scope');
+    expect(first).toBeInstanceOf(Dict);
+    expect(mod.dictAdmin('dict_scope')).toBe(first);
+  });
+
+  it('dictAdmin 缺省作用域为 os', () => {
+    expect(mod.dictAdmin()).toBeInstanceOf(Dict);
+  });
+});
+
+describe('Dict', () => {
+  let tmp_dir;
+
+  beforeEach(() => {
+    tmp_dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mm-dict-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmp_dir, { recursive: true, force: true });
+  });
+
+  describe('构造', () => {
+    it('默认不传文件路径时 file 为空字符串', () => {
+      const dict = new Dict();
+      expect(dict._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);
+    });
+  });
+
+  describe('set / get', () => {
+    it('set 字符串后可通过 get 读取，并支持链式调用', () => {
+      const dict = new Dict();
+      expect(dict.set('val', 'value')).toBe(dict);
+      expect(dict.get('val')).toBe('value');
+    });
+
+    it('set 可覆盖已有值', () => {
+      const dict = new Dict();
+      dict.set('val', 'value');
+      dict.set('val', 'value2');
+      expect(dict.get('val')).toBe('value2');
+    });
+
+    it('set 非字符串值抛 TypeError', () => {
+      const dict = new Dict();
+      expect(() => dict.set('val', 123)).toThrow('dict 的值必须是字符串');
+    });
+
+    it('get 不存在的键返回 undefined', () => {
+      const dict = new Dict();
+      expect(dict.get('nope')).toBeUndefined();
+    });
+
+    it('set 非字符串键抛 TypeError', () => {
+      const dict = new Dict();
+      expect(() => dict.set(123, 'x')).toThrow('键名必须是非空字符串');
+    });
+
+    it('set 空字符串键抛 TypeError', () => {
+      const dict = new Dict();
+      expect(() => dict.set('', 'x')).toThrow('键名必须是非空字符串');
+    });
+
+    it('get 非字符串键抛 TypeError', () => {
+      const dict = new Dict();
+      expect(() => dict.get(null)).toThrow('键名必须是非空字符串');
+    });
+  });
+
+  describe('del / has', () => {
+    it('del 删除存在的键返回 true', () => {
+      const dict = new Dict();
+      dict.set('val', 'value');
+      expect(dict.del('val')).toBe(true);
+      expect(dict.has('val')).toBe(false);
+    });
+
+    it('del 不存在的键返回 false', () => {
+      const dict = new Dict();
+      expect(dict.del('nope')).toBe(false);
+    });
+
+    it('del 非字符串键抛 TypeError', () => {
+      const dict = new Dict();
+      expect(() => dict.del('')).toThrow('键名必须是非空字符串');
+    });
+
+    it('has 存在返回 true，不存在返回 false', () => {
+      const dict = new Dict();
+      dict.set('val', 'value');
+      expect(dict.has('val')).toBe(true);
+      expect(dict.has('other')).toBe(false);
+    });
+
+    it('has 非字符串键抛 TypeError', () => {
+      const dict = new Dict();
+      expect(() => dict.has(undefined)).toThrow('键名必须是非空字符串');
+    });
+  });
+
+  describe('list / clear', () => {
+    it('list 返回副本，不引用内部对象', () => {
+      const dict = new Dict();
+      dict.set('val', 'value');
+      const list = dict.list();
+      expect(list).toEqual({ val: 'value' });
+      list.val = 'changed';
+      expect(dict.get('val')).toBe('value');
+    });
+
+    it('clear 清空所有字典项', () => {
+      const dict = new Dict();
+      dict.set('a', 'x');
+      dict.set('b', 'y');
+      expect(dict.clear()).toBe(dict);
+      expect(dict.list()).toEqual({});
+    });
+  });
+
+  describe('save / load', () => {
+    it('未配置文件路径时 save 抛 Error', () => {
+      const dict = new Dict();
+      expect(() => dict.save()).toThrow('未配置持久化文件路径');
+    });
+
+    it('save 写入文件返回 true', () => {
+      const file = path.join(tmp_dir, 'dict.json');
+      const dict = new Dict(file);
+      dict.set('val', 'value');
+      expect(dict.save()).toBe(true);
+      expect(JSON.parse(fs.readFileSync(file, 'utf8'))).toEqual({ val: 'value' });
+    });
+
+    it('未配置文件路径时 load 返回 false', () => {
+      const dict = new Dict();
+      expect(dict.load()).toBe(false);
+    });
+
+    it('文件不存在时 load 返回 false', () => {
+      const dict = new Dict(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);
+      expect(dict.load()).toBe(true);
+      expect(dict.get('val')).toBe('value');
+      expect(dict.get('key')).toBe('k');
+    });
+
+    it('文件含非字符串值时 load 抛 TypeError', () => {
+      const file = path.join(tmp_dir, 'dict.json');
+      fs.writeFileSync(file, JSON.stringify({ val: 123 }));
+      const dict = new Dict(file);
+      expect(() => dict.load()).toThrow('dict 的值必须是字符串');
+    });
+  });
+});