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.
- package/README.md +594 -3
- package/dist/core/BatchProcessor.d.ts +48 -0
- package/dist/core/BatchProcessor.d.ts.map +1 -0
- package/dist/core/BatchProcessor.js +273 -0
- package/dist/core/BatchProcessor.js.map +1 -0
- package/dist/core/ConversionResult.d.ts +22 -0
- package/dist/core/ConversionResult.d.ts.map +1 -1
- package/dist/core/ConversionResult.js +44 -30
- package/dist/core/ConversionResult.js.map +1 -1
- package/dist/core/Converter.d.ts +63 -3
- package/dist/core/Converter.d.ts.map +1 -1
- package/dist/core/Converter.js +180 -27
- package/dist/core/Converter.js.map +1 -1
- package/dist/core/IncrementalProcessor.d.ts +75 -0
- package/dist/core/IncrementalProcessor.d.ts.map +1 -0
- package/dist/core/IncrementalProcessor.js +298 -0
- package/dist/core/IncrementalProcessor.js.map +1 -0
- package/dist/core/PerformanceMonitor.d.ts +103 -0
- package/dist/core/PerformanceMonitor.d.ts.map +1 -0
- package/dist/core/PerformanceMonitor.js +253 -0
- package/dist/core/PerformanceMonitor.js.map +1 -0
- package/dist/core/Pipeline.js +1 -1
- package/dist/core/Pipeline.js.map +1 -1
- package/dist/core/index.d.ts +3 -0
- package/dist/core/index.d.ts.map +1 -1
- package/dist/core/index.js +8 -1
- package/dist/core/index.js.map +1 -1
- package/dist/core/pipeline/PipelineBuilder.d.ts +4 -0
- package/dist/core/pipeline/PipelineBuilder.d.ts.map +1 -1
- package/dist/core/pipeline/PipelineBuilder.js +8 -0
- package/dist/core/pipeline/PipelineBuilder.js.map +1 -1
- package/dist/core/pipeline/PipelineSteps.d.ts.map +1 -1
- package/dist/core/pipeline/PipelineSteps.js +6 -4
- package/dist/core/pipeline/PipelineSteps.js.map +1 -1
- package/dist/errors/ErrorCollector.d.ts +119 -0
- package/dist/errors/ErrorCollector.d.ts.map +1 -0
- package/dist/errors/ErrorCollector.js +197 -0
- package/dist/errors/ErrorCollector.js.map +1 -0
- package/dist/errors/ErrorContext.d.ts +168 -0
- package/dist/errors/ErrorContext.d.ts.map +1 -0
- package/dist/errors/ErrorContext.js +356 -0
- package/dist/errors/ErrorContext.js.map +1 -0
- package/dist/errors/ErrorRecovery.d.ts +91 -0
- package/dist/errors/ErrorRecovery.d.ts.map +1 -0
- package/dist/errors/ErrorRecovery.js +321 -0
- package/dist/errors/ErrorRecovery.js.map +1 -0
- package/dist/errors/ErrorReporter.d.ts +58 -0
- package/dist/errors/ErrorReporter.d.ts.map +1 -0
- package/dist/errors/ErrorReporter.js +262 -0
- package/dist/errors/ErrorReporter.js.map +1 -0
- package/dist/errors/ErrorTypes.d.ts +103 -0
- package/dist/errors/ErrorTypes.d.ts.map +1 -0
- package/dist/errors/ErrorTypes.js +125 -0
- package/dist/errors/ErrorTypes.js.map +1 -0
- package/dist/errors/SpecificErrors.d.ts +45 -0
- package/dist/errors/SpecificErrors.d.ts.map +1 -0
- package/dist/errors/SpecificErrors.js +124 -0
- package/dist/errors/SpecificErrors.js.map +1 -0
- package/dist/errors/SuggestionEngine.d.ts +63 -0
- package/dist/errors/SuggestionEngine.d.ts.map +1 -0
- package/dist/errors/SuggestionEngine.js +328 -0
- package/dist/errors/SuggestionEngine.js.map +1 -0
- package/dist/errors/index.d.ts +12 -0
- package/dist/errors/index.d.ts.map +1 -0
- package/dist/errors/index.js +39 -0
- package/dist/errors/index.js.map +1 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +17 -1
- package/dist/index.js.map +1 -1
- package/dist/plugins/Plugin.d.ts +95 -0
- package/dist/plugins/Plugin.d.ts.map +1 -0
- package/dist/plugins/Plugin.js +3 -0
- package/dist/plugins/Plugin.js.map +1 -0
- package/dist/plugins/PluginManager.d.ts +73 -0
- package/dist/plugins/PluginManager.d.ts.map +1 -0
- package/dist/plugins/PluginManager.js +220 -0
- package/dist/plugins/PluginManager.js.map +1 -0
- package/dist/plugins/PluginRegistry.d.ts +122 -0
- package/dist/plugins/PluginRegistry.d.ts.map +1 -0
- package/dist/plugins/PluginRegistry.js +385 -0
- package/dist/plugins/PluginRegistry.js.map +1 -0
- package/dist/plugins/built-in/AuditPlugin.d.ts +81 -0
- package/dist/plugins/built-in/AuditPlugin.d.ts.map +1 -0
- package/dist/plugins/built-in/AuditPlugin.js +235 -0
- package/dist/plugins/built-in/AuditPlugin.js.map +1 -0
- package/dist/plugins/built-in/BackupPlugin.d.ts +38 -0
- package/dist/plugins/built-in/BackupPlugin.d.ts.map +1 -0
- package/dist/plugins/built-in/BackupPlugin.js +105 -0
- package/dist/plugins/built-in/BackupPlugin.js.map +1 -0
- package/dist/plugins/built-in/ValidationPlugin.d.ts +61 -0
- package/dist/plugins/built-in/ValidationPlugin.d.ts.map +1 -0
- package/dist/plugins/built-in/ValidationPlugin.js +235 -0
- package/dist/plugins/built-in/ValidationPlugin.js.map +1 -0
- package/dist/plugins/built-in/index.d.ts +7 -0
- package/dist/plugins/built-in/index.d.ts.map +1 -0
- package/dist/plugins/built-in/index.js +14 -0
- package/dist/plugins/built-in/index.js.map +1 -0
- package/dist/plugins/index.d.ts +5 -0
- package/dist/plugins/index.d.ts.map +1 -0
- package/dist/plugins/index.js +25 -0
- package/dist/plugins/index.js.map +1 -0
- package/dist/scripts/CLIGenerator.d.ts +109 -0
- package/dist/scripts/CLIGenerator.d.ts.map +1 -0
- package/dist/scripts/CLIGenerator.js +440 -0
- package/dist/scripts/CLIGenerator.js.map +1 -0
- package/dist/scripts/CLIUtils.d.ts +136 -0
- package/dist/scripts/CLIUtils.d.ts.map +1 -0
- package/dist/scripts/CLIUtils.js +361 -0
- package/dist/scripts/CLIUtils.js.map +1 -0
- package/dist/scripts/CommandBuilder.d.ts +72 -0
- package/dist/scripts/CommandBuilder.d.ts.map +1 -0
- package/dist/scripts/CommandBuilder.js +280 -0
- package/dist/scripts/CommandBuilder.js.map +1 -0
- package/dist/scripts/index.d.ts +23 -0
- package/dist/scripts/index.d.ts.map +1 -0
- package/dist/scripts/index.js +43 -0
- package/dist/scripts/index.js.map +1 -0
- 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:
|
|
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
|
-
-
|
|
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"}
|