configforge 1.0.0-beta.1 → 1.0.0-beta.11

package/README.md

@@ -1,6 +1,8 @@
 # ConfigForge
 
-> Universal config converter framework with a fluent API
+> A TypeScript library for converting, mapping, and transforming config data in JSON and YAML.
+
+ConfigForge is a universal config converter library with a fluent API
 
 ConfigForge makes it easy to convert configuration files between different formats and structures. Just define your mappings and let ConfigForge handle the rest.
 
@@ -86,17 +88,123 @@ const converter = forge()
 })
 ```
 
-### 4. Set Default Values
+### 4. Add Conditional Logic
+
+```javascript
+// Function conditions - only apply when condition returns true
+.when(source => source.user?.type === 'admin')
+  .map('user.permissions', 'adminPermissions')
+  .map('user.role', 'adminRole')
+  .end()
+
+// String conditions - only apply when field exists and is truthy
+.when('user.isActive')
+  .map('user.lastLogin', 'lastActiveLogin')
+  .end()
+```
+
+### 5. Merge Multiple Fields
+
+```javascript
+// Combine multiple source fields into one target field
+.merge(['firstName', 'lastName'], 'fullName', (first, last) => `${first} ${last}`)
+
+// Merge with transformation
+.merge(['basePrice', 'tax'], 'totalPrice',
+  (price, tax) => price + tax,
+  total => `$${total.toFixed(2)}`
+)
+
+// Merge complex data
+.merge(['user.profile', 'user.settings'], 'userInfo', (profile, settings) => ({
+  ...profile,
+  ...settings
+}))
+```
+
+### 6. Set Default Values
 
 ```javascript
+// Set static default values
 .defaults({
   version: '1.0.0',
   enabled: true,
   environment: 'production'
 })
+
+// Set dynamic default values using functions
+.defaults({
+  timestamp: () => new Date().toISOString(),
+  id: () => `user_${Date.now()}`,
+  sessionId: () => Math.random().toString(36).substr(2, 9)
+})
 ```
 
-### 5. Convert Data
+### 7. Add Lifecycle Hooks
+
+```javascript
+// Before hooks - run before conversion starts
+.before((sourceData) => {
+  console.log('Starting conversion...');
+  // Modify source data if needed
+  return {
+    ...sourceData,
+    processed: true
+  };
+})
+
+// After hooks - run after conversion completes
+.after((targetData) => {
+  console.log('Conversion completed!');
+  // Add computed fields or modify target data
+  return {
+    ...targetData,
+    processedAt: new Date().toISOString(),
+    checksum: calculateChecksum(targetData)
+  };
+})
+
+// Multiple hooks execute in order
+.before(validateInput)
+.before(preprocessData)
+.after(addMetadata)
+.after(logResults)
+
+// Async hooks are supported
+.before(async (data) => {
+  const enrichedData = await fetchAdditionalData(data.userId);
+  return { ...data, ...enrichedData };
+})
+```
+
+### 8. Add Validation
+
+```javascript
+const { validators } = require('configforge');
+
+// Add field validation
+.validate('email', validators.email)
+.validate('age', validators.all(
+  validators.required,
+  validators.type('number'),
+  validators.range(18, 120)
+))
+.validate('username', validators.all(
+  validators.required,
+  validators.minLength(3),
+  validators.pattern(/^[a-zA-Z0-9_]+$/, 'Only letters, numbers, and underscores allowed')
+))
+
+// Custom validation with context
+.validate('password', (value, context) => {
+  if (context.source.confirmPassword !== value) {
+    return 'Passwords do not match';
+  }
+  return validators.minLength(8)(value, context);
+})
+```
+
+### 9. Convert Data
 
 ```javascript
 // Convert object data
