configforge 1.0.0-beta.9 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. package/README.md +594 -3
  2. package/dist/core/BatchProcessor.d.ts +48 -0
  3. package/dist/core/BatchProcessor.d.ts.map +1 -0
  4. package/dist/core/BatchProcessor.js +273 -0
  5. package/dist/core/BatchProcessor.js.map +1 -0
  6. package/dist/core/ConversionResult.d.ts +22 -0
  7. package/dist/core/ConversionResult.d.ts.map +1 -1
  8. package/dist/core/ConversionResult.js +44 -30
  9. package/dist/core/ConversionResult.js.map +1 -1
  10. package/dist/core/Converter.d.ts +63 -3
  11. package/dist/core/Converter.d.ts.map +1 -1
  12. package/dist/core/Converter.js +180 -27
  13. package/dist/core/Converter.js.map +1 -1
  14. package/dist/core/IncrementalProcessor.d.ts +75 -0
  15. package/dist/core/IncrementalProcessor.d.ts.map +1 -0
  16. package/dist/core/IncrementalProcessor.js +298 -0
  17. package/dist/core/IncrementalProcessor.js.map +1 -0
  18. package/dist/core/PerformanceMonitor.d.ts +103 -0
  19. package/dist/core/PerformanceMonitor.d.ts.map +1 -0
  20. package/dist/core/PerformanceMonitor.js +253 -0
  21. package/dist/core/PerformanceMonitor.js.map +1 -0
  22. package/dist/core/Pipeline.js +1 -1
  23. package/dist/core/Pipeline.js.map +1 -1
  24. package/dist/core/index.d.ts +3 -0
  25. package/dist/core/index.d.ts.map +1 -1
  26. package/dist/core/index.js +8 -1
  27. package/dist/core/index.js.map +1 -1
  28. package/dist/core/pipeline/PipelineBuilder.d.ts +4 -0
  29. package/dist/core/pipeline/PipelineBuilder.d.ts.map +1 -1
  30. package/dist/core/pipeline/PipelineBuilder.js +8 -0
  31. package/dist/core/pipeline/PipelineBuilder.js.map +1 -1
  32. package/dist/core/pipeline/PipelineSteps.d.ts.map +1 -1
  33. package/dist/core/pipeline/PipelineSteps.js +6 -4
  34. package/dist/core/pipeline/PipelineSteps.js.map +1 -1
  35. package/dist/errors/ErrorCollector.d.ts +119 -0
  36. package/dist/errors/ErrorCollector.d.ts.map +1 -0
  37. package/dist/errors/ErrorCollector.js +197 -0
  38. package/dist/errors/ErrorCollector.js.map +1 -0
  39. package/dist/errors/ErrorContext.d.ts +168 -0
  40. package/dist/errors/ErrorContext.d.ts.map +1 -0
  41. package/dist/errors/ErrorContext.js +356 -0
  42. package/dist/errors/ErrorContext.js.map +1 -0
  43. package/dist/errors/ErrorRecovery.d.ts +91 -0
  44. package/dist/errors/ErrorRecovery.d.ts.map +1 -0
  45. package/dist/errors/ErrorRecovery.js +321 -0
  46. package/dist/errors/ErrorRecovery.js.map +1 -0
  47. package/dist/errors/ErrorReporter.d.ts +58 -0
  48. package/dist/errors/ErrorReporter.d.ts.map +1 -0
  49. package/dist/errors/ErrorReporter.js +262 -0
  50. package/dist/errors/ErrorReporter.js.map +1 -0
  51. package/dist/errors/ErrorTypes.d.ts +103 -0
  52. package/dist/errors/ErrorTypes.d.ts.map +1 -0
  53. package/dist/errors/ErrorTypes.js +125 -0
  54. package/dist/errors/ErrorTypes.js.map +1 -0
  55. package/dist/errors/SpecificErrors.d.ts +45 -0
  56. package/dist/errors/SpecificErrors.d.ts.map +1 -0
  57. package/dist/errors/SpecificErrors.js +124 -0
  58. package/dist/errors/SpecificErrors.js.map +1 -0
  59. package/dist/errors/SuggestionEngine.d.ts +63 -0
  60. package/dist/errors/SuggestionEngine.d.ts.map +1 -0
  61. package/dist/errors/SuggestionEngine.js +328 -0
  62. package/dist/errors/SuggestionEngine.js.map +1 -0
  63. package/dist/errors/index.d.ts +12 -0
  64. package/dist/errors/index.d.ts.map +1 -0
  65. package/dist/errors/index.js +39 -0
  66. package/dist/errors/index.js.map +1 -0
  67. package/dist/index.d.ts +3 -0
  68. package/dist/index.d.ts.map +1 -1
  69. package/dist/index.js +17 -1
  70. package/dist/index.js.map +1 -1
  71. package/dist/plugins/Plugin.d.ts +95 -0
  72. package/dist/plugins/Plugin.d.ts.map +1 -0
  73. package/dist/plugins/Plugin.js +3 -0
  74. package/dist/plugins/Plugin.js.map +1 -0
  75. package/dist/plugins/PluginManager.d.ts +73 -0
  76. package/dist/plugins/PluginManager.d.ts.map +1 -0
  77. package/dist/plugins/PluginManager.js +220 -0
  78. package/dist/plugins/PluginManager.js.map +1 -0
  79. package/dist/plugins/PluginRegistry.d.ts +122 -0
  80. package/dist/plugins/PluginRegistry.d.ts.map +1 -0
  81. package/dist/plugins/PluginRegistry.js +385 -0
  82. package/dist/plugins/PluginRegistry.js.map +1 -0
  83. package/dist/plugins/built-in/AuditPlugin.d.ts +81 -0
  84. package/dist/plugins/built-in/AuditPlugin.d.ts.map +1 -0
  85. package/dist/plugins/built-in/AuditPlugin.js +235 -0
  86. package/dist/plugins/built-in/AuditPlugin.js.map +1 -0
  87. package/dist/plugins/built-in/BackupPlugin.d.ts +38 -0
  88. package/dist/plugins/built-in/BackupPlugin.d.ts.map +1 -0
  89. package/dist/plugins/built-in/BackupPlugin.js +105 -0
  90. package/dist/plugins/built-in/BackupPlugin.js.map +1 -0
  91. package/dist/plugins/built-in/ValidationPlugin.d.ts +61 -0
  92. package/dist/plugins/built-in/ValidationPlugin.d.ts.map +1 -0
  93. package/dist/plugins/built-in/ValidationPlugin.js +235 -0
  94. package/dist/plugins/built-in/ValidationPlugin.js.map +1 -0
  95. package/dist/plugins/built-in/index.d.ts +7 -0
  96. package/dist/plugins/built-in/index.d.ts.map +1 -0
  97. package/dist/plugins/built-in/index.js +14 -0
  98. package/dist/plugins/built-in/index.js.map +1 -0
  99. package/dist/plugins/index.d.ts +5 -0
  100. package/dist/plugins/index.d.ts.map +1 -0
  101. package/dist/plugins/index.js +25 -0
  102. package/dist/plugins/index.js.map +1 -0
  103. package/dist/scripts/CLIGenerator.d.ts +109 -0
  104. package/dist/scripts/CLIGenerator.d.ts.map +1 -0
  105. package/dist/scripts/CLIGenerator.js +440 -0
  106. package/dist/scripts/CLIGenerator.js.map +1 -0
  107. package/dist/scripts/CLIUtils.d.ts +136 -0
  108. package/dist/scripts/CLIUtils.d.ts.map +1 -0
  109. package/dist/scripts/CLIUtils.js +361 -0
  110. package/dist/scripts/CLIUtils.js.map +1 -0
  111. package/dist/scripts/CommandBuilder.d.ts +72 -0
  112. package/dist/scripts/CommandBuilder.d.ts.map +1 -0
  113. package/dist/scripts/CommandBuilder.js +280 -0
  114. package/dist/scripts/CommandBuilder.js.map +1 -0
  115. package/dist/scripts/index.d.ts +23 -0
  116. package/dist/scripts/index.d.ts.map +1 -0
  117. package/dist/scripts/index.js +43 -0
  118. package/dist/scripts/index.js.map +1 -0
  119. package/package.json +1 -1
