mm_config 1.1.5 → 2.1.0

package/README.md

@@ -7,7 +7,11 @@
 - 支持配置文件的动态读取和修改
 - 修改配置后自动同步保存到JSON文件
 - 使用Proxy实现属性监听，操作方便
-- 支持无配置文件时的默认配置创建
+- 支持同步和异步API操作
+- 支持配置修改防抖功能，减少频繁保存
+- 内置错误处理机制，提高稳定性
+- 支持JSON5格式配置文件
+- 向后兼容原有API
 
 ## 安装
 
@@ -17,32 +21,61 @@ 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);
+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);
 ```
 
-### 参数说明
+#### 代理对象特殊方法
 
-- `_config`: 初始配置对象，可选参数
-  - 当传入对象时，将使用该对象作为初始配置
-  - 当不传入时，将从配置文件中读取配置
+通过代理对象可以访问以下特殊方法：
 
-- `_jsonFile`: 配置文件路径，可选参数
-  - 当传入路径时，将使用该路径作为配置文件
-  - 当不传入时，将使用`this.filename`作为配置文件路径
+- `_saveSync()`: 同步保存配置到文件
+- `_saveAsync()`: 异步保存配置到文件
+- `_raw`: 获取原始配置对象
 
 ## 使用示例
 
-### 1. 创建新配置
+### 1. 基本同步配置（兼容原API）
 
 ```javascript
 // 创建配置并指定保存路径
@@ -54,47 +87,106 @@ const config = conf({
 // 修改配置会自动保存到文件
 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;
+}
 ```
 
-### 2. 读取现有配置
+### 3. 使用防抖功能
 
 ```javascript
-// 设置配置文件路径
-this.filename = "./config.json";
+// 创建带防抖的配置（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();
+}
+```
 
-// 读取现有配置文件
-const config = conf();
+### 4. 使用JSON5格式
 
-// 获取配置
-console.log(config.name);
+```javascript
+// 创建支持JSON5格式的配置
+const json5Config = conf(null, "./config.json5", {
+    format: 'json5'
+});
 
-// 修改配置
-config.age = 26;
+// JSON5格式支持注释、尾随逗号等特性
+json5Config.description = "This supports JSON5 format";
 ```
 
-### 3. 使用默认配置
+### 5. 直接使用ConfigManager类
 
 ```javascript
-// 使用默认配置，并指定保存路径
-const config = conf({
-    name: "default",
-    version: "1.0.0"
-}, "./config.json");
+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. 配置文件使用UTF-8编码的JSON格式
+4. 使用防抖功能可以减少频繁的文件IO操作
+5. 异步API适合在非阻塞环境中使用
+6. 当使用JSON5格式时，保存仍使用标准JSON格式，但可读取JSON5格式的文件
 
 ## 依赖
 
-- json5: 用于解析JSON
+- json5: 用于解析JSON5格式
 - mm_expand: 提供文件操作扩展
 
 ## 许可证

package/index.js

