mm_config 2.1.6 → 2.1.8

package/README.md

@@ -1,284 +1,382 @@
-# mm_config
-
-超级美眉配置帮助类，动态同步文件修改配置。
-
-## 功能特点
-
-- 支持配置文件的动态读取和修改
-- 修改配置后自动同步保存到JSON文件
-- 使用Proxy实现属性监听，操作方便
-- 支持同步和异步API操作
-- 支持配置修改防抖功能，减少频繁保存
-- 内置错误处理机制，提高稳定性
-- 支持JSON5格式配置文件
-- 简洁命名，遵循单字优先原则
-- 内置缓存管理，避免重复创建配置实例
-
-## 安装
-
-```bash
-npm install mm_config
-```
-
-## API说明
-
-### 导入模块
-
-```javascript
-// 导入配置类
-const { Config, create, createAsync, clear, clearAll } = require('mm_config');
-```
-
-### 配置初始化
-
-#### 同步API
-
-```javascript
-/**
- * 创建同步配置
- * @param {String} file - 配置文件路径
- * @param {Object} config - 配置对象，可选
- * @param {Object} options - 配置选项，可选
- * @param {Number} options.debounce_time - 防抖时间(ms)，默认0
- * @param {Boolean} options.pretty - 是否美化输出，默认true
- * @param {String} options.format - 格式(json/json5)，默认json
- * @returns {Proxy} 返回配置代理对象
- */
-const config = create(file, config, options);
-```
-
-#### 异步API
-
-```javascript
-/**
- * 创建异步配置
- * @param {String} file - 配置文件路径
- * @param {Object} config - 配置对象，可选
- * @param {Object} options - 配置选项，可选
- * @returns {Promise<Proxy>} 返回配置代理对象的Promise
- */
-const config = await createAsync(file, config, options);
-```
-
-#### 缓存管理API
-
-```javascript
-/**
- * 清理指定文件配置缓存
- * @param {String} file - 配置文件路径
- */
-clear(file);
-
-/**
- * 清理所有配置缓存
- */
-clearAll();
-```
-
-#### 代理对象特殊方法
-
-通过代理对象可以访问以下特殊方法：
-
-- `_saveSync()`: 同步保存配置到文件
-- `_saveAsync()`: 异步保存配置到文件
-- `_raw`: 获取原始配置对象
-
-## 使用示例
-
-### 1. 基本同步配置
-
-```javascript
-const { create } = require('mm_config');
-
-// 创建配置并指定保存路径
-const config = create("./config.json", {
-    name: "demo",
-    state: 1
-});
-
-// 修改配置会自动保存到文件
-config.name = "test";
-config.sort = 2;
-
-// 显式调用保存
-config._saveSync();
-
-// 读取现有配置
-const existingConfig = create("./config.json");
-```
-
-### 2. 使用异步API
-
-```javascript
-const { createAsync } = require('mm_config');
-
-async function setupConfig() {
-    // 创建异步配置
-    const config = await createAsync("./async_config.json", {
-        name: "asyncDemo",
-        version: "1.0.0"
-    });
-    
-    // 修改配置会异步自动保存
-    config.timestamp = new Date().toISOString();
-    
-    // 显式调用异步保存
-    await config._saveAsync();
-    
-    return config;
-}
-```
-
-### 3. 使用防抖功能
-
-```javascript
-const { create } = require('mm_config');
-
-// 创建带防抖的配置（500ms延迟保存）
-const config = create("./debounce_config.json", {
-    name: "debounceDemo"
-}, {
-    debounce_time: 500 // 500ms防抖时间
-});
-
-// 快速多次修改，只会在最后一次修改后500ms保存一次
-for (let i = 0; i < 10; i++) {
-    config.counter = i;
-    config.timestamp = new Date().toISOString();
-}
-```
-
-### 4. 使用JSON5格式
-
-```javascript
-const { create } = require('mm_config');
-
-// 创建支持JSON5格式的配置
-const config = create("./config.json5", null, {
-    format: 'json5'
-});
-
-// JSON5格式支持注释、尾随逗号等特性
-config.description = "This supports JSON5 format";
-```
-
-### 5. 直接使用Config类
-
-```javascript
-const { Config } = require('mm_config');
-
-// 创建配置实例
-const cfg = new Config({
-    name: "directDemo"
-}, "./direct_config.json");
-
-// 获取代理对象
-const config = cfg.getProxy();
-
-// 使用配置
-config.version = "1.0.0";
-
-// 手动调用保存方法
-cfg.saveSync();
-await cfg.saveAsync();
-```
-
-### 6. 使用配置操作方法
-
-```javascript
-const { Config } = require('mm_config');
-
-const cfg = new Config({}, "./methods_config.json");
-
-// 设置配置值
-await cfg.set("name", "test");
-
-// 获取配置值
-const name = await cfg.get("name");
-
-// 检查配置是否存在
-const hasName = await cfg.has("name");
-
-// 删除配置项
-await cfg.del("name");
-
-// 获取所有键
-const keys = await cfg.keys();
-```
-
-### 7. 缓存管理功能
-
-```javascript
-const { create, clear, clearAll } = require('mm_config');
-
-// 创建配置实例
-const config1 = create("./cache1.json", { test: "cache1" });
-const config2 = create("./cache2.json", { test: "cache2" });
-
-// 清理指定文件缓存
-clear("./cache1.json");
-
-// 重新创建会生成新实例
-const config1New = create("./cache1.json", { test: "cache1_new" });
-
-// 清理所有缓存
-clearAll();
-
-// 所有配置都会重新创建
-const config2New = create("./cache2.json", { test: "cache2_new" });
-```
-
-## 配置选项
-
-创建配置时可提供以下选项：
-
-| 选项 | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| debounce_time | Number | 0 | 防抖时间(毫秒)，设置后多次修改会延迟保存 |
-| pretty | Boolean | true | 是否美化JSON输出，设为false可生成压缩的JSON |
-| format | String | 'json' | 配置文件格式，可选'json'或'json5' |
-
-## 注意事项
-
-1. 配置文件会自动创建和同步
-2. 修改配置对象的属性会自动保存到文件
-3. 确保有文件的写入权限
-4. 使用防抖功能可以减少频繁的文件IO操作
-5. 异步API适合在非阻塞环境中使用
-6. 当使用JSON5格式时，保存仍使用标准JSON格式，但可读取JSON5格式的文件
-7. 配置实例会被缓存，相同文件路径会返回同一实例，使用clear/clearAll可清理缓存
-
-## 依赖
-
-- json5: 用于解析JSON5格式
-- mm_expand: 提供文件操作扩展
-
-## 命名规范
-
-本模块遵循简洁命名原则：
-- 类名：`Config`（单字优先）
-- 方法名：`get()`、`set()`、`has()`、`del()`（动词开头）
-- 变量名：`val`、`key`、`bl`（简洁无废话）
-
-## 测试
-
-```bash
-# 运行测试
-npm test
-```
-
-## 许可证
-
-ISC License
-
-## 版本历史
-
-- v2.1.4: 添加缓存管理功能，修复内存泄漏问题
-- v2.1.3: 重构API，遵循简洁命名规范
-- v2.1.2: 添加JSON5格式支持
-- v2.1.1: 优化防抖功能
-- v2.1.0: 初始版本发布
-
-## 贡献
-
-欢迎提交Issue和Pull Request来改进这个项目。
+# mm_config
+
+超级美眉配置帮助类，动态同步文件修改配置。
+
+## 功能特点
+
+- 支持配置文件的动态读取和修改
+- 修改配置后自动同步保存到JSON文件
+- 使用Proxy实现属性监听，操作方便
+- 支持同步和异步API操作
+- 支持配置修改防抖功能，减少频繁保存
+- 内置错误处理机制，提高稳定性
+- 支持JSON5格式配置文件
+- 简洁命名，遵循单字优先原则
+- 内置缓存管理，避免重复创建配置实例
+
+## 安装
+
+```bash
+npm install mm_config
+```
+
+## 快速开始
+
+### 基本使用
+
+```javascript
+const { create } = require('mm_config');
+
+// 创建配置并指定保存路径
+const config = create("./config.json", {
+    name: "demo",
+    state: 1
+});
+
+// 修改配置会自动保存到文件
+config.name = "test";
+config.sort = 2;
+
+console.log(config); // { name: 'test', state: 1, sort: 2 }
+```
+
+### 异步使用
+
+```javascript
+const { createAsync } = require('mm_config');
+
+async function setup() {
+    const config = await createAsync("./async_config.json", {
+        name: "asyncDemo"
+    });
+    
+    config.timestamp = new Date().toISOString();
+    return config;
+}
+```
+
+## API说明
+
+### 导入模块
+
+```javascript
+// 导入配置类
+const { Config, create, createAsync, clear, clearAll } = require('mm_config');
+```
+
+### 配置初始化
+
+#### 同步API
+
+```javascript
+/**
+ * 创建同步配置
+ * @param {string} file - 配置文件路径
+ * @param {object} config - 配置对象，可选
+ * @param {object} options - 配置选项，可选
+ * @param {number} options.debounce_time - 防抖时间(ms)，默认0
+ * @param {boolean} options.pretty - 是否美化输出，默认true
+ * @param {string} options.format - 格式(json/json5)，默认json
+ * @returns {Proxy} 返回配置代理对象
+ */
+const config = create(file, config, options);
+```
+
+#### 异步API
+
+```javascript
+/**
+ * 创建异步配置
+ * @param {string} file - 配置文件路径
+ * @param {object} config - 配置对象，可选
+ * @param {object} options - 配置选项，可选
+ * @returns {Promise<Proxy>} 返回配置代理对象的Promise
+ */
+const config = await createAsync(file, config, options);
+```
+
+#### 缓存管理API
+
+```javascript
+/**
+ * 清理指定文件配置缓存
+ * @param {string} file - 配置文件路径
+ */
+clear(file);
+
+/**
+ * 清理所有配置缓存
+ */
+clearAll();
+```
+
+#### 代理对象特殊方法
+
+通过代理对象可以访问以下特殊方法：
+
+- `_saveSync()`: 同步保存配置到文件
+- `_saveAsync()`: 异步保存配置到文件
+- `_raw`: 获取原始配置对象
+
+## 使用示例
+
+### 1. 基本同步配置
+
+```javascript
+const { create } = require('mm_config');
+
+// 创建配置并指定保存路径
+const config = create("./config.json", {
+    name: "demo",
+    state: 1
+});
+
+// 修改配置会自动保存到文件
+config.name = "test";
+config.sort = 2;
+
+// 显式调用保存
+config._saveSync();
+
+// 读取现有配置
+const existingConfig = create("./config.json");
+console.log(existingConfig.name); // "test"
+```
+
+### 2. 使用异步API
+
+```javascript
+const { createAsync } = require('mm_config');
+
+async function setupConfig() {
+    // 创建异步配置
+    const config = await createAsync("./async_config.json", {
+        name: "asyncDemo",
+        version: "1.0.0"
+    });
+    
+    // 修改配置会异步自动保存
+    config.timestamp = new Date().toISOString();
+    
+    // 显式调用异步保存
+    await config._saveAsync();
+    
+    return config;
+}
+
+setupConfig().then(config => {
+    console.log('配置设置完成:', config);
+});
+```
+
+### 3. 使用防抖功能
+
+```javascript
+const { create } = require('mm_config');
+
+// 创建带防抖的配置（500ms延迟保存）
+const config = create("./debounce_config.json", {
+    name: "debounceDemo"
+}, {
+    debounce_time: 500 // 500ms防抖时间
+});
+
+// 快速多次修改，只会在最后一次修改后500ms保存一次
+for (let i = 0; i < 10; i++) {
+    config.counter = i;
+    config.timestamp = new Date().toISOString();
+}
+
+// 最终只会保存最后一次的值
+console.log(config.counter); // 9
+```
+
+### 4. 使用JSON5格式
+
+```javascript
+const { create } = require('mm_config');
+
+// 创建支持JSON5格式的配置
+const config = create("./config.json5", null, {
+    format: 'json5'
+});
+
+// JSON5格式支持注释、尾随逗号等特性
+config.description = "This supports JSON5 format";
+config.version = "1.0.0";
+```
+
+### 5. 直接使用Config类
+
+```javascript
+const { Config } = require('mm_config');
+
+// 创建配置实例
+const cfg = new Config({
+    debounce_time: 100,
+    pretty: true
+}, {
+    name: "directDemo"
+});
+
+// 获取代理对象
+const config = cfg.getProxy();
+
+// 使用配置
+config.version = "1.0.0";
+
+// 手动调用保存方法
+cfg.saveSync();
+await cfg.saveAsync();
+```
+
+### 6. 使用配置操作方法
+
+```javascript
+const { Config } = require('mm_config');
+
+const cfg = new Config({}, "./methods_config.json");
+
+async function manageConfig() {
+    // 设置配置值
+    await cfg.set("name", "test");
+    
+    // 获取配置值
+    const name = await cfg.get("name");
+    console.log('获取到的名称:', name); // "test"
+    
+    // 检查配置是否存在
+    const hasName = await cfg.has("name");
+    console.log('是否存在名称:', hasName); // true
+    
+    // 删除配置项
+    await cfg.del("name");
+    
+    // 获取所有键
+    const keys = await cfg.keys();
+    console.log('所有键:', keys);
+}
+
+manageConfig();
+```
+
+### 7. 缓存管理功能
+
+```javascript
+const { create, clear, clearAll } = require('mm_config');
+
+// 创建配置实例
+const config1 = create("./cache1.json", { test: "cache1" });
+const config2 = create("./cache2.json", { test: "cache2" });
+
+// 清理指定文件缓存
+clear("./cache1.json");
+
+// 重新创建会生成新实例
+const config1New = create("./cache1.json", { test: "cache1_new" });
+
+// 清理所有缓存
+clearAll();
+
+// 所有配置都会重新创建
+const config2New = create("./cache2.json", { test: "cache2_new" });
+```
+
+## 配置选项
+
+创建配置时可提供以下选项：
+
+| 选项 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| debounce_time | number | 0 | 防抖时间(毫秒)，设置后多次修改会延迟保存 |
+| pretty | boolean | true | 是否美化JSON输出，设为false可生成压缩的JSON |
+| format | string | 'json' | 配置文件格式，可选'json'或'json5' |
+
+## 高级用法
+
+### 错误处理
+
+```javascript
+const { create } = require('mm_config');
+
+try {
+    const config = create("./config.json", { test: 1 });
+    config.invalid = "value";
+} catch (error) {
+    console.error('配置操作出错:', error.message);
+}
+```
+
+### 性能优化
+
+```javascript
+// 使用防抖减少频繁的文件IO操作
+const config = create("./config.json", {}, {
+    debounce_time: 1000 // 1秒防抖
+});
+
+// 批量操作时使用_raw属性避免频繁保存
+const rawConfig = config._raw;
+rawConfig.field1 = "value1";
+rawConfig.field2 = "value2";
+rawConfig.field3 = "value3";
+// 手动保存一次
+config._saveSync();
+```
+
+## 注意事项
+
+1. **文件权限**: 确保有文件的写入权限
+2. **异步操作**: 异步API适合在非阻塞环境中使用
+3. **缓存管理**: 配置实例会被缓存，相同文件路径会返回同一实例
+4. **JSON5格式**: 当使用JSON5格式时，保存仍使用标准JSON格式，但可读取JSON5格式的文件
+5. **内存管理**: 使用clear/clearAll可清理缓存，避免内存泄漏
+
+## 依赖
+
+- **json5**: 用于解析JSON5格式
+- **mm_expand**: 提供文件操作扩展
+
+## 命名规范
+
+本模块遵循简洁命名原则：
+- 类名：`Config`（单字优先）
+- 方法名：`get()`、`set()`、`has()`、`del()`（动词开头）
+- 变量名：`val`、`key`、`bl`（简洁无废话）
+
+## 测试
+
+```bash
+# 运行测试
+npm test
+
+# 或直接运行测试文件
+node test.js
+```
+
+## 许可证
+
+ISC License
+
+## 版本历史
+
+- **v2.1.6**: 修复代码规范问题，完善文档
+- **v2.1.5**: 优化ESLint配置，提升代码质量
+- **v2.1.4**: 添加缓存管理功能，修复内存泄漏问题
+- **v2.1.3**: 重构API，遵循简洁命名规范
+- **v2.1.2**: 添加JSON5格式支持
+- **v2.1.1**: 优化防抖功能
+- **v2.1.0**: 初始版本发布
+
+## 贡献
+
+欢迎提交Issue和Pull Request来改进这个项目。
+
+## 相关项目
+
+- [mm_expand](https://github.com/supermm/mm_expand) - 文件操作扩展模块
+- [mm_eslint](https://github.com/supermm/mm_eslint) - ESLint配置插件
+
+---
+
+**mm_config** - 让配置管理变得简单高效！