mm_config

超级美眉配置帮助类，动态同步文件修改配置。

功能特点

• 支持配置文件的动态读取和修改
• 修改配置后自动同步保存到JSON文件
• 使用Proxy实现属性监听，操作方便
• 支持同步和异步API操作
• 支持配置修改防抖功能，减少频繁保存
• 内置错误处理机制，提高稳定性
• 支持JSON5格式配置文件
• 简洁命名，遵循单字优先原则
• 内置缓存管理，避免重复创建配置实例

安装

npm install mm_config

快速开始

基本使用

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 }

异步使用

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说明

导入模块

// 导入配置类
const { Config, create, createAsync, clear, clearAll } = require('mm_config');

配置初始化

同步API

/**
 * 创建同步配置
 * @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

/**
 * 创建异步配置
 * @param {string} file - 配置文件路径
 * @param {object} config - 配置对象，可选
 * @param {object} options - 配置选项，可选
 * @returns {Promise<Proxy>} 返回配置代理对象的Promise
 */
const config = await createAsync(file, config, options);

缓存管理API

/**
 * 清理指定文件配置缓存
 * @param {string} file - 配置文件路径
 */
clear(file);

/**
 * 清理所有配置缓存
 */
clearAll();

代理对象特殊方法

通过代理对象可以访问以下特殊方法：

• _saveSync(): 同步保存配置到文件
• _saveAsync(): 异步保存配置到文件
• _raw: 获取原始配置对象

使用示例

1. 基本同步配置

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

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. 使用防抖功能

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格式

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类

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. 使用配置操作方法

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. 缓存管理功能

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' |

高级用法

错误处理

const { create } = require('mm_config');

try {
    const config = create("./config.json", { test: 1 });
    config.invalid = "value";
} catch (error) {
    console.error('配置操作出错:', error.message);
}

性能优化

// 使用防抖减少频繁的文件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（简洁无废话）

测试

# 运行测试
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 - 文件操作扩展模块
• mm_eslint - ESLint配置插件

mm_config - 让配置管理变得简单高效！