package/README.md CHANGED
@@ -52,6 +52,53 @@ console.log(result.data);
52
52
  // }
53
53
  ```
54
54
 
55
+ ### String Input Support ⭐ NEW!
56
+
57
+ ConfigForge now supports converting raw YAML and JSON strings directly:
58
+
59
+ ```javascript
60
+ const { forge } = require('configforge');
61
+
62
+ // Raw YAML string
63
+ const yamlString = `
64
+ name: MyApp
65
+ version: 2.0
66
+ database:
67
+ host: localhost
68
+ port: 5432
69
+ `;
70
+
71
+ // Raw JSON string
72
+ const jsonString = `{
73
+ "name": "MyApp",
74
+ "version": "2.0",
75
+ "database": {
76
+ "host": "localhost",
77
+ "port": 5432
78
+ }
79
+ }`;
80
+
81
+ const converter = forge()
82
+ .map('name', 'appName')
83
+ .map('version', 'appVersion')
84
+ .map('database.host', 'dbHost');
85
+
86
+ // Method 1: Using convertString() (recommended)
87
+ const yamlResult = await converter.convertString(yamlString);
88
+ const jsonResult = await converter.convertString(jsonString);
89
+
90
+ // Method 2: Using convert() with isRawContent option
91
+ const result = await converter.convert(yamlString, { isRawContent: true });
92
+
93
+ console.log(result.data);
94
+ // Output:
95
+ // {
96
+ // appName: 'MyApp',
97
+ // appVersion: '2.0',
98
+ // dbHost: 'localhost'
99
+ // }
100
+ ```
101
+
55
102
  ## 📖 How It Works
56
103
 
57
104
  ### 1. Create a Converter
@@ -213,6 +260,20 @@ const result = await converter.convert(sourceConfig);
213
260
  // Convert from file
214
261
  const result = await converter.convert('./config.yml');
215
262
 
263
+ // Convert raw string content (YAML or JSON) ⭐ NEW!
264
+ const yamlString = `
265
+ name: MyApp
266
+ version: 1.0.0
267
+ database:
268
+ host: localhost
269
+ port: 5432
270
+ `;
271
+
272
+ const result = await converter.convertString(yamlString);
273
+
274
+ // Alternative: Use convert() with isRawContent option
275
+ const result = await converter.convert(yamlString, { isRawContent: true });
276
+
216
277
  // Synchronous conversion (objects only)
217
278
  const result = converter.convertSync(sourceConfig);
218
279
  ```
