mm_vars 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# 变量管理器（mm_vars）
+## 说明
+mm_vars 是变量存储模块，用于存储和检索程序的临时变量，可随时修改和删除。
+例如：step = 1，state = 'busy'。
 
-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_vars
+```
+
+## 快速开始
+```javascript
+const { Vars, varsAdmin } = require('mm_vars');
+
+// 直接使用存储类
+const vars = new Vars('./data/vars.json');
+vars.set('step', 1).set('state', 'busy');
+vars.save();
+
+// 通过管理器按作用域获取实例（相同作用域返回同一实例）
+const scoped = varsAdmin('app', './data/app_vars.json');
+scoped.set('count', 10);
+```
+
+## API
+| 方法 | 说明 | 参数 | 返回值 |
+|---|---|---|---|
+| set | 设置变量，可覆盖 | key, value | Vars |
+| get | 获取变量 | key | * |
+| del | 删除变量 | key | boolean |
+| has | 判断变量是否存在 | key | boolean |
+| list | 获取变量表副本 | - | object |
+| clear | 清空所有变量 | - | Vars |
+| save | 保存到持久化文件 | - | boolean |
+| load | 从持久化文件加载 | - | boolean |
+
+## 依赖
+- mm_corejs：提供 Admin 管理器
+
+## 许可证
+ISC

package/index.js

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

package/lib/vars.js

@@ -0,0 +1,10 @@
+const KvStore = require('mm_corejs').KvStore;
+
+/**
+ * 变量存储类，可随时修改和删除
+ * @class
+ * @augments {KvStore}
+ */
+class Vars extends KvStore {}
+
+module.exports = Vars;

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "mm_vars",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "变量存储模块：用于存储可随时修改和删除的键值变量",
+  "main": "index.js",
+  "keywords": [
+    "mm_mod",
+    "mm_infra",
+    "mm_data",
+    "vars",
+    "变量",
+    "存储"
+  ],
+  "layer": "infra",
+  "group": "data",
+  "author": "邱文武",
+  "license": "ISC",
+  "scripts": {
+    "test": "jest --coverage"
+  },
+  "dependencies": {
+    "mm_corejs": "^1.1.4"
+  },
+  "devDependencies": {
+    "jest": "^30.5.2"
+  }
+}

package/test/vars.test.js

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