@@ -1,24 +1,210 @@
-require("mm_expand");
+const JSON5 = require('json5');
+const { writeFileSync, readFileSync, writeFile } = require('fs');
+const { promisify } = require('util');
+const writeFileAsync = promisify(writeFile);
 
 /**
- * 重够配置，同步保存
+ * 配置管理器类，提供同步和异步API
+ */
+class ConfigManager {
+  /**
+   * 构造函数
+   * @param {Object} _config 配置对象
+   * @param {String} _jsonFile 配置文件路径
+   * @param {Object} options 配置选项
+   * @param {Number} options.debounceTime 防抖时间(ms)
+   * @param {Boolean} options.pretty 是否美化输出
+   * @param {String} options.format 格式(json/json5)
+   */
+  constructor(_config, _jsonFile, options = {}) {
+    this.config = _config || {};
+    this.filePath = _jsonFile;
+    this.options = {
+      debounceTime: 0, // 默认不防抖
+      pretty: true,
+      format: 'json',
+      ...options
+    };
+    this.writeTimer = null;
+    this.writePromise = Promise.resolve();
+
+    // 如果没有提供配置且有文件路径，则从文件加载
+    if (!_config && _jsonFile) {
+      try {
+        const content = readFileSync(_jsonFile, 'utf-8');
+        if (content) {
+          this.config = this.options.format === 'json5' ? JSON5.parse(content) : JSON.parse(content);
+        }
+      } catch (error) {
+        console.error(`Error loading config from ${_jsonFile}:`, error.message);
+        this.config = {};
+      }
+    }
+  }
+
+  /**
+   * 保存配置到文件（同步）
+   */
+  saveSync() {
+    if (!this.filePath) return;
+    
+    try {
+      const content = this.options.pretty 
+        ? JSON.stringify(this.config, null, 4) 
+        : JSON.stringify(this.config);
+      writeFileSync(this.filePath, content, 'utf-8');
+      return true;
+    } catch (error) {
+      console.error(`Error saving config to ${this.filePath}:`, error.message);
+      return false;
+    }
+  }
+
+  /**
+   * 保存配置到文件（异步）
+   * @returns {Promise<Boolean>}
+   */
+  async saveAsync() {
+    if (!this.filePath) return Promise.resolve(true);
+    
+    // 确保之前的写操作完成
+    await this.writePromise;
+    
+    const content = this.options.pretty 
+      ? JSON.stringify(this.config, null, 4) 
+      : JSON.stringify(this.config);
+    
+    this.writePromise = writeFileAsync(this.filePath, content, 'utf-8')
+      .then(() => true)
+      .catch(error => {
+        console.error(`Error saving config to ${this.filePath}:`, error.message);
+        return false;
+      });
+    
+    return this.writePromise;
+  }
+
+  /**
+   * 获取代理对象
+   * @returns {Proxy}
+   */
+  getProxy() {
+    const self = this;
+    
+    return new Proxy(this.config, {
+      set(obj, prop, value) {
+        obj[prop] = value;
+        
+        if (self.options.debounceTime > 0) {
+          // 防抖处理
+          if (self.writeTimer) {
+            clearTimeout(self.writeTimer);
+          }
+          self.writeTimer = setTimeout(() => {
+            self.saveSync();
+          }, self.options.debounceTime);
+        } else {
+          // 无防抖，直接保存
+          self.saveSync();
+        }
+        
+        return true;
+      },
+      
+      get(obj, prop) {
+        // 提供一些特殊属性访问
+        if (prop === '_saveAsync') {
+          return () => self.saveAsync();
+        }
+        if (prop === '_saveSync') {
+          return () => self.saveSync();
+        }
+        if (prop === '_raw') {
+          return obj;
+        }
+        
+        return obj[prop];
+      }
+    });
+  }
+
+  /**
+   * 获取异步代理对象
+   * @returns {Proxy}
+   */
+  getAsyncProxy() {
+    const self = this;
+    
+    return new Proxy(this.config, {
+      set(obj, prop, value) {
+        obj[prop] = value;
+        
+        if (self.options.debounceTime > 0) {
+          if (self.writeTimer) {
+            clearTimeout(self.writeTimer);
+          }
+          self.writeTimer = setTimeout(() => {
+            self.saveAsync();
+          }, self.options.debounceTime);
+        } else {
+          self.saveAsync();
+        }
+        
+        return true;
+      },
+      
+      get(obj, prop) {
+        if (prop === '_saveAsync') {
+          return () => self.saveAsync();
+        }
+        if (prop === '_saveSync') {
+          return () => self.saveSync();
+        }
+        if (prop === '_raw') {
+          return obj;
+        }
+        
+        return obj[prop];
+      }
+    });
+  }
+}
+
+/**
+ * 创建配置管理器的工厂函数
+ * @param {Object} _config 配置对象
+ * @param {String} _jsonFile 配置文件路径
+ * @param {Object} options 配置选项
+ * @returns {Proxy}
+ */
+function createConfig(_config, _jsonFile, options = {}) {
+  // 兼容旧的调用方式（this.filename）
+  if (!_jsonFile && this && this.filename) {
+    _jsonFile = this.filename;
+  }
+  
+  const manager = new ConfigManager(_config, _jsonFile, options);
+  return manager.getProxy(); // 默认返回同步代理
+}
+
+/**
+ * 创建异步配置管理器的工厂函数
  * @param {Object} _config 配置对象
- * @param {String} _jsonFile 配置文件
+ * @param {String} _jsonFile 配置文件路径
+ * @param {Object} options 配置选项
+ * @returns {Promise<Proxy>}
  */
-module.exports = function(_config, _jsonFile) {
-	if (!_jsonFile) {
-		_jsonFile = this.filename;
-	}
-	if (!_config) {
-		_config = _jsonFile.loadJson() || {};
-	}
-	return new Proxy(_config, {
-		set: function(obj, prop, value) {
-			obj[prop] = value;
-			if (_jsonFile) {
-				_jsonFile.saveJson(obj);
-			}
-			return true
-		}
-	});
-}
+async function createConfigAsync(_config, _jsonFile, options = {}) {
+  // 兼容旧的调用方式（this.filename）
+  if (!_jsonFile && this && this.filename) {
+    _jsonFile = this.filename;
+  }
+  
+  const manager = new ConfigManager(_config, _jsonFile, options);
+  return manager.getAsyncProxy();
+}
+
+// 导出工厂函数和类
+module.exports = createConfig;
+module.exports.createConfigAsync = createConfigAsync;
+module.exports.ConfigManager = ConfigManager;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mm_config",
-    "version": "1.1.5",
+    "version": "2.1.0",
     "description": "这是超级美眉配置同步器,用于更改配置同步保存为JSON文件",
     "main": "index.js",
     "scripts": {
@@ -14,7 +14,10 @@
         "config",
         "JSON",
         "file",
-        "sync"
+        "sync",
+        "async",
+        "debounce",
+        "json5"
     ],
     "author": "邱文武",
     "license": "ISC",

