configforge 1.0.0-beta.8 → 1.0.0

package/README.md

@@ -781,9 +781,348 @@ const result = await converter.convert('./config.yml');
 await result.save('./config.json');
 ```
 
+### Example 9: Plugin System with Built-in Plugins
+
+```javascript
+const {
+  forge,
+  createValidationPlugin,
+  createAuditPlugin,
+  createBackupPlugin,
+} = require('configforge');
+
+// Create converter with plugin support
+const converter = forge()
+  .from('userForm')
+  .to('userProfile')
+  .map('personalInfo.firstName', 'firstName')
+  .map('personalInfo.lastName', 'lastName')
+  .map('personalInfo.email', 'email')
+  .map('accountInfo.username', 'username')
+  .merge(
+    ['personalInfo.firstName', 'personalInfo.lastName'],
+    'fullName',
+    (first, last) => `${first} ${last}`
+  );
+
+// Add built-in plugins
+const validationPlugin = createValidationPlugin({
+  strictMode: true,
+  failOnWarnings: false,
+});
+
+const auditPlugin = createAuditPlugin({
+  logFile: './conversion-audit.log',
+  logLevel: 'detailed',
+  includeData: false,
+});
+
+const backupPlugin = createBackupPlugin({
+  backupDir: './backups',
+  keepVersions: 5,
+  timestampFormat: 'YYYY-MM-DD_HH-mm-ss',
+});
+
+// Install plugins
+await converter.use(validationPlugin);
+await converter.use(auditPlugin);
+await converter.use(backupPlugin);
+
+// Convert with plugin enhancements
+const userData = {
+  personalInfo: {
+    firstName: 'John',
+    lastName: 'Doe',
+    email: 'john.doe@example.com',
+  },
+  accountInfo: {
+    username: 'johndoe123',
+  },
+};
+
+const result = await converter.convert(userData);
+
+// Plugins automatically:
+// - Validate data quality (ValidationPlugin)
+// - Log conversion activities (AuditPlugin)
+// - Create backups of source data (BackupPlugin)
+// - Handle errors gracefully with detailed reporting
+
+console.log(result.data);
+// {
+//   firstName: 'John',
+//   lastName: 'Doe',
+//   email: 'john.doe@example.com',
+//   username: 'johndoe123',
+//   fullName: 'John Doe'
+// }
+
+// Check plugin results
+console.log('Validation results:', result.context?.validationResults);
+console.log('Backup created:', result.context?.backupPath);
+```
+
+### Example 10: Batch Processing and Performance Features
+
+```javascript
+const {
+  forge,
+  BatchProcessor,
+  IncrementalProcessor,
+  PerformanceMonitor,
+} = require('configforge');
+
+// Create converter for processing multiple config files
+const converter = forge()
+  .from('legacy-config')
+  .to('modern-config')
+  .map('app_name', 'application.name')
+  .map('app_version', 'application.version')
+  .map('database.host', 'db.hostname')
+  .map('database.port', 'db.port')
+  .map('server.port', 'application.port')
+  .defaults({
+    environment: 'production',
+    createdAt: () => new Date().toISOString(),
+  });
+
+// 1. Batch Processing - Convert multiple files efficiently
+const batchResult = await converter.convertBatch(
+  ['./configs/app1.yml', './configs/app2.yml', './configs/app3.yml'],
+  {
+    parallel: true,
+    workers: 3,
+    errorStrategy: 'continue',
+    progressCallback: progress => {
+      console.log(`Progress: ${progress.completed}/${progress.total} files`);
+    },
+  }
+);
+
+console.log(
+  `Processed ${batchResult.stats.successfulFiles} files successfully`
+);
+console.log(`Failed: ${batchResult.stats.failedFiles} files`);
+console.log(`Total duration: ${batchResult.stats.totalDuration}ms`);
+
+// 2. Incremental Processing - Only process changed files
+const incrementalResult = await converter.convertIncremental(
+  './config.yml',
+  './output/config.json',
+  './.cache' // Cache directory
+);
+
+if (incrementalResult) {
+  console.log('File was processed (changed since last run)');
+} else {
+  console.log('File skipped (no changes detected)');
+}
+
+// 3. Incremental Batch Processing
+const incrementalBatchResult = await converter.convertIncrementalBatch(
+  ['./configs/app1.yml', './configs/app2.yml', './configs/app3.yml'],
+  './output',
+  {
+    cacheDir: './.cache',
+    getOutputPath: inputPath => {
+      const fileName = inputPath.split('/').pop().replace('.yml', '.json');
+      return `./output/${fileName}`;
+    },
+  }
+);
+
+console.log(`Processed: ${incrementalBatchResult.processed.length} files`);
+console.log(
+  `Skipped: ${incrementalBatchResult.skipped.length} files (unchanged)`
+);
+
+// 4. Performance Monitoring
+const monitor = new PerformanceMonitor();
+monitor.start();
+
+// Track individual steps
+monitor.startStep('parse');
+const result = await converter.convert('./large-config.yml');
+monitor.endStep('parse');
+
+// Record file sizes for throughput calculation
+monitor.recordSizes(1024 * 1024, 800 * 1024); // 1MB input, 800KB output
+
+// Get detailed performance metrics
+const metrics = monitor.finish(result.stats);
+const report = monitor.createReport(metrics);
+
+console.log(report);
+// === Performance Report ===
+//
+// Timing Breakdown:
+//   Parse:     15.23ms
+//   Map:       8.45ms
+//   Transform: 3.21ms
+//   Validate:  2.10ms
+//   Serialize: 5.67ms
+//   Total:     34.66ms
+//
+// Throughput:
+//   Fields/sec:     2890
+//   Transforms/sec: 1445
+//   Bytes/sec:      29.64 MB/s
+//
+// Memory Usage:
+//   Heap Used:  45.23 MB
+//   Heap Total: 67.89 MB
+//   RSS:        89.12 MB
+//
+// File Sizes:
+//   Input:      1.00 MB
+//   Output:     800.00 KB
+//   Ratio:      80.0%
+
+// 5. Performance Benchmarking
+const { PerformanceBenchmark } = require('configforge');
+
+const sequentialOperation = async () => {
+  return converter.convertBatch(['./config1.yml', './config2.yml'], {
+    parallel: false,
+  });
+};
+
+const parallelOperation = async () => {
+  return converter.convertBatch(['./config1.yml', './config2.yml'], {
+    parallel: true,
+    workers: 2,
+  });
+};
+
+const benchmarks = [
+  { name: 'sequential-processing', operation: sequentialOperation },
+  { name: 'parallel-processing', operation: parallelOperation },
+];
+
+const benchmarkResults = await PerformanceBenchmark.compareBenchmarks(
+  benchmarks,
+  10
+);
+const comparisonReport =
+  PerformanceBenchmark.createComparisonReport(benchmarkResults);
+
+console.log(comparisonReport);
+// === Benchmark Comparison ===
+//
+// Results (sorted by average time):
+//   parallel-processing:
+//     Average: 45.23ms (fastest)
+//     Range:   42.10ms - 48.90ms
+//     Std Dev: 2.15ms
+//     Ops/sec: 22
+//
+//   sequential-processing:
+//     Average: 78.45ms (1.73x slower)
+//     Range:   75.20ms - 82.10ms
+//     Std Dev: 2.89ms
+//     Ops/sec: 13
+
+// 6. Advanced Batch Processing with Custom Options
+const advancedBatchResult = await converter.convertBatch(
+  [
+    './configs/*.yml', // Glob patterns supported
+  ],
+  {
+    parallel: true,
+    workers: 4,
+    errorStrategy: 'fail-fast', // Stop on first error
+    progressCallback: progress => {
+      const percentage = Math.round(
+        (progress.completed / progress.total) * 100
+      );
+      console.log(`[${percentage}%] Processing: ${progress.current}`);
+      if (progress.failed > 0) {
+        console.log(`⚠️  ${progress.failed} files failed`);
+      }
+    },
+  }
+);
+
+// Save all results to output directory
+const batchProcessor = new BatchProcessor(converter);
+await batchProcessor.saveBatch(advancedBatchResult.results, './output', [
+  './configs/app1.yml',
+  './configs/app2.yml',
+]);
+
+// 7. Cache Management for Incremental Processing
+const incrementalProcessor = new IncrementalProcessor(converter, './.cache');
+
+// Get cache statistics
+const cacheStats = incrementalProcessor.getCacheStats();
+console.log(`Cache entries: ${cacheStats.totalEntries}`);
+console.log(`Successful: ${cacheStats.successfulEntries}`);
+console.log(`Failed: ${cacheStats.failedEntries}`);
+
+// Clean up stale cache entries
+const removedEntries = await incrementalProcessor.cleanupCache();
+console.log(`Removed ${removedEntries} stale cache entries`);
+
+// Clear entire cache
+await incrementalProcessor.clearCache();
+console.log('Cache cleared');
+```
+
+### Example 11: CLI Generation System
+
+```javascript
+const { forge, CLIGenerator } = require('configforge');
+
+// Create your converter
+const converter = forge()
+  .from('legacy')
+  .to('modern')
+  .map('app_name', 'name')
+  .map('app_version', 'version')
+  .map('database.host', 'db.hostname')
+  .map('database.port', 'db.port')
+  .defaults({
+    environment: 'production',
+  });
+
+// Generate CLI for your converter
+const cli = CLIGenerator.forConverter(converter, {
+  name: 'config-converter',
+  version: '1.0.0',
+  description: 'Convert legacy config to modern format',
+});
+
+// Add custom commands
+cli.addCommand({
+  name: 'migrate',
+  description: 'Migrate all configs in a directory',
+  options: [
+    {
+      flags: '-d, --directory <dir>',
+      description: 'Directory containing config files',
+    },
+  ],
+  action: async options => {
+    // Custom migration logic
+    console.log(`Migrating configs in ${options.directory}`);
+  },
+});
+
+// Parse command line arguments
+cli.parse();
+
+// Now you can use your CLI:
+// $ config-converter convert input.yml output.json
+// $ config-converter validate config.yml
+// $ config-converter profile save my-config
+// $ config-converter profile list
+// $ config-converter migrate -d ./configs
+```
+
 ## 🎯 Key Features
 
 - ✅ **Simple API**: Just map fields and convert
+- ✅ **Pipeline Architecture**: Robust internal processing with configurable steps and error handling
 - ✅ **No direct Mapper usage needed**: The `convert()` method handles everything
 - ✅ **Nested object support**: Use dot notation like `user.profile.name`
 - ✅ **Array access**: Use bracket notation like `items[0]`
@@ -791,6 +1130,12 @@ await result.save('./config.json');
 - ✅ **Conditional mapping**: Use `when()` for conditional logic
 - ✅ **Multi-field merging**: Use `merge()` to combine multiple sources into one target
 - ✅ **Default values**: Set fallback values
+- ✅ **Comprehensive Error Handling**: Advanced error reporting with context and suggestions ⭐ ENHANCED!
+- ✅ **CLI Generation System**: Create command-line interfaces for converters ⭐ ENHANCED!
+- ✅ **Plugin System**: Extensible architecture with built-in plugins for validation, auditing, and backups ⭐ ENHANCED!
+- ✅ **Batch Processing**: Efficiently process multiple files with parallel support and progress tracking ⭐ ENHANCED!
+- ✅ **Incremental Processing**: Only process changed files using content hashing and modification times ⭐ ENHANCED!
+- ✅ **Performance Monitoring**: Detailed performance tracking, benchmarking, and reporting ⭐ ENHANCED!
 - ✅ **File support**: Convert YAML, JSON files directly
 - ✅ **Statistics**: Get detailed conversion reports
 - ✅ **TypeScript**: Full type safety
@@ -808,14 +1153,19 @@ await result.save('./config.json');
 - **Multi-field merging with `merge()`**
 - **Field validation with `validate()`**
 - **Lifecycle hooks with `before()` and `after()`** ⭐ NEW!
+- **Advanced error handling and reporting system** ⭐ NEW!
+- **CLI generation system with command-line interfaces** ⭐ ENHANCED!
+- **Plugin system foundation with built-in plugins** ⭐ NEW!
+- **Batch processing with parallel support and progress tracking** ⭐ ENHANCED!
+- **Incremental processing with content hashing and modification times** ⭐ ENHANCED!
+- **Performance monitoring with detailed benchmarking and reporting** ⭐ ENHANCED!
 - File parsing (YAML, JSON)
 - Conversion statistics and reporting
 - Async and sync conversion support
 
 **🚧 Coming Soon:**
 
-- CLI generation
-- Plugin system
+- Advanced plugin ecosystem
 
 ## 💡 Tips
 
@@ -837,6 +1187,25 @@ await result.save('./config.json');
 16. **Use `after()` hooks** to postprocess target data after conversion
 17. **Hooks can be async** - just use `async (data) => { ... }` and they'll be awaited
 18. **Multiple hooks execute in order** - add as many as you need for complex workflows
+19. **Error handling provides helpful suggestions** - when field mapping fails, you'll get suggestions for similar field names
+20. **Errors include rich context** - see exactly where and why conversions failed with detailed error information
+21. **Use error categories** to filter and handle different types of errors (validation, mapping, parsing, etc.)
+22. **Create CLIs for converters** - use `CLIGenerator.forConverter(converter)` to generate command-line interfaces
+23. **Use CLI profiles** - save converter configurations as profiles for reuse: `cli profile save my-converter`
+24. **CLI supports batch processing** - convert multiple files at once with pattern matching and parallel processing
+25. **Use built-in plugins** - leverage ValidationPlugin, AuditPlugin, and BackupPlugin for enhanced functionality
+26. **Plugin hooks execute in order** - plugins can intercept and modify data at different conversion stages
+27. **Error hooks provide recovery** - plugins can handle errors gracefully and provide fallback behavior
+28. **Use batch processing for multiple files** - `convertBatch()` processes multiple files efficiently with parallel support
+29. **Enable parallel processing** - set `parallel: true` and configure `workers` for faster batch processing
+30. **Use incremental processing** - `convertIncremental()` only processes files that have changed since last run
+31. **Monitor performance** - use `PerformanceMonitor` to track conversion speed, memory usage, and throughput
+32. **Benchmark different approaches** - use `PerformanceBenchmark` to compare sequential vs parallel processing
+33. **Configure error strategies** - use `errorStrategy: 'continue'` to process all files even if some fail, or `'fail-fast'` to stop on first error
+34. **Track progress** - provide `progressCallback` to monitor batch processing progress in real-time
+35. **Cache management** - use `IncrementalProcessor.getCacheStats()` and `cleanupCache()` to manage incremental processing cache
+36. **Save batch results** - use `BatchProcessor.saveBatch()` to save all conversion results to an output directory
+37. **Use forge() with options** - pass `ForgeOptions` to `forge({ strict: true, parallel: true })` to configure converter behavior globally
 
 ---
 

package/dist/core/BatchProcessor.d.ts

@@ -0,0 +1,48 @@
+import { BatchOptions, BatchProgress, BatchResult, ConversionResult } from '../types';
+import { Converter } from './Converter';
+/**
+ * BatchProcessor handles efficient processing of multiple files
+ * with parallel processing support and progress tracking
+ */
+export declare class BatchProcessor {
+    private converter;
+    private options;
+    constructor(converter: Converter, options?: BatchOptions);
+    /**
+     * Process multiple files efficiently
+     */
+    process(inputs: string[]): Promise<BatchResult>;
+    /**
+     * Process files sequentially
+     */
+    private processSequentially;
+    /**
+     * Process files in parallel using worker threads or Promise.all
+     */
+    private processInParallel;
+    /**
+     * Process a single file
+     */
+    private processFile;
+    /**
+     * Create an empty batch result
+     */
+    private createEmptyResult;
+    /**
+     * Split array into chunks
+     */
+    private chunkArray;
+    /**
+     * Save batch results to files
+     */
+    saveBatch(results: ConversionResult[], outputDir: string, inputPaths: string[]): Promise<void>;
+    /**
+     * Generate a progress report
+     */
+    generateProgressReport(progress: BatchProgress): string;
+    /**
+     * Create a simple progress bar
+     */
+    private createProgressBar;
+}
+//# sourceMappingURL=BatchProcessor.d.ts.map

package/dist/core/BatchProcessor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BatchProcessor.d.ts","sourceRoot":"","sources":["../../src/core/BatchProcessor.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,WAAW,EAEX,gBAAgB,EAGjB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAKxC;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,OAAO,CAAyB;gBAE5B,SAAS,EAAE,SAAS,EAAE,OAAO,GAAE,YAAiB;IAU5D;;OAEG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAyDrD;;OAEG;YACW,mBAAmB;IA2CjC;;OAEG;YACW,iBAAiB;IA4E/B;;OAEG;YACW,WAAW;IAwCzB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAczB;;OAEG;IACH,OAAO,CAAC,UAAU;IAQlB;;OAEG;IACG,SAAS,CACb,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,IAAI,CAAC;IAyBhB;;OAEG;IACH,sBAAsB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM;IAcvD;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAK1B"}