@@ -227,7 +335,435 @@ console.log(result.data);
 // }
 ```
 
-### Example 3: File Conversion
+### Example 3: Array Processing with forEach()
+
+```javascript
+// Simple fruit inventory
+const fruitData = {
+  storeId: 'STORE-001',
+  fruits: [
+    {
+      name: 'Apple',
+      color: 'red',
+      price: 1.5,
+      quantity: 100,
+    },
+    {
+      name: 'Banana',
+      color: 'yellow',
+      price: 0.75,
+      quantity: 80,
+    },
+    {
+      name: 'Orange',
+      color: 'orange',
+      price: 1.25,
+      quantity: 60,
+    },
+  ],
+};
+
+const converter = forge()
+  .from('inventory')
+  .to('catalog')
+  .map('storeId', 'storeId')
+  .forEach('fruits', (fruit, index) => {
+    return {
+      id: index + 1,
+      fruitName: fruit.name,
+      displayColor: fruit.color,
+      pricePerItem: fruit.price,
+      inStock: fruit.quantity,
+      totalValue: fruit.price * fruit.quantity,
+      isExpensive: fruit.price > 1.0,
+    };
+  });
+
+const result = await converter.convert(fruitData);
+console.log(result.data);
+// {
+//   storeId: 'STORE-001',
+//   fruits: [
+//     {
+//       id: 1,
+//       fruitName: 'Apple',
+//       displayColor: 'red',
+//       pricePerItem: 1.50,
+//       inStock: 100,
+//       totalValue: 150,
+//       isExpensive: true
+//     },
+//     {
+//       id: 2,
+//       fruitName: 'Banana',
+//       displayColor: 'yellow',
+//       pricePerItem: 0.75,
+//       inStock: 80,
+//       totalValue: 60,
+//       isExpensive: false
+//     },
+//     // ... more fruits
+//   ]
+// }
+```
+
+### Example 4: Conditional Mapping with when()
+
+```javascript
+// Different types of pets need different mappings
+const petData = {
+  type: 'dog',
+  name: 'Buddy',
+  age: 3,
+  dogInfo: {
+    breed: 'Golden Retriever',
+    tricks: ['sit', 'stay', 'fetch'],
+  },
+  catInfo: {
+    breed: 'Persian',
+    indoor: true,
+  },
+  birdInfo: {
+    species: 'Parrot',
+    canTalk: true,
+  },
+};
+
+const converter = forge()
+  .from('petData')
+  .to('petProfile')
+  .map('name', 'petName')
+  .map('age', 'petAge')
+  .map('type', 'animalType')
+
+  // Only map dog-specific info for dogs
+  .when(source => source.type === 'dog')
+  .map('dogInfo.breed', 'breed')
+  .map('dogInfo.tricks', 'knownTricks')
+  .end()
+
+  // Only map cat-specific info for cats
+  .when(source => source.type === 'cat')
+  .map('catInfo.breed', 'breed')
+  .map('catInfo.indoor', 'isIndoorCat')
+  .end()
+
+  // Only map bird-specific info for birds
+  .when(source => source.type === 'bird')
+  .map('birdInfo.species', 'species')
+  .map('birdInfo.canTalk', 'canSpeak')
+  .end();
+
+const result = await converter.convert(petData);
+console.log(result.data);
+// {
+//   petName: 'Buddy',
+//   petAge: 3,
+//   animalType: 'dog',
+//   breed: 'Golden Retriever',
+//   knownTricks: ['sit', 'stay', 'fetch']
+// }
+```
+
+### Example 5: Merge Multiple Fields with merge()
+
+```javascript
+// Simple student report card
+const studentData = {
+  student: {
+    firstName: 'Alice',
+    lastName: 'Smith',
+  },
+  grades: {
+    math: 85,
+    english: 92,
+    science: 78,
+  },
+  activities: ['soccer', 'chess', 'art'],
+  info: {
+    grade: '5th',
+    teacher: 'Ms. Johnson',
+  },
+};
+
+const converter = forge()
+  .from('report')
+  .to('summary')
+
+  // Merge student name fields
+  .merge(
+    ['student.firstName', 'student.lastName'],
+    'studentName',
+    (first, last) => `${first} ${last}`
+  )
+
+  // Calculate total with transformation
+  .merge(
+    ['order.basePrice', 'order.tax', 'order.shipping'],
+    'subtotal',
+    (base, tax, shipping) => base + tax + shipping
+  )
+
+  .merge(
+    ['order.basePrice', 'order.tax', 'order.shipping', 'order.discount'],
+    'total',
+    (base, tax, shipping, discount) => base + tax + shipping - discount,
+    total => `$${total.toFixed(2)}`
+  ) // Transform to currency format
+
+  // Merge arrays and objects
+  .merge(['items', 'metadata'], 'orderSummary', (items, meta) => ({
+    itemCount: items.length,
+    items: items.join(', '),
+    ...meta,
+  }))
+
+  // Simple field mappings
+  .map('customer.email', 'billingEmail');
+
+const result = await converter.convert(orderData);
+console.log(result.data);
+// {
+//   customerName: 'John Doe',
+//   subtotal: 121.49,
+//   total: '$106.49',
+//   orderSummary: {
+//     itemCount: 3,
+//     items: 'laptop, mouse, keyboard',
+//     orderDate: '2023-12-01',
+//     source: 'web'
+//   },
+//   billingEmail: 'john.doe@example.com'
+// }
+```
+
+### Example 6: Data Validation
+
+```javascript
+const { forge, validators } = require('configforge');
+
+// User registration form data
+const formData = {
+  personalInfo: {
+    firstName: 'John',
+    lastName: 'Doe',
+    email: 'john.doe@example.com',
+    age: 28,
+  },
+  accountInfo: {
+    username: 'johndoe123',
+    password: 'SecurePass123!',
+    confirmPassword: 'SecurePass123!',
+  },
+  preferences: {
+    newsletter: 'yes',
+    theme: 'dark',
+    language: 'en',
+  },
+};
+
+const converter = forge()
+  .from('form')
+  .to('user')
+  // Map fields
+  .merge(
+    ['personalInfo.firstName', 'personalInfo.lastName'],
+    'fullName',
+    (first, last) => `${first} ${last}`
+  )
+  .map('personalInfo.email', 'email')
+  .map('personalInfo.age', 'age')
+  .map('accountInfo.username', 'username')
+  .map('accountInfo.password', 'password')
+  .map(
+    'preferences.newsletter',
+    'subscribeToNewsletter',
+    value => value === 'yes'
+  )
+  .map('preferences.theme', 'theme')
+  .map('preferences.language', 'language')
+
+  // Add validation rules
+  .validate(
+    'fullName',
+    validators.all(
+      validators.required,
+      validators.minLength(2),
+      validators.maxLength(100)
+    )
+  )
+  .validate('email', validators.all(validators.required, validators.email))
+  .validate(
+    'age',
+    validators.all(
+      validators.required,
+      validators.type('number'),
+      validators.range(13, 120)
+    )
+  )
+  .validate(
+    'username',
+    validators.all(
+      validators.required,
+      validators.minLength(3),
+      validators.maxLength(20),
+      validators.pattern(
+        /^[a-zA-Z0-9_]+$/,
+        'Username can only contain letters, numbers, and underscores'
+      )
+    )
+  )
+  .validate(
+    'password',
+    validators.all(
+      validators.required,
+      validators.minLength(8),
+      validators.pattern(
+        /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/,
+        'Password must contain lowercase, uppercase, and number'
+      )
+    )
+  )
+  .validate('theme', validators.oneOf(['light', 'dark', 'auto']))
+  .validate('language', validators.oneOf(['en', 'es', 'fr', 'de']))
+
+  // Custom validation
+  .validate('password', (value, context) => {
+    if (context.source.accountInfo.confirmPassword !== value) {
+      return 'Passwords do not match';
+    }
+    return true;
+  });
+
+const result = await converter.convert(formData);
+
+if (result.errors.length > 0) {
+  console.log('Validation errors:');
+  result.errors.forEach(error => {
+    console.log(`- ${error.path}: ${error.message}`);
+  });
+} else {
+  console.log('User data is valid!');
+  console.log(result.data);
+  // {
+  //   fullName: 'John Doe',
+  //   email: 'john.doe@example.com',
+  //   age: 28,
+  //   username: 'johndoe123',
+  //   password: 'SecurePass123!',
+  //   subscribeToNewsletter: true,
+  //   theme: 'dark',
+  //   language: 'en'
+  // }
+}
+```
+
+### Example 7: Defaults and Hooks
+
+```javascript
+// Student data with missing fields
+const studentData = {
+  student: {
+    firstName: 'Alice',
+    lastName: 'Smith',
+    // age is missing
+  },
+  grades: {
+    math: 85,
+    english: 92,
+    // science grade is missing
+  },
+  // activities array is missing
+  info: {
+    grade: '5th',
+    teacher: 'Ms. Johnson',
+    // school year is missing
+  },
+};
+
+const converter = forge()
+  .from('studentReport')
+  .to('completeProfile')
+
+  // Basic mappings
+  .map('student.firstName', 'firstName')
+  .map('student.lastName', 'lastName')
+  .map('student.age', 'age')
+  .map('grades.math', 'mathGrade')
+  .map('grades.english', 'englishGrade')
+  .map('grades.science', 'scienceGrade')
+  .map('activities', 'extracurriculars')
+  .map('info.grade', 'gradeLevel')
+  .map('info.teacher', 'teacher')
+  .map('info.schoolYear', 'academicYear')
+
+  // Set default values for missing fields
+  .defaults({
+    age: 10, // Default age for 5th graders
+    scienceGrade: 80, // Default science grade
+    extracurriculars: ['reading'], // Default activity
+    academicYear: () => {
+      // Dynamic default - current school year
+      const now = new Date();
+      const year = now.getFullYear();
+      const month = now.getMonth();
+      return month >= 8 ? `${year}-${year + 1}` : `${year - 1}-${year}`;
+    },
+    status: 'active',
+    lastUpdated: () => new Date().toISOString(),
+  })
+
+  // Add before hook to log conversion start
+  .before(data => {
+    console.log('🔄 Starting conversion...');
+    console.log(
+      `Processing student: ${data.student?.firstName} ${data.student?.lastName}`
+    );
+    return data; // Return the data unchanged
+  })
+
+  // Add after hook to calculate grade average
+  .after(data => {
+    console.log('✅ Conversion completed!');
+
+    // Create full name from first and last name
+    if (data.firstName && data.lastName) {
+      data.fullName = `${data.firstName} ${data.lastName}`;
+    }
+
+    // Calculate and add grade average
+    const { mathGrade, englishGrade, scienceGrade } = data;
+    if (mathGrade && englishGrade && scienceGrade) {
+      data.gradeAverage = Math.round(
+        (mathGrade + englishGrade + scienceGrade) / 3
+      );
+      console.log(`Calculated grade average: ${data.gradeAverage}`);
+    }
+
+    return data; // Return the modified data
+  });
+
+const result = await converter.convert(studentData);
+console.log(result.data);
+// {
+//   firstName: 'Alice',
+//   lastName: 'Smith',
+//   mathGrade: 85,
+//   englishGrade: 92,
+//   gradeLevel: '5th',
+//   teacher: 'Ms. Johnson',
+//   age: 10,
+//   scienceGrade: 80,
+//   extracurriculars: ['reading'],
+//   academicYear: '2024-2025',
+//   status: 'active',
+//   lastUpdated: '2024-12-23T06:22:05.491Z',
+//   fullName: 'Alice Smith',
+//   gradeAverage: 86
+// }
+```
+
+### Example 8: File Conversion
 
 ```javascript
 // Convert YAML file to JSON structure
