@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/02-CORE-GUIDES/parsers/modules/02-core-guides-parsers-07-troubleshooting.md

@@ -1,727 +1,727 @@
-# Module 7: Troubleshooting & Optimization
-
-**Level:** Intermediate
-**Estimated Time:** 20 minutes
-
-## Overview
-
-This module covers common parser errors, performance optimization techniques, and troubleshooting strategies. You'll learn how to diagnose issues, optimize performance, and handle edge cases.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Diagnose and fix common parser errors
-- ✅ Optimize parser performance for large files
-- ✅ Handle malformed or edge-case data
-- ✅ Implement recovery strategies
-- ✅ Monitor and log parser operations
-- ✅ Debug integration issues
-
-## Common Errors and Solutions
-
-### CSV Parser Errors
-
-#### Error: "Invalid CSV format"
-
-**Cause:** Malformed CSV structure (unclosed quotes, wrong delimiter)
-
-**Solution:**
-```typescript
-// Try different delimiter
-const records = await csvParser.parse(csvContent, {
-  delimiter: ';' // Try semicolon instead of comma
-});
-
-// Or skip problematic lines
-const records = await csvParser.parse(csvContent, {
-  skip_empty_lines: true,
-  relax_column_count: true // Allow inconsistent column counts
-});
-```
-
-#### Error: "Column count mismatch"
-
-**Cause:** Rows have different number of columns
-
-**Solution:**
-```typescript
-// Option 1: Relax column count validation
-const records = await csvParser.parse(csvContent, {
-  relax_column_count: true
-});
-
-// Option 2: Provide explicit column names
-const records = await csvParser.parse(csvContent, {
-  columns: ['sku', 'qty', 'location']
-});
-```
-
-#### Error: "Memory limit exceeded"
-
-**Cause:** Loading large CSV into memory
-
-**Solution:**
-```typescript
-// ❌ BAD: Load entire file
-const records = await csvParser.parse(largeCsvContent);
-
-// ✅ GOOD: Stream in batches
-for await (const batch of csvParser.parseStreaming(largeCsvContent, {}, 1000)) {
-  await processBatch(batch);
-}
-```
-
-### JSON Parser Errors
-
-#### Error: "Unexpected token"
-
-**Cause:** Invalid JSON syntax (missing quotes, trailing commas)
-
-**Solution:**
-```typescript
-// Try with relaxed options
-const parsed = await jsonParser.parse(jsonContent, {
-  allowComments: true,        // Allow // and /* */ comments
-  allowTrailingCommas: true  // Allow trailing commas
-});
-
-// Or repair common issues
-const repaired = jsonContent
-  .replace(/^\uFEFF/, '')     // Remove BOM
-  .replace(/,(\s*[}\]])/g, '$1'); // Remove trailing commas
-
-const parsed = await jsonParser.parse(repaired);
-```
-
-#### Error: "Cannot parse nested data"
-
-**Cause:** Accessing deeply nested properties incorrectly
-
-**Solution:**
-```typescript
-// Use dataPath to extract nested data
-const items = await jsonParser.parse(jsonContent, {
-  dataPath: 'response.data.inventory.items'
-});
-
-// Or use query() method
-const items = jsonParser.query(parsed, 'response.data.inventory.items');
-```
-
-#### Error: "JSONL parsing fails"
-
-**Cause:** Not setting jsonLines option
-
-**Solution:**
-```typescript
-// Ensure jsonLines option is set
-for await (const item of jsonParser.parseStreaming(jsonlContent, {
-  jsonLines: true,
-  batchSize: 100
-})) {
-  await processItem(item);
-}
-```
-
-### XML Parser Errors
-
-#### Error: "Mismatched tags"
-
-**Cause:** Malformed XML structure
-
-**Solution:**
-```typescript
-// Validate first
-const validation = xmlParser.validate(xmlContent);
-
-if (!validation.valid) {
-  console.error('XML validation errors:', validation.errors);
-  // Fix XML or reject
-}
-
-// Parse with error handling
-try {
-  const parsed = await xmlParser.parse(xmlContent);
-} catch (error) {
-  console.error('Parsing failed at:', error.message);
-  // Contains line/column info
-}
-```
-
-#### Error: "Cannot access attribute"
-
-**Cause:** Incorrect path syntax or direct access
-
-**Solution:**
-```typescript
-// ❌ WRONG: Direct access
-const value = parsed.order['@id'];
-
-// ✅ CORRECT: Use XMLPathResolver
-import { XMLPathResolver } from '@fluentcommerce/fc-connect-sdk';
-const resolver = new XMLPathResolver();
-const value = resolver.resolve(parsed, 'order@id');
-```
-
-#### Error: "Namespace prefix not found"
-
-**Cause:** XML namespaces not handled
-
-**Solution:**
-```typescript
-// Option 1: Remove namespaces
-const options = {
-  removeNamespacePrefix: true
-};
-
-const parsed = await xmlParser.parse(xmlContent, options);
-
-// Option 2: Preprocess XML
-const cleanXML = xmlContent.replace(/<(\/?)\w+:/g, '<$1');
-const parsed = await xmlParser.parse(cleanXML);
-```
-
-#### Error: "Text appears as child element instead of content"
-
-**Cause:** Not using `#text` key in XML generation
-
-**Solution:**
-```typescript
-// ❌ WRONG
-const data = {
-  Color: { "@id": "9101", "text": "MULTI-COLOR" }
-};
-
-// ✅ CORRECT
-const data = {
-  Color: { "@id": "9101", "#text": "MULTI-COLOR" }
-};
-
-const xml = builder.build(data);
-```
-
-### Parquet Parser Errors
-
-#### Error: "Invalid Parquet file"
-
-**Cause:** File is corrupted or not Parquet format
-
-**Solution:**
-```typescript
-// Validate before parsing
-const validation = await parquetParser.validate(parquetBuffer, {
-  requiredColumns: ['sku', 'qty']
-});
-
-if (!validation.valid) {
-  throw new Error(`Invalid Parquet: ${validation.errors.join(', ')}`);
-}
-
-// Check file magic bytes
-const magic = parquetBuffer.slice(0, 4).toString();
-if (magic !== 'PAR1') {
-  throw new Error('Not a valid Parquet file');
-}
-```
-
-#### Error: "Column not found"
-
-**Cause:** Requesting non-existent column
-
-**Solution:**
-```typescript
-// Get available columns first
-const stats = await parquetParser.getColumnStatistics(parquetBuffer);
-const availableColumns = Object.keys(stats);
-
-console.log('Available columns:', availableColumns);
-
-// Only request existing columns
-const records = await parquetParser.parse(parquetBuffer, {
-  columns: availableColumns.filter(c => ['sku', 'qty'].includes(c))
-});
-```
-
-## Performance Optimization
-
-### 1. Choose Right Parser for File Size
-
-```typescript
-// Small files (<10MB): Parse directly
-const records = await csvParser.parse(csvContent);
-
-// Medium files (10MB-100MB): Stream with batches
-for await (const batch of csvParser.parseStreaming(csvContent, {}, 1000)) {
-  await processBatch(batch);
-}
-
-// Large files (>100MB): Stream with smaller batches + parallel processing
-for await (const batch of csvParser.parseStreaming(csvContent, {}, 500)) {
-  // Process batches in parallel (with concurrency limit)
-  await processBatchParallel(batch);
-}
-```
-
-### 2. Optimize Batch Sizes
-
-```typescript
-// Memory-constrained (Versori, Lambda): Small batches
-const batchSize = 100;
-
-// High-memory environment: Large batches
-const batchSize = 5000;
-
-// Adaptive batch size based on record complexity
-function calculateBatchSize(recordSize: number): number {
-  const targetMemory = 10 * 1024 * 1024; // 10MB target
-  return Math.floor(targetMemory / recordSize);
-}
-```
-
-### 3. Disable Unnecessary Features
-
-```typescript
-// CSV: Disable features you don't need
-const records = await csvParser.parse(csvContent, {
-  trim: false,              // Skip if data already clean
-  cast: false,              // Skip type casting
-  skip_empty_lines: false   // Process all lines
-});
-
-// JSON: Skip validation and date parsing if not needed
-const parsed = await jsonParser.parse(jsonContent, {
-  parseDates: false,
-  validateSchema: false,
-  maxDepth: 10  // Limit recursion
-});
-
-// XML: Minimal options for speed
-const parsed = await xmlParser.parse(xmlContent, {
-  includeAttributes: false,
-  parseNumbers: false,
-  normalizeWhitespace: false
-});
-```
-
-### 4. Use Streaming Effectively
-
-```typescript
-// Process as you stream (don't accumulate)
-async function efficientStreaming(csvContent: string) {
-  const csvParser = new CSVParserService();
-
-  for await (const batch of csvParser.parseStreaming(csvContent, {}, 1000)) {
-    // Transform and send immediately
-    const mapper = new UniversalMapper(mappingConfig);
-    const result = await mapper.map(batch);
-
-    await sendToFluent(result.data);
-
-    // Don't store results - free memory immediately
-  }
-}
-```
-
-### 5. Parallel Processing
-
-```typescript
-import pLimit from 'p-limit';
-
-async function parallelProcessing(csvFiles: string[]) {
-  const limit = pLimit(5); // Max 5 concurrent
-
-  const promises = csvFiles.map(file =>
-    limit(async () => {
-      const csvParser = new CSVParserService();
-      const records = await csvParser.parse(file);
-      return processRecords(records);
-    })
-  );
-
-  const results = await Promise.all(promises);
-  return results.flat();
-}
-```
-
-## Handling Edge Cases
-
-### Empty Files
-
-```typescript
-async function handleEmptyFile(csvContent: string) {
-  const csvParser = new CSVParserService();
-  const records = await csvParser.parse(csvContent);
-
-  if (records.length === 0) {
-    console.warn('Empty file - no records to process');
-    return;
-  }
-
-  // Process records
-}
-```
-
-### Malformed Data
-
-```typescript
-async function handleMalformedData(csvContent: string) {
-  const csvParser = new CSVParserService();
-  const records = await csvParser.parse(csvContent, {
-    relax_column_count: true,  // Allow inconsistent columns
-    skip_empty_lines: true,    // Skip empty lines
-    on_record: (record, { lines }) => {
-      // Validate each record
-      if (!record.sku || !record.qty) {
-        console.warn(`Skipping invalid record at line ${lines}`);
-        return null; // Skip this record
-      }
-      return record;
-    }
-  });
-
-  console.log(`Parsed ${records.length} valid records`);
-}
-```
-
-### Encoding Issues
-
-```typescript
-// Handle different encodings
-import iconv from 'iconv-lite';
-
-// Detect and convert encoding
-function convertEncoding(buffer: Buffer): string {
-  // Try UTF-8 first
-  try {
-    return buffer.toString('utf-8');
-  } catch (error) {
-    // Try Latin1
-    return iconv.decode(buffer, 'latin1');
-  }
-}
-
-const csvContent = convertEncoding(fileBuffer);
-const records = await csvParser.parse(csvContent);
-```
-
-### Special Characters
-
-```typescript
-// Handle special characters in CSV
-const records = await csvParser.parse(csvContent, {
-  quote: '"',      // Quote character
-  escape: '\\',    // Escape character
-  ltrim: true,     // Trim left
-  rtrim: true      // Trim right
-});
-```
-
-## Monitoring and Logging
-
-### Progress Tracking
-
-```typescript
-async function parseWithProgress(csvContent: string) {
-  const csvParser = new CSVParserService();
-  const startTime = Date.now();
-  let recordCount = 0;
-
-  for await (const batch of csvParser.parseStreaming(csvContent, {}, 1000)) {
-    recordCount += batch.length;
-
-    // Log progress
-    const elapsed = (Date.now() - startTime) / 1000;
-    const rate = recordCount / elapsed;
-
-    console.log({
-      recordsProcessed: recordCount,
-      elapsedSeconds: elapsed.toFixed(2),
-      recordsPerSecond: rate.toFixed(2)
-    });
-
-    await processBatch(batch);
-  }
-}
-```
-
-### Error Logging
-
-```typescript
-import { FileParsingError } from '@fluentcommerce/fc-connect-sdk';
-
-async function parseWithLogging(csvContent: string) {
-  const csvParser = new CSVParserService();
-
-  try {
-    const records = await csvParser.parse(csvContent);
-    console.log({
-      status: 'success',
-      recordCount: records.length
-    });
-
-  } catch (error) {
-    if (error instanceof FileParsingError) {
-      console.error({
-        status: 'error',
-        type: 'parsing_error',
-        message: error.message,
-        fileName: error.fileName,
-        context: error.context
-      });
-    } else {
-      console.error({
-        status: 'error',
-        type: 'unknown_error',
-        message: error.message,
-        stack: error.stack
-      });
-    }
-
-    throw error;
-  }
-}
-```
-
-### Performance Metrics
-
-```typescript
-interface ParsingMetrics {
-  startTime: number;
-  endTime: number;
-  recordCount: number;
-  fileSize: number;
-  recordsPerSecond: number;
-  bytesPerSecond: number;
-}
-
-async function parseWithMetrics(csvContent: string): Promise<ParsingMetrics> {
-  const csvParser = new CSVParserService();
-  const startTime = Date.now();
-  const fileSize = Buffer.byteLength(csvContent);
-
-  const records = await csvParser.parse(csvContent);
-
-  const endTime = Date.now();
-  const elapsed = (endTime - startTime) / 1000;
-
-  const metrics: ParsingMetrics = {
-    startTime,
-    endTime,
-    recordCount: records.length,
-    fileSize,
-    recordsPerSecond: records.length / elapsed,
-    bytesPerSecond: fileSize / elapsed
-  };
-
-  console.log('Parsing metrics:', metrics);
-  return metrics;
-}
-```
-
-## Recovery Strategies
-
-### Retry Logic
-
-```typescript
-async function parseWithRetry(
-  csvContent: string,
-  maxRetries: number = 3
-): Promise<any[]> {
-  const csvParser = new CSVParserService();
-  let lastError: Error;
-
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    try {
-      return await csvParser.parse(csvContent);
-    } catch (error) {
-      lastError = error;
-      console.warn(`Parse attempt ${attempt} failed:`, error.message);
-
-      if (attempt < maxRetries) {
-        // Wait before retry (exponential backoff)
-        const delay = Math.pow(2, attempt) * 1000;
-        await new Promise(resolve => setTimeout(resolve, delay));
-      }
-    }
-  }
-
-  throw new Error(`Parsing failed after ${maxRetries} attempts: ${lastError.message}`);
-}
-```
-
-### Fallback Parsing
-
-```typescript
-async function parseWithFallback(csvContent: string) {
-  const csvParser = new CSVParserService();
-
-  // Try standard parsing
-  try {
-    return await csvParser.parse(csvContent);
-  } catch (error) {
-    console.warn('Standard parsing failed, trying relaxed options');
-  }
-
-  // Try with relaxed options
-  try {
-    return await csvParser.parse(csvContent, {
-      relax_column_count: true,
-      skip_empty_lines: true,
-      trim: true
-    });
-  } catch (error) {
-    console.warn('Relaxed parsing failed, trying alternative delimiter');
-  }
-
-  // Try alternative delimiter
-  try {
-    return await csvParser.parse(csvContent, {
-      delimiter: ';',
-      relax_column_count: true
-    });
-  } catch (error) {
-    throw new Error('All parsing strategies failed');
-  }
-}
-```
-
-### Partial Success
-
-```typescript
-async function parseWithPartialSuccess(csvContent: string) {
-  const csvParser = new CSVParserService();
-  const successfulRecords = [];
-  const failedRecords = [];
-
-  // Process line by line
-  const lines = csvContent.split('\n');
-  const headers = lines[0].split(',');
-
-  for (let i = 1; i < lines.length; i++) {
-    try {
-      const values = lines[i].split(',');
-      const record = Object.fromEntries(
-        headers.map((h, idx) => [h, values[idx]])
-      );
-
-      // Validate record
-      if (record.sku && record.qty) {
-        successfulRecords.push(record);
-      } else {
-        failedRecords.push({ line: i + 1, reason: 'Missing required fields' });
-      }
-    } catch (error) {
-      failedRecords.push({ line: i + 1, reason: error.message });
-    }
-  }
-
-  console.log({
-    successful: successfulRecords.length,
-    failed: failedRecords.length
-  });
-
-  if (failedRecords.length > 0) {
-    console.warn('Failed records:', failedRecords);
-  }
-
-  return successfulRecords;
-}
-```
-
-## Debugging Tips
-
-### 1. Enable Verbose Logging
-
-```typescript
-// Log each step
-async function parseWithDebugLogging(csvContent: string) {
-  console.log('1. Starting CSV parsing');
-  console.log('File size:', Buffer.byteLength(csvContent), 'bytes');
-
-  const csvParser = new CSVParserService();
-
-  console.log('2. Parsing CSV');
-  const records = await csvParser.parse(csvContent);
-
-  console.log('3. Parsed records:', records.length);
-  console.log('First record:', records[0]);
-  console.log('Last record:', records[records.length - 1]);
-
-  return records;
-}
-```
-
-### 2. Inspect Parsed Structure
-
-```typescript
-// Pretty-print parsed data
-const parsed = await jsonParser.parse(jsonContent);
-console.log(JSON.stringify(parsed, null, 2));
-
-// Or use util.inspect for better formatting
-import util from 'util';
-console.log(util.inspect(parsed, { depth: null, colors: true }));
-```
-
-### 3. Test with Sample Data
-
-```typescript
-// Test with small sample first
-const sampleCsv = csvContent.split('\n').slice(0, 10).join('\n');
-const sampleRecords = await csvParser.parse(sampleCsv);
-
-console.log('Sample parsing successful:', sampleRecords);
-
-// If sample works, try full file
-const allRecords = await csvParser.parse(csvContent);
-```
-
-## Common Patterns Summary
-
-| Issue | Solution |
-|-------|----------|
-| Memory issues | Use streaming with batches |
-| Malformed data | Use relaxed options + validation |
-| Wrong delimiter | Try different delimiters |
-| Encoding issues | Convert encoding before parsing |
-| Slow parsing | Disable unnecessary features |
-| Partial failures | Process line-by-line with error handling |
-| Nested data | Use dataPath or query() |
-| XML attributes | Use XMLPathResolver |
-| Large files | Stream + parallel processing |
-
-## Key Takeaways
-
-- 🎯 Always validate input before parsing
-- 🎯 Use streaming for files >10MB
-- 🎯 Optimize batch sizes for your environment
-- 🎯 Implement retry logic for transient failures
-- 🎯 Log metrics for performance monitoring
-- 🎯 Handle partial failures gracefully
-- 🎯 Test with sample data first
-
-## Practice Exercise
-
-**Challenge:** Build a robust parser that handles all edge cases:
-
-**Requirements:**
-1. Accept CSV, JSON, or XML input
-2. Detect and handle malformed data
-3. Stream large files efficiently
-4. Log progress and errors
-5. Implement retry logic
-6. Return both successful and failed records
-
-**Solution:** See [Parser Examples](../examples/)
-
----
-
-**Module 7 Complete!** ✅
-
-You've completed the Parser Services Learning Path! 🎉
-
-**Next Steps:**
-- Review [Quick Reference](../../advanced-services/advanced-services-quick-reference.md) for quick lookups
-- Explore [Examples](../examples/) for copy-paste code
-- Check [Universal Mapping Guide](../../mapping/) for transformations
-- See [Auto-Pagination Guide](../../auto-pagination/) for data extraction
+# Module 7: Troubleshooting & Optimization
+
+**Level:** Intermediate
+**Estimated Time:** 20 minutes
+
+## Overview
+
+This module covers common parser errors, performance optimization techniques, and troubleshooting strategies. You'll learn how to diagnose issues, optimize performance, and handle edge cases.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Diagnose and fix common parser errors
+- ✅ Optimize parser performance for large files
+- ✅ Handle malformed or edge-case data
+- ✅ Implement recovery strategies
+- ✅ Monitor and log parser operations
+- ✅ Debug integration issues
+
+## Common Errors and Solutions
+
+### CSV Parser Errors
+
+#### Error: "Invalid CSV format"
+
+**Cause:** Malformed CSV structure (unclosed quotes, wrong delimiter)
+
+**Solution:**
+```typescript
+// Try different delimiter
+const records = await csvParser.parse(csvContent, {
+  delimiter: ';' // Try semicolon instead of comma
+});
+
+// Or skip problematic lines
+const records = await csvParser.parse(csvContent, {
+  skip_empty_lines: true,
+  relax_column_count: true // Allow inconsistent column counts
+});
+```
+
+#### Error: "Column count mismatch"
+
+**Cause:** Rows have different number of columns
+
+**Solution:**
+```typescript
+// Option 1: Relax column count validation
+const records = await csvParser.parse(csvContent, {
+  relax_column_count: true
+});
+
+// Option 2: Provide explicit column names
+const records = await csvParser.parse(csvContent, {
+  columns: ['sku', 'qty', 'location']
+});
+```
+
+#### Error: "Memory limit exceeded"
+
+**Cause:** Loading large CSV into memory
+
+**Solution:**
+```typescript
+// ❌ BAD: Load entire file
+const records = await csvParser.parse(largeCsvContent);
+
+// ✅ GOOD: Stream in batches
+for await (const batch of csvParser.parseStreaming(largeCsvContent, {}, 1000)) {
+  await processBatch(batch);
+}
+```
+
+### JSON Parser Errors
+
+#### Error: "Unexpected token"
+
+**Cause:** Invalid JSON syntax (missing quotes, trailing commas)
+
+**Solution:**
+```typescript
+// Try with relaxed options
+const parsed = await jsonParser.parse(jsonContent, {
+  allowComments: true,        // Allow // and /* */ comments
+  allowTrailingCommas: true  // Allow trailing commas
+});
+
+// Or repair common issues
+const repaired = jsonContent
+  .replace(/^\uFEFF/, '')     // Remove BOM
+  .replace(/,(\s*[}\]])/g, '$1'); // Remove trailing commas
+
+const parsed = await jsonParser.parse(repaired);
+```
+
+#### Error: "Cannot parse nested data"
+
+**Cause:** Accessing deeply nested properties incorrectly
+
+**Solution:**
+```typescript
+// Use dataPath to extract nested data
+const items = await jsonParser.parse(jsonContent, {
+  dataPath: 'response.data.inventory.items'
+});
+
+// Or use query() method
+const items = jsonParser.query(parsed, 'response.data.inventory.items');
+```
+
+#### Error: "JSONL parsing fails"
+
+**Cause:** Not setting jsonLines option
+
+**Solution:**
+```typescript
+// Ensure jsonLines option is set
+for await (const item of jsonParser.parseStreaming(jsonlContent, {
+  jsonLines: true,
+  batchSize: 100
+})) {
+  await processItem(item);
+}
+```
+
+### XML Parser Errors
+
+#### Error: "Mismatched tags"
+
+**Cause:** Malformed XML structure
+
+**Solution:**
+```typescript
+// Validate first
+const validation = xmlParser.validate(xmlContent);
+
+if (!validation.valid) {
+  console.error('XML validation errors:', validation.errors);
+  // Fix XML or reject
+}
+
+// Parse with error handling
+try {
+  const parsed = await xmlParser.parse(xmlContent);
+} catch (error) {
+  console.error('Parsing failed at:', error.message);
+  // Contains line/column info
+}
+```
+
+#### Error: "Cannot access attribute"
+
+**Cause:** Incorrect path syntax or direct access
+
+**Solution:**
+```typescript
+// ❌ WRONG: Direct access
+const value = parsed.order['@id'];
+
+// ✅ CORRECT: Use XMLPathResolver
+import { XMLPathResolver } from '@fluentcommerce/fc-connect-sdk';
+const resolver = new XMLPathResolver();
+const value = resolver.resolve(parsed, 'order@id');
+```
+
+#### Error: "Namespace prefix not found"
+
+**Cause:** XML namespaces not handled
+
+**Solution:**
+```typescript
+// Option 1: Remove namespaces
+const options = {
+  removeNamespacePrefix: true
+};
+
+const parsed = await xmlParser.parse(xmlContent, options);
+
+// Option 2: Preprocess XML
+const cleanXML = xmlContent.replace(/<(\/?)\w+:/g, '<$1');
+const parsed = await xmlParser.parse(cleanXML);
+```
+
+#### Error: "Text appears as child element instead of content"
+
+**Cause:** Not using `#text` key in XML generation
+
+**Solution:**
+```typescript
+// ❌ WRONG
+const data = {
+  Color: { "@id": "9101", "text": "MULTI-COLOR" }
+};
+
+// ✅ CORRECT
+const data = {
+  Color: { "@id": "9101", "#text": "MULTI-COLOR" }
+};
+
+const xml = builder.build(data);
+```
+
+### Parquet Parser Errors
+
+#### Error: "Invalid Parquet file"
+
+**Cause:** File is corrupted or not Parquet format
+
+**Solution:**
+```typescript
+// Validate before parsing
+const validation = await parquetParser.validate(parquetBuffer, {
+  requiredColumns: ['sku', 'qty']
+});
+
+if (!validation.valid) {
+  throw new Error(`Invalid Parquet: ${validation.errors.join(', ')}`);
+}
+
+// Check file magic bytes
+const magic = parquetBuffer.slice(0, 4).toString();
+if (magic !== 'PAR1') {
+  throw new Error('Not a valid Parquet file');
+}
+```
+
+#### Error: "Column not found"
+
+**Cause:** Requesting non-existent column
+
+**Solution:**
+```typescript
+// Get available columns first
+const stats = await parquetParser.getColumnStatistics(parquetBuffer);
+const availableColumns = Object.keys(stats);
+
+console.log('Available columns:', availableColumns);
+
+// Only request existing columns
+const records = await parquetParser.parse(parquetBuffer, {
+  columns: availableColumns.filter(c => ['sku', 'qty'].includes(c))
+});
+```
+
+## Performance Optimization
+
+### 1. Choose Right Parser for File Size
+
+```typescript
+// Small files (<10MB): Parse directly
+const records = await csvParser.parse(csvContent);
+
+// Medium files (10MB-100MB): Stream with batches
+for await (const batch of csvParser.parseStreaming(csvContent, {}, 1000)) {
+  await processBatch(batch);
+}
+
+// Large files (>100MB): Stream with smaller batches + parallel processing
+for await (const batch of csvParser.parseStreaming(csvContent, {}, 500)) {
+  // Process batches in parallel (with concurrency limit)
+  await processBatchParallel(batch);
+}
+```
+
+### 2. Optimize Batch Sizes
+
+```typescript
+// Memory-constrained (Versori, Lambda): Small batches
+const batchSize = 100;
+
+// High-memory environment: Large batches
+const batchSize = 5000;
+
+// Adaptive batch size based on record complexity
+function calculateBatchSize(recordSize: number): number {
+  const targetMemory = 10 * 1024 * 1024; // 10MB target
+  return Math.floor(targetMemory / recordSize);
+}
+```
+
+### 3. Disable Unnecessary Features
+
+```typescript
+// CSV: Disable features you don't need
+const records = await csvParser.parse(csvContent, {
+  trim: false,              // Skip if data already clean
+  cast: false,              // Skip type casting
+  skip_empty_lines: false   // Process all lines
+});
+
+// JSON: Skip validation and date parsing if not needed
+const parsed = await jsonParser.parse(jsonContent, {
+  parseDates: false,
+  validateSchema: false,
+  maxDepth: 10  // Limit recursion
+});
+
+// XML: Minimal options for speed
+const parsed = await xmlParser.parse(xmlContent, {
+  includeAttributes: false,
+  parseNumbers: false,
+  normalizeWhitespace: false
+});
+```
+
+### 4. Use Streaming Effectively
+
+```typescript
+// Process as you stream (don't accumulate)
+async function efficientStreaming(csvContent: string) {
+  const csvParser = new CSVParserService();
+
+  for await (const batch of csvParser.parseStreaming(csvContent, {}, 1000)) {
+    // Transform and send immediately
+    const mapper = new UniversalMapper(mappingConfig);
+    const result = await mapper.map(batch);
+
+    await sendToFluent(result.data);
+
+    // Don't store results - free memory immediately
+  }
+}
+```
+
+### 5. Parallel Processing
+
+```typescript
+import pLimit from 'p-limit';
+
+async function parallelProcessing(csvFiles: string[]) {
+  const limit = pLimit(5); // Max 5 concurrent
+
+  const promises = csvFiles.map(file =>
+    limit(async () => {
+      const csvParser = new CSVParserService();
+      const records = await csvParser.parse(file);
+      return processRecords(records);
+    })
+  );
+
+  const results = await Promise.all(promises);
+  return results.flat();
+}
+```
+
+## Handling Edge Cases
+
+### Empty Files
+
+```typescript
+async function handleEmptyFile(csvContent: string) {
+  const csvParser = new CSVParserService();
+  const records = await csvParser.parse(csvContent);
+
+  if (records.length === 0) {
+    console.warn('Empty file - no records to process');
+    return;
+  }
+
+  // Process records
+}
+```
+
+### Malformed Data
+
+```typescript
+async function handleMalformedData(csvContent: string) {
+  const csvParser = new CSVParserService();
+  const records = await csvParser.parse(csvContent, {
+    relax_column_count: true,  // Allow inconsistent columns
+    skip_empty_lines: true,    // Skip empty lines
+    on_record: (record, { lines }) => {
+      // Validate each record
+      if (!record.sku || !record.qty) {
+        console.warn(`Skipping invalid record at line ${lines}`);
+        return null; // Skip this record
+      }
+      return record;
+    }
+  });
+
+  console.log(`Parsed ${records.length} valid records`);
+}
+```
+
+### Encoding Issues
+
+```typescript
+// Handle different encodings
+import iconv from 'iconv-lite';
+
+// Detect and convert encoding
+function convertEncoding(buffer: Buffer): string {
+  // Try UTF-8 first
+  try {
+    return buffer.toString('utf-8');
+  } catch (error) {
+    // Try Latin1
+    return iconv.decode(buffer, 'latin1');
+  }
+}
+
+const csvContent = convertEncoding(fileBuffer);
+const records = await csvParser.parse(csvContent);
+```
+
+### Special Characters
+
+```typescript
+// Handle special characters in CSV
+const records = await csvParser.parse(csvContent, {
+  quote: '"',      // Quote character
+  escape: '\\',    // Escape character
+  ltrim: true,     // Trim left
+  rtrim: true      // Trim right
+});
+```
+
+## Monitoring and Logging
+
+### Progress Tracking
+
+```typescript
+async function parseWithProgress(csvContent: string) {
+  const csvParser = new CSVParserService();
+  const startTime = Date.now();
+  let recordCount = 0;
+
+  for await (const batch of csvParser.parseStreaming(csvContent, {}, 1000)) {
+    recordCount += batch.length;
+
+    // Log progress
+    const elapsed = (Date.now() - startTime) / 1000;
+    const rate = recordCount / elapsed;
+
+    console.log({
+      recordsProcessed: recordCount,
+      elapsedSeconds: elapsed.toFixed(2),
+      recordsPerSecond: rate.toFixed(2)
+    });
+
+    await processBatch(batch);
+  }
+}
+```
+
+### Error Logging
+
+```typescript
+import { FileParsingError } from '@fluentcommerce/fc-connect-sdk';
+
+async function parseWithLogging(csvContent: string) {
+  const csvParser = new CSVParserService();
+
+  try {
+    const records = await csvParser.parse(csvContent);
+    console.log({
+      status: 'success',
+      recordCount: records.length
+    });
+
+  } catch (error) {
+    if (error instanceof FileParsingError) {
+      console.error({
+        status: 'error',
+        type: 'parsing_error',
+        message: error.message,
+        fileName: error.fileName,
+        context: error.context
+      });
+    } else {
+      console.error({
+        status: 'error',
+        type: 'unknown_error',
+        message: error.message,
+        stack: error.stack
+      });
+    }
+
+    throw error;
+  }
+}
+```
+
+### Performance Metrics
+
+```typescript
+interface ParsingMetrics {
+  startTime: number;
+  endTime: number;
+  recordCount: number;
+  fileSize: number;
+  recordsPerSecond: number;
+  bytesPerSecond: number;
+}
+
+async function parseWithMetrics(csvContent: string): Promise<ParsingMetrics> {
+  const csvParser = new CSVParserService();
+  const startTime = Date.now();
+  const fileSize = Buffer.byteLength(csvContent);
+
+  const records = await csvParser.parse(csvContent);
+
+  const endTime = Date.now();
+  const elapsed = (endTime - startTime) / 1000;
+
+  const metrics: ParsingMetrics = {
+    startTime,
+    endTime,
+    recordCount: records.length,
+    fileSize,
+    recordsPerSecond: records.length / elapsed,
+    bytesPerSecond: fileSize / elapsed
+  };
+
+  console.log('Parsing metrics:', metrics);
+  return metrics;
+}
+```
+
+## Recovery Strategies
+
+### Retry Logic
+
+```typescript
+async function parseWithRetry(
+  csvContent: string,
+  maxRetries: number = 3
+): Promise<any[]> {
+  const csvParser = new CSVParserService();
+  let lastError: Error;
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await csvParser.parse(csvContent);
+    } catch (error) {
+      lastError = error;
+      console.warn(`Parse attempt ${attempt} failed:`, error.message);
+
+      if (attempt < maxRetries) {
+        // Wait before retry (exponential backoff)
+        const delay = Math.pow(2, attempt) * 1000;
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  throw new Error(`Parsing failed after ${maxRetries} attempts: ${lastError.message}`);
+}
+```
+
+### Fallback Parsing
+
+```typescript
+async function parseWithFallback(csvContent: string) {
+  const csvParser = new CSVParserService();
+
+  // Try standard parsing
+  try {
+    return await csvParser.parse(csvContent);
+  } catch (error) {
+    console.warn('Standard parsing failed, trying relaxed options');
+  }
+
+  // Try with relaxed options
+  try {
+    return await csvParser.parse(csvContent, {
+      relax_column_count: true,
+      skip_empty_lines: true,
+      trim: true
+    });
+  } catch (error) {
+    console.warn('Relaxed parsing failed, trying alternative delimiter');
+  }
+
+  // Try alternative delimiter
+  try {
+    return await csvParser.parse(csvContent, {
+      delimiter: ';',
+      relax_column_count: true
+    });
+  } catch (error) {
+    throw new Error('All parsing strategies failed');
+  }
+}
+```
+
+### Partial Success
+
+```typescript
+async function parseWithPartialSuccess(csvContent: string) {
+  const csvParser = new CSVParserService();
+  const successfulRecords = [];
+  const failedRecords = [];
+
+  // Process line by line
+  const lines = csvContent.split('\n');
+  const headers = lines[0].split(',');
+
+  for (let i = 1; i < lines.length; i++) {
+    try {
+      const values = lines[i].split(',');
+      const record = Object.fromEntries(
+        headers.map((h, idx) => [h, values[idx]])
+      );
+
+      // Validate record
+      if (record.sku && record.qty) {
+        successfulRecords.push(record);
+      } else {
+        failedRecords.push({ line: i + 1, reason: 'Missing required fields' });
+      }
+    } catch (error) {
+      failedRecords.push({ line: i + 1, reason: error.message });
+    }
+  }
+
+  console.log({
+    successful: successfulRecords.length,
+    failed: failedRecords.length
+  });
+
+  if (failedRecords.length > 0) {
+    console.warn('Failed records:', failedRecords);
+  }
+
+  return successfulRecords;
+}
+```
+
+## Debugging Tips
+
+### 1. Enable Verbose Logging
+
+```typescript
+// Log each step
+async function parseWithDebugLogging(csvContent: string) {
+  console.log('1. Starting CSV parsing');
+  console.log('File size:', Buffer.byteLength(csvContent), 'bytes');
+
+  const csvParser = new CSVParserService();
+
+  console.log('2. Parsing CSV');
+  const records = await csvParser.parse(csvContent);
+
+  console.log('3. Parsed records:', records.length);
+  console.log('First record:', records[0]);
+  console.log('Last record:', records[records.length - 1]);
+
+  return records;
+}
+```
+
+### 2. Inspect Parsed Structure
+
+```typescript
+// Pretty-print parsed data
+const parsed = await jsonParser.parse(jsonContent);
+console.log(JSON.stringify(parsed, null, 2));
+
+// Or use util.inspect for better formatting
+import util from 'util';
+console.log(util.inspect(parsed, { depth: null, colors: true }));
+```
+
+### 3. Test with Sample Data
+
+```typescript
+// Test with small sample first
+const sampleCsv = csvContent.split('\n').slice(0, 10).join('\n');
+const sampleRecords = await csvParser.parse(sampleCsv);
+
+console.log('Sample parsing successful:', sampleRecords);
+
+// If sample works, try full file
+const allRecords = await csvParser.parse(csvContent);
+```
+
+## Common Patterns Summary
+
+| Issue | Solution |
+|-------|----------|
+| Memory issues | Use streaming with batches |
+| Malformed data | Use relaxed options + validation |
+| Wrong delimiter | Try different delimiters |
+| Encoding issues | Convert encoding before parsing |
+| Slow parsing | Disable unnecessary features |
+| Partial failures | Process line-by-line with error handling |
+| Nested data | Use dataPath or query() |
+| XML attributes | Use XMLPathResolver |
+| Large files | Stream + parallel processing |
+
+## Key Takeaways
+
+- 🎯 Always validate input before parsing
+- 🎯 Use streaming for files >10MB
+- 🎯 Optimize batch sizes for your environment
+- 🎯 Implement retry logic for transient failures
+- 🎯 Log metrics for performance monitoring
+- 🎯 Handle partial failures gracefully
+- 🎯 Test with sample data first
+
+## Practice Exercise
+
+**Challenge:** Build a robust parser that handles all edge cases:
+
+**Requirements:**
+1. Accept CSV, JSON, or XML input
+2. Detect and handle malformed data
+3. Stream large files efficiently
+4. Log progress and errors
+5. Implement retry logic
+6. Return both successful and failed records
+
+**Solution:** See [Parser Examples](../examples/)
+
+---
+
+**Module 7 Complete!** ✅
+
+You've completed the Parser Services Learning Path! 🎉
+
+**Next Steps:**
+- Review [Quick Reference](../../advanced-services/advanced-services-quick-reference.md) for quick lookups
+- Explore [Examples](../examples/) for copy-paste code
+- Check [Universal Mapping Guide](../../mapping/) for transformations
+- See [Auto-Pagination Guide](../../auto-pagination/) for data extraction