npm - @fluentcommerce/fc-connect-sdk - Versions diffs - 0.1.54 → 0.1.56 - Mend

@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (476) hide show

package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-07-parsers.md CHANGED Viewed

@@ -1,1097 +1,1097 @@
-# Module 07: Parsers
-**Level:** Beginner to Intermediate
-**Category:** Data Processing
-## Overview
-Parsers convert raw data formats (CSV, JSON, XML, Parquet) into JavaScript objects. The SDK provides robust parsers with streaming support, validation, and format-specific optimizations for processing data from various sources.
-## Table of Contents
-- [CSV Parser](#csv-parser)
-- [JSON Parser Service](#json-parser-service)
-  - [parse Method](#parse)
-  - [parseStreaming Method](#parsestreaming)
-  - [parseMultiple Method](#parsemultiple)
-  - [validate Method](#validate)
-  - [query Method](#query)
-  - [stringify Method](#stringify)
-- [XML Parser Service](#xml-parser-service)
-  - [parse Method](#parse-1)
-  - [parseSync Method](#parsesync)
-  - [parseStreaming Method](#parsestreaming-1)
-  - [parseWithSelector Method](#parsewithselector)
-  - [validate Method](#validate-1)
-  - [build Method](#build)
-- [XMLBuilder](#xmlbuilder)
-  - [Understanding @ and #text Pattern](#understanding-the-and-text-pattern)
-  - [Constructor](#constructor)
-  - [build Method](#build-method)
-  - [Pattern Examples](#pattern-examples)
-- [Parquet Parser Service](#parquet-parser-service)
-  - [parse Method](#parse-2)
-  - [parseStreaming Method](#parsestreaming-2)
-  - [validateFile Method](#validatefile)
-  - [getPerformanceMetrics Method](#getperformancemetrics)
-  - [resetMetrics Method](#resetmetrics)
-- [Parser Comparison](#parser-comparison)
-- [See Also](#see-also)
----
-## CSV Parser
-Parse CSV files with eager and streaming APIs. Defaults: `columns=true`, `skip_empty_lines=true`, `trim=true`.
-```typescript
-import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
-const parser = new CSVParserService();
-// Eager parse from string
-const records = await parser.parse(csvString);
-// Streaming from string (per record)
-for await (const rec of parser.parseStreaming(csvString)) {
-  // rec is a single record
-}
-// Streaming from string (batches)
-for await (const batch of parser.parseStreaming(csvString, {}, 100)) {
-  // batch is an array of up to 100 records
-}
-// Eager parse from Node stream
-const stream = fs.createReadStream('file.csv');
-const fromStream = await parser.parseStream(stream);
-// Streaming from Node stream
-for await (const rec of parser.parseStreamStreaming(stream)) {
-  // consume records one by one
-}
-// Parse with custom headers
-const withHeaders = await parser.parseWithHeaders(csvString, ['sku', 'qty', 'location']);
-// Parse and transform
-const transformed = await parser.parseAndTransform(csvString, r => ({ ...r, qty: Number(r.qty) }));
-// Stringify back to CSV
-const csvOut = parser.stringify(transformed, { headers: true, delimiter: ',' });
-// Validate structure
-const validation = await parser.validate(csvString, {
-  requiredColumns: ['sku', 'qty'],
-  columnTypes: { qty: 'number' },
-  minRows: 1,
-});
-```
-Key options (internal defaults via csv-parse):
-- `columns: true` (previously shown as headers)
-- `skip_empty_lines: true` (previously shown as skipEmptyLines)
-- `trim: true`
-## JSON Parser Service
-Parse JSON, JSONL, and stream large JSON files with validation support.
-```typescript
-import { JSONParserService } from '@fluentcommerce/fc-connect-sdk';
-const parser = new JSONParserService();
-// Parse standard JSON
-const data = await parser.parse(jsonString);
-// Parse with type safety
-interface Product {
-  sku: string;
-  name: string;
-  price: number;
-}
-const products = await parser.parse<Product[]>(jsonString);
-// Parse with options
-const parsed = await parser.parse(jsonString, {
-  parseDates: true,
-  dataPath: 'response.data.items',
-  validateSchema: true,
-  schema: productSchema,
-});
-// Stream JSONL (JSON Lines)
-for await (const item of parser.parseStreaming(jsonlContent, {
-  jsonLines: true,
-  batchSize: 100,
-})) {
-  console.log('Processing batch:', item);
-}
-```
-**Methods:**
-### parse
-Parse JSON string with optional validation and transformation.
-```typescript
-async parse<T = Record<string, unknown>>(
-  jsonContent: string,
-  options?: JSONParseOptions
-): Promise<T>
-```
-**Example:**
-```typescript
-// Parse simple JSON
-const data = await parser.parse('{"sku":"PROD-001","qty":100}');
-// Parse with validation (enable via options)
-const validated = await parser.parse(jsonString, {
-  validateSchema: true,
-  schema: {
-    type: 'object',
-    properties: {
-      sku: { type: 'string' },
-      qty: { type: 'number' },
-    },
-    required: ['sku', 'qty'],
-  },
-});
-```
-### parseStreaming
-Stream parse JSON or JSONL for memory efficiency.
-```typescript
-async *parseStreaming<T = Record<string, unknown>>(
-  jsonContent: string | Readable,
-  options?: JSONStreamOptions
-): AsyncGenerator<T | T[], void, unknown>
-```
-**Example - JSONL (JSON Lines):**
-```typescript
-// Parse JSONL content using parseStreaming with jsonLines option
-const jsonlContent = `{"sku":"PROD-001","qty":100}\n{"sku":"PROD-002","qty":200}`;
-for await (const item of parser.parseStreaming(jsonlContent, {
-  jsonLines: true,
-  batchSize: 1,
-})) {
-  console.log('Parsed item:', item);
-}
-```
-### validate
-Validate JSON structure and syntax.
-```typescript
-validate(
-  jsonContent: string,
-  options?: JSONParseOptions
-): JSONValidationResult
-```
-### parseMultiple
-Parse an array of JSON objects.
-```typescript
-async parseMultiple<T = Record<string, unknown>>(
-  jsonArray: unknown[],
-  options?: JSONParseOptions
-): Promise<T[]>
-```
-### query
-Query JSON data using JSONPath-like syntax.
-```typescript
-query(data: unknown, path: string): unknown
-```
-### stringify
-Convert JavaScript object to JSON string.
-```typescript
-stringify(
-  data: unknown,
-  options?: {
-    pretty?: boolean;
-    indent?: number | string;
-    replacer?: (key: string, value: unknown) => unknown;
-    sortKeys?: boolean;
-  }
-): string
-```
-**Options (JSONParseOptions):**
-- `maxDepth?: number` - Maximum nesting depth
-- `parseDates?: boolean` - Auto-parse date strings
-- `dateFormats?: string[]` - Custom date formats
-- `validateSchema?: boolean` - Enable schema validation
-- `schema?: Record<string, unknown>` - JSON schema
-- `dataPath?: string` - Path to extract data from
-- `jsonLines?: boolean` - Handle JSONL format
-- `reviver?: (key: string, value: unknown) => unknown` - Custom reviver
-- `allowComments?: boolean` - Allow // and /\* \*/ comments
-- `allowTrailingCommas?: boolean` - Allow trailing commas
-## XML Parser Service
-Parse XML files with streaming support, validation, and XPath-like selectors.
-```typescript
-import { XMLParserService } from '@fluentcommerce/fc-connect-sdk';
-const parser = new XMLParserService();
-// Parse XML string
-const data = await parser.parse(xmlString);
-// Parse with options
-const parsed = await parser.parse(xmlString, {
-  lowercaseKeys: true,
-  parseNumbers: true,
-  includeAttributes: true,
-  attributePrefix: '@',
-});
-// Stream large XML files
-for await (const item of parser.parseStreaming(xmlContent, {
-  itemPath: '//product',
-})) {
-  console.log('Processing product:', item);
-}
-// Use XPath-like selectors
-const products = await parser.parseWithSelector(xmlContent, '//catalog/product');
-// Convert object to XML
-const xmlString = parser.stringify(data, {
-  rootElement: 'catalog',
-  indent: '  ',
-  declaration: true,
-});
-```
-**Methods:**
-### parse
-Parse XML string to JavaScript object (async).
-```typescript
-async parse(
-  xmlContent: string,
-  options?: XMLParseOptions
-): Promise<Record<string, unknown>>
-```
-**Example:**
-```typescript
-// Parse simple XML
-const xmlContent = `
-  <inventory>
-    <item>
-      <sku>PROD-001</sku>
-      <qty>100</qty>
-    </item>
-  </inventory>
-`;
-const data = await parser.parse(xmlContent);
-console.log(data.inventory.item.sku); // 'PROD-001'
-// Parse with options
-const parsed = await parser.parse(xmlContent, {
-  parseNumbers: true, // qty becomes number 100
-  lowercaseKeys: true, // SKU becomes sku
-  includeAttributes: true, // Include XML attributes
-  attributePrefix: '@', // Prefix for attributes
-});
-```
-### parseSync
-Parse XML string to JavaScript object synchronously.
-```typescript
-parseSync(
-  xmlContent: string,
-  options?: XMLParseOptions
-): Record<string, unknown>
-```
-**Description:**
-Identical to `parse()` but returns synchronously. Used internally by `XMLPathResolver` when auto-parsing raw XML strings. Useful when working in non-async contexts or when integrating with synchronous code paths.
-**Attributes Format:**
-- Returns @-prefixed attributes by default: `{ order: { "@id": "123" } }`
-- When `includeAttributes: true`, attributes are accessible via `@` prefix
-- XMLPathResolver automatically handles both @-prefix and $-object attribute formats
-**Example:**
-```typescript
-// Basic synchronous parsing
-const xml = '<order id="123"><customer>John</customer></order>';
-const data = parser.parseSync(xml, { includeAttributes: true });
-console.log(data.order['@id']); // '123'
-console.log(data.order.customer); // 'John'
-// With XMLPathResolver (handles both formats)
-import { XMLPathResolver } from '@fluentcommerce/fc-connect-sdk';
-const resolver = new XMLPathResolver();
-// Works with raw XML (auto-parsed via parseSync)
-const orderId = resolver.resolve(xml, 'order@id'); // '123'
-// Also works with pre-parsed objects
-const customerId = resolver.resolve(data, 'order.customer'); // 'John'
-```
-**Use Cases:**
-- Internal SDK usage (XMLPathResolver auto-parsing)
-- Synchronous workflows where async is not available
-- Testing and debugging with immediate results
-- Integration with older synchronous code
-### parseStreaming
-Stream parse XML for large files.
-```typescript
-async *parseStreaming(
-  xmlContent: string,
-  options?: XMLParseOptions & { itemPath?: string }
-): AsyncGenerator<Record<string, unknown>, void, unknown>
-```
-### parseWithSelector
-Parse specific elements using XPath-like selectors.
-```typescript
-async parseWithSelector(
-  xmlContent: string,
-  selector: string,
-  options?: XMLParseOptions
-): Promise<unknown[]>
-```
-### validate
-Validate XML structure.
-```typescript
-validate(xmlContent: string): {
-  valid: boolean;
-  errors: string[];
-}
-```
-### build
-Convert JavaScript object to XML string.
-```typescript
-build(
-  data: Record<string, unknown>,
-  options?: {
-    format?: boolean;
-    indentBy?: string;
-    declaration?: boolean;
-    rootElement?: string;
-  }
-): string
-```
-**Example:**
-```typescript
-// Build XML from object
-const xmlString = parser.build(
-  {
-    inventory: {
-      item: [
-        { sku: 'PROD-001', qty: 100 },
-        { sku: 'PROD-002', qty: 200 },
-      ],
-    },
-  },
-  {
-    format: true,
-    indentBy: '  ',
-    declaration: true,
-  }
-);
-console.log(xmlString);
-// <?xml version="1.0" encoding="UTF-8"?>
-// <inventory>
-//   <item>
-//     <sku>PROD-001</sku>
-//     <qty>100</qty>
-//   </item>
-//   <item>
-//     <sku>PROD-002</sku>
-//     <qty>200</qty>
-//   </item>
-// </inventory>
-```
-**Options (XMLParseOptions):**
-- `lowercaseKeys?: boolean` - Convert element names to lowercase
-- `normalizeWhitespace?: boolean` - Normalize whitespace in text
-- `parseNumbers?: boolean` - Auto-parse numeric values
-- `parseBooleans?: boolean` - Auto-parse boolean values
-- `rootElement?: string` - Root element to start from
-- `arrayElements?: string[]` - Elements to treat as arrays
-- `includeAttributes?: boolean` - Include XML attributes
-- `attributePrefix?: string` - Prefix for attributes (default: '@')
-- `textKey?: string` - Key for text content (default: '#text')
-- `maxDepth?: number` - Maximum parsing depth (default: 100)
-## XMLBuilder
-Generate XML from JavaScript objects with support for attributes, text content, and complex nested structures.
-```typescript
-import { XMLBuilder } from '@fluentcommerce/fc-connect-sdk';
-const builder = new XMLBuilder({
-  xmlDeclaration: true,
-  prettyPrint: true,
-  encoding: 'UTF-8',
-});
-// Generate XML
-const xml = builder.build(data, 'OrderDetailResponse');
-```
-### Understanding the `@` and `#text` Pattern
-XMLBuilder uses special keys to represent XML structures in JSON:
-| JSON Key    | XML Output    | Example                             |
-| ----------- | ------------- | ----------------------------------- |
-| `@prefix`   | Attribute     | `"@id": "123"` → `<Order id="123">` |
-| `#text`     | Text content  | `"#text": "Value"` → Element text   |
-| `fieldName` | Child element | `"Customer": {...}` → `<Customer>`  |
-**When to use `#text`:** Use it when an XML element has **BOTH attributes AND text content** (mixed content).
-### Constructor
-```typescript
-new XMLBuilder(options?: XMLBuildOptions)
-```
-**Options:**
-```typescript
-interface XMLBuildOptions {
-  rootElement?: string; // Root element name (default: 'root')
-  xmlDeclaration?: boolean; // Add <?xml version="1.0"?> (default: true)
-  prettyPrint?: boolean; // Format with indentation (default: true)
-  indent?: string; // Indentation string (default: '  ')
-  attributePrefix?: string; // Attribute prefix (default: '@')
-  textKey?: string; // Text content key (default: '#text')
-  cdataKeys?: string[]; // Fields to wrap in CDATA
-  encoding?: string; // Character encoding (default: 'UTF-8')
-}
-```
-### build Method
-Generate XML from JavaScript object.
-```typescript
-build(
-  data: Record<string, unknown>,
-  rootElement?: string
-): string
-```
-### Pattern Examples
-#### Pattern 1: Simple Text Element
-```typescript
-const data = { ItemId: 'SKU001' };
-builder.build(data, 'Order');
-// Output:
-// <Order>
-//   <ItemId>SKU001</ItemId>
-// </Order>
-```
-#### Pattern 2: Attributes Only
-```typescript
-const data = {
-  Order: {
-    '@id': '12345',
-    '@status': 'confirmed',
-  },
-};
-builder.build(data);
-// Output:
-// <Order id="12345" status="confirmed"/>
-```
-#### Pattern 3: Attributes + Text Content (Using `#text`)
-```typescript
-const data = {
-  Color: {
-    '@id': '9101',
-    '#text': 'MULTI-COLOR',
-  },
-};
-builder.build(data, 'Product');
-// Output:
-// <Product>
-//   <Color id="9101">MULTI-COLOR</Color>
-// </Product>
-```
-**Why `#text`?** This is the standard convention used by XML parsers (like `fast-xml-parser`) to represent text content in JSON. The SDK follows the same convention for consistency.
-#### Pattern 4: Complex Nested Structure
-```typescript
-const data = {
-  Order: {
-    '@customerOrderId': '12345',
-    '@levelOfService': 'REGULAR',
-    Customer: {
-      '@customerId': '232',
-      Name: {
-        FirstName: 'John',
-        LastName: 'Doe',
-      },
-      EmailAddress: 'john@example.com',
-    },
-    OrderSource: {
-      '@type': 'source',
-      '#text': 'WEBSTORE',
-    },
-    OrderItems: {
-      OrderItem: [
-        {
-          '@id': 'item1',
-          ItemId: 'SKU001',
-          Quantity: 2,
-          Description: {
-            Color: {
-              '@id': '9101',
-              '#text': 'Black',
-            },
-            Size: {
-              '@id': 'M',
-              '#text': 'Medium',
-            },
-          },
-        },
-      ],
-    },
-  },
-};
-const xml = builder.build(data, 'OrderDetailResponse');
-// Output:
-// <?xml version="1.0" encoding="UTF-8"?>
-// <OrderDetailResponse>
-//   <Order customerOrderId="12345" levelOfService="REGULAR">
-//     <Customer customerId="232">
-//       <Name>
-//         <FirstName>John</FirstName>
-//         <LastName>Doe</LastName>
-//       </Name>
-//       <EmailAddress>john@example.com</EmailAddress>
-//     </Customer>
-//     <OrderSource type="source">WEBSTORE</OrderSource>
-//     <OrderItems>
-//       <OrderItem id="item1">
-//         <ItemId>SKU001</ItemId>
-//         <Quantity>2</Quantity>
-//         <Description>
-//           <Color id="9101">Black</Color>
-//           <Size id="M">Medium</Size>
-//         </Description>
-//       </OrderItem>
-//     </OrderItems>
-//   </Order>
-// </OrderDetailResponse>
-```
-#### Pattern 5: Arrays (Repeated Elements)
-```typescript
-const data = {
-  OrderItems: {
-    OrderItem: [
-      { ItemId: 'SKU001', Quantity: 2 },
-      { ItemId: 'SKU002', Quantity: 1 },
-    ],
-  },
-};
-// Output:
-// <OrderItems>
-//   <OrderItem>
-//     <ItemId>SKU001</ItemId>
-//     <Quantity>2</Quantity>
-//   </OrderItem>
-//   <OrderItem>
-//     <ItemId>SKU002</ItemId>
-//     <Quantity>1</Quantity>
-//   </OrderItem>
-// </OrderItems>
-```
-#### Decision Tree: When to Use `#text`
-```
-Does the element have attributes?
-├─ NO  → Just use field name
-│       "ItemId": "SKU001"
-│       Result: <ItemId>SKU001</ItemId>
-│
-└─ YES → Does it also have text content?
-    ├─ NO  → Just use @prefix
-    │        "@id": "123"
-    │        Result: <Order id="123"/>
-    │
-    └─ YES → Use BOTH @prefix AND #text
-             "@id": "9101", "#text": "MULTI-COLOR"
-             Result: <Color id="9101">MULTI-COLOR</Color>
-```
-#### Common Issues and Solutions
-**Issue: Text appears as child element**
-```typescript
-// ❌ Wrong - creates <text> element
-"Color": { "@id": "9101", "text": "MULTI-COLOR" }
-// ✅ Correct - creates text content
-"Color": { "@id": "9101", "#text": "MULTI-COLOR" }
-```
-**Issue: Attributes not showing**
-```typescript
-// ❌ Wrong - 'id' becomes child element
-"Color": { "id": "9101", "#text": "MULTI-COLOR" }
-// ✅ Correct - @ prefix makes it an attribute
-"Color": { "@id": "9101", "#text": "MULTI-COLOR" }
-```
-**Issue: Self-closing tag when content expected**
-```typescript
-// ❌ Wrong - empty or undefined value
-"Description": { "#text": undefined }  // → <Description/>
-// ✅ Correct - provide actual value
-"Description": { "#text": product?.description || '' }
-```
-#### Real-World Example: Fluent → SFCC Order Export
-```typescript
-// Fluent Commerce order data
-const fluentOrder = await fluentClient.graphql({
-  query: orderQuery,
-  variables: { ref: orderId },
-});
-// Map to SFCC XML structure using UniversalMapper
-const mapper = new UniversalMapper(mappingConfig, {
-  customResolvers: extractionResolvers,
-});
-const mapped = await mapper.map(fluentOrder);
-// Generate XML
-const builder = new XMLBuilder({
-  xmlDeclaration: true,
-  prettyPrint: true,
-  encoding: 'UTF-8',
-});
-const sfccXml = builder.build(mapped.data, 'OrderDetailResponse');
-// Returns valid SFCC XML ready to send
-console.log(sfccXml);
-```
-## Parquet Parser Service
-**FULLY FUNCTIONAL**: The ParquetParserService is now **FULLY IMPLEMENTED** and ready for use, powered by the high-performance `hyparquet` library. It provides complete Parquet file parsing with streaming support, validation, and detailed statistics.
-**Large File Testing Support**: The SDK includes complete test files for performance validation:
-- **Small**: 3KB files for unit testing
-- **Medium**: 170KB files for integration testing
-- **Large**: 1.7MB files for standard processing
-- **50K Records**: 8.5MB files with 50,000 records
-- **100K Records**: 17MB files with 100,000 records
-- **250K Records**: 43MB files with 250,000 records
-- **500K Records**: 85MB files with 500,000 records
-- **1M Records**: 169MB files with 1,000,000 records
-```typescript
-import {
-  ParquetParserService,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-const logger = toStructuredLogger(createConsoleLogger(), {
-  logLevel: 'info'
-});
-const parser = new ParquetParserService(logger, {
-  batchSize: 1000,
-  maxFileSize: 100 * 1024 * 1024, // 100MB
-  enableStreaming: true,
-  validation: {
-    enabled: true,
-    requiredColumns: ['productRef', 'qty'],
-    columnTypes: {
-      productRef: 'string',
-      qty: 'int32',
-    },
-  },
-});
-// Parse Parquet file - FULLY WORKING
-const { records, stats } = await parser.parse(arrayBuffer, 'inventory.parquet');
-console.log(`Parsed ${stats.totalRecords} records`);
-console.log(`Processing time: ${stats.processingTimeMs}ms`);
-console.log(`Records per second: ${stats.recordsPerSecond}`);
-// Parse large files (e.g., 500K records)
-const largeBuffer = await fs.readFile('inventory-position-500k.parquet');
-const largeArrayBuffer = largeBuffer.buffer.slice(
-  largeBuffer.byteOffset,
-  largeBuffer.byteOffset + largeBuffer.byteLength
-);
-const { records: largeRecords, stats: largeStats } = await parser.parse(
-  largeArrayBuffer,
-  'inventory-position-500k.parquet',
-  {
-    batchSize: 10000, // Larger batch size for performance
-    validation: {
-      enabled: false, // Disable validation for speed
-    },
-  }
-);
-console.log(`Processed ${largeStats.totalRecords} records in ${largeStats.processingTimeMs}ms`);
-console.log(`Throughput: ${largeStats.recordsPerSecond} records/sec`);
-// Stream massive files (1M+ records)
-const streamResult = await parser.parseStreaming(massiveArrayBuffer, 'mixed-positions-1m.parquet');
-for await (const batch of streamResult.records) {
-  console.log(`Processing batch of ${batch.length} records`);
-}
-```
-**Constructor:**
-```typescript
-constructor(
-  logger: StructuredLogger,
-  options?: ParquetParsingOptions
-)
-```
-**Methods:**
-### parse
-Parse a complete Parquet file into memory. Fully functional with hyparquet.
-```typescript
-async parse(
-  arrayBuffer: ArrayBuffer,
-  fileName: string,
-  options?: Partial<ParquetParsingOptions>
-): Promise<{
-  records: ParquetDataRecord[];
-  stats: ParquetParsingStats;
-}>
-```
-**Parameters:**
-- `arrayBuffer: ArrayBuffer` - The Parquet file data as ArrayBuffer
-- `fileName: string` - Name of the file being parsed (for logging)
-- `options?: Partial<ParquetParsingOptions>` - Optional parsing configuration
-**Returns:**
-- `records: ParquetDataRecord[]` - Array of parsed records
-- `stats: ParquetParsingStats` - Detailed parsing statistics
-**Example:**
-```typescript
-const buffer = await fs.readFile('data.parquet');
-const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
-const { records, stats } = await parser.parse(arrayBuffer, 'data.parquet', {
-  batchSize: 500,
-  validation: {
-    enabled: true,
-    requiredColumns: ['id', 'name', 'qty'],
-  },
-});
-// Check validation results
-if (stats.validation && !stats.validation.isValid) {
-  console.error('Validation errors:', stats.validation.errors);
-}
-```
-### parseStreaming
-Parse Parquet file with streaming support for memory-efficient processing of large files.
-```typescript
-async parseStreaming(
-  arrayBuffer: ArrayBuffer,
-  fileName: string,
-  options?: Partial<ParquetParsingOptions>
-): Promise<ParquetStreamingResult>
-```
-**Parameters:**
-- `arrayBuffer: ArrayBuffer` - The Parquet file data
-- `fileName: string` - Name of the file being parsed
-- `options?: Partial<ParquetParsingOptions>` - Optional configuration
-**Returns:**
-- `records: AsyncIterable<ParquetDataRecord[]>` - Async iterator of record batches
-- `stats: Promise<ParquetParsingStats>` - Promise resolving to final statistics
-- `cancel: () => void` - Function to cancel streaming
-**Example:**
-```typescript
-const streamResult = await parser.parseStreaming(arrayBuffer, 'large_dataset.parquet', {
-  batchSize: 1000,
-});
-// Process batches as they stream
-for await (const batch of streamResult.records) {
-  for (const record of batch) {
-    await processRecord(record);
-  }
-}
-// Get final statistics
-const stats = await streamResult.stats;
-console.log(`Total records: ${stats.totalRecords}`);
-// Cancel if needed
-setTimeout(() => streamResult.cancel(), 5000);
-```
-### validateFile
-Validate a Parquet file before parsing.
-```typescript
-async validateFile(
-  arrayBuffer: ArrayBuffer,
-  fileName: string
-): Promise<ValidationResult>
-```
-**Parameters:**
-- `arrayBuffer: ArrayBuffer` - The Parquet file data
-- `fileName: string` - Name of the file
-**Returns:**
-- `ValidationResult` - Validation results with errors and warnings
-**Example:**
-```typescript
-const validation = await parser.validateFile(arrayBuffer, 'data.parquet');
-if (!validation.isValid) {
-  console.error('File validation failed:');
-  validation.errors.forEach(error => {
-    console.error(`- ${error.field}: ${error.message}`);
-  });
-}
-```
-### getPerformanceMetrics
-Get current performance metrics for the parser.
-```typescript
-getPerformanceMetrics(): ParquetPerformanceMetrics
-```
-**Returns:**
-- `totalRequests: number` - Total parsing requests
-- `successfulRequests: number` - Successful parses
-- `failedRequests: number` - Failed parses
-- `averageResponseTime: number` - Average parsing time (ms)
-- `lastRequestTime: Date` - Timestamp of last request
-**Example:**
-```typescript
-const metrics = parser.getPerformanceMetrics();
-console.log(
-  `Success rate: ${((metrics.successfulRequests / metrics.totalRequests) * 100).toFixed(2)}%`
-);
-console.log(`Average time: ${metrics.averageResponseTime.toFixed(2)}ms`);
-```
-### resetMetrics
-Reset performance metrics to initial state.
-```typescript
-resetMetrics(): void
-```
-**Example:**
-```typescript
-// Reset metrics after batch processing
-parser.resetMetrics();
-console.log('Performance metrics reset');
-```
-**Interfaces:**
-#### ParquetParsingOptions
-```typescript
-interface ParquetParsingOptions {
-  batchSize?: number; // Records per batch (default: 1000)
-  maxFileSize?: number; // Max file size in bytes (default: 100MB)
-  enableStreaming?: boolean; // Enable streaming mode (default: true)
-  validation?: ParquetValidationOptions;
-}
-```
-#### ParquetValidationOptions
-```typescript
-interface ParquetValidationOptions {
-  enabled?: boolean;
-  requiredColumns?: string[];
-  columnTypes?: Record<string, ParquetDataType>;
-  allowAdditionalColumns?: boolean;
-}
-```
-#### ParquetParsingStats
-```typescript
-interface ParquetParsingStats {
-  totalRecords: number;
-  processingTimeMs: number;
-  fileSizeBytes: number;
-  recordsPerSecond: number;
-  peakMemoryUsage: number;
-  batchesProcessed: number;
-  compressionRatio?: number;
-  columnStats: Record<string, ParquetColumnStatistics>;
-  validation?: ValidationResult;
-}
-```
-#### ParquetStreamingResult
-```typescript
-interface ParquetStreamingResult {
-  records: AsyncIterable<ParquetDataRecord[]>;
-  stats: Promise<ParquetParsingStats>;
-  cancel: () => void;
-}
-```
-#### ParquetDataType
-```typescript
-type ParquetDataType =
-  | 'string'
-  | 'number'
-  | 'boolean'
-  | 'date'
-  | 'int32'
-  | 'int64'
-  | 'float'
-  | 'double'
-  | 'binary';
-```
-## Parser Comparison
-| Parser                   | Streaming | Validation | Best For                          |
-| ------------------------ | --------- | ---------- | --------------------------------- |
-| **CSVParserService**     | ✅        | ✅         | Text-based tabular data           |
-| **JSONParserService**    | ✅        | ✅         | JSON/JSONL formats, API responses |
-| **XMLParserService**     | ✅        | ✅         | XML documents, SOAP APIs, SFCC    |
-| **ParquetParserService** | ✅        | ✅         | Columnar data, large datasets     |
-**Choosing a Parser:**
-- **CSV**: Simple imports, spreadsheets, EDI and B2B systems
-- **JSON**: Modern APIs, flexible schemas, nested data
-- **XML**: Enterprise systems, SOAP, SFCC orders
-- **Parquet**: Big data, analytics, data lakes
-## See Also
-- [Module 06: Data Sources](./api-reference-06-data-sources.md) - File operations
-- [Module 05: Services](./api-reference-05-services.md#universal-mapper) - Field transformations
-- [Module 10: Utilities](./api-reference-10-utilities.md) - Helper functions
-- [Parquet Guide](../../../03-PATTERN-GUIDES/parquet/parquet-readme.md) - Detailed Parquet examples
-- [XML Parser Guide](../../parsers/modules/02-core-guides-parsers-04-xml-parser.md) - XML patterns
----
-**[← Previous: Module 06 - Data Sources](./api-reference-06-data-sources.md)** | **[API Reference Home](../api-reference-readme.md)** | **[Next: Module 08 - Types →](./api-reference-08-types.md)**
+# Module 07: Parsers
+**Level:** Beginner to Intermediate
+**Category:** Data Processing
+## Overview
+Parsers convert raw data formats (CSV, JSON, XML, Parquet) into JavaScript objects. The SDK provides robust parsers with streaming support, validation, and format-specific optimizations for processing data from various sources.
+## Table of Contents
+- [CSV Parser](#csv-parser)
+- [JSON Parser Service](#json-parser-service)
+  - [parse Method](#parse)
+  - [parseStreaming Method](#parsestreaming)
+  - [parseMultiple Method](#parsemultiple)
+  - [validate Method](#validate)
+  - [query Method](#query)
+  - [stringify Method](#stringify)
+- [XML Parser Service](#xml-parser-service)
+  - [parse Method](#parse-1)
+  - [parseSync Method](#parsesync)
+  - [parseStreaming Method](#parsestreaming-1)
+  - [parseWithSelector Method](#parsewithselector)
+  - [validate Method](#validate-1)
+  - [build Method](#build)
+- [XMLBuilder](#xmlbuilder)
+  - [Understanding @ and #text Pattern](#understanding-the-and-text-pattern)
+  - [Constructor](#constructor)
+  - [build Method](#build-method)
+  - [Pattern Examples](#pattern-examples)
+- [Parquet Parser Service](#parquet-parser-service)
+  - [parse Method](#parse-2)
+  - [parseStreaming Method](#parsestreaming-2)
+  - [validateFile Method](#validatefile)
+  - [getPerformanceMetrics Method](#getperformancemetrics)
+  - [resetMetrics Method](#resetmetrics)
+- [Parser Comparison](#parser-comparison)
+- [See Also](#see-also)
+---
+## CSV Parser
+Parse CSV files with eager and streaming APIs. Defaults: `columns=true`, `skip_empty_lines=true`, `trim=true`.
+```typescript
+import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
+const parser = new CSVParserService();
+// Eager parse from string
+const records = await parser.parse(csvString);
+// Streaming from string (per record)
+for await (const rec of parser.parseStreaming(csvString)) {
+  // rec is a single record
+}
+// Streaming from string (batches)
+for await (const batch of parser.parseStreaming(csvString, {}, 100)) {
+  // batch is an array of up to 100 records
+}
+// Eager parse from Node stream
+const stream = fs.createReadStream('file.csv');
+const fromStream = await parser.parseStream(stream);
+// Streaming from Node stream
+for await (const rec of parser.parseStreamStreaming(stream)) {
+  // consume records one by one
+}
+// Parse with custom headers
+const withHeaders = await parser.parseWithHeaders(csvString, ['sku', 'qty', 'location']);
+// Parse and transform
+const transformed = await parser.parseAndTransform(csvString, r => ({ ...r, qty: Number(r.qty) }));
+// Stringify back to CSV
+const csvOut = parser.stringify(transformed, { headers: true, delimiter: ',' });
+// Validate structure
+const validation = await parser.validate(csvString, {
+  requiredColumns: ['sku', 'qty'],
+  columnTypes: { qty: 'number' },
+  minRows: 1,
+});
+```
+Key options (internal defaults via csv-parse):
+- `columns: true` (previously shown as headers)
+- `skip_empty_lines: true` (previously shown as skipEmptyLines)
+- `trim: true`
+## JSON Parser Service
+Parse JSON, JSONL, and stream large JSON files with validation support.
+```typescript
+import { JSONParserService } from '@fluentcommerce/fc-connect-sdk';
+const parser = new JSONParserService();
+// Parse standard JSON
+const data = await parser.parse(jsonString);
+// Parse with type safety
+interface Product {
+  sku: string;
+  name: string;
+  price: number;
+}
+const products = await parser.parse<Product[]>(jsonString);
+// Parse with options
+const parsed = await parser.parse(jsonString, {
+  parseDates: true,
+  dataPath: 'response.data.items',
+  validateSchema: true,
+  schema: productSchema,
+});
+// Stream JSONL (JSON Lines)
+for await (const item of parser.parseStreaming(jsonlContent, {
+  jsonLines: true,
+  batchSize: 100,
+})) {
+  console.log('Processing batch:', item);
+}
+```
+**Methods:**
+### parse
+Parse JSON string with optional validation and transformation.
+```typescript
+async parse<T = Record<string, unknown>>(
+  jsonContent: string,
+  options?: JSONParseOptions
+): Promise<T>
+```
+**Example:**
+```typescript
+// Parse simple JSON
+const data = await parser.parse('{"sku":"PROD-001","qty":100}');
+// Parse with validation (enable via options)
+const validated = await parser.parse(jsonString, {
+  validateSchema: true,
+  schema: {
+    type: 'object',
+    properties: {
+      sku: { type: 'string' },
+      qty: { type: 'number' },
+    },
+    required: ['sku', 'qty'],
+  },
+});
+```
+### parseStreaming
+Stream parse JSON or JSONL for memory efficiency.
+```typescript
+async *parseStreaming<T = Record<string, unknown>>(
+  jsonContent: string | Readable,
+  options?: JSONStreamOptions
+): AsyncGenerator<T | T[], void, unknown>
+```
+**Example - JSONL (JSON Lines):**
+```typescript
+// Parse JSONL content using parseStreaming with jsonLines option
+const jsonlContent = `{"sku":"PROD-001","qty":100}\n{"sku":"PROD-002","qty":200}`;
+for await (const item of parser.parseStreaming(jsonlContent, {
+  jsonLines: true,
+  batchSize: 1,
+})) {
+  console.log('Parsed item:', item);
+}
+```
+### validate
+Validate JSON structure and syntax.
+```typescript
+validate(
+  jsonContent: string,
+  options?: JSONParseOptions
+): JSONValidationResult
+```
+### parseMultiple
+Parse an array of JSON objects.
+```typescript
+async parseMultiple<T = Record<string, unknown>>(
+  jsonArray: unknown[],
+  options?: JSONParseOptions
+): Promise<T[]>
+```
+### query
+Query JSON data using JSONPath-like syntax.
+```typescript
+query(data: unknown, path: string): unknown
+```
+### stringify
+Convert JavaScript object to JSON string.
+```typescript
+stringify(
+  data: unknown,
+  options?: {
+    pretty?: boolean;
+    indent?: number | string;
+    replacer?: (key: string, value: unknown) => unknown;
+    sortKeys?: boolean;
+  }
+): string
+```
+**Options (JSONParseOptions):**
+- `maxDepth?: number` - Maximum nesting depth
+- `parseDates?: boolean` - Auto-parse date strings
+- `dateFormats?: string[]` - Custom date formats
+- `validateSchema?: boolean` - Enable schema validation
+- `schema?: Record<string, unknown>` - JSON schema
+- `dataPath?: string` - Path to extract data from
+- `jsonLines?: boolean` - Handle JSONL format
+- `reviver?: (key: string, value: unknown) => unknown` - Custom reviver
+- `allowComments?: boolean` - Allow // and /\* \*/ comments
+- `allowTrailingCommas?: boolean` - Allow trailing commas
+## XML Parser Service
+Parse XML files with streaming support, validation, and XPath-like selectors.
+```typescript
+import { XMLParserService } from '@fluentcommerce/fc-connect-sdk';
+const parser = new XMLParserService();
+// Parse XML string
+const data = await parser.parse(xmlString);
+// Parse with options
+const parsed = await parser.parse(xmlString, {
+  lowercaseKeys: true,
+  parseNumbers: true,
+  includeAttributes: true,
+  attributePrefix: '@',
+});
+// Stream large XML files
+for await (const item of parser.parseStreaming(xmlContent, {
+  itemPath: '//product',
+})) {
+  console.log('Processing product:', item);
+}
+// Use XPath-like selectors
+const products = await parser.parseWithSelector(xmlContent, '//catalog/product');
+// Convert object to XML
+const xmlString = parser.stringify(data, {
+  rootElement: 'catalog',
+  indent: '  ',
+  declaration: true,
+});
+```
+**Methods:**
+### parse
+Parse XML string to JavaScript object (async).
+```typescript
+async parse(
+  xmlContent: string,
+  options?: XMLParseOptions
+): Promise<Record<string, unknown>>
+```
+**Example:**
+```typescript
+// Parse simple XML
+const xmlContent = `
+  <inventory>
+    <item>
+      <sku>PROD-001</sku>
+      <qty>100</qty>
+    </item>
+  </inventory>
+`;
+const data = await parser.parse(xmlContent);
+console.log(data.inventory.item.sku); // 'PROD-001'
+// Parse with options
+const parsed = await parser.parse(xmlContent, {
+  parseNumbers: true, // qty becomes number 100
+  lowercaseKeys: true, // SKU becomes sku
+  includeAttributes: true, // Include XML attributes
+  attributePrefix: '@', // Prefix for attributes
+});
+```
+### parseSync
+Parse XML string to JavaScript object synchronously.
+```typescript
+parseSync(
+  xmlContent: string,
+  options?: XMLParseOptions
+): Record<string, unknown>
+```
+**Description:**
+Identical to `parse()` but returns synchronously. Used internally by `XMLPathResolver` when auto-parsing raw XML strings. Useful when working in non-async contexts or when integrating with synchronous code paths.
+**Attributes Format:**
+- Returns @-prefixed attributes by default: `{ order: { "@id": "123" } }`
+- When `includeAttributes: true`, attributes are accessible via `@` prefix
+- XMLPathResolver automatically handles both @-prefix and $-object attribute formats
+**Example:**
+```typescript
+// Basic synchronous parsing
+const xml = '<order id="123"><customer>John</customer></order>';
+const data = parser.parseSync(xml, { includeAttributes: true });
+console.log(data.order['@id']); // '123'
+console.log(data.order.customer); // 'John'
+// With XMLPathResolver (handles both formats)
+import { XMLPathResolver } from '@fluentcommerce/fc-connect-sdk';
+const resolver = new XMLPathResolver();
+// Works with raw XML (auto-parsed via parseSync)
+const orderId = resolver.resolve(xml, 'order@id'); // '123'
+// Also works with pre-parsed objects
+const customerId = resolver.resolve(data, 'order.customer'); // 'John'
+```
+**Use Cases:**
+- Internal SDK usage (XMLPathResolver auto-parsing)
+- Synchronous workflows where async is not available
+- Testing and debugging with immediate results
+- Integration with older synchronous code
+### parseStreaming
+Stream parse XML for large files.
+```typescript
+async *parseStreaming(
+  xmlContent: string,
+  options?: XMLParseOptions & { itemPath?: string }
+): AsyncGenerator<Record<string, unknown>, void, unknown>
+```
+### parseWithSelector
+Parse specific elements using XPath-like selectors.
+```typescript
+async parseWithSelector(
+  xmlContent: string,
+  selector: string,
+  options?: XMLParseOptions
+): Promise<unknown[]>
+```
+### validate
+Validate XML structure.
+```typescript
+validate(xmlContent: string): {
+  valid: boolean;
+  errors: string[];
+}
+```
+### build
+Convert JavaScript object to XML string.
+```typescript
+build(
+  data: Record<string, unknown>,
+  options?: {
+    format?: boolean;
+    indentBy?: string;
+    declaration?: boolean;
+    rootElement?: string;
+  }
+): string
+```
+**Example:**
+```typescript
+// Build XML from object
+const xmlString = parser.build(
+  {
+    inventory: {
+      item: [
+        { sku: 'PROD-001', qty: 100 },
+        { sku: 'PROD-002', qty: 200 },
+      ],
+    },
+  },
+  {
+    format: true,
+    indentBy: '  ',
+    declaration: true,
+  }
+);
+console.log(xmlString);
+// <?xml version="1.0" encoding="UTF-8"?>
+// <inventory>
+//   <item>
+//     <sku>PROD-001</sku>
+//     <qty>100</qty>
+//   </item>
+//   <item>
+//     <sku>PROD-002</sku>
+//     <qty>200</qty>
+//   </item>
+// </inventory>
+```
+**Options (XMLParseOptions):**
+- `lowercaseKeys?: boolean` - Convert element names to lowercase
+- `normalizeWhitespace?: boolean` - Normalize whitespace in text
+- `parseNumbers?: boolean` - Auto-parse numeric values
+- `parseBooleans?: boolean` - Auto-parse boolean values
+- `rootElement?: string` - Root element to start from
+- `arrayElements?: string[]` - Elements to treat as arrays
+- `includeAttributes?: boolean` - Include XML attributes
+- `attributePrefix?: string` - Prefix for attributes (default: '@')
+- `textKey?: string` - Key for text content (default: '#text')
+- `maxDepth?: number` - Maximum parsing depth (default: 100)
+## XMLBuilder
+Generate XML from JavaScript objects with support for attributes, text content, and complex nested structures.
+```typescript
+import { XMLBuilder } from '@fluentcommerce/fc-connect-sdk';
+const builder = new XMLBuilder({
+  xmlDeclaration: true,
+  prettyPrint: true,
+  encoding: 'UTF-8',
+});
+// Generate XML
+const xml = builder.build(data, 'OrderDetailResponse');
+```
+### Understanding the `@` and `#text` Pattern
+XMLBuilder uses special keys to represent XML structures in JSON:
+| JSON Key    | XML Output    | Example                             |
+| ----------- | ------------- | ----------------------------------- |
+| `@prefix`   | Attribute     | `"@id": "123"` → `<Order id="123">` |
+| `#text`     | Text content  | `"#text": "Value"` → Element text   |
+| `fieldName` | Child element | `"Customer": {...}` → `<Customer>`  |
+**When to use `#text`:** Use it when an XML element has **BOTH attributes AND text content** (mixed content).
+### Constructor
+```typescript
+new XMLBuilder(options?: XMLBuildOptions)
+```
+**Options:**
+```typescript
+interface XMLBuildOptions {
+  rootElement?: string; // Root element name (default: 'root')
+  xmlDeclaration?: boolean; // Add <?xml version="1.0"?> (default: true)
+  prettyPrint?: boolean; // Format with indentation (default: true)
+  indent?: string; // Indentation string (default: '  ')
+  attributePrefix?: string; // Attribute prefix (default: '@')
+  textKey?: string; // Text content key (default: '#text')
+  cdataKeys?: string[]; // Fields to wrap in CDATA
+  encoding?: string; // Character encoding (default: 'UTF-8')
+}
+```
+### build Method
+Generate XML from JavaScript object.
+```typescript
+build(
+  data: Record<string, unknown>,
+  rootElement?: string
+): string
+```
+### Pattern Examples
+#### Pattern 1: Simple Text Element
+```typescript
+const data = { ItemId: 'SKU001' };
+builder.build(data, 'Order');
+// Output:
+// <Order>
+//   <ItemId>SKU001</ItemId>
+// </Order>
+```
+#### Pattern 2: Attributes Only
+```typescript
+const data = {
+  Order: {
+    '@id': '12345',
+    '@status': 'confirmed',
+  },
+};
+builder.build(data);
+// Output:
+// <Order id="12345" status="confirmed"/>
+```
+#### Pattern 3: Attributes + Text Content (Using `#text`)
+```typescript
+const data = {
+  Color: {
+    '@id': '9101',
+    '#text': 'MULTI-COLOR',
+  },
+};
+builder.build(data, 'Product');
+// Output:
+// <Product>
+//   <Color id="9101">MULTI-COLOR</Color>
+// </Product>
+```
+**Why `#text`?** This is the standard convention used by XML parsers (like `fast-xml-parser`) to represent text content in JSON. The SDK follows the same convention for consistency.
+#### Pattern 4: Complex Nested Structure
+```typescript
+const data = {
+  Order: {
+    '@customerOrderId': '12345',
+    '@levelOfService': 'REGULAR',
+    Customer: {
+      '@customerId': '232',
+      Name: {
+        FirstName: 'John',
+        LastName: 'Doe',
+      },
+      EmailAddress: 'john@example.com',
+    },
+    OrderSource: {
+      '@type': 'source',
+      '#text': 'WEBSTORE',
+    },
+    OrderItems: {
+      OrderItem: [
+        {
+          '@id': 'item1',
+          ItemId: 'SKU001',
+          Quantity: 2,
+          Description: {
+            Color: {
+              '@id': '9101',
+              '#text': 'Black',
+            },
+            Size: {
+              '@id': 'M',
+              '#text': 'Medium',
+            },
+          },
+        },
+      ],
+    },
+  },
+};
+const xml = builder.build(data, 'OrderDetailResponse');
+// Output:
+// <?xml version="1.0" encoding="UTF-8"?>
+// <OrderDetailResponse>
+//   <Order customerOrderId="12345" levelOfService="REGULAR">
+//     <Customer customerId="232">
+//       <Name>
+//         <FirstName>John</FirstName>
+//         <LastName>Doe</LastName>
+//       </Name>
+//       <EmailAddress>john@example.com</EmailAddress>
+//     </Customer>
+//     <OrderSource type="source">WEBSTORE</OrderSource>
+//     <OrderItems>
+//       <OrderItem id="item1">
+//         <ItemId>SKU001</ItemId>
+//         <Quantity>2</Quantity>
+//         <Description>
+//           <Color id="9101">Black</Color>
+//           <Size id="M">Medium</Size>
+//         </Description>
+//       </OrderItem>
+//     </OrderItems>
+//   </Order>
+// </OrderDetailResponse>
+```
+#### Pattern 5: Arrays (Repeated Elements)
+```typescript
+const data = {
+  OrderItems: {
+    OrderItem: [
+      { ItemId: 'SKU001', Quantity: 2 },
+      { ItemId: 'SKU002', Quantity: 1 },
+    ],
+  },
+};
+// Output:
+// <OrderItems>
+//   <OrderItem>
+//     <ItemId>SKU001</ItemId>
+//     <Quantity>2</Quantity>
+//   </OrderItem>
+//   <OrderItem>
+//     <ItemId>SKU002</ItemId>
+//     <Quantity>1</Quantity>
+//   </OrderItem>
+// </OrderItems>
+```
+#### Decision Tree: When to Use `#text`
+```
+Does the element have attributes?
+├─ NO  → Just use field name
+│       "ItemId": "SKU001"
+│       Result: <ItemId>SKU001</ItemId>
+│
+└─ YES → Does it also have text content?
+    ├─ NO  → Just use @prefix
+    │        "@id": "123"
+    │        Result: <Order id="123"/>
+    │
+    └─ YES → Use BOTH @prefix AND #text
+             "@id": "9101", "#text": "MULTI-COLOR"
+             Result: <Color id="9101">MULTI-COLOR</Color>
+```
+#### Common Issues and Solutions
+**Issue: Text appears as child element**
+```typescript
+// ❌ Wrong - creates <text> element
+"Color": { "@id": "9101", "text": "MULTI-COLOR" }
+// ✅ Correct - creates text content
+"Color": { "@id": "9101", "#text": "MULTI-COLOR" }
+```
+**Issue: Attributes not showing**
+```typescript
+// ❌ Wrong - 'id' becomes child element
+"Color": { "id": "9101", "#text": "MULTI-COLOR" }
+// ✅ Correct - @ prefix makes it an attribute
+"Color": { "@id": "9101", "#text": "MULTI-COLOR" }
+```
+**Issue: Self-closing tag when content expected**
+```typescript
+// ❌ Wrong - empty or undefined value
+"Description": { "#text": undefined }  // → <Description/>
+// ✅ Correct - provide actual value
+"Description": { "#text": product?.description || '' }
+```
+#### Real-World Example: Fluent → SFCC Order Export
+```typescript
+// Fluent Commerce order data
+const fluentOrder = await fluentClient.graphql({
+  query: orderQuery,
+  variables: { ref: orderId },
+});
+// Map to SFCC XML structure using UniversalMapper
+const mapper = new UniversalMapper(mappingConfig, {
+  customResolvers: extractionResolvers,
+});
+const mapped = await mapper.map(fluentOrder);
+// Generate XML
+const builder = new XMLBuilder({
+  xmlDeclaration: true,
+  prettyPrint: true,
+  encoding: 'UTF-8',
+});
+const sfccXml = builder.build(mapped.data, 'OrderDetailResponse');
+// Returns valid SFCC XML ready to send
+console.log(sfccXml);
+```
+## Parquet Parser Service
+**FULLY FUNCTIONAL**: The ParquetParserService is now **FULLY IMPLEMENTED** and ready for use, powered by the high-performance `hyparquet` library. It provides complete Parquet file parsing with streaming support, validation, and detailed statistics.
+**Large File Testing Support**: The SDK includes complete test files for performance validation:
+- **Small**: 3KB files for unit testing
+- **Medium**: 170KB files for integration testing
+- **Large**: 1.7MB files for standard processing
+- **50K Records**: 8.5MB files with 50,000 records
+- **100K Records**: 17MB files with 100,000 records
+- **250K Records**: 43MB files with 250,000 records
+- **500K Records**: 85MB files with 500,000 records
+- **1M Records**: 169MB files with 1,000,000 records
+```typescript
+import {
+  ParquetParserService,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+const logger = toStructuredLogger(createConsoleLogger(), {
+  logLevel: 'info'
+});
+const parser = new ParquetParserService(logger, {
+  batchSize: 1000,
+  maxFileSize: 100 * 1024 * 1024, // 100MB
+  enableStreaming: true,
+  validation: {
+    enabled: true,
+    requiredColumns: ['productRef', 'qty'],
+    columnTypes: {
+      productRef: 'string',
+      qty: 'int32',
+    },
+  },
+});
+// Parse Parquet file - FULLY WORKING
+const { records, stats } = await parser.parse(arrayBuffer, 'inventory.parquet');
+console.log(`Parsed ${stats.totalRecords} records`);
+console.log(`Processing time: ${stats.processingTimeMs}ms`);
+console.log(`Records per second: ${stats.recordsPerSecond}`);
+// Parse large files (e.g., 500K records)
+const largeBuffer = await fs.readFile('inventory-position-500k.parquet');
+const largeArrayBuffer = largeBuffer.buffer.slice(
+  largeBuffer.byteOffset,
+  largeBuffer.byteOffset + largeBuffer.byteLength
+);
+const { records: largeRecords, stats: largeStats } = await parser.parse(
+  largeArrayBuffer,
+  'inventory-position-500k.parquet',
+  {
+    batchSize: 10000, // Larger batch size for performance
+    validation: {
+      enabled: false, // Disable validation for speed
+    },
+  }
+);
+console.log(`Processed ${largeStats.totalRecords} records in ${largeStats.processingTimeMs}ms`);
+console.log(`Throughput: ${largeStats.recordsPerSecond} records/sec`);
+// Stream massive files (1M+ records)
+const streamResult = await parser.parseStreaming(massiveArrayBuffer, 'mixed-positions-1m.parquet');
+for await (const batch of streamResult.records) {
+  console.log(`Processing batch of ${batch.length} records`);
+}
+```
+**Constructor:**
+```typescript
+constructor(
+  logger: StructuredLogger,
+  options?: ParquetParsingOptions
+)
+```
+**Methods:**
+### parse
+Parse a complete Parquet file into memory. Fully functional with hyparquet.
+```typescript
+async parse(
+  arrayBuffer: ArrayBuffer,
+  fileName: string,
+  options?: Partial<ParquetParsingOptions>
+): Promise<{
+  records: ParquetDataRecord[];
+  stats: ParquetParsingStats;
+}>
+```
+**Parameters:**
+- `arrayBuffer: ArrayBuffer` - The Parquet file data as ArrayBuffer
+- `fileName: string` - Name of the file being parsed (for logging)
+- `options?: Partial<ParquetParsingOptions>` - Optional parsing configuration
+**Returns:**
+- `records: ParquetDataRecord[]` - Array of parsed records
+- `stats: ParquetParsingStats` - Detailed parsing statistics
+**Example:**
+```typescript
+const buffer = await fs.readFile('data.parquet');
+const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+const { records, stats } = await parser.parse(arrayBuffer, 'data.parquet', {
+  batchSize: 500,
+  validation: {
+    enabled: true,
+    requiredColumns: ['id', 'name', 'qty'],
+  },
+});
+// Check validation results
+if (stats.validation && !stats.validation.isValid) {
+  console.error('Validation errors:', stats.validation.errors);
+}
+```
+### parseStreaming
+Parse Parquet file with streaming support for memory-efficient processing of large files.
+```typescript
+async parseStreaming(
+  arrayBuffer: ArrayBuffer,
+  fileName: string,
+  options?: Partial<ParquetParsingOptions>
+): Promise<ParquetStreamingResult>
+```
+**Parameters:**
+- `arrayBuffer: ArrayBuffer` - The Parquet file data
+- `fileName: string` - Name of the file being parsed
+- `options?: Partial<ParquetParsingOptions>` - Optional configuration
+**Returns:**
+- `records: AsyncIterable<ParquetDataRecord[]>` - Async iterator of record batches
+- `stats: Promise<ParquetParsingStats>` - Promise resolving to final statistics
+- `cancel: () => void` - Function to cancel streaming
+**Example:**
+```typescript
+const streamResult = await parser.parseStreaming(arrayBuffer, 'large_dataset.parquet', {
+  batchSize: 1000,
+});
+// Process batches as they stream
+for await (const batch of streamResult.records) {
+  for (const record of batch) {
+    await processRecord(record);
+  }
+}
+// Get final statistics
+const stats = await streamResult.stats;
+console.log(`Total records: ${stats.totalRecords}`);
+// Cancel if needed
+setTimeout(() => streamResult.cancel(), 5000);
+```
+### validateFile
+Validate a Parquet file before parsing.
+```typescript
+async validateFile(
+  arrayBuffer: ArrayBuffer,
+  fileName: string
+): Promise<ValidationResult>
+```
+**Parameters:**
+- `arrayBuffer: ArrayBuffer` - The Parquet file data
+- `fileName: string` - Name of the file
+**Returns:**
+- `ValidationResult` - Validation results with errors and warnings
+**Example:**
+```typescript
+const validation = await parser.validateFile(arrayBuffer, 'data.parquet');
+if (!validation.isValid) {
+  console.error('File validation failed:');
+  validation.errors.forEach(error => {
+    console.error(`- ${error.field}: ${error.message}`);
+  });
+}
+```
+### getPerformanceMetrics
+Get current performance metrics for the parser.
+```typescript
+getPerformanceMetrics(): ParquetPerformanceMetrics
+```
+**Returns:**
+- `totalRequests: number` - Total parsing requests
+- `successfulRequests: number` - Successful parses
+- `failedRequests: number` - Failed parses
+- `averageResponseTime: number` - Average parsing time (ms)
+- `lastRequestTime: Date` - Timestamp of last request
+**Example:**
+```typescript
+const metrics = parser.getPerformanceMetrics();
+console.log(
+  `Success rate: ${((metrics.successfulRequests / metrics.totalRequests) * 100).toFixed(2)}%`
+);
+console.log(`Average time: ${metrics.averageResponseTime.toFixed(2)}ms`);
+```
+### resetMetrics
+Reset performance metrics to initial state.
+```typescript
+resetMetrics(): void
+```
+**Example:**
+```typescript
+// Reset metrics after batch processing
+parser.resetMetrics();
+console.log('Performance metrics reset');
+```
+**Interfaces:**
+#### ParquetParsingOptions
+```typescript
+interface ParquetParsingOptions {
+  batchSize?: number; // Records per batch (default: 1000)
+  maxFileSize?: number; // Max file size in bytes (default: 100MB)
+  enableStreaming?: boolean; // Enable streaming mode (default: true)
+  validation?: ParquetValidationOptions;
+}
+```
+#### ParquetValidationOptions
+```typescript
+interface ParquetValidationOptions {
+  enabled?: boolean;
+  requiredColumns?: string[];
+  columnTypes?: Record<string, ParquetDataType>;
+  allowAdditionalColumns?: boolean;
+}
+```
+#### ParquetParsingStats
+```typescript
+interface ParquetParsingStats {
+  totalRecords: number;
+  processingTimeMs: number;
+  fileSizeBytes: number;
+  recordsPerSecond: number;
+  peakMemoryUsage: number;
+  batchesProcessed: number;
+  compressionRatio?: number;
+  columnStats: Record<string, ParquetColumnStatistics>;
+  validation?: ValidationResult;
+}
+```
+#### ParquetStreamingResult
+```typescript
+interface ParquetStreamingResult {
+  records: AsyncIterable<ParquetDataRecord[]>;
+  stats: Promise<ParquetParsingStats>;
+  cancel: () => void;
+}
+```
+#### ParquetDataType
+```typescript
+type ParquetDataType =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'date'
+  | 'int32'
+  | 'int64'
+  | 'float'
+  | 'double'
+  | 'binary';
+```
+## Parser Comparison
+| Parser                   | Streaming | Validation | Best For                          |
+| ------------------------ | --------- | ---------- | --------------------------------- |
+| **CSVParserService**     | ✅        | ✅         | Text-based tabular data           |
+| **JSONParserService**    | ✅        | ✅         | JSON/JSONL formats, API responses |
+| **XMLParserService**     | ✅        | ✅         | XML documents, SOAP APIs, SFCC    |
+| **ParquetParserService** | ✅        | ✅         | Columnar data, large datasets     |
+**Choosing a Parser:**
+- **CSV**: Simple imports, spreadsheets, EDI and B2B systems
+- **JSON**: Modern APIs, flexible schemas, nested data
+- **XML**: Enterprise systems, SOAP, SFCC orders
+- **Parquet**: Big data, analytics, data lakes
+## See Also
+- [Module 06: Data Sources](./api-reference-06-data-sources.md) - File operations
+- [Module 05: Services](./api-reference-05-services.md#universal-mapper) - Field transformations
+- [Module 10: Utilities](./api-reference-10-utilities.md) - Helper functions
+- [Parquet Guide](../../../03-PATTERN-GUIDES/parquet/parquet-readme.md) - Detailed Parquet examples
+- [XML Parser Guide](../../parsers/modules/02-core-guides-parsers-04-xml-parser.md) - XML patterns
+---
+**[← Previous: Module 06 - Data Sources](./api-reference-06-data-sources.md)** | **[API Reference Home](../api-reference-readme.md)** | **[Next: Module 08 - Types →](./api-reference-08-types.md)**