mm_config 2.1.6 → 2.1.7

package/README_EN.md

@@ -0,0 +1,382 @@
+# mm_config
+
+Super Meimei Configuration Helper - Dynamic file-based configuration with automatic synchronization.
+
+## Features
+
+- Dynamic reading and modification of configuration files
+- Automatic synchronization to JSON files when configuration changes
+- Proxy-based property monitoring for convenient operation
+- Support for both synchronous and asynchronous API operations
+- Debounce functionality to reduce frequent file saves
+- Built-in error handling mechanism for improved stability
+- Support for JSON5 format configuration files
+- Concise naming following single-word priority principle
+- Built-in cache management to avoid duplicate configuration instances
+
+## Installation
+
+```bash
+npm install mm_config
+```
+
+## Quick Start
+
+### Basic Usage
+
+```javascript
+const { create } = require('mm_config');
+
+// Create configuration with file path
+const config = create("./config.json", {
+    name: "demo",
+    state: 1
+});
+
+// Modifications automatically save to file
+config.name = "test";
+config.sort = 2;
+
+console.log(config); // { name: 'test', state: 1, sort: 2 }
+```
+
+### Async Usage
+
+```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 Reference
+
+### Import Module
+
+```javascript
+// Import configuration classes
+const { Config, create, createAsync, clear, clearAll } = require('mm_config');
+```
+
+### Configuration Initialization
+
+#### Synchronous API
+
+```javascript
+/**
+ * Create synchronous configuration
+ * @param {string} file - Configuration file path
+ * @param {object} config - Configuration object, optional
+ * @param {object} options - Configuration options, optional
+ * @param {number} options.debounce_time - Debounce time in ms, default 0
+ * @param {boolean} options.pretty - Whether to prettify output, default true
+ * @param {string} options.format - Format (json/json5), default 'json'
+ * @returns {Proxy} Configuration proxy object
+ */
+const config = create(file, config, options);
+```
+
+#### Asynchronous API
+
+```javascript
+/**
+ * Create asynchronous configuration
+ * @param {string} file - Configuration file path
+ * @param {object} config - Configuration object, optional
+ * @param {object} options - Configuration options, optional
+ * @returns {Promise<Proxy>} Promise of configuration proxy object
+ */
+const config = await createAsync(file, config, options);
+```
+
+#### Cache Management API
+
+```javascript
+/**
+ * Clear configuration cache for specific file
+ * @param {string} file - Configuration file path
+ */
+clear(file);
+
+/**
+ * Clear all configuration caches
+ */
+clearAll();
+```
+
+#### Proxy Object Special Methods
+
+Access these special methods through the proxy object:
+
+- `_saveSync()`: Synchronously save configuration to file
+- `_saveAsync()`: Asynchronously save configuration to file
+- `_raw`: Get the raw configuration object
+
+## Usage Examples
+
+### 1. Basic Synchronous Configuration
+
+```javascript
+const { create } = require('mm_config');
+
+// Create configuration with file path
+const config = create("./config.json", {
+    name: "demo",
+    state: 1
+});
+
+// Modifications automatically save to file
+config.name = "test";
+config.sort = 2;
+
+// Explicit save call
+config._saveSync();
+
+// Read existing configuration
+const existingConfig = create("./config.json");
+console.log(existingConfig.name); // "test"
+```
+
+### 2. Using Async API
+
+```javascript
+const { createAsync } = require('mm_config');
+
+async function setupConfig() {
+    // Create async configuration
+    const config = await createAsync("./async_config.json", {
+        name: "asyncDemo",
+        version: "1.0.0"
+    });
+    
+    // Modifications asynchronously save to file
+    config.timestamp = new Date().toISOString();
+    
+    // Explicit async save call
+    await config._saveAsync();
+    
+    return config;
+}
+
+setupConfig().then(config => {
+    console.log('Configuration setup complete:', config);
+});
+```
+
+### 3. Using Debounce Functionality
+
+```javascript
+const { create } = require('mm_config');
+
+// Create configuration with debounce (500ms delay)
+const config = create("./debounce_config.json", {
+    name: "debounceDemo"
+}, {
+    debounce_time: 500 // 500ms debounce time
+});
+
+// Rapid modifications will only save the last change after 500ms
+for (let i = 0; i < 10; i++) {
+    config.counter = i;
+    config.timestamp = new Date().toISOString();
+}
+
+// Only the last value will be saved
+console.log(config.counter); // 9
+```
+
+### 4. Using JSON5 Format
+
+```javascript
+const { create } = require('mm_config');
+
+// Create configuration with JSON5 format support
+const config = create("./config.json5", null, {
+    format: 'json5'
+});
+
+// JSON5 format supports comments, trailing commas, etc.
+config.description = "This supports JSON5 format";
+config.version = "1.0.0";
+```
+
+### 5. Direct Config Class Usage
+
+```javascript
+const { Config } = require('mm_config');
+
+// Create configuration instance
+const cfg = new Config({
+    debounce_time: 100,
+    pretty: true
+}, {
+    name: "directDemo"
+});
+
+// Get proxy object
+const config = cfg.getProxy();
+
+// Use configuration
+config.version = "1.0.0";
+
+// Manual save methods
+cfg.saveSync();
+await cfg.saveAsync();
+```
+
+### 6. Using Configuration Operation Methods
+
+```javascript
+const { Config } = require('mm_config');
+
+const cfg = new Config({}, "./methods_config.json");
+
+async function manageConfig() {
+    // Set configuration value
+    await cfg.set("name", "test");
+    
+    // Get configuration value
+    const name = await cfg.get("name");
+    console.log('Retrieved name:', name); // "test"
+    
+    // Check if configuration exists
+    const hasName = await cfg.has("name");
+    console.log('Has name:', hasName); // true
+    
+    // Delete configuration item
+    await cfg.del("name");
+    
+    // Get all keys
+    const keys = await cfg.keys();
+    console.log('All keys:', keys);
+}
+
+manageConfig();
+```
+
+### 7. Cache Management Functionality
+
+```javascript
+const { create, clear, clearAll } = require('mm_config');
+
+// Create configuration instances
+const config1 = create("./cache1.json", { test: "cache1" });
+const config2 = create("./cache2.json", { test: "cache2" });
+
+// Clear specific file cache
+clear("./cache1.json");
+
+// Recreate will generate new instance
+const config1New = create("./cache1.json", { test: "cache1_new" });
+
+// Clear all caches
+clearAll();
+
+// All configurations will be recreated
+const config2New = create("./cache2.json", { test: "cache2_new" });
+```
+
+## Configuration Options
+
+Available options when creating configurations:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| debounce_time | number | 0 | Debounce time in milliseconds, delays saves after multiple modifications |
+| pretty | boolean | true | Whether to prettify JSON output, set to false for compressed JSON |
+| format | string | 'json' | Configuration file format, options: 'json' or 'json5' |
+
+## Advanced Usage
+
+### Error Handling
+
+```javascript
+const { create } = require('mm_config');
+
+try {
+    const config = create("./config.json", { test: 1 });
+    config.invalid = "value";
+} catch (error) {
+    console.error('Configuration operation error:', error.message);
+}
+```
+
+### Performance Optimization
+
+```javascript
+// Use debounce to reduce frequent file I/O operations
+const config = create("./config.json", {}, {
+    debounce_time: 1000 // 1 second debounce
+});
+
+// Use _raw property for batch operations to avoid frequent saves
+const rawConfig = config._raw;
+rawConfig.field1 = "value1";
+rawConfig.field2 = "value2";
+rawConfig.field3 = "value3";
+// Manual save once
+config._saveSync();
+```
+
+## Important Notes
+
+1. **File Permissions**: Ensure write permissions for the files
+2. **Async Operations**: Async API is suitable for non-blocking environments
+3. **Cache Management**: Configuration instances are cached, same file path returns same instance
+4. **JSON5 Format**: When using JSON5 format, saves still use standard JSON format but can read JSON5 files
+5. **Memory Management**: Use clear/clearAll to clean cache and avoid memory leaks
+
+## Dependencies
+
+- **json5**: For parsing JSON5 format
+- **mm_expand**: For file operation extensions
+
+## Naming Convention
+
+This module follows concise naming principles:
+- Class names: `Config` (single-word priority)
+- Method names: `get()`, `set()`, `has()`, `del()` (verb-first)
+- Variable names: `val`, `key`, `bl` (concise and no redundancy)
+
+## Testing
+
+```bash
+# Run tests
+npm test
+
+# Or run test file directly
+node test.js
+```
+
+## License
+
+ISC License
+
+## Version History
+
+- **v2.1.6**: Fixed code standards issues, improved documentation
+- **v2.1.5**: Optimized ESLint configuration, improved code quality
+- **v2.1.4**: Added cache management, fixed memory leaks
+- **v2.1.3**: Refactored API, following concise naming conventions
+- **v2.1.2**: Added JSON5 format support
+- **v2.1.1**: Optimized debounce functionality
+- **v2.1.0**: Initial release
+
+## Contributing
+
+Welcome to submit Issues and Pull Requests to improve this project.
+
+## Related Projects
+
+- [mm_expand](https://github.com/supermm/mm_expand) - File operation extension module
+- [mm_eslint](https://github.com/supermm/mm_eslint) - ESLint configuration plugin
+
+---
+
+**mm_config** - Making configuration management simple and efficient!