mm_config 2.1.3 → 2.1.4

package/README.md

@@ -1,194 +1,284 @@
-# mm_config
-
-超级美眉配置帮助类，动态同步文件修改配置。
-
-## 功能特点
-
-- 支持配置文件的动态读取和修改
-- 修改配置后自动同步保存到JSON文件
-- 使用Proxy实现属性监听，操作方便
-- 支持同步和异步API操作
-- 支持配置修改防抖功能，减少频繁保存
-- 内置错误处理机制，提高稳定性
-- 支持JSON5格式配置文件
-- 向后兼容原有API
-
-## 安装
-
-```bash
-npm install mm_config
-```
-
-## API说明
-
-### 导入模块
-
-```javascript
-// 导入同步配置创建函数（默认）
-const conf = require('mm_config');
-
-// 导入异步配置创建函数
-const createConfigAsync = conf.createConfigAsync;
-
-// 导入配置管理器类
-const { ConfigManager } = require('mm_config');
-```
-
-### 配置初始化
-
-#### 同步API
-
-```javascript
-/**
- * 创建同步配置管理器
- * @param {Object} _config 配置对象，可选，不传则从文件读取
- * @param {String} _jsonFile 配置文件路径，可选，不传则使用this.filename
- * @param {Object} options 配置选项，可选
- * @param {Number} options.debounceTime 防抖时间(ms)，默认0
- * @param {Boolean} options.pretty 是否美化输出，默认true
- * @param {String} options.format 格式(json/json5)，默认json
- * @returns {Proxy} 返回配置代理对象
- */
-const config = conf(_config, _jsonFile, options);
-```
-
-#### 异步API
-
-```javascript
-/**
- * 创建异步配置管理器
- * @param {Object} _config 配置对象，可选，不传则从文件读取
- * @param {String} _jsonFile 配置文件路径，可选，不传则使用this.filename
- * @param {Object} options 配置选项，可选
- * @returns {Promise<Proxy>} 返回配置代理对象的Promise
- */
-const config = await createConfigAsync(_config, _jsonFile, options);
-```
-
-#### 代理对象特殊方法
-
-通过代理对象可以访问以下特殊方法：
-
-- `_saveSync()`: 同步保存配置到文件
-- `_saveAsync()`: 异步保存配置到文件
-- `_raw`: 获取原始配置对象
-
-## 使用示例
-
-### 1. 基本同步配置（兼容原API）
-
-```javascript
-// 创建配置并指定保存路径
-const config = conf({
-    name: "demo",
-    state: 1
-}, "./config.json");
-
-// 修改配置会自动保存到文件
-config.name = "test";
-config.sort = 2;
-
-// 显式调用保存
-config._saveSync();
-
-// 读取现有配置
-const existingConfig = conf(null, "./config.json");
-```
-
-### 2. 使用异步API
-
-```javascript
-async function setupConfig() {
-    // 创建异步配置
-    const config = await createConfigAsync({
-        name: "asyncDemo",
-        version: "1.0.0"
-    }, "./async_config.json");
-    
-    // 修改配置会异步自动保存
-    config.timestamp = new Date().toISOString();
-    
-    // 显式调用异步保存
-    await config._saveAsync();
-    
-    return config;
-}
-```
-
-### 3. 使用防抖功能
-
-```javascript
-// 创建带防抖的配置（500ms延迟保存）
-const debouncedConfig = conf({
-    name: "debounceDemo"
-}, "./debounce_config.json", {
-    debounceTime: 500 // 500ms防抖时间
-});
-
-// 快速多次修改，只会在最后一次修改后500ms保存一次
-for (let i = 0; i < 10; i++) {
-    debouncedConfig.counter = i;
-    debouncedConfig.timestamp = new Date().toISOString();
-}
-```
-
-### 4. 使用JSON5格式
-
-```javascript
-// 创建支持JSON5格式的配置
-const json5Config = conf(null, "./config.json5", {
-    format: 'json5'
-});
-
-// JSON5格式支持注释、尾随逗号等特性
-json5Config.description = "This supports JSON5 format";
-```
-
-### 5. 直接使用ConfigManager类
-
-```javascript
-const { ConfigManager } = require('mm_config');
-
-// 创建配置管理器实例
-const manager = new ConfigManager({
-    name: "directDemo"
-}, "./direct_config.json");
-
-// 获取代理对象
-const config = manager.getProxy();
-
-// 使用配置
-config.version = "1.0.0";
-
-// 手动调用保存方法
-manager.saveSync();
-await manager.saveAsync();
-```
-
-## 配置选项
-
-创建配置时可提供以下选项：
-
-| 选项 | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| debounceTime | Number | 0 | 防抖时间(毫秒)，设置后多次修改会延迟保存 |
-| pretty | Boolean | true | 是否美化JSON输出，设为false可生成压缩的JSON |
-| format | String | 'json' | 配置文件格式，可选'json'或'json5' |
-
-## 注意事项
-
-1. 配置文件会自动创建和同步
-2. 修改配置对象的属性会自动保存到文件
-3. 确保有文件的写入权限
-4. 使用防抖功能可以减少频繁的文件IO操作
-5. 异步API适合在非阻塞环境中使用
-6. 当使用JSON5格式时，保存仍使用标准JSON格式，但可读取JSON5格式的文件
-
-## 依赖
-
-- json5: 用于解析JSON5格式
-- mm_expand: 提供文件操作扩展
-
-## 许可证
-
-ISC License
+# 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来改进这个项目。

package/cache_test1.json

@@ -0,0 +1,3 @@
+{
+    "test": "cache1_new"
+}

package/cache_test2.json

@@ -0,0 +1,3 @@
+{
+    "test": "cache2_new"
+}

package/cache_test3.json

@@ -0,0 +1,3 @@
+{
+    "test": "cache3_new"
+}

package/config1.json

@@ -0,0 +1,6 @@
+{
+    "name": "test1",
+    "state": 1,
+    "sort": 1,
+    "age": 26
+}

package/config2.json

@@ -0,0 +1,4 @@
+{
+    "name": "test2",
+    "sort": 2
+}

package/config_async.json

@@ -0,0 +1,5 @@
+{
+    "name": "asyncTest2",
+    "state": 3,
+    "timestamp": "2025-12-07T09:25:55.408Z"
+}

package/config_debounce.json

@@ -0,0 +1,5 @@
+{
+    "name": "debounceDemo",
+    "value": 4,
+    "timestamp": "2025-12-07T09:25:55.414Z"
+}

package/config_json5.json

@@ -0,0 +1,4 @@
+{
+    "name": "json5Demo",
+    "description": "This uses JSON5 format"
+}