configforge 1.5.0 → 1.6.0

package/README.md

@@ -1244,235 +1244,300 @@ console.log('Backup created:', result.context?.backupPath);
 
 ### Example 10: Multi-File Processing ⭐ NEW!
 
-ConfigForge now supports processing multiple input files into a single output (many-to-one) or splitting a single input into multiple outputs (one-to-many). This is perfect for plugin conversions like DecentHolograms to CMI.
+ConfigForge makes it easy to work with multiple files at once. Think of it like organizing your music collection - you might have individual song files that you want to combine into a playlist, or a big playlist that you want to split into smaller themed playlists.
 
 ```javascript
 const { forge } = require('configforge');
 
-// Example: Converting DecentHolograms to CMI (many-to-one)
-// DecentHolograms stores each hologram in separate files:
-// - NPCCoinshop.yml, NPCCosmetics.yml, Welcome.yml, etc.
-// CMI stores all holograms in a single file
+// Example 1: Combining Multiple Files (Many-to-One)
+// Like combining individual recipe cards into a cookbook
 
-const decentToCmiConverter = forge()
-  .from('decentholograms')
-  .to('cmi-holograms')
-
-  // Map location format: "spawn:0.500:103.500:-6.5" -> "world;0.5;82.75;-36.5"
-  .map('location', 'Loc', location => {
-    if (typeof location !== 'string') return location;
-
-    const parts = location.split(':');
-    if (parts.length >= 4) {
-      const world = parts[0] || 'world';
-      const x = parseFloat(parts[1]) || 0;
-      const y = parseFloat(parts[2]) || 0;
-      const z = parseFloat(parts[3]) || 0;
-
-      return `${world};${x};${y};${z}`;
-    }
-    return location;
-  })
-
-  // Map other fields
-  .map('display-range', 'RangeExtra')
-  .map('update-interval', 'Interval')
-
-  // Transform pages to CMI Lines format
-  .map('pages', 'Lines', pages => {
-    if (!Array.isArray(pages) || pages.length === 0) return [];
-
-    const firstPage = pages[0];
-    if (!firstPage || !Array.isArray(firstPage.lines)) return [];
-
-    return firstPage.lines
-      .map(line => {
-        if (typeof line === 'string') return line;
-        if (line && typeof line.content === 'string') {
-          return line.content;
-        }
-        return '';
-      })
-      .filter(line => line.length > 0);
-  })
+// You have separate recipe files:
+const recipeFiles = [
+  {
+    filename: 'chocolate-cake.yml',
+    content: `
+name: Chocolate Cake
+category: dessert
+servings: 8
+ingredients:
+  - flour: 2 cups
+  - sugar: 1.5 cups
+  - cocoa: 0.5 cups
+cookTime: 45
+difficulty: medium
+`,
+  },
+  {
+    filename: 'pasta-salad.yml',
+    content: `
+name: Pasta Salad
+category: main
+servings: 6
+ingredients:
+  - pasta: 1 lb
+  - tomatoes: 2 cups
+  - cheese: 1 cup
+cookTime: 20
+difficulty: easy
+`,
+  },
+  {
+    filename: 'fruit-smoothie.yml',
+    content: `
+name: Fruit Smoothie
+category: drink
+servings: 2
+ingredients:
+  - banana: 1
+  - berries: 1 cup
+  - yogurt: 0.5 cups
+cookTime: 5
+difficulty: easy
+`,
+  },
+];
 
-  // Set CMI defaults
+// Create a converter to combine recipes into a cookbook
+const cookbookConverter = forge()
+  .from('*.yml')
+  .to('cookbook.yml')
+  // Use filename as the recipe key (removes .yml automatically)
+  .useFilenameAsKey()
+  // Map recipe fields to cookbook format
+  .map('name', 'title')
+  .map('category', 'type')
+  .map('servings', 'serves')
+  .map('ingredients', 'ingredientList')
+  .map('cookTime', 'prepTime')
+  .map('difficulty', 'skillLevel')
+  // Add some defaults for the cookbook
   .defaults({
-    Filler: 245,
+    tested: true,
+    addedDate: () => new Date().toISOString().split('T')[0], // Just the date
   });
 
-// Convert multiple DecentHolograms files to single CMI format
-const inputFiles = [
-  'holograms/NPCCoinshop.yml',
-  'holograms/NPCCosmetics.yml',
-  'holograms/Welcome.yml',
-  'holograms/CrateCommon.yml',
-];
-
-const result = await decentToCmiConverter.convertMany(inputFiles, {
-  mergeStrategy: 'merge',
-  preserveFileNames: true,
-  keyExtractor: filePath => {
-    // Extract hologram name from filename
-    return path.basename(filePath, path.extname(filePath));
-  },
-});
+// Convert all recipe files into one cookbook
+const cookbook = await cookbookConverter.convert(recipeFiles);
 
-console.log('✅ Converted', result.fileResults.length, 'hologram files');
-console.log(result.data);
+console.log(
+  '📚 Created cookbook with',
+  Object.keys(cookbook.data).length,
+  'recipes'
+);
+console.log(cookbook.data);
 // {
-//   NPCCoinshop: {
-//     Loc: 'world;-26.5;82.05;-24.5',
-//     RangeExtra: 50,
-//     Lines: ['ICON:TOTEM_OF_UNDYING', '{#FFCB6C>}&lSTORE{#FFAB3D<}'],
-//     Filler: 245
+//   'chocolate-cake': {
+//     title: 'Chocolate Cake',
+//     type: 'dessert',
+//     serves: 8,
+//     ingredientList: [{ flour: '2 cups' }, { sugar: '1.5 cups' }, { cocoa: '0.5 cups' }],
+//     prepTime: 45,
+//     skillLevel: 'medium',
+//     tested: true,
+//     addedDate: '2024-01-22'
 //   },
-//   NPCCosmetics: {
-//     Loc: 'world;10.0;64.0;20.0',
-//     RangeExtra: 30,
-//     Lines: ['&6Cosmetics Shop', '&eClick to browse!'],
-//     Filler: 245
+//   'pasta-salad': {
+//     title: 'Pasta Salad',
+//     type: 'main',
+//     serves: 6,
+//     ingredientList: [{ pasta: '1 lb' }, { tomatoes: '2 cups' }, { cheese: '1 cup' }],
+//     prepTime: 20,
+//     skillLevel: 'easy',
+//     tested: true,
+//     addedDate: '2024-01-22'
 //   },
-//   // ... more holograms
+//   'fruit-smoothie': {
+//     title: 'Fruit Smoothie',
+//     type: 'drink',
+//     serves: 2,
+//     ingredientList: [{ banana: 1 }, { berries: '1 cup' }, { yogurt: '0.5 cups' }],
+//     prepTime: 5,
+//     skillLevel: 'easy',
+//     tested: true,
+//     addedDate: '2024-01-22'
+//   }
 // }
 
-// Save the merged result
-await result.save('cmi-holograms.yml');
-
-// Example: Converting CMI back to DecentHolograms (one-to-many)
-const cmiToDecentConverter = forge()
-  .from('cmi-holograms')
-  .to('decentholograms')
-
-  // Reverse the location mapping
-  .map('Loc', 'location', loc => {
-    if (typeof loc !== 'string') return loc;
-
-    const parts = loc.split(';');
-    if (parts.length >= 4) {
-      const world = parts[0] || 'spawn';
-      const x = parseFloat(parts[1]) || 0;
-      const y = parseFloat(parts[2]) || 0;
-      const z = parseFloat(parts[3]) || 0;
+// Example 2: Splitting One File into Many (One-to-Many)
+// Like taking a big address book and creating separate contact cards
+
+const addressBookData = {
+  filename: 'contacts.yml',
+  content: `
+contacts:
+  john-doe:
+    name: John Doe
+    email: john@example.com
+    phone: 555-0123
+    category: friend
+    city: New York
+  jane-smith:
+    name: Jane Smith
+    email: jane@company.com
+    phone: 555-0456
+    category: work
+    city: Boston
+  mom:
+    name: Mary Johnson
+    email: mom@family.com
+    phone: 555-0789
+    category: family
+    city: Chicago
+`,
+};
 
-      return `${world}:${x}:${y}:${z}`;
-    }
-    return loc;
+// Create converter to split contacts into individual cards
+const contactConverter = forge()
+  .from('*.yml')
+  .to('json')
+  // Transform each contact
+  .map('name', 'fullName')
+  .map('email', 'emailAddress')
+  .map('phone', 'phoneNumber')
+  .map('category', 'group')
+  .map('city', 'location')
+  // Add some useful defaults
+  .defaults({
+    favorite: false,
+    lastContacted: null,
   })
+  // Split the contacts into separate files
+  .split(data => {
+    const result = {};
+
+    // Take each contact and make it a separate file
+    if (data.contacts) {
+      for (const [contactId, contactInfo] of Object.entries(data.contacts)) {
+        // Create filename based on contact name and category
+        const filename = `${contactInfo.category}-${contactId}.yml`;
+        result[filename] = contactInfo;
+      }
+    }
 
-  .map('RangeExtra', 'display-range')
-  .map('Interval', 'update-interval')
+    return result;
+  });
 
-  // Transform CMI Lines to DecentHolograms pages
-  .map('Lines', 'pages', lines => {
-    if (!Array.isArray(lines)) return [];
+const splitContacts = await contactConverter.convert([addressBookData]);
 
-    const pageLines = lines.map(line => ({
-      content: line,
-      height: 0.3,
-    }));
+// Get the individual contact files
+const contactFiles = splitContacts.toFiles();
+console.log(`📇 Split into ${contactFiles.length} contact cards:`);
 
-    return [
-      {
-        lines: pageLines,
-        actions: {},
-      },
-    ];
-  })
+contactFiles.forEach(file => {
+  console.log(`📄 ${file.filename}`);
+  console.log(file.content.substring(0, 100) + '...');
+});
 
-  .defaults({
-    enabled: true,
-    'update-range': 100,
-    facing: 0.0,
-    'down-origin': false,
-  });
+// Output:
+// 📇 Split into 3 contact cards:
+// 📄 friend-john-doe.yml
+// fullName: John Doe
+// emailAddress: john@example.com
+// phoneNumber: 555-0123
+// group: friend
+// location: New York...
+//
+// 📄 work-jane-smith.yml
+// fullName: Jane Smith
+// emailAddress: jane@company.com
+// phoneNumber: 555-0456
+// group: work
+// location: Boston...
+//
+// 📄 family-mom.yml
+// fullName: Mary Johnson
+// emailAddress: mom@family.com
+// phoneNumber: 555-0789
+// group: family
+// location: Chicago...
 
-// Split function to separate each hologram into its own file
-const splitFn = cmiData => {
-  const result = {};
+// Example 3: Handling Conflicts (When Files Have Same Names)
+// Like when you have two recipes both called "cake.yml"
 
-  for (const [hologramName, hologramData] of Object.entries(cmiData)) {
-    if (typeof hologramData === 'object' && hologramData !== null) {
-      result[hologramName] = hologramData;
-    }
-  }
+const conflictingFiles = [
+  {
+    filename: 'cake.yml',
+    content: 'name: Chocolate Cake\ntype: dessert\nrating: 5',
+  },
+  {
+    filename: 'cake.yml', // Same filename!
+    content: 'name: Vanilla Cake\ntype: dessert\nrating: 4',
+  },
+];
 
-  return result;
-};
+// Option 1: Merge conflicts (combine the values)
+const mergeConverter = forge()
+  .from('*.yml')
+  .to('json')
+  .useFilenameAsKey()
+  .onKeyConflict('merge'); // Combine conflicting values into arrays
 
-// Convert single CMI file to multiple DecentHolograms files
-const splitResults = await cmiToDecentConverter.convertSplit(
-  'cmi-holograms.yml',
-  splitFn
-);
+const mergedResult = await mergeConverter.convert(conflictingFiles);
+console.log('🔀 Merged conflicts:', mergedResult.data);
+// {
+//   cake: {
+//     name: ['Chocolate Cake', 'Vanilla Cake'],  // Both names in an array
+//     type: 'dessert',  // Same value, no conflict
+//     rating: [5, 4]    // Both ratings in an array
+//   }
+// }
 
-console.log('✅ Created', Object.keys(splitResults).length, 'hologram files');
+// Option 2: Error on conflicts (be strict)
+const strictConverter = forge()
+  .from('*.yml')
+  .to('json')
+  .useFilenameAsKey()
+  .onKeyConflict('error'); // Stop and report the problem
 
-// Save each hologram to its own file
-const outputDir = 'decent-holograms-output';
-for (const [hologramName, result] of Object.entries(splitResults)) {
-  await result.save(`${outputDir}/${hologramName}.yml`);
+try {
+  await strictConverter.convert(conflictingFiles);
+} catch (error) {
+  console.log('⚠️ Conflict detected:', error.message);
+  // "Key conflict detected: 'cake' appears in multiple files"
 }
 
-// Advanced: Custom merge strategies
-const customMergeConverter = forge()
-  .from('decentholograms')
-  .to('cmi-holograms');
-
-// Custom merger that groups holograms by type
-const customMerger = (inputs, filePaths) => {
-  const grouped = {
-    spawn_holograms: {},
-    npc_holograms: {},
-    other_holograms: {},
-  };
-
-  inputs.forEach((data, index) => {
-    const fileName = path.basename(filePaths[index], '.yml');
+// Real-world example: Simple server config merger
+const serverConfigs = [
+  {
+    filename: 'database.yml',
+    content: 'host: db.example.com\nport: 5432\nname: myapp',
+  },
+  {
+    filename: 'cache.yml',
+    content: 'host: cache.example.com\nport: 6379\nttl: 3600',
+  },
+];
 
-    if (fileName.toLowerCase().includes('npc')) {
-      grouped.npc_holograms[fileName] = data;
-    } else if (data.location && data.location.includes('spawn')) {
-      grouped.spawn_holograms[fileName] = data;
-    } else {
-      grouped.other_holograms[fileName] = data;
-    }
+const serverConverter = forge()
+  .from('*.yml')
+  .to('config.yml')
+  .useFilenameAsKey()
+  .map('host', 'hostname')
+  .map('port', 'port')
+  .defaults({
+    enabled: true,
+    timeout: 30,
   });
 
-  return grouped;
-};
-
-const groupedResult = await customMergeConverter.convertMany(inputFiles, {
-  mergeStrategy: 'custom',
-  customMerger: customMerger,
-});
-
-console.log(groupedResult.data);
+const serverConfig = await serverConverter.convert(serverConfigs);
+console.log('🖥️ Server configuration:', serverConfig.data);
 // {
-//   spawn_holograms: {
-//     Welcome: { Loc: 'spawn;0.5;103.5;-6.5', ... }
-//   },
-//   npc_holograms: {
-//     NPCCoinshop: { Loc: 'world;-26.5;82.05;-24.5', ... },
-//     NPCCosmetics: { Loc: 'world;10.0;64.0;20.0', ... }
+//   database: {
+//     hostname: 'db.example.com',
+//     port: 5432,
+//     name: 'myapp',
+//     enabled: true,
+//     timeout: 30
 //   },
-//   other_holograms: {
-//     CrateCommon: { Loc: 'world;100;64;200', ... }
+//   cache: {
+//     hostname: 'cache.example.com',
+//     port: 6379,
+//     ttl: 3600,
+//     enabled: true,
+//     timeout: 30
 //   }
 // }
-
-// Multi-file processing options:
-//
-// mergeStrategy: 'merge' (default) - Merge objects using file names as keys
-// mergeStrategy: 'array' - Combine all inputs into an array
-// mergeStrategy: 'custom' - Use custom merger function
-//
-// preserveFileNames: true (default) - Use filenames as object keys
-// preserveFileNames: false - Simple deep merge without keys
-//
-// keyExtractor: function - Custom function to extract keys from file paths
-// continueOnError: true (default) - Continue processing other files if one fails
-// rootKey: string - Wrap merged data in a root key
 ```
 
 ### Example 11: Batch Processing and Performance Features