package/test.js

@@ -1,21 +1,132 @@
-var conf = require('./index.js');
+const conf = require('./index.js');
+const createConfigAsync = conf.createConfigAsync;
 
-async function test(){
-	// var config = conf({
-	// 	name: "demo",
-	// 	state: 1
-	// }, "./config.json");
-	
-	this.filename = "./config.json";
-	var config = conf({
-		name: "demo",
-		state: 2
-	});
-	config.name = "test";
-	config.sort = 2;
-	
-	config = conf(null, this.filename);
-	console.log(config);
-	config.age = 26;
+// 测试同步API（向后兼容）
+function testSyncConfig() {
+  console.log('=== 测试同步配置 API（向后兼容）===');
+  
+  // 方式1：提供配置对象和文件路径
+  const config1 = conf({
+    name: "demo",
+    state: 1
+  }, "./config1.json");
+  
+  // 修改配置，会自动保存
+  config1.name = "test1";
+  config1.sort = 1;
+  console.log('配置1:', config1);
+  
+  // 方式2：使用this.filename（兼容旧用法）
+  const context = {
+    filename: "./config2.json"
+  };
+  
+  const config2 = conf.call(context, {
+    name: "demo",
+    state: 2
+  });
+  
+  config2.name = "test2";
+  config2.sort = 2;
+  console.log('配置2:', config2);
+  
+  // 从文件加载配置
+  const config3 = conf(null, "./config1.json");
+  console.log('从文件加载的配置:', config3);
+  
+  // 手动保存
+  config3.age = 26;
+  config3._saveSync(); // 显式调用保存
+  console.log('更新后的配置3:', config3);
 }
-test();
+
+// 测试异步API
+async function testAsyncConfig() {
+  console.log('\n=== 测试异步配置 API ===');
+  
+  try {
+    // 创建异步配置
+    const configAsync = await createConfigAsync({
+      name: "asyncDemo",
+      state: 3
+    }, "./config_async.json");
+    
+    // 修改配置，会异步自动保存
+    configAsync.name = "asyncTest2";
+    configAsync.timestamp = new Date().toISOString();
+    console.log('异步配置:', configAsync);
+    
+    // 显式调用异步保存
+    // await configAsync._saveAsync();
+    console.log('异步保存完成');
+    
+  } catch (error) {
+    console.error('异步配置测试出错:', error);
+  }
+}
+
+// 测试高级功能：防抖
+function testDebounce() {
+  console.log('\n=== 测试防抖功能 ===');
+  
+  // 创建带防抖的配置（500ms延迟保存）
+  const configDebounce = conf({
+    name: "debounceDemo"
+  }, "./config_debounce.json", {
+    debounceTime: 500, // 500ms防抖时间
+    pretty: true       // 美化JSON输出
+  });
+  
+  // 快速多次修改，应该只保存最后一次
+  console.log('开始多次快速修改...');
+  for (let i = 0; i < 5; i++) {
+    configDebounce.value = i;
+    configDebounce.timestamp = new Date().toISOString();
+  }
+  
+  console.log('修改完成，等待防抖触发保存...');
+  console.log('最终配置:', configDebounce);
+}
+
+// 测试JSON5格式
+function testJson5() {
+  console.log('\n=== 测试JSON5格式支持 ===');
+  
+  // 创建配置时指定JSON5格式
+  const configJson5 = conf({
+    name: "json5Demo",
+    // JSON5支持的一些特性，如注释、尾随逗号等
+    // 虽然保存时会转为标准JSON，但读取时可以处理JSON5格式
+  }, "./config_json5.json", {
+    format: 'json5',
+    pretty: true
+  });
+  
+  configJson5.description = "This uses JSON5 format";
+  console.log('JSON5配置:', configJson5);
+}
+
+// 运行所有测试
+async function runAllTests() {
+  console.log('开始运行配置管理器测试...');
+  
+  // 运行同步测试
+  testSyncConfig();
+  
+  // 运行异步测试
+  await testAsyncConfig();
+  
+  // 运行防抖测试
+  testDebounce();
+  
+  // 运行JSON5测试
+  testJson5();
+  
+  console.log('\n所有测试完成！');
+  console.log('请查看生成的配置文件以验证保存结果。');
+}
+
+// 执行测试
+runAllTests().catch(err => {
+  console.error('测试过程中出现错误:', err);
+});