mm_options 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,47 @@
1
- # Temporary Holding Version
1
+ # 动态配置管理器(mm_options)
2
+ ## 说明
3
+ mm_options 是动态配置存储模块,适用于站长 / 用户配置,可在运行时动态修改。
4
+ 与固定配置(mm_config)不同,其配置项可随时覆盖、删除。
2
5
 
3
- 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.
6
+ ## 功能
7
+ - 键名称为非空字符串,值可为任意类型
8
+ - 支持覆盖已有值、删除、判断存在、获取副本、清空
9
+ - 支持保存到 JSON 文件与从 JSON 文件加载
10
+
11
+ ## 安装
12
+ ```bash
13
+ npm install mm_options
14
+ ```
15
+
16
+ ## 快速开始
17
+ ```javascript
18
+ const { Options, optionsAdmin } = require('mm_options');
19
+
20
+ // 直接使用存储类
21
+ const options = new Options('./data/options.json');
22
+ options.set('theme', 'dark').set('size', 12);
23
+ options.set('theme', 'light'); // 覆盖
24
+ options.save();
25
+
26
+ // 通过管理器按作用域获取实例(相同作用域返回同一实例)
27
+ const scoped = optionsAdmin('app', './data/app_options.json');
28
+ scoped.set('lang', 'zh');
29
+ ```
30
+
31
+ ## API
32
+ | 方法 | 说明 | 参数 | 返回值 |
33
+ |---|---|---|---|
34
+ | set | 设置配置,可覆盖 | key, value | Options |
35
+ | get | 获取配置 | key | * |
36
+ | del | 删除配置 | key | boolean |
37
+ | has | 判断配置是否存在 | key | boolean |
38
+ | list | 获取配置表副本 | - | object |
39
+ | clear | 清空所有配置 | - | Options |
40
+ | save | 保存到持久化文件 | - | boolean |
41
+ | load | 从持久化文件加载 | - | boolean |
42
+
43
+ ## 依赖
44
+ - mm_corejs:提供 Admin 管理器
45
+
46
+ ## 许可证
47
+ ISC
package/index.js ADDED
@@ -0,0 +1,22 @@
1
+ const Admin = require('mm_corejs').Admin;
2
+ const Options = require('./lib/options.js');
3
+
4
+ let admin = new Admin();
5
+ admin.setClass(Options);
6
+
7
+ module.exports = {
8
+ Options,
9
+ admin,
10
+ /**
11
+ * 获取指定作用域的动态配置实例,不存在时创建
12
+ * @param {string} [scope] 作用域名称,缺省时使用 os
13
+ * @param {string} [config] 持久化文件路径
14
+ * @returns {Options} 动态配置实例
15
+ */
16
+ optionsAdmin(scope, config) {
17
+ if (!scope) {
18
+ scope = 'os';
19
+ }
20
+ return admin.get(scope, config);
21
+ }
22
+ };
package/lib/options.js ADDED
@@ -0,0 +1,10 @@
1
+ const KvStore = require('mm_corejs').KvStore;
2
+
3
+ /**
4
+ * 动态配置存储类,适用于站长或用户配置,可在运行时动态修改
5
+ * @class
6
+ * @augments {KvStore}
7
+ */
8
+ class Options extends KvStore {}
9
+
10
+ module.exports = Options;
package/package.json CHANGED
@@ -1,6 +1,27 @@
1
1
  {
2
2
  "name": "mm_options",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.0",
4
+ "description": "动态配置存储模块:适用于站长/用户配置,可在运行时动态修改",
5
+ "main": "index.js",
6
+ "keywords": [
7
+ "mm_mod",
8
+ "mm_infra",
9
+ "mm_data",
10
+ "options",
11
+ "配置",
12
+ "存储"
13
+ ],
14
+ "layer": "infra",
15
+ "group": "data",
16
+ "author": "邱文武",
17
+ "license": "ISC",
18
+ "scripts": {
19
+ "test": "jest --coverage"
20
+ },
21
+ "dependencies": {
22
+ "mm_corejs": "^1.1.4"
23
+ },
24
+ "devDependencies": {
25
+ "jest": "^30.5.2"
26
+ }
27
+ }
@@ -0,0 +1,169 @@
1
+ 'use strict';
2
+
3
+ const fs = require('fs');
4
+ const os = require('os');
5
+ const path = require('path');
6
+ const mod = require('../index');
7
+ const Options = require('../lib/options');
8
+
9
+ describe('mm_options 模块入口', () => {
10
+ it('导出 Options 类与管理器', () => {
11
+ expect(mod.Options).toBe(Options);
12
+ expect(mod.admin).toBeDefined();
13
+ });
14
+
15
+ it('optionsAdmin 按作用域缓存并返回实例', () => {
16
+ const first = mod.optionsAdmin('options_scope');
17
+ expect(first).toBeInstanceOf(Options);
18
+ expect(mod.optionsAdmin('options_scope')).toBe(first);
19
+ });
20
+
21
+ it('optionsAdmin 缺省作用域为 os', () => {
22
+ expect(mod.optionsAdmin()).toBeInstanceOf(Options);
23
+ });
24
+ });
25
+
26
+ describe('Options', () => {
27
+ let tmp_dir;
28
+
29
+ beforeEach(() => {
30
+ tmp_dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mm-options-'));
31
+ });
32
+
33
+ afterEach(() => {
34
+ fs.rmSync(tmp_dir, { recursive: true, force: true });
35
+ });
36
+
37
+ describe('构造', () => {
38
+ it('默认不传文件路径时 file 为空字符串', () => {
39
+ const options = new Options();
40
+ expect(options._file).toBe('');
41
+ expect(options.list()).toEqual({});
42
+ });
43
+
44
+ it('传入文件路径时保存路径', () => {
45
+ const file = path.join(tmp_dir, 'options.json');
46
+ const options = new Options(file);
47
+ expect(options._file).toBe(file);
48
+ });
49
+ });
50
+
51
+ describe('set / get', () => {
52
+ it('set 后可通过 get 读取,并支持链式调用', () => {
53
+ const options = new Options();
54
+ expect(options.set('theme', 'dark')).toBe(options);
55
+ expect(options.get('theme')).toBe('dark');
56
+ });
57
+
58
+ it('set 可覆盖已有值', () => {
59
+ const options = new Options();
60
+ options.set('theme', 'dark');
61
+ options.set('theme', 'light');
62
+ expect(options.get('theme')).toBe('light');
63
+ });
64
+
65
+ it('get 不存在的键返回 undefined', () => {
66
+ const options = new Options();
67
+ expect(options.get('nope')).toBeUndefined();
68
+ });
69
+
70
+ it('set 非字符串键抛 TypeError', () => {
71
+ const options = new Options();
72
+ expect(() => options.set(123, 'x')).toThrow('键名必须是非空字符串');
73
+ });
74
+
75
+ it('set 空字符串键抛 TypeError', () => {
76
+ const options = new Options();
77
+ expect(() => options.set('', 'x')).toThrow('键名必须是非空字符串');
78
+ });
79
+
80
+ it('get 非字符串键抛 TypeError', () => {
81
+ const options = new Options();
82
+ expect(() => options.get(null)).toThrow('键名必须是非空字符串');
83
+ });
84
+ });
85
+
86
+ describe('del / has', () => {
87
+ it('del 删除存在的键返回 true', () => {
88
+ const options = new Options();
89
+ options.set('a', 1);
90
+ expect(options.del('a')).toBe(true);
91
+ expect(options.has('a')).toBe(false);
92
+ });
93
+
94
+ it('del 不存在的键返回 false', () => {
95
+ const options = new Options();
96
+ expect(options.del('nope')).toBe(false);
97
+ });
98
+
99
+ it('del 非字符串键抛 TypeError', () => {
100
+ const options = new Options();
101
+ expect(() => options.del('')).toThrow('键名必须是非空字符串');
102
+ });
103
+
104
+ it('has 存在返回 true,不存在返回 false', () => {
105
+ const options = new Options();
106
+ options.set('a', 1);
107
+ expect(options.has('a')).toBe(true);
108
+ expect(options.has('b')).toBe(false);
109
+ });
110
+
111
+ it('has 非字符串键抛 TypeError', () => {
112
+ const options = new Options();
113
+ expect(() => options.has(undefined)).toThrow('键名必须是非空字符串');
114
+ });
115
+ });
116
+
117
+ describe('list / clear', () => {
118
+ it('list 返回副本,不引用内部对象', () => {
119
+ const options = new Options();
120
+ options.set('a', 1);
121
+ const list = options.list();
122
+ expect(list).toEqual({ a: 1 });
123
+ list.a = 99;
124
+ expect(options.get('a')).toBe(1);
125
+ });
126
+
127
+ it('clear 清空所有配置项', () => {
128
+ const options = new Options();
129
+ options.set('a', 1);
130
+ options.set('b', 2);
131
+ expect(options.clear()).toBe(options);
132
+ expect(options.list()).toEqual({});
133
+ });
134
+ });
135
+
136
+ describe('save / load', () => {
137
+ it('未配置文件路径时 save 抛 Error', () => {
138
+ const options = new Options();
139
+ expect(() => options.save()).toThrow('未配置持久化文件路径');
140
+ });
141
+
142
+ it('save 写入文件返回 true', () => {
143
+ const file = path.join(tmp_dir, 'options.json');
144
+ const options = new Options(file);
145
+ options.set('a', 1);
146
+ expect(options.save()).toBe(true);
147
+ expect(JSON.parse(fs.readFileSync(file, 'utf8'))).toEqual({ a: 1 });
148
+ });
149
+
150
+ it('未配置文件路径时 load 返回 false', () => {
151
+ const options = new Options();
152
+ expect(options.load()).toBe(false);
153
+ });
154
+
155
+ it('文件不存在时 load 返回 false', () => {
156
+ const options = new Options(path.join(tmp_dir, 'nope.json'));
157
+ expect(options.load()).toBe(false);
158
+ });
159
+
160
+ it('文件存在时 load 加载数据返回 true', () => {
161
+ const file = path.join(tmp_dir, 'options.json');
162
+ fs.writeFileSync(file, JSON.stringify({ a: 1, b: 'x' }));
163
+ const options = new Options(file);
164
+ expect(options.load()).toBe(true);
165
+ expect(options.get('a')).toBe(1);
166
+ expect(options.get('b')).toBe('x');
167
+ });
168
+ });
169
+ });