@@ -245,14 +781,70 @@ const result = await converter.convert('./config.yml');
 await result.save('./config.json');
 ```
 
+### Example 9: 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]`
 - ✅ **Transformations**: Transform values during mapping
+- ✅ **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 ⭐ NEW!
+- ✅ **CLI Generation System**: Create command-line interfaces for converters ⭐ NEW!
 - ✅ **File support**: Convert YAML, JSON files directly
 - ✅ **Statistics**: Get detailed conversion reports
 - ✅ **TypeScript**: Full type safety
@@ -264,17 +856,20 @@ await result.save('./config.json');
 - Basic field mapping with `map()`
 - Nested object and array access
 - Value transformations
-- Default values with `defaults()`
+- **Default values with `defaults()`** ⭐ ENHANCED!
+- **Array/object processing with `forEach()`**
+- **Conditional mapping with `when()`**
+- **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!
 - File parsing (YAML, JSON)
 - Conversion statistics and reporting
-- Before/after hooks
+- Async and sync conversion support
 
 **🚧 Coming Soon:**
 
-- Conditional mapping with `when()`
-- Array processing with `forEach()`
-- Field validation
-- CLI generation
 - Plugin system
 
 ## 💡 Tips
@@ -283,9 +878,32 @@ await result.save('./config.json');
 2. **Use dot notation** for nested objects: `'user.profile.name'`
 3. **Use bracket notation** for arrays: `'items[0]'`, `'items[1]'`
 4. **Transform functions** get the value and context: `(value, ctx) => { ... }`