@@ -763,7 +824,163 @@ console.log(result.data);
763
824
  // }
764
825
  ```
765
826
 
766
- ### Example 8: File Conversion
827
+ ### Example 8: String Input Support
828
+
829
+ ```javascript
830
+ const { forge } = require('configforge');
831
+
832
+ // Example: Converting raw YAML string content
833
+ const yamlConfigString = `
834
+ # Server Configuration
835
+ server:
836
+ host: localhost
837
+ port: 8080
838
+ ssl: true
839
+
840
+ # Database Configuration
841
+ database:
842
+ type: postgresql
843
+ host: db.example.com
844
+ port: 5432
845
+ name: myapp
846
+ credentials:
847
+ username: admin
848
+ password: secret123
849
+
850
+ # Features
851
+ features:
852
+ - authentication
853
+ - logging
854
+ - monitoring
855
+ `;
856
+
857
+ // Example: Converting raw JSON string content
858
+ const jsonConfigString = `{
859
+ "api": {
860
+ "version": "v2",
861
+ "baseUrl": "https://api.example.com",
862
+ "timeout": 30000
863
+ },
864
+ "cache": {
865
+ "enabled": true,
866
+ "ttl": 3600,
867
+ "provider": "redis"
868
+ },
869
+ "logging": {
870
+ "level": "info",
871
+ "format": "json"
872
+ }
873
+ }`;
874
+
875
+ // Create converter for YAML string
876
+ const yamlConverter = forge()
877
+ .from('legacy-config')
878
+ .to('standard-config')
879
+ .map('server.host', 'app.host')
880
+ .map('server.port', 'app.port')
881
+ .map('server.ssl', 'app.secure')
882
+ .map('database.host', 'db.host')
883
+ .map('database.port', 'db.port')
884
+ .map('database.name', 'db.database')
885
+ .map('database.credentials.username', 'db.user')
886
+ .map('database.credentials.password', 'db.password')
887
+ .map('features', 'app.enabledFeatures')
888
+ .defaults({
889
+ 'app.environment': 'production',
890
+ 'app.debug': false,
891
+ });
892
+
893
+ // Method 1: Using convertString() - recommended for string content
894
+ const yamlResult = await yamlConverter.convertString(yamlConfigString);
895
+ console.log('YAML Result:', yamlResult.data);
896
+ // {
897
+ // app: {
898
+ // host: 'localhost',
899
+ // port: 8080,
900
+ // secure: true,
901
+ // enabledFeatures: ['authentication', 'logging', 'monitoring'],
902
+ // environment: 'production',
903
+ // debug: false
904
+ // },
905
+ // db: {
906
+ // host: 'db.example.com',
907
+ // port: 5432,
908
+ // database: 'myapp',
909
+ // user: 'admin',
910
+ // password: 'secret123'
911
+ // }
912
+ // }
913
+
914
+ // Method 2: Using convert() with isRawContent option
915
+ const alternativeResult = await yamlConverter.convert(yamlConfigString, {
916
+ isRawContent: true,
917
+ });
918
+ console.log('Alternative Result:', alternativeResult.data);
919
+
920
+ // Create converter for JSON string
921
+ const jsonConverter = forge()
922
+ .from('api-config')
923
+ .to('service-config')
924
+ .map('api.version', 'service.apiVersion')
925
+ .map('api.baseUrl', 'service.endpoint')
926
+ .map('api.timeout', 'service.requestTimeout')
927
+ .map('cache.enabled', 'service.caching.enabled')
928
+ .map('cache.ttl', 'service.caching.duration')
929
+ .map('logging.level', 'service.log.level')
930
+ .defaults({
931
+ 'service.retries': 3,
932
+ 'service.caching.provider': 'memory',
933
+ });
934
+
935
+ // Convert JSON string content
936
+ const jsonResult = await jsonConverter.convertString(jsonConfigString);
937
+ console.log('JSON Result:', jsonResult.data);
938
+ // {
939
+ // service: {
940
+ // apiVersion: 'v2',
941
+ // endpoint: 'https://api.example.com',
942
+ // requestTimeout: 30000,
943
+ // caching: {
944
+ // enabled: true,
945
+ // duration: 3600,
946
+ // provider: 'memory'
947
+ // },
948
+ // log: {
949
+ // level: 'info'
950
+ // },
951
+ // retries: 3
952
+ // }
953
+ // }
954
+
955
+ // Format auto-detection works for both YAML and JSON
956
+ const mixedConverter = forge()
957
+ .map('name', 'appName')
958
+ .map('version', 'appVersion');
959
+
960
+ // Auto-detects YAML format
961
+ const yamlData = await mixedConverter.convertString(`
962
+ name: MyApp
963
+ version: 1.0.0
964
+ `);
965
+
966
+ // Auto-detects JSON format
967
+ const jsonData = await mixedConverter.convertString(`{
968
+ "name": "MyApp",
969
+ "version": "1.0.0"
970
+ }`);
971
+
972
+ // Error handling for malformed content
973
+ try {
974
+ const malformedResult = await converter.convertString(`{
975
+ "name": "Test"
976
+ "missing": "comma"
977
+ }`);
978
+ } catch (error) {
979
+ console.log('Parse error handled gracefully:', error.message);
980
+ }
981
+ ```
982
+
983
+ ### Example 9: File Conversion
767
984
 
768
985
  ```javascript