@@ -1737,6 +1802,9 @@ cli.parse();
 - ✅ **Simple API**: Just map fields and convert
 - ✅ **String Input Support**: Convert raw YAML/JSON strings directly with `convertString()` ⭐ NEW!
 - ✅ **Multi-File Processing**: Process multiple input files into single output (many-to-one) or split single input into multiple outputs (one-to-many) ⭐ NEW!
+- ✅ **Split Functionality**: Break single input files into multiple outputs with configurable split functions ⭐ NEW!
+- ✅ **Conflict Resolution**: Handle field conflicts in multi-file processing with configurable strategies (error, overwrite, merge, suffix) ⭐ NEW!
+- ✅ **Enhanced Result Handling**: Comprehensive result objects with `getSummary()`, `toFiles()`, and enhanced `print()` methods ⭐ NEW!
 - ✅ **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`
@@ -1765,7 +1833,11 @@ cli.parse();
 - Nested object and array access
 - Value transformations
 - **String input support with `convertString()` and `convert()` with `isRawContent` option** ⭐ NEW!
+- **Enhanced result handling with `getSummary()`, `toFiles()`, and improved `print()` methods** ⭐ NEW!
 - **Multi-file processing with `convertMany()` (many-to-one) and `convertSplit()` (one-to-many)** ⭐ NEW!
+- **Complete pipeline integration with multi-file processing** ⭐ NEW!
+- **Multi-file conflict resolution with configurable strategies (error, overwrite, merge, suffix)** ⭐ NEW!
+- **Split functionality with `split()` method for one-to-many processing** ⭐ NEW!
 - **Default values with `defaults()`** ⭐ ENHANCED!
 - **Array/object processing with `forEach()` and `mapToObject()`** ⭐ ENHANCED!
 - **Conditional mapping with `when()`**
@@ -1824,31 +1896,49 @@ cli.parse();
 34. **Use `forEach()` with `{ output: 'object' }` to transform arrays into keyed objects** - perfect for converting indexed arrays to UUID-keyed objects
 35. **`forEach()` with object output merges returned objects** - return `{ [key]: value }` to create dynamic keys from your data
 36. **Filter with `forEach()`** - return `null` from the mapping function to exclude items from the result
-37. **Choose forEach output type** - use `{ output: 'array' }` (default) to maintain structure, `{ output: 'object' }` to create keyed objects
-38. **Track progress** - provide `progressCallback` to monitor batch processing progress in real-time
-39. **Cache management** - use `IncrementalProcessor.getCacheStats()` and `cleanupCache()` to manage incremental processing cache
-40. **Save batch results** - use `BatchProcessor.saveBatch()` to save all conversion results to an output directory
-41. **Use forge() with options** - pass `ForgeOptions` to `forge({ strict: true, parallel: true })` to configure converter behavior globally
-42. **Use convertString() for raw content** - when you have YAML or JSON as a string, use `convertString()` instead of `convert()` ⭐ NEW!
-43. **Use convert() with isRawContent option** - alternatively, use `convert(stringContent, { isRawContent: true })` for string input ⭐ NEW!
-44. **Format auto-detection works with strings** - ConfigForge automatically detects YAML vs JSON format in string content ⭐ NEW!
-45. **String input handles parsing errors gracefully** - malformed YAML/JSON strings will produce helpful error messages ⭐ NEW!
-46. **forEach field tracking is automatic** - when you access fields inside forEach callbacks, they're automatically marked as mapped in statistics ⭐ NEW!
-47. **forEach with target renaming** - use `forEach('source', 'target', mapFn)` to rename arrays/objects in output: `forEach('npc', 'npcs', mapFn)` ⭐ NEW!
-48. **Array indices are always numbers** - in forEach for arrays, the index parameter is guaranteed to be a number, so `index + 1` works correctly ⭐ NEW!
-49. **Object keys in forEach** - for objects, forEach passes the key as the second parameter for backward compatibility ⭐ NEW!
-50. **Access object keys in context** - when processing objects with forEach, the key is also available in `context.metadata.objectKey` ⭐ NEW!
-51. **Use convertMany() for many-to-one processing** - merge multiple input files into a single output with `convertMany(inputPaths, options)` ⭐ NEW!
-52. **Use convertSplit() for one-to-many processing** - split a single input file into multiple outputs with `convertSplit(inputPath, splitFn)` ⭐ NEW!
-53. **Choose merge strategies wisely** - use `'merge'` for object merging, `'array'` for simple arrays, or `'custom'` for complex logic ⭐ NEW!
-54. **Custom key extractors for file naming** - use `keyExtractor: (filePath) => customKey` to control how filenames become object keys ⭐ NEW!
-55. **Multi-file processing is fully tested and stable** - both `convertMany()` and `convertSplit()` have comprehensive test coverage and error handling ⭐ ENHANCED!
-56. **Handle file errors gracefully** - set `continueOnError: true` to process all files even if some fail, or `false` to stop on first error ⭐ NEW!
-57. **Perfect for plugin conversions** - multi-file processing is ideal for converting between plugin formats like DecentHolograms ↔ CMI ⭐ NEW!
-58. **Use rootKey for wrapping** - set `rootKey: 'holograms'` to wrap merged data in a parent object ⭐ NEW!
-59. **Check fileResults for debugging** - `result.fileResults` shows success/failure status for each processed file ⭐ NEW!
-60. **Monitor failed files** - `result.failedFiles` contains paths of files that couldn't be processed ⭐ NEW!
-61. **Split functions control output structure** - return `{ key1: data1, key2: data2 }` from split functions to create multiple output files ⭐ NEW!
+37. **Use `result.getSummary()`** - get detailed statistics about conversion success, file counts, errors, and duration
+38. **Use `result.toFiles()`** - convert any result to FileObject arrays for consistent multi-file handling
+39. **Enhanced `print()` methods** - result printing now includes emojis and better formatting for easier debugging
+40. **Multi-file results provide file-specific statistics** - track success/failure per file in batch operations
+41. **Split results include generated file lists** - `getSummary().generatedFiles` shows all files created from split operations
+42. **Pipeline integration works seamlessly with multi-file processing** - all pipeline steps (parse, map, transform, validate, hooks) work correctly across multiple files
+43. **Multi-file context is available in all pipeline steps** - access filename, fileIndex, and other multi-file metadata in transforms and hooks
+44. **Error collection spans multiple files** - validation errors and processing errors are collected across all files with proper context
+45. **Choose forEach output type** - use `{ output: 'array' }` (default) to maintain structure, `{ output: 'object' }` to create keyed objects
+46. **Track progress** - provide `progressCallback` to monitor batch processing progress in real-time
+47. **Cache management** - use `IncrementalProcessor.getCacheStats()` and `cleanupCache()` to manage incremental processing cache
+48. **Save batch results** - use `BatchProcessor.saveBatch()` to save all conversion results to an output directory
+49. **Use forge() with options** - pass `ForgeOptions` to `forge({ strict: true, parallel: true })` to configure converter behavior globally
+50. **Use convertString() for raw content** - when you have YAML or JSON as a string, use `convertString()` instead of `convert()` ⭐ NEW!
+51. **Use convert() with isRawContent option** - alternatively, use `convert(stringContent, { isRawContent: true })` for string input ⭐ NEW!
+52. **Format auto-detection works with strings** - ConfigForge automatically detects YAML vs JSON format in string content ⭐ NEW!
+53. **String input handles parsing errors gracefully** - malformed YAML/JSON strings will produce helpful error messages ⭐ NEW!
+54. **forEach field tracking is automatic** - when you access fields inside forEach callbacks, they're automatically marked as mapped in statistics ⭐ NEW!
+55. **forEach with target renaming** - use `forEach('source', 'target', mapFn)` to rename arrays/objects in output: `forEach('npc', 'npcs', mapFn)` ⭐ NEW!
+56. **Array indices are always numbers** - in forEach for arrays, the index parameter is guaranteed to be a number, so `index + 1` works correctly ⭐ NEW!
+57. **Object keys in forEach** - for objects, forEach passes the key as the second parameter for backward compatibility ⭐ NEW!
+58. **Access object keys in context** - when processing objects with forEach, the key is also available in `context.metadata.objectKey` ⭐ NEW!
+59. **Use convertMany() for many-to-one processing** - merge multiple input files into a single output with `convertMany(inputPaths, options)` ⭐ NEW!
+60. **Use convertSplit() for one-to-many processing** - split a single input file into multiple outputs with `convertSplit(inputPath, splitFn)` ⭐ NEW!
+61. **Choose merge strategies wisely** - use `'merge'` for object merging, `'array'` for simple arrays, or `'custom'` for complex logic ⭐ NEW!
+62. **Custom key extractors for file naming** - use `keyExtractor: (filePath) => customKey` to control how filenames become object keys ⭐ NEW!
+63. **Multi-file processing is fully tested and stable** - both `convertMany()` and `convertSplit()` have comprehensive test coverage and error handling ⭐ ENHANCED!
+64. **Handle file errors gracefully** - set `continueOnError: true` to process all files even if some fail, or `false` to stop on first error ⭐ NEW!
+65. **Perfect for plugin conversions** - multi-file processing is ideal for converting between plugin formats like DecentHolograms ↔ CMI ⭐ NEW!
+66. **Use rootKey for wrapping** - set `rootKey: 'holograms'` to wrap merged data in a parent object ⭐ NEW!
+67. **Check fileResults for debugging** - `result.fileResults` shows success/failure status for each processed file ⭐ NEW!
+68. **Monitor failed files** - `result.failedFiles` contains paths of files that couldn't be processed ⭐ NEW!
+69. **Split functions control output structure** - return `{ key1: data1, key2: data2 }` from split functions to create multiple output files ⭐ NEW!
+70. **Handle field conflicts in multi-file processing** - use `onKeyConflict()` to configure how to handle conflicting field names across files ⭐ NEW!
+71. **Choose conflict resolution strategy** - use `'error'` to fail on conflicts, `'overwrite'` for last-wins, `'merge'` to combine into arrays, or `'suffix'` to add unique suffixes ⭐ NEW!
+72. **Merge strategy combines conflicting fields** - when using `onKeyConflict('merge')`, fields with the same name across files are combined into arrays ⭐ NEW!
+73. **Custom conflict suffixes** - use `onKeyConflict('suffix', '_backup')` to customize the suffix added to conflicting field names ⭐ NEW!
+74. **Force same key for conflict testing** - use `useKey('fixedKey')` to force all files to use the same key, creating conflicts for testing resolution strategies ⭐ NEW!
+75. **Use split() for one-to-many processing** - break single input files into multiple outputs with `split(data => ({ file1: data.part1, file2: data.part2 }))` ⭐ NEW!
+76. **Split functions control output structure** - return an object where keys become filenames and values become file content ⭐ NEW!
+77. **Split works with all mappings and transforms** - apply field mappings, transformations, defaults, and hooks to each split output ⭐ NEW!
+78. **Split handles errors gracefully** - if split function fails or individual conversions error, detailed error information is provided ⭐ NEW!
+79. **Combine split with filename mapping** - use `mapFilename()` to include source filename information in each split output ⭐ NEW!
 
 ---
 

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

@@ -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"}
+{"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;IAiDzB;;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"}

package/dist/core/BatchProcessor.js

@@ -191,7 +191,16 @@ class BatchProcessor {
                 save: async () => { },
                 toJSON: () => '{}',
                 toYAML: () => '{}',
+                toFiles: () => [{ filename: 'error.yml', content: '{}' }], // ⭐ NEW! Required method
                 print: () => { },
+                getSummary: () => ({
+                    success: false,
+                    fileCount: 1,
+                    errorCount: 1,
+                    warningCount: 0,
+                    unmappedCount: 0,
+                    duration: 0,
+                }),
             };
         }
     }