-5. **Check `result.unmapped`** to see which fields weren't mapped
-6. **Use `result.print()`** for a nice conversion report
+5. **Use conditional mapping** with `when()` for type-specific logic: `when(source => source.accountType === 'premium')`
+6. **Use merge()** to combine multiple fields: `merge(['field1', 'field2'], 'result', (a, b) => a + b)`
+7. **Use validation** to ensure data quality: `validate('email', validators.email)`
+8. **Combine validators** with `validators.all()` for multiple rules
+9. **Always call `.end()`** after conditional mappings to return to the main converter
+10. **Check `result.errors`** to see validation failures
+11. **Check `result.unmapped`** to see which fields weren't mapped
+12. **Use `result.print()`** for a nice conversion report
+13. **Use `defaults()`** to provide fallback values for missing fields: `defaults({ status: 'active' })`
+14. **Use function defaults** for dynamic values: `defaults({ timestamp: () => new Date().toISOString() })`
+15. **Use `before()` hooks** to preprocess source data before conversion
+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
 
 ---
 
 That's it! ConfigForge makes config conversion simple and straightforward. No complex setup, no direct class manipulation - just define your mappings and convert.
+
+## License
+
+This package is licensed under the **PolyForm Noncommercial License 1.0.0**.  
+See the [LICENSE](./LICENSE) file for full terms.