769
986
  // Convert YAML file to JSON structure
@@ -781,9 +998,348 @@ const result = await converter.convert('./config.yml');
781
998
  await result.save('./config.json');
782
999
  ```
783
1000
 
1001
+ ### Example 9: Plugin System with Built-in Plugins
1002
+
1003
+ ```javascript
1004
+ const {
1005
+ forge,
1006
+ createValidationPlugin,
1007
+ createAuditPlugin,
1008
+ createBackupPlugin,
1009
+ } = require('configforge');
1010
+
1011
+ // Create converter with plugin support
1012
+ const converter = forge()
1013
+ .from('userForm')
1014
+ .to('userProfile')
1015
+ .map('personalInfo.firstName', 'firstName')
1016
+ .map('personalInfo.lastName', 'lastName')
1017
+ .map('personalInfo.email', 'email')
1018
+ .map('accountInfo.username', 'username')
1019
+ .merge(
1020
+ ['personalInfo.firstName', 'personalInfo.lastName'],
1021
+ 'fullName',
1022
+ (first, last) => `${first} ${last}`
1023
+ );
1024
+
1025
+ // Add built-in plugins
1026
+ const validationPlugin = createValidationPlugin({
1027
+ strictMode: true,
1028
+ failOnWarnings: false,
1029
+ });
1030
+
1031
+ const auditPlugin = createAuditPlugin({
1032
+ logFile: './conversion-audit.log',
1033
+ logLevel: 'detailed',
1034
+ includeData: false,
1035
+ });
1036
+
1037
+ const backupPlugin = createBackupPlugin({
1038
+ backupDir: './backups',
1039
+ keepVersions: 5,
1040
+ timestampFormat: 'YYYY-MM-DD_HH-mm-ss',
1041
+ });
1042
+
1043
+ // Install plugins
1044
+ await converter.use(validationPlugin);
1045
+ await converter.use(auditPlugin);
1046
+ await converter.use(backupPlugin);
1047
+
1048
+ // Convert with plugin enhancements
1049
+ const userData = {
1050
+ personalInfo: {
1051
+ firstName: 'John',
1052
+ lastName: 'Doe',
1053
+ email: 'john.doe@example.com',
1054
+ },
1055
+ accountInfo: {
1056
+ username: 'johndoe123',
1057
+ },
1058
+ };
1059
+
1060
+ const result = await converter.convert(userData);
1061
+
1062
+ // Plugins automatically:
1063
+ // - Validate data quality (ValidationPlugin)
1064
+ // - Log conversion activities (AuditPlugin)
1065
+ // - Create backups of source data (BackupPlugin)
1066
+ // - Handle errors gracefully with detailed reporting
1067
+
1068
+ console.log(result.data);
1069
+ // {
1070
+ // firstName: 'John',
1071
+ // lastName: 'Doe',
1072
+ // email: 'john.doe@example.com',
1073
+ // username: 'johndoe123',
1074
+ // fullName: 'John Doe'
1075
+ // }
1076
+
1077
+ // Check plugin results
1078
+ console.log('Validation results:', result.context?.validationResults);
1079
+ console.log('Backup created:', result.context?.backupPath);
1080
+ ```
1081
+
1082
+ ### Example 10: Batch Processing and Performance Features
1083
+
1084
+ ```javascript
1085
+ const {
1086
+ forge,
1087
+ BatchProcessor,
1088
+ IncrementalProcessor,
1089
+ PerformanceMonitor,
1090
+ } = require('configforge');
1091
+
1092
+ // Create converter for processing multiple config files
1093
+ const converter = forge()
1094
+ .from('legacy-config')
1095
+ .to('modern-config')
1096
+ .map('app_name', 'application.name')
1097
+ .map('app_version', 'application.version')
1098
+ .map('database.host', 'db.hostname')
1099
+ .map('database.port', 'db.port')
1100
+ .map('server.port', 'application.port')
1101
+ .defaults({
1102
+ environment: 'production',
1103
+ createdAt: () => new Date().toISOString(),
1104
+ });
1105
+
1106
+ // 1. Batch Processing - Convert multiple files efficiently
1107
+ const batchResult = await converter.convertBatch(
1108
+ ['./configs/app1.yml', './configs/app2.yml', './configs/app3.yml'],
1109
+ {
1110
+ parallel: true,
1111
+ workers: 3,
1112
+ errorStrategy: 'continue',
1113
+ progressCallback: progress => {
1114
+ console.log(`Progress: ${progress.completed}/${progress.total} files`);
1115
+ },
1116
+ }
1117
+ );
1118
+
1119
+ console.log(
1120
+ `Processed ${batchResult.stats.successfulFiles} files successfully`
1121
+ );
1122
+ console.log(`Failed: ${batchResult.stats.failedFiles} files`);
1123
+ console.log(`Total duration: ${batchResult.stats.totalDuration}ms`);
1124
+
1125
+ // 2. Incremental Processing - Only process changed files
1126
+ const incrementalResult = await converter.convertIncremental(
1127
+ './config.yml',
1128
+ './output/config.json',
1129
+ './.cache' // Cache directory
1130
+ );
1131
+
1132
+ if (incrementalResult) {
1133
+ console.log('File was processed (changed since last run)');
1134
+ } else {
1135
+ console.log('File skipped (no changes detected)');
1136
+ }
1137
+
1138
+ // 3. Incremental Batch Processing
1139
+ const incrementalBatchResult = await converter.convertIncrementalBatch(
1140
+ ['./configs/app1.yml', './configs/app2.yml', './configs/app3.yml'],
1141
+ './output',
1142
+ {
1143
+ cacheDir: './.cache',
1144
+ getOutputPath: inputPath => {
1145
+ const fileName = inputPath.split('/').pop().replace('.yml', '.json');
1146
+ return `./output/${fileName}`;
1147
+ },
1148
+ }
1149
+ );
1150
+
1151
+ console.log(`Processed: ${incrementalBatchResult.processed.length} files`);
1152
+ console.log(
1153
+ `Skipped: ${incrementalBatchResult.skipped.length} files (unchanged)`
1154
+ );
1155
+
1156
+ // 4. Performance Monitoring
1157
+ const monitor = new PerformanceMonitor();
1158
+ monitor.start();
1159
+
1160
+ // Track individual steps
1161
+ monitor.startStep('parse');
1162
+ const result = await converter.convert('./large-config.yml');
1163
+ monitor.endStep('parse');
1164
+
1165
+ // Record file sizes for throughput calculation
1166
+ monitor.recordSizes(1024 * 1024, 800 * 1024); // 1MB input, 800KB output
1167
+
1168
+ // Get detailed performance metrics
1169
+ const metrics = monitor.finish(result.stats);
1170
+ const report = monitor.createReport(metrics);
1171
+
1172
+ console.log(report);
1173
+ // === Performance Report ===
1174
+ //
1175
+ // Timing Breakdown:
1176
+ // Parse: 15.23ms
1177
+ // Map: 8.45ms
1178
+ // Transform: 3.21ms
1179
+ // Validate: 2.10ms
1180
+ // Serialize: 5.67ms
1181
+ // Total: 34.66ms
1182
+ //
1183
+ // Throughput:
1184
+ // Fields/sec: 2890
1185
+ // Transforms/sec: 1445
1186
+ // Bytes/sec: 29.64 MB/s
1187
+ //
1188
+ // Memory Usage:
1189
+ // Heap Used: 45.23 MB
1190
+ // Heap Total: 67.89 MB
1191
+ // RSS: 89.12 MB
1192
+ //
1193
+ // File Sizes:
1194
+ // Input: 1.00 MB
1195
+ // Output: 800.00 KB
1196
+ // Ratio: 80.0%
1197
+
1198
+ // 5. Performance Benchmarking
1199
+ const { PerformanceBenchmark } = require('configforge');
1200
+
1201
+ const sequentialOperation = async () => {
1202
+ return converter.convertBatch(['./config1.yml', './config2.yml'], {
1203
+ parallel: false,
1204
+ });
1205
+ };
1206
+
1207
+ const parallelOperation = async () => {
1208
+ return converter.convertBatch(['./config1.yml', './config2.yml'], {
1209
+ parallel: true,
1210
+ workers: 2,
1211
+ });
1212
+ };
1213
+
1214
+ const benchmarks = [
1215
+ { name: 'sequential-processing', operation: sequentialOperation },
1216
+ { name: 'parallel-processing', operation: parallelOperation },
1217
+ ];
1218
+
1219
+ const benchmarkResults = await PerformanceBenchmark.compareBenchmarks(
1220
+ benchmarks,
1221
+ 10
1222
+ );
1223
+ const comparisonReport =
1224
+ PerformanceBenchmark.createComparisonReport(benchmarkResults);
1225
+
1226
+ console.log(comparisonReport);
1227
+ // === Benchmark Comparison ===
1228
+ //
1229
+ // Results (sorted by average time):
1230
+ // parallel-processing:
1231
+ // Average: 45.23ms (fastest)
1232
+ // Range: 42.10ms - 48.90ms
1233
+ // Std Dev: 2.15ms
1234
+ // Ops/sec: 22
1235
+ //
1236
+ // sequential-processing:
1237
+ // Average: 78.45ms (1.73x slower)
1238
+ // Range: 75.20ms - 82.10ms
1239
+ // Std Dev: 2.89ms
1240
+ // Ops/sec: 13
1241
+
1242
+ // 6. Advanced Batch Processing with Custom Options
1243
+ const advancedBatchResult = await converter.convertBatch(
1244
+ [
1245
+ './configs/*.yml', // Glob patterns supported
1246
+ ],
1247
+ {
1248
+ parallel: true,
1249
+ workers: 4,
1250
+ errorStrategy: 'fail-fast', // Stop on first error
1251
+ progressCallback: progress => {
1252
+ const percentage = Math.round(
1253
+ (progress.completed / progress.total) * 100
1254
+ );
1255
+ console.log(`[${percentage}%] Processing: ${progress.current}`);
1256
+ if (progress.failed > 0) {
1257
+ console.log(`⚠️ ${progress.failed} files failed`);
1258
+ }
1259
+ },
1260
+ }
1261
+ );
1262
+
1263
+ // Save all results to output directory
1264
+ const batchProcessor = new BatchProcessor(converter);
1265
+ await batchProcessor.saveBatch(advancedBatchResult.results, './output', [
1266
+ './configs/app1.yml',
1267
+ './configs/app2.yml',
1268
+ ]);
1269
+
1270
+ // 7. Cache Management for Incremental Processing
1271
+ const incrementalProcessor = new IncrementalProcessor(converter, './.cache');
1272
+
1273
+ // Get cache statistics
1274
+ const cacheStats = incrementalProcessor.getCacheStats();
1275
+ console.log(`Cache entries: ${cacheStats.totalEntries}`);
1276
+ console.log(`Successful: ${cacheStats.successfulEntries}`);
1277
+ console.log(`Failed: ${cacheStats.failedEntries}`);
1278
+
1279
+ // Clean up stale cache entries
1280
+ const removedEntries = await incrementalProcessor.cleanupCache();
1281
+ console.log(`Removed ${removedEntries} stale cache entries`);
1282
+
1283
+ // Clear entire cache
1284
+ await incrementalProcessor.clearCache();
1285
+ console.log('Cache cleared');
1286
+ ```
1287
+
1288
+ ### Example 11: CLI Generation System
1289
+
1290
+ ```javascript
1291
+ const { forge, CLIGenerator } = require('configforge');
1292
+
1293
+ // Create your converter
1294
+ const converter = forge()
1295
+ .from('legacy')
1296
+ .to('modern')
1297
+ .map('app_name', 'name')
1298
+ .map('app_version', 'version')
1299
+ .map('database.host', 'db.hostname')
1300
+ .map('database.port', 'db.port')
1301
+ .defaults({
1302
+ environment: 'production',
1303
+ });
1304
+
1305
+ // Generate CLI for your converter
1306
+ const cli = CLIGenerator.forConverter(converter, {
1307
+ name: 'config-converter',
1308
+ version: '1.0.0',
1309
+ description: 'Convert legacy config to modern format',
1310
+ });
1311
+
1312
+ // Add custom commands
1313
+ cli.addCommand({
1314
+ name: 'migrate',
1315
+ description: 'Migrate all configs in a directory',
1316
+ options: [
1317
+ {
1318
+ flags: '-d, --directory <dir>',
1319
+ description: 'Directory containing config files',
1320
+ },
1321
+ ],
1322
+ action: async options => {
1323
+ // Custom migration logic
1324
+ console.log(`Migrating configs in ${options.directory}`);
1325
+ },
1326
+ });
1327
+
1328
+ // Parse command line arguments
1329
+ cli.parse();
1330
+
1331
+ // Now you can use your CLI:
1332
+ // $ config-converter convert input.yml output.json
1333
+ // $ config-converter validate config.yml
1334
+ // $ config-converter profile save my-config
1335
+ // $ config-converter profile list
1336
+ // $ config-converter migrate -d ./configs
1337
+ ```
1338
+
784
1339
  ## 🎯 Key Features
785
1340
 
786
1341
  - ✅ **Simple API**: Just map fields and convert
1342
+ - ✅ **String Input Support**: Convert raw YAML/JSON strings directly with `convertString()` ⭐ NEW!
787
1343
  - ✅ **Pipeline Architecture**: Robust internal processing with configurable steps and error handling
788
1344
  - ✅ **No direct Mapper usage needed**: The `convert()` method handles everything
789
1345
  - ✅ **Nested object support**: Use dot notation like `user.profile.name`
@@ -792,6 +1348,12 @@ await result.save('./config.json');
792
1348
  - ✅ **Conditional mapping**: Use `when()` for conditional logic
793
1349
  - ✅ **Multi-field merging**: Use `merge()` to combine multiple sources into one target
794
1350
  - ✅ **Default values**: Set fallback values
1351
+ - ✅ **Comprehensive Error Handling**: Advanced error reporting with context and suggestions ⭐ ENHANCED!
1352
+ - ✅ **CLI Generation System**: Create command-line interfaces for converters ⭐ ENHANCED!
1353
+ - ✅ **Plugin System**: Extensible architecture with built-in plugins for validation, auditing, and backups ⭐ ENHANCED!
1354
+ - ✅ **Batch Processing**: Efficiently process multiple files with parallel support and progress tracking ⭐ ENHANCED!
1355
+ - ✅ **Incremental Processing**: Only process changed files using content hashing and modification times ⭐ ENHANCED!
1356
+ - ✅ **Performance Monitoring**: Detailed performance tracking, benchmarking, and reporting ⭐ ENHANCED!
795
1357
  - ✅ **File support**: Convert YAML, JSON files directly
796
1358
  - ✅ **Statistics**: Get detailed conversion reports
797
1359
  - ✅ **TypeScript**: Full type safety
@@ -803,20 +1365,26 @@ await result.save('./config.json');
803
1365
  - Basic field mapping with `map()`
804
1366
  - Nested object and array access
805
1367
  - Value transformations
1368
+ - **String input support with `convertString()` and `convert()` with `isRawContent` option** ⭐ NEW!
806
1369
  - **Default values with `defaults()`** ⭐ ENHANCED!
807
1370
  - **Array/object processing with `forEach()`**
808
1371
  - **Conditional mapping with `when()`**
809
1372
  - **Multi-field merging with `merge()`**
810
1373
  - **Field validation with `validate()`**
811
1374
  - **Lifecycle hooks with `before()` and `after()`** ⭐ NEW!
1375
+ - **Advanced error handling and reporting system** ⭐ NEW!
1376
+ - **CLI generation system with command-line interfaces** ⭐ ENHANCED!
1377
+ - **Plugin system foundation with built-in plugins** ⭐ NEW!
1378
+ - **Batch processing with parallel support and progress tracking** ⭐ ENHANCED!
1379
+ - **Incremental processing with content hashing and modification times** ⭐ ENHANCED!
1380
+ - **Performance monitoring with detailed benchmarking and reporting** ⭐ ENHANCED!
812
1381
  - File parsing (YAML, JSON)
813
1382
  - Conversion statistics and reporting
814
1383
  - Async and sync conversion support
815
1384
 
816
1385
  **🚧 Coming Soon:**
817
1386
 
818
- - CLI generation
819
- - Plugin system
1387
+ - Advanced plugin ecosystem
820
1388
 
821
1389
  ## 💡 Tips
822
1390
 
@@ -838,6 +1406,29 @@ await result.save('./config.json');
838
1406
  16. **Use `after()` hooks** to postprocess target data after conversion
839
1407
  17. **Hooks can be async** - just use `async (data) => { ... }` and they'll be awaited
840
1408
  18. **Multiple hooks execute in order** - add as many as you need for complex workflows
1409
+ 19. **Error handling provides helpful suggestions** - when field mapping fails, you'll get suggestions for similar field names
1410
+ 20. **Errors include rich context** - see exactly where and why conversions failed with detailed error information
1411
+ 21. **Use error categories** to filter and handle different types of errors (validation, mapping, parsing, etc.)
1412
+ 22. **Create CLIs for converters** - use `CLIGenerator.forConverter(converter)` to generate command-line interfaces
1413
+ 23. **Use CLI profiles** - save converter configurations as profiles for reuse: `cli profile save my-converter`
1414
+ 24. **CLI supports batch processing** - convert multiple files at once with pattern matching and parallel processing
1415
+ 25. **Use built-in plugins** - leverage ValidationPlugin, AuditPlugin, and BackupPlugin for enhanced functionality
1416
+ 26. **Plugin hooks execute in order** - plugins can intercept and modify data at different conversion stages
1417
+ 27. **Error hooks provide recovery** - plugins can handle errors gracefully and provide fallback behavior
1418
+ 28. **Use batch processing for multiple files** - `convertBatch()` processes multiple files efficiently with parallel support
1419
+ 29. **Enable parallel processing** - set `parallel: true` and configure `workers` for faster batch processing
1420
+ 30. **Use incremental processing** - `convertIncremental()` only processes files that have changed since last run
1421
+ 31. **Monitor performance** - use `PerformanceMonitor` to track conversion speed, memory usage, and throughput
1422
+ 32. **Benchmark different approaches** - use `PerformanceBenchmark` to compare sequential vs parallel processing
1423
+ 33. **Configure error strategies** - use `errorStrategy: 'continue'` to process all files even if some fail, or `'fail-fast'` to stop on first error
1424
+ 34. **Track progress** - provide `progressCallback` to monitor batch processing progress in real-time
1425
+ 35. **Cache management** - use `IncrementalProcessor.getCacheStats()` and `cleanupCache()` to manage incremental processing cache
1426
+ 36. **Save batch results** - use `BatchProcessor.saveBatch()` to save all conversion results to an output directory
1427
+ 37. **Use forge() with options** - pass `ForgeOptions` to `forge({ strict: true, parallel: true })` to configure converter behavior globally
1428
+ 38. **Use convertString() for raw content** - when you have YAML or JSON as a string, use `convertString()` instead of `convert()` ⭐ NEW!
1429
+ 39. **Use convert() with isRawContent option** - alternatively, use `convert(stringContent, { isRawContent: true })` for string input ⭐ NEW!
1430
+ 40. **Format auto-detection works with strings** - ConfigForge automatically detects YAML vs JSON format in string content ⭐ NEW!
1431
+ 41. **String input handles parsing errors gracefully** - malformed YAML/JSON strings will produce helpful error messages ⭐ NEW!
841
1432
 
842
1433
  ---
843
1434
 
@@ -0,0 +1,48 @@
1
+ import { BatchOptions, BatchProgress, BatchResult, ConversionResult } from '../types';
2
+ import { Converter } from './Converter';
3
+ /**
4
+ * BatchProcessor handles efficient processing of multiple files
5
+ * with parallel processing support and progress tracking
6
+ */
7
+ export declare class BatchProcessor {
8
+ private converter;
9
+ private options;
10
+ constructor(converter: Converter, options?: BatchOptions);
11
+ /**
12
+ * Process multiple files efficiently
13
+ */
14
+ process(inputs: string[]): Promise<BatchResult>;
15
+ /**
16
+ * Process files sequentially
17
+ */
18
+ private processSequentially;
19
+ /**
20
+ * Process files in parallel using worker threads or Promise.all
21
+ */
22
+ private processInParallel;
23
+ /**
24
+ * Process a single file
25
+ */
26
+ private processFile;
27
+ /**
28
+ * Create an empty batch result
29
+ */
30
+ private createEmptyResult;
31
+ /**
32
+ * Split array into chunks
33
+ */
34
+ private chunkArray;
35
+ /**
36
+ * Save batch results to files
37
+ */
38
+ saveBatch(results: ConversionResult[], outputDir: string, inputPaths: string[]): Promise<void>;
39
+ /**
40
+ * Generate a progress report
41
+ */
42
+ generateProgressReport(progress: BatchProgress): string;
43
+ /**
44
+ * Create a simple progress bar
45
+ */
46
+ private createProgressBar;
47
+ }
48
+ //# sourceMappingURL=BatchProcessor.d.ts.map
@@ -0,0 +1 @@
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"}