@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/02-CORE-GUIDES/mapping/mapping-javascript-objects.md

@@ -1,2369 +1,2369 @@
----
-title: Understanding Mapping - JavaScript Object Paths
-description: Comprehensive guide to how mapping configurations work with parsed data structures
-category: mapping
-priority: high
-related:
-  - mapping/modules/01-foundations.md
-  - mapping/modules/06-helpers-resolvers.md
-  - parsers/modules/04-xml-parser.md
----
-
-# Understanding Mapping: JavaScript Object Paths
-
-**Critical Concept:** Mapping paths reference **JavaScript object structure**, not source file format.
-
----
-
-## Table of Contents
-
-1. [Core Concept: Mapping AFTER Parsing](#core-concept-mapping-after-parsing)
-2. [The ETL Pattern](#the-etl-pattern)
-3. [Format Examples](#format-examples)
-   - [CSV Examples](#csv-examples)
-   - [JSON Examples](#json-examples)
-   - [XML Examples](#xml-examples)
-   - [Complex XML with Attributes](#complex-xml-with-attributes)
-   - [Complex JSON with Deep Nesting](#complex-json-with-deep-nesting)
-   - [XML with Shared Parent Data](#xml-with-shared-parent-data)
-4. [Common Transformation Patterns](#common-transformation-patterns)
-5. [Visual Flow Diagrams](#visual-flow-diagrams)
-6. [Debugging Guide](#debugging-guide)
-7. [Real-World Example: InventoryStatus](#real-world-example-inventorystatus)
-8. [Best Practices](#best-practices)
-9. [Common Mistakes to Avoid](#common-mistakes-to-avoid)
-
----
-
-## Core Concept: Mapping AFTER Parsing
-
-### The Key Principle
-
-**Mapping configurations map JAVASCRIPT OBJECTS, not file formats.**
-
-When you write a mapping configuration like this:
-
-```json
-{
-  "fields": {
-    "skuRef": { "source": "product.sku" }
-  }
-}
-```
-
-The path `"product.sku"` refers to **JavaScript object property access**, not:
-- NOT CSV column names directly
-- NOT XPath expressions
-- NOT JSONPath queries
-- NOT file format structure
-
-### Why This Matters
-
-Understanding this principle prevents confusion when working with different data sources:
-
-```typescript
-// This is what the mapper receives - ALWAYS a JavaScript object
-const jsObject = {
-  product: {
-    sku: "SKU-001",
-    name: "Widget"
-  }
-};
-
-// Your mapping config uses JavaScript paths
-const mappingConfig = {
-  fields: {
-    skuRef: { source: "product.sku" }  // JavaScript object path
-  }
-};
-```
-
-The mapper **NEVER** sees the original CSV, XML, or JSON file. It only sees the JavaScript object that results from parsing and transformation.
-
----
-
-## The ETL Pattern
-
-All SDK data flows follow this standard Extract-Transform-Load pattern:
-
-```mermaid
-flowchart TD
-    A[Source File<br/>CSV/JSON/XML] --> B[Step 1: Parse<br/>→ JavaScript Objects]
-    B --> C[Step 2: Extract/Normalize<br/>→ Array of Records]
-    C --> D[Step 3: Map Each Record<br/>→ Fluent Format]
-    D --> E[Step 4: Load<br/>→ Batch API/GraphQL]
-    
-    style A fill:#e1f5ff
-    style B fill:#fff4e1
-    style C fill:#fff4e1
-    style D fill:#e8f5e9
-    style E fill:#f3e5f5
-```
-
-**Text Version:**
-```
-Source File (CSV/JSON/XML)
-  ↓
-[Step 1] Parse → JavaScript Objects
-  ↓
-[Step 2] Extract/Normalize → Array of Records
-  ↓
-[Step 3] Map Each Record → Fluent Format
-  ↓
-[Step 4] Load → Batch API/GraphQL
-```
-
-**Detailed Breakdown:**
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                         ETL WORKFLOW PATTERN                                │
-└─────────────────────────────────────────────────────────────────────────────┘
-
-Step 1: SOURCE FILE
-┌────────────────────┐
-│  inventory.csv     │   File format: CSV, JSON, XML, Parquet
-│  inventory.json    │   Location: S3, SFTP, Local
-│  inventory.xml     │
-└────────────────────┘
-         │
-         │ Read from data source
-         ↓
-Step 2: PARSE → JavaScript Objects
-┌────────────────────┐
-│  CSVParserService  │   Converts file format to JavaScript
-│  XMLParserService  │   Result: Array of objects or nested structure
-│  JSONParserService │
-│  ParquetParser     │
-└────────────────────┘
-         │
-         │ Parser output: JavaScript objects
-         ↓
-Step 3: EXTRACT/NORMALIZE → Array of Records
-┌────────────────────┐
-│  Extract items     │   Navigate to the data you need
-│  Normalize arrays  │   Flatten nested structures
-│  Enrich with       │   Add shared context data
-│  parent data       │
-└────────────────────┘
-         │
-         │ What gets passed to mapper
-         ↓
-Step 4: MAP EACH RECORD → Fluent Format
-┌────────────────────┐
-│  UniversalMapper   │   Maps JavaScript object paths to Fluent fields
-│  or                │   Uses mapping configuration
-│  GraphQLMutation   │   Applies resolvers for transformations
-│  Mapper            │
-└────────────────────┘
-         │
-         │ Fluent-formatted data
-         ↓
-Step 5: LOAD → Fluent Commerce
-┌────────────────────┐
-│  Batch API         │   Send data to Fluent
-│  Event API         │   create/update entities
-│  GraphQL Mutations │
-└────────────────────┘
-```
-
-**Key Insight:** Mapping (Step 4) operates on JavaScript objects from Step 3, not on the original file from Step 1. **Mapping configuration matches Step 3** - the structure you pass to `mapper.map()`, which is the result of Step 2.
-
----
-
-## Format Examples
-
-### CSV Examples
-
-#### Simple CSV: No Transformation Needed
-
-**Original CSV File:**
-```csv
-sku_id,quantity,location_code,status
-SKU-001,100,LOC-A,AVAILABLE
-SKU-002,50,LOC-B,RESERVED
-```
-
-**Step 1: Parse**
-```typescript
-const csvParser = new CSVParserService();
-const records = await csvParser.parse(csvContent);
-```
-
-**Step 2: Parsed JavaScript Object (CSVParserService output)**
-```javascript
-[
-  {
-    sku_id: "SKU-001",
-    quantity: "100",        // Note: strings by default
-    location_code: "LOC-A",
-    status: "AVAILABLE"
-  },
-  {
-    sku_id: "SKU-002",
-    quantity: "50",
-    location_code: "LOC-B",
-    status: "RESERVED"
-  }
-]
-```
-
-**Step 3: Extraction (No transformation needed)**
-```javascript
-// CSV parser already gives us an array of flat objects
-const records = parsedCsv; // Use directly
-```
-
-**Step 4: Mapping Configuration**
-```json
-{
-  "fields": {
-    "skuRef": {
-      "source": "sku_id",
-      "required": true
-    },
-    "qty": {
-      "source": "quantity",
-      "resolver": "sdk.parseInt"
-    },
-    "locationRef": {
-      "source": "location_code"
-    },
-    "status": {
-      "source": "status",
-      "resolver": "sdk.uppercase"
-    }
-  }
-}
-```
-
-**What gets passed to mapper.map():**
-```javascript
-// For each record in the array:
-await mapper.map({
-  sku_id: "SKU-001",
-  quantity: "100",
-  location_code: "LOC-A",
-  status: "AVAILABLE"
-});
-```
-
-**Key Points:**
-- CSV columns become JavaScript object keys
-- Column names in file match `source` paths in mapping config
-- No dot notation needed (flat structure)
-
----
-
-#### Complex CSV: Requires Transformation
-
-**CSV File:**
-```csv
-ref,price_default_currency,price_default_value,price_special_currency,price_special_value
-PROD-001,USD,50.00,USD,35.00
-```
-
-**Step 1: Parse**
-```typescript
-const csvParser = new CSVParserService();
-const records = await csvParser.parse(csvContent);
-```
-
-**Parsed JavaScript Object:**
-```javascript
-[
-  { 
-    ref: "PROD-001", 
-    price_default_currency: "USD", 
-    price_default_value: "50.00",
-    price_special_currency: "USD",
-    price_special_value: "35.00"
-  }
-]
-```
-
-**Step 2: Extract/Normalize**
-```typescript
-// CSV is flat, but we need nested structure for prices
-// Two options:
-
-// Option A: Transform in code before mapping
-const records = parsed.map(row => ({
-  ref: row.ref,
-  price: [
-    { type: "DEFAULT", currency: row.price_default_currency, value: row.price_default_value },
-    { type: "SPECIAL", currency: row.price_special_currency, value: row.price_special_value }
-  ]
-}));
-// Result: [{ ref: "PROD-001", price: [{ type: "DEFAULT", ... }, { type: "SPECIAL", ... }] }]
-
-// Option B: Use custom resolver in mapping (see Step 3)
-```
-
-**Step 3: Map**
-
-**Option A - After Code Transformation:**
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    ref: { source: "ref" },
-    price: { 
-      source: "price",           // ← Reads from transformed record.price
-      isArray: true,
-      fields: {
-        type: { source: "type" },
-        currency: { source: "currency" },
-        value: { source: "value", resolver: "sdk.parseFloat" }
-      }
-    }
-  }
-});
-
-for (const record of records) {
-  const result = await mapper.map(record);  // ← Pass transformed structure
-}
-```
-
-**Option B - Using Custom Resolver:**
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    ref: { source: "ref" },
-    price: {
-      resolver: "custom.buildPriceArray",  // ← Custom resolver builds nested structure
-      // No source - resolver receives full record
-    }
-  }
-}, {
-  customResolvers: {
-    'custom.buildPriceArray': (value, sourceData) => {
-      // sourceData = full CSV row
-      return [
-        { 
-          type: "DEFAULT", 
-          currency: sourceData.price_default_currency, 
-          value: parseFloat(sourceData.price_default_value) 
-        },
-        { 
-          type: "SPECIAL", 
-          currency: sourceData.price_special_currency, 
-          value: parseFloat(sourceData.price_special_value) 
-        }
-      ];
-    }
-  }
-});
-
-for (const record of records) {
-  const result = await mapper.map(record);  // ← Pass flat CSV row
-}
-```
-
-**Mapping Matches:** 
-- Option A: Transformed structure (`record.price[]`)
-- Option B: Flat CSV row (`record.price_default_currency` via resolver)
-
----
-
-### JSON Examples
-
-#### Simple JSON: Array Extraction Needed
-
-**Original JSON File:**
-```json
-{
-  "timestamp": "2025-01-15T10:00:00Z",
-  "warehouse": "WH-01",
-  "inventory": [
-    {
-      "product_code": "SKU-001",
-      "stock_level": 100,
-      "location": "A1"
-    },
-    {
-      "product_code": "SKU-002",
-      "stock_level": 50,
-      "location": "B2"
-    }
-  ]
-}
-```
-
-**Step 1: Parse**
-```typescript
-const jsonParser = new JSONParserService();
-const parsed = await jsonParser.parse(jsonContent);
-```
-
-**Step 2: Parsed JavaScript Object (JSONParserService output)**
-```javascript
-{
-  timestamp: "2025-01-15T10:00:00Z",
-  warehouse: "WH-01",
-  inventory: [
-    {
-      product_code: "SKU-001",
-      stock_level: 100,
-      location: "A1"
-    },
-    {
-      product_code: "SKU-002",
-      stock_level: 50,
-      location: "B2"
-    }
-  ]
-}
-```
-
-**Step 3: Extraction**
-```javascript
-// Extract the array we want to process
-const parsed = await jsonParser.parse(jsonContent);
-const records = parsed.inventory; // Extract nested array
-
-// Now we have an array of inventory items
-```
-
-**Step 4: Mapping Configuration**
-```json
-{
-  "fields": {
-    "skuRef": {
-      "source": "product_code",
-      "required": true
-    },
-    "qty": {
-      "source": "stock_level",
-      "resolver": "sdk.parseInt"
-    },
-    "locationRef": {
-      "source": "location"
-    }
-  }
-}
-```
-
-**What gets passed to mapper.map():**
-```javascript
-// For each item in the inventory array:
-await mapper.map({
-  product_code: "SKU-001",
-  stock_level: 100,
-  location: "A1"
-});
-```
-
-**Key Points:**
-- JSON parsing preserves nested structure
-- You extract the array you need (`parsed.inventory`)
-- Mapping config references the **extracted object** structure, not the full JSON
-
----
-
-#### Complex JSON: Nested Structure with Transformation Options
-
-**JSON File:**
-```json
-{
-  "inventory": {
-    "warehouse": "WH-001",
-    "items": [
-      {
-        "product": {
-          "sku": "SKU-001",
-          "details": {
-            "name": "Product 1"
-          }
-        },
-        "stock": {
-          "quantity": 100,
-          "status": "available"
-        }
-      },
-      {
-        "product": {
-          "sku": "SKU-002",
-          "details": {
-            "name": "Product 2"
-          }
-        },
-        "stock": {
-          "quantity": 50,
-          "status": "reserved"
-        }
-      }
-    ]
-  }
-}
-```
-
-**Step 1: Parse**
-```typescript
-const jsonParser = new JSONParserService();
-const parsed = await jsonParser.parse(jsonContent);
-```
-
-**Parsed JavaScript Object:**
-```javascript
-{
-  inventory: {
-    warehouse: "WH-001",
-    items: [
-      {
-        product: { sku: "SKU-001", details: { name: "Product 1" } },
-        stock: { quantity: 100, status: "available" }
-      },
-      {
-        product: { sku: "SKU-002", details: { name: "Product 2" } },
-        stock: { quantity: 50, status: "reserved" }
-      }
-    ]
-  }
-}
-```
-
-**Step 2: Extract/Normalize**
-```typescript
-// Extract items array, and add warehouse from parent
-const warehouse = parsed.inventory.warehouse;
-const items = parsed.inventory.items;
-
-// Option A: Transform to add warehouse to each item
-const records = items.map(item => ({
-  warehouse: warehouse,      // ← Add shared data
-  product: item.product,
-  stock: item.stock
-}));
-// Result: [{ warehouse: "WH-001", product: {...}, stock: {...} }, ...]
-
-// Option B: Pass full structure and use dot notation in mapping
-```
-
-**Step 3: Map**
-
-**Option A - After Transformation:**
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    locationRef: { source: "warehouse" },              // ← From transformed record
-    productRef: { source: "product.sku" },            // ← From transformed record
-    quantity: { source: "stock.quantity" },            // ← From transformed record
-    status: { source: "stock.status" }                 // ← From transformed record
-  }
-});
-
-for (const record of records) {
-  const result = await mapper.map(record);  // ← Pass transformed structure
-}
-```
-
-**Option B - Direct Mapping (No Transformation):**
-```typescript
-// Map each item directly, accessing parent via root context
-const mapper = new UniversalMapper({
-  fields: {
-    items: {
-      source: "inventory.items",                      // ← Extract items array
-      isArray: true,                                  // ← Iterate over items
-      fields: {
-        locationRef: { 
-          // Access parent warehouse from root context
-          // Note: You may need a custom resolver to access parent data
-          resolver: "custom.getWarehouse"  // Custom resolver accesses root
-        },
-        productRef: { source: "product.sku" },       // ← From current item
-        quantity: { source: "stock.quantity" },      // ← From current item
-        status: { source: "stock.status" }           // ← From current item
-      }
-    }
-  }
-});
-
-const result = await mapper.map(parsed);  // ← Pass full parsed structure
-```
-
-**Mapping Matches:**
-- Option A: Transformed structure (`record.warehouse`, `record.product.sku`)
-- Option B: Full parsed structure (`inventory.items[]`, requires custom resolver for parent access)
-
----
-
-#### Simple XML: Array Normalization Required
-
-**Original XML File:**
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<products>
-  <product>
-    <sku>SKU-001</sku>
-    <name>Product 1</name>
-    <quantity>100</quantity>
-    <location>LOC-A</location>
-  </product>
-  <product>
-    <sku>SKU-002</sku>
-    <name>Product 2</name>
-    <quantity>50</quantity>
-    <location>LOC-B</location>
-  </product>
-</products>
-```
-
-**Step 1: Parse**
-```typescript
-const xmlParser = new XMLParserService();
-const parsed = await xmlParser.parse(xmlContent);
-```
-
-**Step 2: Parsed JavaScript Object (XMLParserService output)**
-```javascript
-{
-  products: {
-    product: [  // Multiple <product> elements → array
-      {
-        sku: "SKU-001",
-        name: "Product 1",
-        quantity: 100,    // Auto-parsed as number
-        location: "LOC-A"
-      },
-      {
-        sku: "SKU-002",
-        name: "Product 2",
-        quantity: 50,
-        location: "LOC-B"
-      }
-    ]
-  }
-}
-```
-
-**CRITICAL: XML Array Normalization**
-
-XML parsing has a gotcha: single vs multiple elements
-```javascript
-// Multiple <product> elements
-parsed.products.product  // → array []
-
-// Single <product> element (gotcha!)
-parsed.products.product  // → object {} (NOT array!)
-```
-
-**Step 3: Extraction with Normalization**
-```javascript
-const parsed = await xmlParser.parse(xmlContent);
-
-// ALWAYS normalize XML arrays
-const items = parsed.products?.product;
-const records = Array.isArray(items) ? items : items ? [items] : [];
-
-// Now records is ALWAYS an array
-```
-
-**Step 4: Mapping Configuration**
-```json
-{
-  "fields": {
-    "skuRef": {
-      "source": "sku",
-      "required": true
-    },
-    "name": {
-      "source": "name"
-    },
-    "qty": {
-      "source": "quantity",
-      "resolver": "sdk.parseInt"
-    },
-    "locationRef": {
-      "source": "location"
-    }
-  }
-}
-```
-
-**What gets passed to mapper.map():**
-```javascript
-// For each normalized item:
-await mapper.map({
-  sku: "SKU-001",
-  name: "Product 1",
-  quantity: 100,
-  location: "LOC-A"
-});
-```
-
-**Key Points:**
-- XML element names become JavaScript object keys
-- Multiple elements create arrays
-- Single element creates object (must normalize!)
-- Always use: `Array.isArray(items) ? items : items ? [items] : []`
-
----
-
-### Complex XML with Attributes
-
-#### XML Attributes Use @ Prefix
-
-**Original XML File:**
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<inventory>
-  <item locationRef="LOC-A" skuRef="SKU-001">
-    <qty>100</qty>
-    <status>AVAILABLE</status>
-    <expectedOn>2025-01-20</expectedOn>
-  </item>
-  <item locationRef="LOC-B" skuRef="SKU-002">
-    <qty>50</qty>
-    <status>RESERVED</status>
-  </item>
-</inventory>
-```
-
-**Step 2: Parsed JavaScript Object (XMLParserService output)**
-```javascript
-{
-  inventory: {
-    item: [
-      {
-        "@locationRef": "LOC-A",   // Attributes use @ prefix
-        "@skuRef": "SKU-001",
-        qty: 100,
-        status: "AVAILABLE",
-        expectedOn: "2025-01-20"
-  },
-      {
-        "@locationRef": "LOC-B",
-        "@skuRef": "SKU-002",
-        qty: 50,
-        status: "RESERVED"
-      }
-    ]
-  }
-}
-```
-
-**Step 3: Extraction with Normalization**
-```javascript
-const parsed = await xmlParser.parse(xmlContent);
-
-// Normalize array
-const items = parsed.inventory?.item;
-const records = Array.isArray(items) ? items : items ? [items] : [];
-```
-
-**Step 4: Mapping Configuration**
-```json
-{
-  "fields": {
-    "locationRef": {
-      "source": "@locationRef",
-      "required": true,
-      "resolver": "sdk.trim"
-    },
-    "skuRef": {
-      "source": "@skuRef",
-      "required": true,
-      "resolver": "sdk.trim"
-    },
-    "qty": {
-      "source": "qty",
-      "required": true,
-      "resolver": "sdk.parseInt"
-    },
-    "status": {
-      "source": "status",
-      "required": true,
-      "resolver": "sdk.uppercase"
-    },
-    "expectedOn": {
-      "source": "expectedOn",
-      "resolver": "sdk.formatDate"
-    }
-  }
-}
-```
-
-**What gets passed to mapper.map():**
-```javascript
-// For each normalized item:
-await mapper.map({
-  "@locationRef": "LOC-A",    // @ prefix in JavaScript object
-  "@skuRef": "SKU-001",
-  qty: 100,
-  status: "AVAILABLE",
-  expectedOn: "2025-01-20"
-});
-```
-
-**Key Points:**
-- XML attributes use `@` prefix in parsed JavaScript object
-- Mapping config uses `@` prefix to reference attributes
-- This is a JavaScript object key, not XPath syntax
-- Elements without `@` are child elements
-
----
-
-#### Complex XML: Orders with Attributes and Transformation Options
-
-**XML File:**
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<Orders>
-  <Order id="ORD-001" orderDate="2025-01-22">
-    <Customer>
-      <Name>John Doe</Name>
-      <Email>john@example.com</Email>
-    </Customer>
-    <Items>
-      <Item sku="PROD-001" qty="2">
-        <Price>29.99</Price>
-      </Item>
-      <Item sku="PROD-002" qty="1">
-        <Price>49.99</Price>
-      </Item>
-    </Items>
-  </Order>
-  <Order id="ORD-002" orderDate="2025-01-23">
-    <Customer>
-      <Name>Jane Smith</Name>
-      <Email>jane@example.com</Email>
-    </Customer>
-    <Items>
-      <Item sku="PROD-003" qty="3">
-        <Price>19.99</Price>
-      </Item>
-    </Items>
-  </Order>
-</Orders>
-```
-
-**Step 1: Parse (with attributes)**
-```typescript
-const xmlParser = new XMLParserService();
-const parsed = await xmlParser.parse(xmlContent, { includeAttributes: true });
-```
-
-**Parsed JavaScript Object:**
-```javascript
-{
-  Orders: {
-    Order: [
-      {
-        "@id": "ORD-001",                    // ← Attributes prefixed with @
-        "@orderDate": "2025-01-22",
-        Customer: {
-          Name: "John Doe",
-          Email: "john@example.com"
-        },
-        Items: {
-          Item: [
-            {
-              "@sku": "PROD-001",            // ← Attributes prefixed with @
-              "@qty": "2",
-              Price: "29.99"
-            },
-            {
-              "@sku": "PROD-002",
-              "@qty": "1",
-              Price: "49.99"
-            }
-          ]
-        }
-      },
-      {
-        "@id": "ORD-002",
-        "@orderDate": "2025-01-23",
-        Customer: { ... },
-        Items: { ... }
-      }
-    ]
-  }
-}
-```
-
-**Step 2: Extract/Normalize**
-```typescript
-const orders = parsed.Orders.Order;
-const records = Array.isArray(orders) ? orders : orders ? [orders] : [];
-// Result: [{ "@id": "ORD-001", "@orderDate": "...", Customer: {...}, Items: {...} }, ...]
-```
-
-**Step 3: Map**
-
-**Option A: Map Each Order, Then Items Separately**
-```typescript
-const orderMapper = new UniversalMapper({
-  fields: {
-    orderRef: { source: "@id" },                        // ← XML attribute
-    orderDate: { source: "@orderDate", resolver: "sdk.parseDate" },
-    customerName: { source: "Customer.Name" },
-    customerEmail: { source: "Customer.Email" },
-    items: {
-      source: "Items.Item",                              // ← Extract items array
-      isArray: true,                                     // ← Iterate over items
-      fields: {
-        productRef: { source: "@sku" },                  // ← Attribute from item
-        quantity: { source: "@qty", resolver: "sdk.parseInt" },
-        price: { source: "Price", resolver: "sdk.parseFloat" }
-      }
-    }
-  }
-});
-
-for (const order of records) {
-  const result = await orderMapper.map({ Order: order });  // ← Wrap for context
-  // Mapping: Order.@id, Order.Customer.Name, Order.Items.Item[].@sku
-}
-```
-
-**Option B: Transform First, Then Map**
-```typescript
-// Extract items and flatten with order data
-const allItems = [];
-for (const order of records) {
-  const orderId = order["@id"];
-  const orderDate = order["@orderDate"];
-  const items = Array.isArray(order.Items.Item) 
-    ? order.Items.Item 
-    : order.Items.Item 
-    ? [order.Items.Item] 
-    : [];
-  
-  for (const item of items) {
-    allItems.push({
-      orderId: orderId,                    // ← Add from parent
-      orderDate: orderDate,                // ← Add from parent
-      sku: item["@sku"],                   // ← From item attribute
-      qty: item["@qty"],                   // ← From item attribute
-      price: item.Price                    // ← From item element
-    });
-  }
-}
-
-// Now map flattened structure
-const itemMapper = new UniversalMapper({
-  fields: {
-    orderRef: { source: "orderId" },       // ← From transformed structure
-    orderDate: { source: "orderDate", resolver: "sdk.parseDate" },
-    productRef: { source: "sku" },         // ← From transformed structure
-    quantity: { source: "qty", resolver: "sdk.parseInt" },
-    price: { source: "price", resolver: "sdk.parseFloat" }
-  }
-});
-
-for (const item of allItems) {
-  const result = await itemMapper.map(item);  // ← Pass transformed structure
-}
-```
-
-**Mapping Matches:**
-- Option A: Parsed XML structure (`Order.@id`, `Order.Items.Item[].@sku`)
-- Option B: Transformed structure (`item.orderId`, `item.sku`)
-
----
-
-### Complex JSON with Deep Nesting
-
-#### Nested Path Navigation
-
-**Original JSON File:**
-```json
-{
-  "warehouse": {
-    "id": "WH-01",
-    "location": {
-      "code": "LOC-A",
-      "name": "Warehouse A"
-    },
-    "inventory": {
-      "items": [
-        {
-          "product": {
-            "sku": "SKU-001",
-            "details": {
-              "name": "Widget",
-              "category": "Electronics"
-            }
-          },
-          "stock": {
-            "available": 100,
-            "reserved": 20
-          }
-        }
-      ]
-    }
-  }
-}
-```
-
-**Step 2: Parsed JavaScript Object (JSONParserService output)**
-```javascript
-{
-  warehouse: {
-    id: "WH-01",
-    location: {
-      code: "LOC-A",
-      name: "Warehouse A"
-    },
-    inventory: {
-      items: [
-        {
-          product: {
-            sku: "SKU-001",
-            details: {
-              name: "Widget",
-              category: "Electronics"
-            }
-          },
-          stock: {
-            available: 100,
-            reserved: 20
-          }
-        }
-      ]
-    }
-  }
-}
-```
-
-**Step 3: Extraction**
-```javascript
-const parsed = await jsonParser.parse(jsonContent);
-
-// Extract the nested array
-const records = parsed.warehouse.inventory.items;
-
-// For shared context, store parent data
-const warehouseCode = parsed.warehouse.location.code;
-```
-
-**Step 4: Mapping Configuration**
-```json
-{
-  "fields": {
-    "skuRef": {
-      "source": "product.sku",
-      "required": true
-    },
-    "name": {
-      "source": "product.details.name"
-    },
-    "qty": {
-      "source": "stock.available",
-      "resolver": "sdk.parseInt"
-    },
-    "locationRef": {
-      "value": "LOC-A"
-    }
-  }
-}
-```
-
-**What gets passed to mapper.map():**
-```javascript
-// For each item in the items array:
-await mapper.map({
-  product: {
-    sku: "SKU-001",
-    details: {
-      name: "Widget",
-      category: "Electronics"
-    }
-  },
-  stock: {
-    available: 100,
-    reserved: 20
-  }
-});
-```
-
-**Key Points:**
-- Dot notation navigates nested JavaScript objects
-- `"product.sku"` becomes `obj.product.sku` in JavaScript
-- `"product.details.name"` becomes `obj.product.details.name`
-- You can reference any depth of nesting
-
----
-
-### XML with Shared Parent Data
-
-#### Real-World Pattern: Enriching Child Records
-
-This is a common pattern where parent-level data needs to be added to each child record.
-
-**Original XML File:**
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<InventoryStatus>
-  <ItemInventory>
-    <FacilityId>WAREHOUSE-01</FacilityId>
-    <Item>
-      <SKU>SKU-001</SKU>
-      <Quantity>100</Quantity>
-      <Status>AVAILABLE</Status>
-    </Item>
-    <Item>
-      <SKU>SKU-002</SKU>
-      <Quantity>50</Quantity>
-      <Status>RESERVED</Status>
-    </Item>
-  </ItemInventory>
-</InventoryStatus>
-```
-
-**Step 2: Parsed JavaScript Object (XMLParserService output)**
-```javascript
-{
-  InventoryStatus: {
-    ItemInventory: {
-      FacilityId: "WAREHOUSE-01",
-      Item: [  // Multiple Items
-        {
-          SKU: "SKU-001",
-          Quantity: 100,
-          Status: "AVAILABLE"
-        },
-        {
-          SKU: "SKU-002",
-          Quantity: 50,
-          Status: "RESERVED"
-        }
-      ]
-    }
-  }
-}
-```
-
-**Step 3: Transformation - Enrich Each Item**
-```javascript
-const parsed = await xmlParser.parse(xmlContent);
-
-// Extract parent data
-const facilityId = parsed.InventoryStatus.ItemInventory.FacilityId;
-
-// Extract items
-const items = parsed.InventoryStatus.ItemInventory.Item;
-const normalizedItems = Array.isArray(items) ? items : items ? [items] : [];
-
-// TRANSFORM: Wrap each item with facility context
-const enrichedRecords = normalizedItems.map(item => ({
-  itemInventory: {
-    FacilityId: facilityId,  // Add parent data to each item
-    ...item                   // Spread item properties
-  }
-}));
-
-// Now each record has the FacilityId embedded
-```
-
-**Result of Transformation:**
-```javascript
-[
-  {
-    itemInventory: {
-      FacilityId: "WAREHOUSE-01",  // Parent data added
-      SKU: "SKU-001",
-      Quantity: 100,
-      Status: "AVAILABLE"
-    }
-  },
-  {
-    itemInventory: {
-      FacilityId: "WAREHOUSE-01",  // Parent data added
-      SKU: "SKU-002",
-      Quantity: 50,
-      Status: "RESERVED"
-    }
-  }
-]
-```
-
-**Step 4: Mapping Configuration**
-```json
-{
-  "fields": {
-    "locationRef": {
-      "source": "itemInventory.FacilityId",
-      "required": true
-    },
-    "skuRef": {
-      "source": "itemInventory.SKU",
-      "required": true
-    },
-    "qty": {
-      "source": "itemInventory.Quantity",
-      "resolver": "sdk.parseInt"
-    },
-    "status": {
-      "source": "itemInventory.Status",
-      "resolver": "sdk.uppercase"
-    }
-  }
-}
-```
-
-**What gets passed to mapper.map():**
-```javascript
-// For each enriched record:
-await mapper.map({
-  itemInventory: {
-    FacilityId: "WAREHOUSE-01",
-    SKU: "SKU-001",
-    Quantity: 100,
-    Status: "AVAILABLE"
-  }
-});
-```
-
-**Why This Works:**
-- You transformed the data BEFORE mapping
-- The mapping config references the TRANSFORMED structure
-- Path `"itemInventory.FacilityId"` exists in the JavaScript object
-- This is NOT XPath - it's JavaScript property access
-
-**Why Transformation Needed:** 
-- XML has `FacilityId` in parent `ItemInventory` (shared by all Items)
-- Each `Item` needs its own `FacilityId` to create complete records
-- Mapping can't easily access parent data when iterating arrays
-- Solution: Transform to combine parent data with each child before mapping
-
-**Complete Example Code:**
-```typescript
-import { XMLParserService, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const xmlParser = new XMLParserService();
-const parsed = await xmlParser.parse(xmlContent);
-
-// Step 1: Extract parent data
-const facilityId = parsed.InventoryStatus.ItemInventory.FacilityId;
-
-// Step 2: Extract and normalize items
-const items = parsed.InventoryStatus.ItemInventory.Item;
-const normalizedItems = Array.isArray(items) ? items : items ? [items] : [];
-
-// Step 3: Transform - wrap each item
-const enrichedRecords = normalizedItems.map(item => ({
-  itemInventory: {
-    FacilityId: facilityId,
-    ...item
-  }
-}));
-
-// Step 4: Map each enriched record
-const mapper = new UniversalMapper(mappingConfig);
-
-for (const record of enrichedRecords) {
-  const result = await mapper.map(record);
-
-  if (result.success) {
-    console.log('Mapped:', result.data);
-  } else {
-    console.error('Mapping failed:', result.errors);
-  }
-}
-```
-
----
-
-## Common Transformation Patterns
-
-### Pattern 1: No Transformation (Flat CSV)
-
-**Use Case:** CSV with flat structure
-
-```javascript
-// Parsed CSV is already array of flat objects
-const records = parsedCsv;
-
-// Map directly
-for (const record of records) {
-  await mapper.map(record);
-}
-```
-
-### Pattern 2: Array Extraction (Nested JSON)
-
-**Use Case:** JSON with nested data array
-
-```javascript
-// Extract the array you need
-const parsed = await jsonParser.parse(jsonContent);
-const records = parsed.data.inventory.items;
-
-// Map each item
-for (const record of records) {
-  await mapper.map(record);
-}
-```
-
-### Pattern 3: Array Normalization (XML)
-
-**Use Case:** XML with repeating elements
-
-```javascript
-// Always normalize XML arrays
-const parsed = await xmlParser.parse(xmlContent);
-const items = parsed.products?.product;
-const records = Array.isArray(items) ? items : items ? [items] : [];
-
-// Now safe to iterate
-for (const record of records) {
-  await mapper.map(record);
-}
-```
-
-### Pattern 4: Parent Data Enrichment (XML with Context)
-
-**Use Case:** Child elements need parent data
-
-```javascript
-// Extract parent data
-const facilityId = parsed.warehouse.facility.id;
-
-// Extract items
-const items = parsed.warehouse.facility.inventory;
-const normalizedItems = Array.isArray(items) ? items : items ? [items] : [];
-
-// Enrich each item
-const enrichedRecords = normalizedItems.map(item => ({
-  ...item,
-  facilityId: facilityId  // Add parent data
-}));
-
-// Map enriched records
-for (const record of enrichedRecords) {
-  await mapper.map(record);
-}
-```
-
-### Pattern 5: Attribute Handling (XML Attributes)
-
-**Use Case:** XML with attributes and elements
-
-```javascript
-// XML Parser adds @ prefix for attributes
-const parsed = await xmlParser.parse(xmlContent);
-const items = parsed.catalog?.product;
-const records = Array.isArray(items) ? items : items ? [items] : [];
-
-// Mapping config uses @ prefix
-const mappingConfig = {
-  fields: {
-    id: { source: "@id" },        // Attribute
-    name: { source: "name" },     // Element
-    price: { source: "@price" }   // Attribute
-  }
-};
-```
-
----
-
-## Key Takeaways
-
-### 1. Mapping Uses Parsed JavaScript Objects
-
-✅ **Mapping paths match the JavaScript object structure you pass to `mapper.map()`**
-
-```typescript
-// What you pass:
-await mapper.map({ itemInventory: { FacilityId: "...", Item: {...} } });
-
-// Mapping paths must match:
-{ source: "itemInventory.FacilityId" }     // ✅ Matches
-{ source: "InventoryStatus.ItemInventory.FacilityId" }  // ❌ Doesn't match
-```
-
-### 2. When Transformation is Needed
-
-**Transform when:**
-- ✅ Parent data needs to be combined with child records (like XML with shared parent data)
-- ✅ Flat structure needs to become nested (CSV → nested JSON)
-- ✅ Multiple data sources need to be combined
-- ✅ Complex business logic is easier in code than mapping
-
-**Don't transform when:**
-- ✅ Structure already matches target format
-- ✅ Simple field renaming is sufficient
-- ✅ Resolvers can handle the transformation
-
-### 3. XML Attributes
-
-**XML attributes are prefixed with `@` in parsed objects:**
-```xml
-<Order id="ORD-001">
-```
-```javascript
-{ Order: { "@id": "ORD-001" } }
-```
-```json
-{ "source": "Order@id" }  // ← No dot before @
-```
-
-### 4. Array Normalization
-
-**Always normalize XML arrays (single element → object, multiple → array):**
-```typescript
-const items = parsed.products?.product;
-const records = Array.isArray(items) ? items : items ? [items] : [];
-```
-
-### 5. Mapping Pattern Summary
-
-| Format | Parse Result | Extract/Normalize | Mapping Matches |
-|--------|-------------|-------------------|-----------------|
-| **CSV** | Array of flat objects | Already normalized | Flat record structure |
-| **JSON** | Nested objects | Extract array, optionally transform | Passed structure |
-| **XML** | Nested objects with `@` attributes | Extract array, normalize, optionally transform | Passed structure |
-
----
-
-## Visual Flow Diagrams
-
-### Data Flow: CSV to Fluent
-
-```
-┌───────────────────────────────────────────────────────────────────┐
-│ CSV FILE                                                          │
-├───────────────────────────────────────────────────────────────────┤
-│ sku_id,quantity,location_code                                     │
-│ SKU-001,100,LOC-A                                                 │
-│ SKU-002,50,LOC-B                                                  │
-└───────────────────────────────────────────────────────────────────┘
-                            │
-                            │ CSVParserService.parse()
-                            ↓
-┌───────────────────────────────────────────────────────────────────┐
-│ PARSED JAVASCRIPT ARRAY                                           │
-├───────────────────────────────────────────────────────────────────┤
-│ [                                                                 │
-│   { sku_id: "SKU-001", quantity: "100", location_code: "LOC-A" }, │
-│   { sku_id: "SKU-002", quantity: "50", location_code: "LOC-B" }   │
-│ ]                                                                 │
-└───────────────────────────────────────────────────────────────────┘
-                            │
-                            │ No transformation needed (flat)
-                            ↓
-┌───────────────────────────────────────────────────────────────────┐
-│ WHAT MAPPER RECEIVES                                              │
-├───────────────────────────────────────────────────────────────────┤
-│ {                                                                 │
-│   sku_id: "SKU-001",         ← mapping: "skuRef" from "sku_id"    │
-│   quantity: "100",           ← mapping: "qty" from "quantity"     │
-│   location_code: "LOC-A"     ← mapping: "locationRef" from ...    │
-│ }                                                                 │
-└───────────────────────────────────────────────────────────────────┘
-                            │
-                            │ UniversalMapper.map()
-                            ↓
-┌───────────────────────────────────────────────────────────────────┐
-│ FLUENT FORMAT                                                     │
-├───────────────────────────────────────────────────────────────────┤
-│ {                                                                 │
-│   skuRef: "SKU-001",                                              │
-│   qty: 100,              ← Converted to number by sdk.parseInt    │
-│   locationRef: "LOC-A"                                            │
-│ }                                                                 │
-└───────────────────────────────────────────────────────────────────┘
-```
-
-### Data Flow: XML with Attributes to Fluent
-
-```
-┌────────────────────────────────────────────────────────────────────┐
-│ XML FILE                                                           │
-├────────────────────────────────────────────────────────────────────┤
-│ <inventory>                                                        │
-│   <item locationRef="LOC-A" skuRef="SKU-001">                      │
-│     <qty>100</qty>                                                 │
-│     <status>AVAILABLE</status>                                     │
-│   </item>                                                          │
-│ </inventory>                                                       │
-└────────────────────────────────────────────────────────────────────┘
-                            │
-                            │ XMLParserService.parse()
-                            ↓
-┌────────────────────────────────────────────────────────────────────┐
-│ PARSED JAVASCRIPT OBJECT                                           │
-├────────────────────────────────────────────────────────────────────┤
-│ {                                                                  │
-│   inventory: {                                                     │
-│     item: {                                                        │
-│       "@locationRef": "LOC-A",    ← @ prefix for attributes        │
-│       "@skuRef": "SKU-001",                                        │
-│       qty: 100,                   ← Elements without @             │
-│       status: "AVAILABLE"                                          │
-│     }                                                              │
-│   }                                                                │
-│ }                                                                  │
-└────────────────────────────────────────────────────────────────────┘
-                            │
-                            │ Extract: parsed.inventory.item
-                            │ Normalize: single element, wrap in array
-                            ↓
-┌────────────────────────────────────────────────────────────────────┐
-│ WHAT MAPPER RECEIVES                                               │
-├────────────────────────────────────────────────────────────────────┤
-│ {                                                                  │
-│   "@locationRef": "LOC-A",  ← mapping: source "@locationRef"       │
-│   "@skuRef": "SKU-001",     ← mapping: source "@skuRef"            │
-│   qty: 100,                 ← mapping: source "qty"                │
-│   status: "AVAILABLE"       ← mapping: source "status"             │
-│ }                                                                  │
-└────────────────────────────────────────────────────────────────────┘
-                            │
-                            │ UniversalMapper.map()
-                            ↓
-┌────────────────────────────────────────────────────────────────────┐
-│ FLUENT FORMAT                                                      │
-├────────────────────────────────────────────────────────────────────┤
-│ {                                                                  │
-│   locationRef: "LOC-A",                                            │
-│   skuRef: "SKU-001",                                               │
-│   qty: 100,                                                        │
-│   status: "AVAILABLE"                                              │
-│ }                                                                  │
-└────────────────────────────────────────────────────────────────────┘
-```
-
-### Data Flow: XML with Parent Data Enrichment
-
-```
-┌──────────────────────────────────────────────────────────────────────┐
-│ XML FILE                                                             │
-├──────────────────────────────────────────────────────────────────────┤
-│ <InventoryStatus>                                                    │
-│   <ItemInventory>                                                    │
-│     <FacilityId>WH-01</FacilityId>  ← Parent data                    │
-│     <Item><SKU>SKU-001</SKU><Qty>100</Qty></Item>  ← Children       │
-│     <Item><SKU>SKU-002</SKU><Qty>50</Qty></Item>                     │
-│   </ItemInventory>                                                   │
-│ </InventoryStatus>                                                   │
-└──────────────────────────────────────────────────────────────────────┘
-                            │
-                            │ XMLParserService.parse()
-                            ↓
-┌──────────────────────────────────────────────────────────────────────┐
-│ PARSED JAVASCRIPT OBJECT                                             │
-├──────────────────────────────────────────────────────────────────────┤
-│ {                                                                    │
-│   InventoryStatus: {                                                 │
-│     ItemInventory: {                                                 │
-│       FacilityId: "WH-01",       ← Parent data                       │
-│       Item: [                    ← Array of children                 │
-│         { SKU: "SKU-001", Qty: 100 },                                │
-│         { SKU: "SKU-002", Qty: 50 }                                  │
-│       ]                                                              │
-│     }                                                                │
-│   }                                                                  │
-│ }                                                                    │
-└──────────────────────────────────────────────────────────────────────┘
-                            │
-                            │ TRANSFORMATION:
-                            │ 1. Extract facilityId
-                            │ 2. Normalize Item array
-                            │ 3. Wrap each item with facilityId
-                            ↓
-┌──────────────────────────────────────────────────────────────────────┐
-│ TRANSFORMED RECORDS                                                  │
-├──────────────────────────────────────────────────────────────────────┤
-│ [                                                                    │
-│   {                                                                  │
-│     itemInventory: {                                                 │
-│       FacilityId: "WH-01",   ← Parent data added to each item        │
-│       SKU: "SKU-001",                                                │
-│       Qty: 100                                                       │
-│     }                                                                │
-│   },                                                                 │
-│   {                                                                  │
-│     itemInventory: {                                                 │
-│       FacilityId: "WH-01",   ← Same parent data                      │
-│       SKU: "SKU-002",                                                │
-│       Qty: 50                                                        │
-│     }                                                                │
-│   }                                                                  │
-│ ]                                                                    │
-└──────────────────────────────────────────────────────────────────────┘
-                            │
-                            │ For each record...
-                            ↓
-┌──────────────────────────────────────────────────────────────────────┐
-│ WHAT MAPPER RECEIVES                                                 │
-├──────────────────────────────────────────────────────────────────────┤
-│ {                                                                    │
-│   itemInventory: {                                                   │
-│     FacilityId: "WH-01",   ← source: "itemInventory.FacilityId"      │
-│     SKU: "SKU-001",        ← source: "itemInventory.SKU"             │
-│     Qty: 100               ← source: "itemInventory.Qty"             │
-│   }                                                                  │
-│ }                                                                    │
-└──────────────────────────────────────────────────────────────────────┘
-                            │
-                            │ UniversalMapper.map()
-                            ↓
-┌──────────────────────────────────────────────────────────────────────┐
-│ FLUENT FORMAT                                                        │
-├──────────────────────────────────────────────────────────────────────┤
-│ {                                                                    │
-│   locationRef: "WH-01",                                              │
-│   skuRef: "SKU-001",                                                 │
-│   qty: 100                                                           │
-│ }                                                                    │
-└──────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Debugging Guide
-
-### How to Figure Out What Paths to Use
-
-#### Step 1: Log the Parsed Structure
-
-```typescript
-import { XMLParserService } from '@fluentcommerce/fc-connect-sdk';
-
-const xmlParser = new XMLParserService();
-const parsed = await xmlParser.parse(xmlContent);
-
-// Log the ENTIRE parsed structure
-console.log('Parsed structure:', JSON.stringify(parsed, null, 2));
-```
-
-This shows you the exact JavaScript object structure.
-
-#### Step 2: Identify What You Need
-
-Look at the output and find:
-- Where is the array of items you need to process?
-- What are the property names in the JavaScript object?
-- Are there any `@` prefixes (XML attributes)?
-
-#### Step 3: Test Your Extraction
-
-```typescript
-// Try to extract the array
-const items = parsed.inventory?.item;
-console.log('Extracted items:', items);
-
-// Check if it's an array
-console.log('Is array?', Array.isArray(items));
-
-// Normalize if needed
-const records = Array.isArray(items) ? items : items ? [items] : [];
-console.log('Normalized records:', records);
-```
-
-#### Step 4: Check a Single Record
-
-```typescript
-// Look at one record
-const firstRecord = records[0];
-console.log('First record:', JSON.stringify(firstRecord, null, 2));
-```
-
-This shows you exactly what structure the mapper will receive.
-
-#### Step 5: Match Mapping Config to Structure
-
-```typescript
-// Your mapping config paths must match the JavaScript object
-const mappingConfig = {
-  fields: {
-    // If you see: { "sku": "SKU-001" }
-    skuRef: { source: "sku" },
-
-    // If you see: { "@sku": "SKU-001" }
-    skuRef: { source: "@sku" },
-
-    // If you see: { "product": { "sku": "SKU-001" } }
-    skuRef: { source: "product.sku" }
-  }
-};
-```
-
-#### Step 6: Test Mapping on One Record
-
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const mapper = new UniversalMapper(mappingConfig);
-const result = await mapper.map(firstRecord);
-
-if (result.success) {
-  console.log('Mapping succeeded:', result.data);
-} else {
-  console.error('Mapping failed:', result.errors);
-
-  // Check each error
-  result.errors.forEach(error => {
-    console.error('Field:', error.field);
-    console.error('Message:', error.message);
-    console.error('Path:', error.path);
-  });
-}
-```
-
-### Common Debugging Mistakes
-
-#### Mistake 1: Using File Structure Instead of Object Structure
-
-**WRONG:**
-```typescript
-// CSV file has column "sku_id"
-const mappingConfig = {
-  fields: {
-    skuRef: { source: "columns.sku_id" }  // WRONG!
-  }
-};
-```
-
-**CORRECT:**
-```typescript
-// Parsed CSV gives you { sku_id: "SKU-001" }
-const mappingConfig = {
-  fields: {
-    skuRef: { source: "sku_id" }  // CORRECT
-  }
-};
-```
-
-#### Mistake 2: Using XPath for XML
-
-**WRONG:**
-```typescript
-// XML has <product><sku>SKU-001</sku></product>
-const mappingConfig = {
-  fields: {
-    skuRef: { source: "//product/sku" }  // WRONG! Not XPath
-  }
-};
-```
-
-**CORRECT:**
-```typescript
-// Parsed XML gives you { product: { sku: "SKU-001" } }
-const mappingConfig = {
-  fields: {
-    skuRef: { source: "product.sku" }  // CORRECT: JavaScript path
-  }
-};
-```
-
-#### Mistake 3: Forgetting to Normalize XML Arrays
-
-**WRONG:**
-```typescript
-const items = parsed.products.product;
-
-// If there's only one <product>, this breaks!
-for (const item of items) {  // ERROR: items is not iterable
-  await mapper.map(item);
-}
-```
-
-**CORRECT:**
-```typescript
-const items = parsed.products?.product;
-const records = Array.isArray(items) ? items : items ? [items] : [];
-
-// Now always works
-for (const record of records) {
-  await mapper.map(record);
-}
-```
-
-#### Mistake 4: Missing @ Prefix for XML Attributes
-
-**WRONG:**
-```typescript
-// XML: <item locationRef="LOC-A">
-const mappingConfig = {
-  fields: {
-    locationRef: { source: "locationRef" }  // WRONG: Missing @
-  }
-};
-```
-
-**CORRECT:**
-```typescript
-// Parsed: { "@locationRef": "LOC-A" }
-const mappingConfig = {
-  fields: {
-    locationRef: { source: "@locationRef" }  // CORRECT
-  }
-};
-```
-
-### Debugging Checklist
-
-When your mapping fails, check:
-
-- [ ] Did you log the parsed structure with `JSON.stringify(parsed, null, 2)`?
-- [ ] Did you check what gets passed to `mapper.map()` at line X?
-- [ ] Are you using JavaScript object paths, not file format paths?
-- [ ] Did you normalize XML arrays? (`Array.isArray() ? : []:[]`)
-- [ ] Are you using `@` prefix for XML attributes?
-- [ ] Did you check for typos in property names?
-- [ ] Did you verify the property actually exists in the object?
-- [ ] Are you mapping nested properties with dot notation correctly?
-
----
-
-## Real-World Example: InventoryStatus
-
-This is a real user case that demonstrates the XML parent data enrichment pattern.
-
-### The Problem
-
-User has XML with a parent-level `FacilityId` that needs to be added to each child `Item`:
-
-```xml
-<InventoryStatus>
-  <ItemInventory>
-    <FacilityId>WAREHOUSE-01</FacilityId>
-    <Item>
-      <SKU>SKU-001</SKU>
-      <Quantity>100</Quantity>
-    </Item>
-    <Item>
-      <SKU>SKU-002</SKU>
-      <Quantity>50</Quantity>
-    </Item>
-  </ItemInventory>
-</InventoryStatus>
-```
-
-**Challenge:** Each `Item` needs the `FacilityId` for the Fluent `locationRef` field, but it's at the parent `ItemInventory` level.
-
-### The Solution
-
-**Step 1: Parse XML**
-```typescript
-import { XMLParserService } from '@fluentcommerce/fc-connect-sdk';
-
-const xmlParser = new XMLParserService();
-const parsed = await xmlParser.parse(xmlContent);
-
-// Result:
-// {
-//   InventoryStatus: {
-//     ItemInventory: {
-//       FacilityId: "WAREHOUSE-01",
-//       Item: [
-//         { SKU: "SKU-001", Quantity: 100 },
-//         { SKU: "SKU-002", Quantity: 50 }
-//       ]
-//     }
-//   }
-// }
-```
-
-**Step 2: Extract Parent and Child Data**
-```typescript
-const itemInventory = parsed.InventoryStatus.ItemInventory;
-const facilityId = itemInventory.FacilityId;
-
-// Normalize array (handle single vs multiple Items)
-const items = itemInventory.Item;
-const normalizedItems = Array.isArray(items) ? items : items ? [items] : [];
-```
-
-**Step 3: Transform - Wrap Each Item with Parent Context**
-```typescript
-const enrichedRecords = normalizedItems.map(item => ({
-  itemInventory: {
-    FacilityId: facilityId,  // Parent data
-    ...item                   // Child data
-  }
-}));
-
-// Result:
-// [
-//   {
-//     itemInventory: {
-//       FacilityId: "WAREHOUSE-01",
-//       SKU: "SKU-001",
-//       Quantity: 100
-//     }
-//   },
-//   ...
-// ]
-```
-
-**Step 4: Mapping Configuration**
-```json
-{
-  "fields": {
-    "locationRef": {
-      "source": "itemInventory.FacilityId",
-      "required": true,
-      "resolver": "sdk.trim"
-    },
-    "skuRef": {
-      "source": "itemInventory.SKU",
-      "required": true,
-      "resolver": "sdk.trim"
-    },
-    "qty": {
-      "source": "itemInventory.Quantity",
-      "required": true,
-      "resolver": "sdk.parseInt"
-    }
-  }
-}
-```
-
-**Step 5: Map Each Record**
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const mapper = new UniversalMapper(mappingConfig);
-
-for (const record of enrichedRecords) {
-  const result = await mapper.map(record);
-
-  if (result.success) {
-    console.log('Mapped record:', result.data);
-    // {
-    //   locationRef: "WAREHOUSE-01",
-    //   skuRef: "SKU-001",
-    //   qty: 100
-    // }
-  } else {
-    console.error('Mapping failed:', result.errors);
-  }
-}
-```
-
-### Why This Works
-
-1. **Parsing creates JavaScript object** - XML → `{ InventoryStatus: { ItemInventory: { ... } } }`
-2. **Transformation wraps each item** - Added `FacilityId` to each item's structure
-3. **Mapping uses transformed structure** - Paths like `itemInventory.FacilityId` exist in the JavaScript object
-4. **Not XPath, not XML structure** - Pure JavaScript object property access
-
-### Complete Working Example
-
-```typescript
-import {
-  XMLParserService,
-  UniversalMapper,
-  createClient
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function processInventoryStatus(xmlContent: string) {
-  // Parse XML
-  const xmlParser = new XMLParserService();
-  const parsed = await xmlParser.parse(xmlContent);
-
-  // Extract parent data
-  const itemInventory = parsed.InventoryStatus.ItemInventory;
-  const facilityId = itemInventory.FacilityId;
-
-  // Extract and normalize items
-  const items = itemInventory.Item;
-  const normalizedItems = Array.isArray(items) ? items : items ? [items] : [];
-
-  // Transform: wrap each item with parent context
-  const enrichedRecords = normalizedItems.map(item => ({
-    itemInventory: {
-      FacilityId: facilityId,
-      ...item
-    }
-  }));
-
-  // Mapping configuration
-  const mappingConfig = {
-    fields: {
-      locationRef: {
-        source: "itemInventory.FacilityId",
-        required: true,
-        resolver: "sdk.trim"
-      },
-      skuRef: {
-        source: "itemInventory.SKU",
-        required: true,
-        resolver: "sdk.trim"
-      },
-      qty: {
-        source: "itemInventory.Quantity",
-        required: true,
-        resolver: "sdk.parseInt"
-      }
-    }
-  };
-
-  // Map each record
-  const mapper = new UniversalMapper(mappingConfig);
-  const mappedRecords = [];
-
-  for (const record of enrichedRecords) {
-    const result = await mapper.map(record);
-
-    if (result.success) {
-      mappedRecords.push(result.data);
-    } else {
-      console.error('Mapping failed for record:', record);
-      console.error('Errors:', result.errors);
-    }
-  }
-
-  // Send to Fluent Commerce
-  const client = await createClient({ config });
-
-  const job = await client.createJob({
-    name: 'inventory-status-update',
-    retailerId: process.env.FLUENT_RETAILER_ID!
-  });
-
-  await client.sendBatch(job.id, {
-    action: 'UPSERT',
-    entityType: 'INVENTORY',
-    entities: mappedRecords
-  });
-
-  console.log(`Processed ${mappedRecords.length} inventory records`);
-}
-```
-
----
-
-## Best Practices
-
-### 1. Always Log Parsed Structure First
-
-```typescript
-const parsed = await parser.parse(content);
-console.log('Parsed structure:', JSON.stringify(parsed, null, 2));
-```
-
-This eliminates guesswork about object structure.
-
-### 2. Normalize XML Arrays Immediately
-
-```typescript
-// Always do this for XML
-const items = parsed.inventory?.item;
-const records = Array.isArray(items) ? items : items ? [items] : [];
-```
-
-Prevents runtime errors when XML has only one element.
-
-### 3. Use External JSON for Mapping Configs
-
-```typescript
-// GOOD: External JSON file
-import mappingConfig from './config/inventory.json' with { type: 'json' };
-const mapper = new UniversalMapper(mappingConfig);
-```
-
-Keeps code clean and configs maintainable.
-
-### 4. Transform Before Mapping
-
-```typescript
-// Extract parent data
-const facilityId = parsed.warehouse.id;
-
-// Transform records to include parent data
-const enrichedRecords = items.map(item => ({
-  ...item,
-  facilityId: facilityId
-}));
-
-// Now mapping can reference facilityId
-```
-
-Don't try to access parent data during mapping - transform first.
-
-### 5. Test Mapping on One Record First
-
-```typescript
-// Test with first record
-const testRecord = records[0];
-const result = await mapper.map(testRecord);
-
-if (!result.success) {
-  console.error('Mapping errors:', result.errors);
-  // Fix mapping config before processing all records
-}
-```
-
-Catch mapping errors early.
-
-### 6. Use Descriptive Property Names in Transformations
-
-```typescript
-// GOOD: Clear structure
-const enrichedRecords = items.map(item => ({
-  itemInventory: {
-    FacilityId: facilityId,
-    ...item
-  }
-}));
-
-// BAD: Unclear structure
-const enrichedRecords = items.map(item => ({
-  ...item,
-  f: facilityId  // What is 'f'?
-}));
-```
-
-Makes mapping configs easier to understand.
-
-### 7. Document Your Transformation Logic
-
-```typescript
-// Transform XML structure to include parent FacilityId in each item
-// Original: { ItemInventory: { FacilityId, Item: [...] } }
-// Result: [{ itemInventory: { FacilityId, SKU, Qty } }]
-const enrichedRecords = normalizedItems.map(item => ({
-  itemInventory: {
-    FacilityId: facilityId,
-    ...item
-  }
-}));
-```
-
-Future you (or your team) will thank you.
-
-### 8. Parse First, Then Decide on Transformation
-
-1. **Parse the file format**
-   - Use the appropriate parser service
-   - Log the parsed structure
-
-2. **Inspect the parsed structure**
-   - Understand the data hierarchy
-   - Identify shared parent data
-   - Check for array normalization needs
-
-3. **Decide if transformation is needed**
-   - Can you map directly?
-   - Do you need to enrich child records with parent data?
-   - Is the structure compatible with your mapping config?
-
-### 9. Keep Transformation Minimal
-
-- Only transform when necessary
-- Use resolvers for simple transformations when possible
-- Prefer code transformation for complex restructuring
-
-### 10. Handle Edge Cases
-
-- Single vs multiple elements (XML)
-- Missing fields
-- Null/undefined values
-- Empty arrays
-
----
-
-## Common Mistakes to Avoid
-
-### Mistake 1: Using File Format Syntax in Mapping Config
-
-**WRONG:**
-```typescript
-// Trying to use XPath in mapping config
-const mappingConfig = {
-  fields: {
-    skuRef: { source: "//product/sku" }  // This is XPath, not JavaScript
-  }
-};
-```
-
-**CORRECT:**
-```typescript
-// Use JavaScript object path
-const mappingConfig = {
-  fields: {
-    skuRef: { source: "product.sku" }  // JavaScript property access
-  }
-};
-```
-
-### Mistake 2: Mapping Before Transforming
-
-**WRONG:**
-```typescript
-// Trying to access parent data in mapping config
-const mappingConfig = {
-  fields: {
-    // This won't work - FacilityId is at parent level
-    locationRef: { source: "FacilityId" }  // Item doesn't have FacilityId
-  }
-};
-
-for (const item of items) {
-  await mapper.map(item);  // Fails - item doesn't have FacilityId
-}
-```
-
-**CORRECT:**
-```typescript
-// Transform FIRST to add parent data
-const enrichedRecords = items.map(item => ({
-  ...item,
-  FacilityId: facilityId  // Add parent data
-}));
-
-// NOW mapping can access FacilityId
-const mappingConfig = {
-  fields: {
-    locationRef: { source: "FacilityId" }  // Now it exists!
-  }
-};
-```
-
-### Mistake 3: Not Normalizing XML Arrays
-
-**WRONG:**
-```typescript
-const items = parsed.products.product;
-
-for (const item of items) {  // Breaks if only one <product>!
-  await mapper.map(item);
-}
-```
-
-**CORRECT:**
-```typescript
-const items = parsed.products?.product;
-const records = Array.isArray(items) ? items : items ? [items] : [];
-
-for (const record of records) {  // Always works
-  await mapper.map(record);
-}
-```
-
-### Mistake 4: Forgetting @ Prefix for XML Attributes
-
-**WRONG:**
-```typescript
-// XML: <item locationRef="LOC-A" skuRef="SKU-001">
-const mappingConfig = {
-  fields: {
-    locationRef: { source: "locationRef" },  // Missing @
-    skuRef: { source: "skuRef" }             // Missing @
-  }
-};
-```
-
-**CORRECT:**
-```typescript
-// Parsed object has: { "@locationRef": "LOC-A", "@skuRef": "SKU-001" }
-const mappingConfig = {
-  fields: {
-    locationRef: { source: "@locationRef" },  // @ prefix required
-    skuRef: { source: "@skuRef" }
-  }
-};
-```
-
-### Mistake 5: Mapping Nested Source to Flat Target Without Extraction
-
-**WRONG:**
-```typescript
-// Source: { warehouse: { inventory: { items: [...] } } }
-const items = parsed.warehouse.inventory.items;
-
-// Mapping without extraction
-const mappingConfig = {
-  fields: {
-    skuRef: { source: "warehouse.inventory.items.sku" }  // Path too long
-  }
-};
-```
-
-**CORRECT:**
-```typescript
-// Extract the array first
-const items = parsed.warehouse.inventory.items;
-
-// Now map each item directly
-const mappingConfig = {
-  fields: {
-    skuRef: { source: "sku" }  // Clean path
-  }
-};
-
-for (const item of items) {
-  await mapper.map(item);
-}
-```
-
-### Mistake 6: Assuming Parsed Data Matches File Structure
-
-**WRONG:**
-```typescript
-// CSV has columns: sku_id, quantity, location
-// Assuming mapping uses column positions
-const mappingConfig = {
-  fields: {
-    skuRef: { source: "columns[0]" }  // WRONG! Not how it works
-  }
-};
-```
-
-**CORRECT:**
-```typescript
-// CSV parser creates: { sku_id: "...", quantity: "...", location: "..." }
-const mappingConfig = {
-  fields: {
-    skuRef: { source: "sku_id" }  // Use property name
-  }
-};
-```
-
----
-
-## Related Documentation
-
-- [Mapping Foundations](../auto-pagination/modules/auto-pagination-01-foundations.md) - Core mapping concepts
-- [Universal Mapper Guide](mapping-readme.md) - Complete mapping patterns
-- [SDK Resolvers](./resolvers/mapping-resolvers-readme.md) - Built-in field transformations
-- [XML Parser Guide](../parsers/modules/02-core-guides-parsers-04-xml-parser.md) - XML parsing details
-- [CSV Parser Guide](../parsers/modules/02-core-guides-parsers-02-csv-parser.md) - CSV parsing details
-- [JSON Parser Guide](../parsers/modules/02-core-guides-parsers-03-json-parser.md) - JSON parsing details
-
----
-
-## FAQ
-
-**Q: Do I need to know XPath/JSONPath/SQL to write mapping configs?**
-
-A: No! You only need to know JavaScript object property access. Use dot notation for nested properties and `@` prefix for XML attributes.
-
-**Q: Why does my XML mapping fail when there's only one element?**
-
-A: XML parsers return an object for a single element and an array for multiple elements. Always normalize with: `Array.isArray(items) ? items : items ? [items] : []`
-
-**Q: Can I use the same mapping config for CSV, JSON, and XML?**
-
-A: Only if they produce the same JavaScript object structure after parsing. Usually, you need different configs because each format has different property names.
-
-**Q: How do I map parent data to child records?**
-
-A: Transform the data BEFORE mapping. Extract parent data, then wrap each child record with the parent data. See the [InventoryStatus example](#real-world-example-inventorystatus).
-
-**Q: What's the difference between `"source": "sku"` and `"source": "@sku"`?**
-
-A: `"sku"` is a child element in XML (or object property). `"@sku"` is an XML attribute. The XML parser adds the `@` prefix to attributes in the JavaScript object.
-
-**Q: Can I access nested properties with bracket notation?**
-
-A: Use dot notation for paths: `"source": "product.details.sku"`. The mapper handles the property access internally.
-
-**Q: How do I debug mapping errors?**
-
-A: Log the exact object you pass to `mapper.map()` with `JSON.stringify(object, null, 2)`. Compare property names in the log to your mapping config `source` paths.
-
----
-
-**Last Updated:** 2025-11-03
-
-**Related Guides:**
-- [Universal Mapping Guide](mapping-readme.md)
-- [SDK Resolvers](./resolvers/mapping-resolvers-readme.md)
-- [Parsers Guide](../parsers/parsers-readme.md)
+---
+title: Understanding Mapping - JavaScript Object Paths
+description: Comprehensive guide to how mapping configurations work with parsed data structures
+category: mapping
+priority: high
+related:
+  - mapping/modules/01-foundations.md
+  - mapping/modules/06-helpers-resolvers.md
+  - parsers/modules/04-xml-parser.md
+---
+
+# Understanding Mapping: JavaScript Object Paths
+
+**Critical Concept:** Mapping paths reference **JavaScript object structure**, not source file format.
+
+---
+
+## Table of Contents
+
+1. [Core Concept: Mapping AFTER Parsing](#core-concept-mapping-after-parsing)
+2. [The ETL Pattern](#the-etl-pattern)
+3. [Format Examples](#format-examples)
+   - [CSV Examples](#csv-examples)
+   - [JSON Examples](#json-examples)
+   - [XML Examples](#xml-examples)
+   - [Complex XML with Attributes](#complex-xml-with-attributes)
+   - [Complex JSON with Deep Nesting](#complex-json-with-deep-nesting)
+   - [XML with Shared Parent Data](#xml-with-shared-parent-data)
+4. [Common Transformation Patterns](#common-transformation-patterns)
+5. [Visual Flow Diagrams](#visual-flow-diagrams)
+6. [Debugging Guide](#debugging-guide)
+7. [Real-World Example: InventoryStatus](#real-world-example-inventorystatus)
+8. [Best Practices](#best-practices)
+9. [Common Mistakes to Avoid](#common-mistakes-to-avoid)
+
+---
+
+## Core Concept: Mapping AFTER Parsing
+
+### The Key Principle
+
+**Mapping configurations map JAVASCRIPT OBJECTS, not file formats.**
+
+When you write a mapping configuration like this:
+
+```json
+{
+  "fields": {
+    "skuRef": { "source": "product.sku" }
+  }
+}
+```
+
+The path `"product.sku"` refers to **JavaScript object property access**, not:
+- NOT CSV column names directly
+- NOT XPath expressions
+- NOT JSONPath queries
+- NOT file format structure
+
+### Why This Matters
+
+Understanding this principle prevents confusion when working with different data sources:
+
+```typescript
+// This is what the mapper receives - ALWAYS a JavaScript object
+const jsObject = {
+  product: {
+    sku: "SKU-001",
+    name: "Widget"
+  }
+};
+
+// Your mapping config uses JavaScript paths
+const mappingConfig = {
+  fields: {
+    skuRef: { source: "product.sku" }  // JavaScript object path
+  }
+};
+```
+
+The mapper **NEVER** sees the original CSV, XML, or JSON file. It only sees the JavaScript object that results from parsing and transformation.
+
+---
+
+## The ETL Pattern
+
+All SDK data flows follow this standard Extract-Transform-Load pattern:
+
+```mermaid
+flowchart TD
+    A[Source File<br/>CSV/JSON/XML] --> B[Step 1: Parse<br/>→ JavaScript Objects]
+    B --> C[Step 2: Extract/Normalize<br/>→ Array of Records]
+    C --> D[Step 3: Map Each Record<br/>→ Fluent Format]
+    D --> E[Step 4: Load<br/>→ Batch API/GraphQL]
+    
+    style A fill:#e1f5ff
+    style B fill:#fff4e1
+    style C fill:#fff4e1
+    style D fill:#e8f5e9
+    style E fill:#f3e5f5
+```
+
+**Text Version:**
+```
+Source File (CSV/JSON/XML)
+  ↓
+[Step 1] Parse → JavaScript Objects
+  ↓
+[Step 2] Extract/Normalize → Array of Records
+  ↓
+[Step 3] Map Each Record → Fluent Format
+  ↓
+[Step 4] Load → Batch API/GraphQL
+```
+
+**Detailed Breakdown:**
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         ETL WORKFLOW PATTERN                                │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+Step 1: SOURCE FILE
+┌────────────────────┐
+│  inventory.csv     │   File format: CSV, JSON, XML, Parquet
+│  inventory.json    │   Location: S3, SFTP, Local
+│  inventory.xml     │
+└────────────────────┘
+         │
+         │ Read from data source
+         ↓
+Step 2: PARSE → JavaScript Objects
+┌────────────────────┐
+│  CSVParserService  │   Converts file format to JavaScript
+│  XMLParserService  │   Result: Array of objects or nested structure
+│  JSONParserService │
+│  ParquetParser     │
+└────────────────────┘
+         │
+         │ Parser output: JavaScript objects
+         ↓
+Step 3: EXTRACT/NORMALIZE → Array of Records
+┌────────────────────┐
+│  Extract items     │   Navigate to the data you need
+│  Normalize arrays  │   Flatten nested structures
+│  Enrich with       │   Add shared context data
+│  parent data       │
+└────────────────────┘
+         │
+         │ What gets passed to mapper
+         ↓
+Step 4: MAP EACH RECORD → Fluent Format
+┌────────────────────┐
+│  UniversalMapper   │   Maps JavaScript object paths to Fluent fields
+│  or                │   Uses mapping configuration
+│  GraphQLMutation   │   Applies resolvers for transformations
+│  Mapper            │
+└────────────────────┘
+         │
+         │ Fluent-formatted data
+         ↓
+Step 5: LOAD → Fluent Commerce
+┌────────────────────┐
+│  Batch API         │   Send data to Fluent
+│  Event API         │   create/update entities
+│  GraphQL Mutations │
+└────────────────────┘
+```
+
+**Key Insight:** Mapping (Step 4) operates on JavaScript objects from Step 3, not on the original file from Step 1. **Mapping configuration matches Step 3** - the structure you pass to `mapper.map()`, which is the result of Step 2.
+
+---
+
+## Format Examples
+
+### CSV Examples
+
+#### Simple CSV: No Transformation Needed
+
+**Original CSV File:**
+```csv
+sku_id,quantity,location_code,status
+SKU-001,100,LOC-A,AVAILABLE
+SKU-002,50,LOC-B,RESERVED
+```
+
+**Step 1: Parse**
+```typescript
+const csvParser = new CSVParserService();
+const records = await csvParser.parse(csvContent);
+```
+
+**Step 2: Parsed JavaScript Object (CSVParserService output)**
+```javascript
+[
+  {
+    sku_id: "SKU-001",
+    quantity: "100",        // Note: strings by default
+    location_code: "LOC-A",
+    status: "AVAILABLE"
+  },
+  {
+    sku_id: "SKU-002",
+    quantity: "50",
+    location_code: "LOC-B",
+    status: "RESERVED"
+  }
+]
+```
+
+**Step 3: Extraction (No transformation needed)**
+```javascript
+// CSV parser already gives us an array of flat objects
+const records = parsedCsv; // Use directly
+```
+
+**Step 4: Mapping Configuration**
+```json
+{
+  "fields": {
+    "skuRef": {
+      "source": "sku_id",
+      "required": true
+    },
+    "qty": {
+      "source": "quantity",
+      "resolver": "sdk.parseInt"
+    },
+    "locationRef": {
+      "source": "location_code"
+    },
+    "status": {
+      "source": "status",
+      "resolver": "sdk.uppercase"
+    }
+  }
+}
+```
+
+**What gets passed to mapper.map():**
+```javascript
+// For each record in the array:
+await mapper.map({
+  sku_id: "SKU-001",
+  quantity: "100",
+  location_code: "LOC-A",
+  status: "AVAILABLE"
+});
+```
+
+**Key Points:**
+- CSV columns become JavaScript object keys
+- Column names in file match `source` paths in mapping config
+- No dot notation needed (flat structure)
+
+---
+
+#### Complex CSV: Requires Transformation
+
+**CSV File:**
+```csv
+ref,price_default_currency,price_default_value,price_special_currency,price_special_value
+PROD-001,USD,50.00,USD,35.00
+```
+
+**Step 1: Parse**
+```typescript
+const csvParser = new CSVParserService();
+const records = await csvParser.parse(csvContent);
+```
+
+**Parsed JavaScript Object:**
+```javascript
+[
+  { 
+    ref: "PROD-001", 
+    price_default_currency: "USD", 
+    price_default_value: "50.00",
+    price_special_currency: "USD",
+    price_special_value: "35.00"
+  }
+]
+```
+
+**Step 2: Extract/Normalize**
+```typescript
+// CSV is flat, but we need nested structure for prices
+// Two options:
+
+// Option A: Transform in code before mapping
+const records = parsed.map(row => ({
+  ref: row.ref,
+  price: [
+    { type: "DEFAULT", currency: row.price_default_currency, value: row.price_default_value },
+    { type: "SPECIAL", currency: row.price_special_currency, value: row.price_special_value }
+  ]
+}));
+// Result: [{ ref: "PROD-001", price: [{ type: "DEFAULT", ... }, { type: "SPECIAL", ... }] }]
+
+// Option B: Use custom resolver in mapping (see Step 3)
+```
+
+**Step 3: Map**
+
+**Option A - After Code Transformation:**
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    ref: { source: "ref" },
+    price: { 
+      source: "price",           // ← Reads from transformed record.price
+      isArray: true,
+      fields: {
+        type: { source: "type" },
+        currency: { source: "currency" },
+        value: { source: "value", resolver: "sdk.parseFloat" }
+      }
+    }
+  }
+});
+
+for (const record of records) {
+  const result = await mapper.map(record);  // ← Pass transformed structure
+}
+```
+
+**Option B - Using Custom Resolver:**
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    ref: { source: "ref" },
+    price: {
+      resolver: "custom.buildPriceArray",  // ← Custom resolver builds nested structure
+      // No source - resolver receives full record
+    }
+  }
+}, {
+  customResolvers: {
+    'custom.buildPriceArray': (value, sourceData) => {
+      // sourceData = full CSV row
+      return [
+        { 
+          type: "DEFAULT", 
+          currency: sourceData.price_default_currency, 
+          value: parseFloat(sourceData.price_default_value) 
+        },
+        { 
+          type: "SPECIAL", 
+          currency: sourceData.price_special_currency, 
+          value: parseFloat(sourceData.price_special_value) 
+        }
+      ];
+    }
+  }
+});
+
+for (const record of records) {
+  const result = await mapper.map(record);  // ← Pass flat CSV row
+}
+```
+
+**Mapping Matches:** 
+- Option A: Transformed structure (`record.price[]`)
+- Option B: Flat CSV row (`record.price_default_currency` via resolver)
+
+---
+
+### JSON Examples
+
+#### Simple JSON: Array Extraction Needed
+
+**Original JSON File:**
+```json
+{
+  "timestamp": "2025-01-15T10:00:00Z",
+  "warehouse": "WH-01",
+  "inventory": [
+    {
+      "product_code": "SKU-001",
+      "stock_level": 100,
+      "location": "A1"
+    },
+    {
+      "product_code": "SKU-002",
+      "stock_level": 50,
+      "location": "B2"
+    }
+  ]
+}
+```
+
+**Step 1: Parse**
+```typescript
+const jsonParser = new JSONParserService();
+const parsed = await jsonParser.parse(jsonContent);
+```
+
+**Step 2: Parsed JavaScript Object (JSONParserService output)**
+```javascript
+{
+  timestamp: "2025-01-15T10:00:00Z",
+  warehouse: "WH-01",
+  inventory: [
+    {
+      product_code: "SKU-001",
+      stock_level: 100,
+      location: "A1"
+    },
+    {
+      product_code: "SKU-002",
+      stock_level: 50,
+      location: "B2"
+    }
+  ]
+}
+```
+
+**Step 3: Extraction**
+```javascript
+// Extract the array we want to process
+const parsed = await jsonParser.parse(jsonContent);
+const records = parsed.inventory; // Extract nested array
+
+// Now we have an array of inventory items
+```
+
+**Step 4: Mapping Configuration**
+```json
+{
+  "fields": {
+    "skuRef": {
+      "source": "product_code",
+      "required": true
+    },
+    "qty": {
+      "source": "stock_level",
+      "resolver": "sdk.parseInt"
+    },
+    "locationRef": {
+      "source": "location"
+    }
+  }
+}
+```
+
+**What gets passed to mapper.map():**
+```javascript
+// For each item in the inventory array:
+await mapper.map({
+  product_code: "SKU-001",
+  stock_level: 100,
+  location: "A1"
+});
+```
+
+**Key Points:**
+- JSON parsing preserves nested structure
+- You extract the array you need (`parsed.inventory`)
+- Mapping config references the **extracted object** structure, not the full JSON
+
+---
+
+#### Complex JSON: Nested Structure with Transformation Options
+
+**JSON File:**
+```json
+{
+  "inventory": {
+    "warehouse": "WH-001",
+    "items": [
+      {
+        "product": {
+          "sku": "SKU-001",
+          "details": {
+            "name": "Product 1"
+          }
+        },
+        "stock": {
+          "quantity": 100,
+          "status": "available"
+        }
+      },
+      {
+        "product": {
+          "sku": "SKU-002",
+          "details": {
+            "name": "Product 2"
+          }
+        },
+        "stock": {
+          "quantity": 50,
+          "status": "reserved"
+        }
+      }
+    ]
+  }
+}
+```
+
+**Step 1: Parse**
+```typescript
+const jsonParser = new JSONParserService();
+const parsed = await jsonParser.parse(jsonContent);
+```
+
+**Parsed JavaScript Object:**
+```javascript
+{
+  inventory: {
+    warehouse: "WH-001",
+    items: [
+      {
+        product: { sku: "SKU-001", details: { name: "Product 1" } },
+        stock: { quantity: 100, status: "available" }
+      },
+      {
+        product: { sku: "SKU-002", details: { name: "Product 2" } },
+        stock: { quantity: 50, status: "reserved" }
+      }
+    ]
+  }
+}
+```
+
+**Step 2: Extract/Normalize**
+```typescript
+// Extract items array, and add warehouse from parent
+const warehouse = parsed.inventory.warehouse;
+const items = parsed.inventory.items;
+
+// Option A: Transform to add warehouse to each item
+const records = items.map(item => ({
+  warehouse: warehouse,      // ← Add shared data
+  product: item.product,
+  stock: item.stock
+}));
+// Result: [{ warehouse: "WH-001", product: {...}, stock: {...} }, ...]
+
+// Option B: Pass full structure and use dot notation in mapping
+```
+
+**Step 3: Map**
+
+**Option A - After Transformation:**
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    locationRef: { source: "warehouse" },              // ← From transformed record
+    productRef: { source: "product.sku" },            // ← From transformed record
+    quantity: { source: "stock.quantity" },            // ← From transformed record
+    status: { source: "stock.status" }                 // ← From transformed record
+  }
+});
+
+for (const record of records) {
+  const result = await mapper.map(record);  // ← Pass transformed structure
+}
+```
+
+**Option B - Direct Mapping (No Transformation):**
+```typescript
+// Map each item directly, accessing parent via root context
+const mapper = new UniversalMapper({
+  fields: {
+    items: {
+      source: "inventory.items",                      // ← Extract items array
+      isArray: true,                                  // ← Iterate over items
+      fields: {
+        locationRef: { 
+          // Access parent warehouse from root context
+          // Note: You may need a custom resolver to access parent data
+          resolver: "custom.getWarehouse"  // Custom resolver accesses root
+        },
+        productRef: { source: "product.sku" },       // ← From current item
+        quantity: { source: "stock.quantity" },      // ← From current item
+        status: { source: "stock.status" }           // ← From current item
+      }
+    }
+  }
+});
+
+const result = await mapper.map(parsed);  // ← Pass full parsed structure
+```
+
+**Mapping Matches:**
+- Option A: Transformed structure (`record.warehouse`, `record.product.sku`)
+- Option B: Full parsed structure (`inventory.items[]`, requires custom resolver for parent access)
+
+---
+
+#### Simple XML: Array Normalization Required
+
+**Original XML File:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<products>
+  <product>
+    <sku>SKU-001</sku>
+    <name>Product 1</name>
+    <quantity>100</quantity>
+    <location>LOC-A</location>
+  </product>
+  <product>
+    <sku>SKU-002</sku>
+    <name>Product 2</name>
+    <quantity>50</quantity>
+    <location>LOC-B</location>
+  </product>
+</products>
+```
+
+**Step 1: Parse**
+```typescript
+const xmlParser = new XMLParserService();
+const parsed = await xmlParser.parse(xmlContent);
+```
+
+**Step 2: Parsed JavaScript Object (XMLParserService output)**
+```javascript
+{
+  products: {
+    product: [  // Multiple <product> elements → array
+      {
+        sku: "SKU-001",
+        name: "Product 1",
+        quantity: 100,    // Auto-parsed as number
+        location: "LOC-A"
+      },
+      {
+        sku: "SKU-002",
+        name: "Product 2",
+        quantity: 50,
+        location: "LOC-B"
+      }
+    ]
+  }
+}
+```
+
+**CRITICAL: XML Array Normalization**
+
+XML parsing has a gotcha: single vs multiple elements
+```javascript
+// Multiple <product> elements
+parsed.products.product  // → array []
+
+// Single <product> element (gotcha!)
+parsed.products.product  // → object {} (NOT array!)
+```
+
+**Step 3: Extraction with Normalization**
+```javascript
+const parsed = await xmlParser.parse(xmlContent);
+
+// ALWAYS normalize XML arrays
+const items = parsed.products?.product;
+const records = Array.isArray(items) ? items : items ? [items] : [];
+
+// Now records is ALWAYS an array
+```
+
+**Step 4: Mapping Configuration**
+```json
+{
+  "fields": {
+    "skuRef": {
+      "source": "sku",
+      "required": true
+    },
+    "name": {
+      "source": "name"
+    },
+    "qty": {
+      "source": "quantity",
+      "resolver": "sdk.parseInt"
+    },
+    "locationRef": {
+      "source": "location"
+    }
+  }
+}
+```
+
+**What gets passed to mapper.map():**
+```javascript
+// For each normalized item:
+await mapper.map({
+  sku: "SKU-001",
+  name: "Product 1",
+  quantity: 100,
+  location: "LOC-A"
+});
+```
+
+**Key Points:**
+- XML element names become JavaScript object keys
+- Multiple elements create arrays
+- Single element creates object (must normalize!)
+- Always use: `Array.isArray(items) ? items : items ? [items] : []`
+
+---
+
+### Complex XML with Attributes
+
+#### XML Attributes Use @ Prefix
+
+**Original XML File:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<inventory>
+  <item locationRef="LOC-A" skuRef="SKU-001">
+    <qty>100</qty>
+    <status>AVAILABLE</status>
+    <expectedOn>2025-01-20</expectedOn>
+  </item>
+  <item locationRef="LOC-B" skuRef="SKU-002">
+    <qty>50</qty>
+    <status>RESERVED</status>
+  </item>
+</inventory>
+```
+
+**Step 2: Parsed JavaScript Object (XMLParserService output)**
+```javascript
+{
+  inventory: {
+    item: [
+      {
+        "@locationRef": "LOC-A",   // Attributes use @ prefix
+        "@skuRef": "SKU-001",
+        qty: 100,
+        status: "AVAILABLE",
+        expectedOn: "2025-01-20"
+  },
+      {
+        "@locationRef": "LOC-B",
+        "@skuRef": "SKU-002",
+        qty: 50,
+        status: "RESERVED"
+      }
+    ]
+  }
+}
+```
+
+**Step 3: Extraction with Normalization**
+```javascript
+const parsed = await xmlParser.parse(xmlContent);
+
+// Normalize array
+const items = parsed.inventory?.item;
+const records = Array.isArray(items) ? items : items ? [items] : [];
+```
+
+**Step 4: Mapping Configuration**
+```json
+{
+  "fields": {
+    "locationRef": {
+      "source": "@locationRef",
+      "required": true,
+      "resolver": "sdk.trim"
+    },
+    "skuRef": {
+      "source": "@skuRef",
+      "required": true,
+      "resolver": "sdk.trim"
+    },
+    "qty": {
+      "source": "qty",
+      "required": true,
+      "resolver": "sdk.parseInt"
+    },
+    "status": {
+      "source": "status",
+      "required": true,
+      "resolver": "sdk.uppercase"
+    },
+    "expectedOn": {
+      "source": "expectedOn",
+      "resolver": "sdk.formatDate"
+    }
+  }
+}
+```
+
+**What gets passed to mapper.map():**
+```javascript
+// For each normalized item:
+await mapper.map({
+  "@locationRef": "LOC-A",    // @ prefix in JavaScript object
+  "@skuRef": "SKU-001",
+  qty: 100,
+  status: "AVAILABLE",
+  expectedOn: "2025-01-20"
+});
+```
+
+**Key Points:**
+- XML attributes use `@` prefix in parsed JavaScript object
+- Mapping config uses `@` prefix to reference attributes
+- This is a JavaScript object key, not XPath syntax
+- Elements without `@` are child elements
+
+---
+
+#### Complex XML: Orders with Attributes and Transformation Options
+
+**XML File:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Orders>
+  <Order id="ORD-001" orderDate="2025-01-22">
+    <Customer>
+      <Name>John Doe</Name>
+      <Email>john@example.com</Email>
+    </Customer>
+    <Items>
+      <Item sku="PROD-001" qty="2">
+        <Price>29.99</Price>
+      </Item>
+      <Item sku="PROD-002" qty="1">
+        <Price>49.99</Price>
+      </Item>
+    </Items>
+  </Order>
+  <Order id="ORD-002" orderDate="2025-01-23">
+    <Customer>
+      <Name>Jane Smith</Name>
+      <Email>jane@example.com</Email>
+    </Customer>
+    <Items>
+      <Item sku="PROD-003" qty="3">
+        <Price>19.99</Price>
+      </Item>
+    </Items>
+  </Order>
+</Orders>
+```
+
+**Step 1: Parse (with attributes)**
+```typescript
+const xmlParser = new XMLParserService();
+const parsed = await xmlParser.parse(xmlContent, { includeAttributes: true });
+```
+
+**Parsed JavaScript Object:**
+```javascript
+{
+  Orders: {
+    Order: [
+      {
+        "@id": "ORD-001",                    // ← Attributes prefixed with @
+        "@orderDate": "2025-01-22",
+        Customer: {
+          Name: "John Doe",
+          Email: "john@example.com"
+        },
+        Items: {
+          Item: [
+            {
+              "@sku": "PROD-001",            // ← Attributes prefixed with @
+              "@qty": "2",
+              Price: "29.99"
+            },
+            {
+              "@sku": "PROD-002",
+              "@qty": "1",
+              Price: "49.99"
+            }
+          ]
+        }
+      },
+      {
+        "@id": "ORD-002",
+        "@orderDate": "2025-01-23",
+        Customer: { ... },
+        Items: { ... }
+      }
+    ]
+  }
+}
+```
+
+**Step 2: Extract/Normalize**
+```typescript
+const orders = parsed.Orders.Order;
+const records = Array.isArray(orders) ? orders : orders ? [orders] : [];
+// Result: [{ "@id": "ORD-001", "@orderDate": "...", Customer: {...}, Items: {...} }, ...]
+```
+
+**Step 3: Map**
+
+**Option A: Map Each Order, Then Items Separately**
+```typescript
+const orderMapper = new UniversalMapper({
+  fields: {
+    orderRef: { source: "@id" },                        // ← XML attribute
+    orderDate: { source: "@orderDate", resolver: "sdk.parseDate" },
+    customerName: { source: "Customer.Name" },
+    customerEmail: { source: "Customer.Email" },
+    items: {
+      source: "Items.Item",                              // ← Extract items array
+      isArray: true,                                     // ← Iterate over items
+      fields: {
+        productRef: { source: "@sku" },                  // ← Attribute from item
+        quantity: { source: "@qty", resolver: "sdk.parseInt" },
+        price: { source: "Price", resolver: "sdk.parseFloat" }
+      }
+    }
+  }
+});
+
+for (const order of records) {
+  const result = await orderMapper.map({ Order: order });  // ← Wrap for context
+  // Mapping: Order.@id, Order.Customer.Name, Order.Items.Item[].@sku
+}
+```
+
+**Option B: Transform First, Then Map**
+```typescript
+// Extract items and flatten with order data
+const allItems = [];
+for (const order of records) {
+  const orderId = order["@id"];
+  const orderDate = order["@orderDate"];
+  const items = Array.isArray(order.Items.Item) 
+    ? order.Items.Item 
+    : order.Items.Item 
+    ? [order.Items.Item] 
+    : [];
+  
+  for (const item of items) {
+    allItems.push({
+      orderId: orderId,                    // ← Add from parent
+      orderDate: orderDate,                // ← Add from parent
+      sku: item["@sku"],                   // ← From item attribute
+      qty: item["@qty"],                   // ← From item attribute
+      price: item.Price                    // ← From item element
+    });
+  }
+}
+
+// Now map flattened structure
+const itemMapper = new UniversalMapper({
+  fields: {
+    orderRef: { source: "orderId" },       // ← From transformed structure
+    orderDate: { source: "orderDate", resolver: "sdk.parseDate" },
+    productRef: { source: "sku" },         // ← From transformed structure
+    quantity: { source: "qty", resolver: "sdk.parseInt" },
+    price: { source: "price", resolver: "sdk.parseFloat" }
+  }
+});
+
+for (const item of allItems) {
+  const result = await itemMapper.map(item);  // ← Pass transformed structure
+}
+```
+
+**Mapping Matches:**
+- Option A: Parsed XML structure (`Order.@id`, `Order.Items.Item[].@sku`)
+- Option B: Transformed structure (`item.orderId`, `item.sku`)
+
+---
+
+### Complex JSON with Deep Nesting
+
+#### Nested Path Navigation
+
+**Original JSON File:**
+```json
+{
+  "warehouse": {
+    "id": "WH-01",
+    "location": {
+      "code": "LOC-A",
+      "name": "Warehouse A"
+    },
+    "inventory": {
+      "items": [
+        {
+          "product": {
+            "sku": "SKU-001",
+            "details": {
+              "name": "Widget",
+              "category": "Electronics"
+            }
+          },
+          "stock": {
+            "available": 100,
+            "reserved": 20
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+**Step 2: Parsed JavaScript Object (JSONParserService output)**
+```javascript
+{
+  warehouse: {
+    id: "WH-01",
+    location: {
+      code: "LOC-A",
+      name: "Warehouse A"
+    },
+    inventory: {
+      items: [
+        {
+          product: {
+            sku: "SKU-001",
+            details: {
+              name: "Widget",
+              category: "Electronics"
+            }
+          },
+          stock: {
+            available: 100,
+            reserved: 20
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+**Step 3: Extraction**
+```javascript
+const parsed = await jsonParser.parse(jsonContent);
+
+// Extract the nested array
+const records = parsed.warehouse.inventory.items;
+
+// For shared context, store parent data
+const warehouseCode = parsed.warehouse.location.code;
+```
+
+**Step 4: Mapping Configuration**
+```json
+{
+  "fields": {
+    "skuRef": {
+      "source": "product.sku",
+      "required": true
+    },
+    "name": {
+      "source": "product.details.name"
+    },
+    "qty": {
+      "source": "stock.available",
+      "resolver": "sdk.parseInt"
+    },
+    "locationRef": {
+      "value": "LOC-A"
+    }
+  }
+}
+```
+
+**What gets passed to mapper.map():**
+```javascript
+// For each item in the items array:
+await mapper.map({
+  product: {
+    sku: "SKU-001",
+    details: {
+      name: "Widget",
+      category: "Electronics"
+    }
+  },
+  stock: {
+    available: 100,
+    reserved: 20
+  }
+});
+```
+
+**Key Points:**
+- Dot notation navigates nested JavaScript objects
+- `"product.sku"` becomes `obj.product.sku` in JavaScript
+- `"product.details.name"` becomes `obj.product.details.name`
+- You can reference any depth of nesting
+
+---
+
+### XML with Shared Parent Data
+
+#### Real-World Pattern: Enriching Child Records
+
+This is a common pattern where parent-level data needs to be added to each child record.
+
+**Original XML File:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<InventoryStatus>
+  <ItemInventory>
+    <FacilityId>WAREHOUSE-01</FacilityId>
+    <Item>
+      <SKU>SKU-001</SKU>
+      <Quantity>100</Quantity>
+      <Status>AVAILABLE</Status>
+    </Item>
+    <Item>
+      <SKU>SKU-002</SKU>
+      <Quantity>50</Quantity>
+      <Status>RESERVED</Status>
+    </Item>
+  </ItemInventory>
+</InventoryStatus>
+```
+
+**Step 2: Parsed JavaScript Object (XMLParserService output)**
+```javascript
+{
+  InventoryStatus: {
+    ItemInventory: {
+      FacilityId: "WAREHOUSE-01",
+      Item: [  // Multiple Items
+        {
+          SKU: "SKU-001",
+          Quantity: 100,
+          Status: "AVAILABLE"
+        },
+        {
+          SKU: "SKU-002",
+          Quantity: 50,
+          Status: "RESERVED"
+        }
+      ]
+    }
+  }
+}
+```
+
+**Step 3: Transformation - Enrich Each Item**
+```javascript
+const parsed = await xmlParser.parse(xmlContent);
+
+// Extract parent data
+const facilityId = parsed.InventoryStatus.ItemInventory.FacilityId;
+
+// Extract items
+const items = parsed.InventoryStatus.ItemInventory.Item;
+const normalizedItems = Array.isArray(items) ? items : items ? [items] : [];
+
+// TRANSFORM: Wrap each item with facility context
+const enrichedRecords = normalizedItems.map(item => ({
+  itemInventory: {
+    FacilityId: facilityId,  // Add parent data to each item
+    ...item                   // Spread item properties
+  }
+}));
+
+// Now each record has the FacilityId embedded
+```
+
+**Result of Transformation:**
+```javascript
+[
+  {
+    itemInventory: {
+      FacilityId: "WAREHOUSE-01",  // Parent data added
+      SKU: "SKU-001",
+      Quantity: 100,
+      Status: "AVAILABLE"
+    }
+  },
+  {
+    itemInventory: {
+      FacilityId: "WAREHOUSE-01",  // Parent data added
+      SKU: "SKU-002",
+      Quantity: 50,
+      Status: "RESERVED"
+    }
+  }
+]
+```
+
+**Step 4: Mapping Configuration**
+```json
+{
+  "fields": {
+    "locationRef": {
+      "source": "itemInventory.FacilityId",
+      "required": true
+    },
+    "skuRef": {
+      "source": "itemInventory.SKU",
+      "required": true
+    },
+    "qty": {
+      "source": "itemInventory.Quantity",
+      "resolver": "sdk.parseInt"
+    },
+    "status": {
+      "source": "itemInventory.Status",
+      "resolver": "sdk.uppercase"
+    }
+  }
+}
+```
+
+**What gets passed to mapper.map():**
+```javascript
+// For each enriched record:
+await mapper.map({
+  itemInventory: {
+    FacilityId: "WAREHOUSE-01",
+    SKU: "SKU-001",
+    Quantity: 100,
+    Status: "AVAILABLE"
+  }
+});
+```
+
+**Why This Works:**
+- You transformed the data BEFORE mapping
+- The mapping config references the TRANSFORMED structure
+- Path `"itemInventory.FacilityId"` exists in the JavaScript object
+- This is NOT XPath - it's JavaScript property access
+
+**Why Transformation Needed:** 
+- XML has `FacilityId` in parent `ItemInventory` (shared by all Items)
+- Each `Item` needs its own `FacilityId` to create complete records
+- Mapping can't easily access parent data when iterating arrays
+- Solution: Transform to combine parent data with each child before mapping
+
+**Complete Example Code:**
+```typescript
+import { XMLParserService, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const xmlParser = new XMLParserService();
+const parsed = await xmlParser.parse(xmlContent);
+
+// Step 1: Extract parent data
+const facilityId = parsed.InventoryStatus.ItemInventory.FacilityId;
+
+// Step 2: Extract and normalize items
+const items = parsed.InventoryStatus.ItemInventory.Item;
+const normalizedItems = Array.isArray(items) ? items : items ? [items] : [];
+
+// Step 3: Transform - wrap each item
+const enrichedRecords = normalizedItems.map(item => ({
+  itemInventory: {
+    FacilityId: facilityId,
+    ...item
+  }
+}));
+
+// Step 4: Map each enriched record
+const mapper = new UniversalMapper(mappingConfig);
+
+for (const record of enrichedRecords) {
+  const result = await mapper.map(record);
+
+  if (result.success) {
+    console.log('Mapped:', result.data);
+  } else {
+    console.error('Mapping failed:', result.errors);
+  }
+}
+```
+
+---
+
+## Common Transformation Patterns
+
+### Pattern 1: No Transformation (Flat CSV)
+
+**Use Case:** CSV with flat structure
+
+```javascript
+// Parsed CSV is already array of flat objects
+const records = parsedCsv;
+
+// Map directly
+for (const record of records) {
+  await mapper.map(record);
+}
+```
+
+### Pattern 2: Array Extraction (Nested JSON)
+
+**Use Case:** JSON with nested data array
+
+```javascript
+// Extract the array you need
+const parsed = await jsonParser.parse(jsonContent);
+const records = parsed.data.inventory.items;
+
+// Map each item
+for (const record of records) {
+  await mapper.map(record);
+}
+```
+
+### Pattern 3: Array Normalization (XML)
+
+**Use Case:** XML with repeating elements
+
+```javascript
+// Always normalize XML arrays
+const parsed = await xmlParser.parse(xmlContent);
+const items = parsed.products?.product;
+const records = Array.isArray(items) ? items : items ? [items] : [];
+
+// Now safe to iterate
+for (const record of records) {
+  await mapper.map(record);
+}
+```
+
+### Pattern 4: Parent Data Enrichment (XML with Context)
+
+**Use Case:** Child elements need parent data
+
+```javascript
+// Extract parent data
+const facilityId = parsed.warehouse.facility.id;
+
+// Extract items
+const items = parsed.warehouse.facility.inventory;
+const normalizedItems = Array.isArray(items) ? items : items ? [items] : [];
+
+// Enrich each item
+const enrichedRecords = normalizedItems.map(item => ({
+  ...item,
+  facilityId: facilityId  // Add parent data
+}));
+
+// Map enriched records
+for (const record of enrichedRecords) {
+  await mapper.map(record);
+}
+```
+
+### Pattern 5: Attribute Handling (XML Attributes)
+
+**Use Case:** XML with attributes and elements
+
+```javascript
+// XML Parser adds @ prefix for attributes
+const parsed = await xmlParser.parse(xmlContent);
+const items = parsed.catalog?.product;
+const records = Array.isArray(items) ? items : items ? [items] : [];
+
+// Mapping config uses @ prefix
+const mappingConfig = {
+  fields: {
+    id: { source: "@id" },        // Attribute
+    name: { source: "name" },     // Element
+    price: { source: "@price" }   // Attribute
+  }
+};
+```
+
+---
+
+## Key Takeaways
+
+### 1. Mapping Uses Parsed JavaScript Objects
+
+✅ **Mapping paths match the JavaScript object structure you pass to `mapper.map()`**
+
+```typescript
+// What you pass:
+await mapper.map({ itemInventory: { FacilityId: "...", Item: {...} } });
+
+// Mapping paths must match:
+{ source: "itemInventory.FacilityId" }     // ✅ Matches
+{ source: "InventoryStatus.ItemInventory.FacilityId" }  // ❌ Doesn't match
+```
+
+### 2. When Transformation is Needed
+
+**Transform when:**
+- ✅ Parent data needs to be combined with child records (like XML with shared parent data)
+- ✅ Flat structure needs to become nested (CSV → nested JSON)
+- ✅ Multiple data sources need to be combined
+- ✅ Complex business logic is easier in code than mapping
+
+**Don't transform when:**
+- ✅ Structure already matches target format
+- ✅ Simple field renaming is sufficient
+- ✅ Resolvers can handle the transformation
+
+### 3. XML Attributes
+
+**XML attributes are prefixed with `@` in parsed objects:**
+```xml
+<Order id="ORD-001">
+```
+```javascript
+{ Order: { "@id": "ORD-001" } }
+```
+```json
+{ "source": "Order@id" }  // ← No dot before @
+```
+
+### 4. Array Normalization
+
+**Always normalize XML arrays (single element → object, multiple → array):**
+```typescript
+const items = parsed.products?.product;
+const records = Array.isArray(items) ? items : items ? [items] : [];
+```
+
+### 5. Mapping Pattern Summary
+
+| Format | Parse Result | Extract/Normalize | Mapping Matches |
+|--------|-------------|-------------------|-----------------|
+| **CSV** | Array of flat objects | Already normalized | Flat record structure |
+| **JSON** | Nested objects | Extract array, optionally transform | Passed structure |
+| **XML** | Nested objects with `@` attributes | Extract array, normalize, optionally transform | Passed structure |
+
+---
+
+## Visual Flow Diagrams
+
+### Data Flow: CSV to Fluent
+
+```
+┌───────────────────────────────────────────────────────────────────┐
+│ CSV FILE                                                          │
+├───────────────────────────────────────────────────────────────────┤
+│ sku_id,quantity,location_code                                     │
+│ SKU-001,100,LOC-A                                                 │
+│ SKU-002,50,LOC-B                                                  │
+└───────────────────────────────────────────────────────────────────┘
+                            │
+                            │ CSVParserService.parse()
+                            ↓
+┌───────────────────────────────────────────────────────────────────┐
+│ PARSED JAVASCRIPT ARRAY                                           │
+├───────────────────────────────────────────────────────────────────┤
+│ [                                                                 │
+│   { sku_id: "SKU-001", quantity: "100", location_code: "LOC-A" }, │
+│   { sku_id: "SKU-002", quantity: "50", location_code: "LOC-B" }   │
+│ ]                                                                 │
+└───────────────────────────────────────────────────────────────────┘
+                            │
+                            │ No transformation needed (flat)
+                            ↓
+┌───────────────────────────────────────────────────────────────────┐
+│ WHAT MAPPER RECEIVES                                              │
+├───────────────────────────────────────────────────────────────────┤
+│ {                                                                 │
+│   sku_id: "SKU-001",         ← mapping: "skuRef" from "sku_id"    │
+│   quantity: "100",           ← mapping: "qty" from "quantity"     │
+│   location_code: "LOC-A"     ← mapping: "locationRef" from ...    │
+│ }                                                                 │
+└───────────────────────────────────────────────────────────────────┘
+                            │
+                            │ UniversalMapper.map()
+                            ↓
+┌───────────────────────────────────────────────────────────────────┐
+│ FLUENT FORMAT                                                     │
+├───────────────────────────────────────────────────────────────────┤
+│ {                                                                 │
+│   skuRef: "SKU-001",                                              │
+│   qty: 100,              ← Converted to number by sdk.parseInt    │
+│   locationRef: "LOC-A"                                            │
+│ }                                                                 │
+└───────────────────────────────────────────────────────────────────┘
+```
+
+### Data Flow: XML with Attributes to Fluent
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│ XML FILE                                                           │
+├────────────────────────────────────────────────────────────────────┤
+│ <inventory>                                                        │
+│   <item locationRef="LOC-A" skuRef="SKU-001">                      │
+│     <qty>100</qty>                                                 │
+│     <status>AVAILABLE</status>                                     │
+│   </item>                                                          │
+│ </inventory>                                                       │
+└────────────────────────────────────────────────────────────────────┘
+                            │
+                            │ XMLParserService.parse()
+                            ↓
+┌────────────────────────────────────────────────────────────────────┐
+│ PARSED JAVASCRIPT OBJECT                                           │
+├────────────────────────────────────────────────────────────────────┤
+│ {                                                                  │
+│   inventory: {                                                     │
+│     item: {                                                        │
+│       "@locationRef": "LOC-A",    ← @ prefix for attributes        │
+│       "@skuRef": "SKU-001",                                        │
+│       qty: 100,                   ← Elements without @             │
+│       status: "AVAILABLE"                                          │
+│     }                                                              │
+│   }                                                                │
+│ }                                                                  │
+└────────────────────────────────────────────────────────────────────┘
+                            │
+                            │ Extract: parsed.inventory.item
+                            │ Normalize: single element, wrap in array
+                            ↓
+┌────────────────────────────────────────────────────────────────────┐
+│ WHAT MAPPER RECEIVES                                               │
+├────────────────────────────────────────────────────────────────────┤
+│ {                                                                  │
+│   "@locationRef": "LOC-A",  ← mapping: source "@locationRef"       │
+│   "@skuRef": "SKU-001",     ← mapping: source "@skuRef"            │
+│   qty: 100,                 ← mapping: source "qty"                │
+│   status: "AVAILABLE"       ← mapping: source "status"             │
+│ }                                                                  │
+└────────────────────────────────────────────────────────────────────┘
+                            │
+                            │ UniversalMapper.map()
+                            ↓
+┌────────────────────────────────────────────────────────────────────┐
+│ FLUENT FORMAT                                                      │
+├────────────────────────────────────────────────────────────────────┤
+│ {                                                                  │
+│   locationRef: "LOC-A",                                            │
+│   skuRef: "SKU-001",                                               │
+│   qty: 100,                                                        │
+│   status: "AVAILABLE"                                              │
+│ }                                                                  │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+### Data Flow: XML with Parent Data Enrichment
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│ XML FILE                                                             │
+├──────────────────────────────────────────────────────────────────────┤
+│ <InventoryStatus>                                                    │
+│   <ItemInventory>                                                    │
+│     <FacilityId>WH-01</FacilityId>  ← Parent data                    │
+│     <Item><SKU>SKU-001</SKU><Qty>100</Qty></Item>  ← Children       │
+│     <Item><SKU>SKU-002</SKU><Qty>50</Qty></Item>                     │
+│   </ItemInventory>                                                   │
+│ </InventoryStatus>                                                   │
+└──────────────────────────────────────────────────────────────────────┘
+                            │
+                            │ XMLParserService.parse()
+                            ↓
+┌──────────────────────────────────────────────────────────────────────┐
+│ PARSED JAVASCRIPT OBJECT                                             │
+├──────────────────────────────────────────────────────────────────────┤
+│ {                                                                    │
+│   InventoryStatus: {                                                 │
+│     ItemInventory: {                                                 │
+│       FacilityId: "WH-01",       ← Parent data                       │
+│       Item: [                    ← Array of children                 │
+│         { SKU: "SKU-001", Qty: 100 },                                │
+│         { SKU: "SKU-002", Qty: 50 }                                  │
+│       ]                                                              │
+│     }                                                                │
+│   }                                                                  │
+│ }                                                                    │
+└──────────────────────────────────────────────────────────────────────┘
+                            │
+                            │ TRANSFORMATION:
+                            │ 1. Extract facilityId
+                            │ 2. Normalize Item array
+                            │ 3. Wrap each item with facilityId
+                            ↓
+┌──────────────────────────────────────────────────────────────────────┐
+│ TRANSFORMED RECORDS                                                  │
+├──────────────────────────────────────────────────────────────────────┤
+│ [                                                                    │
+│   {                                                                  │
+│     itemInventory: {                                                 │
+│       FacilityId: "WH-01",   ← Parent data added to each item        │
+│       SKU: "SKU-001",                                                │
+│       Qty: 100                                                       │
+│     }                                                                │
+│   },                                                                 │
+│   {                                                                  │
+│     itemInventory: {                                                 │
+│       FacilityId: "WH-01",   ← Same parent data                      │
+│       SKU: "SKU-002",                                                │
+│       Qty: 50                                                        │
+│     }                                                                │
+│   }                                                                  │
+│ ]                                                                    │
+└──────────────────────────────────────────────────────────────────────┘
+                            │
+                            │ For each record...
+                            ↓
+┌──────────────────────────────────────────────────────────────────────┐
+│ WHAT MAPPER RECEIVES                                                 │
+├──────────────────────────────────────────────────────────────────────┤
+│ {                                                                    │
+│   itemInventory: {                                                   │
+│     FacilityId: "WH-01",   ← source: "itemInventory.FacilityId"      │
+│     SKU: "SKU-001",        ← source: "itemInventory.SKU"             │
+│     Qty: 100               ← source: "itemInventory.Qty"             │
+│   }                                                                  │
+│ }                                                                    │
+└──────────────────────────────────────────────────────────────────────┘
+                            │
+                            │ UniversalMapper.map()
+                            ↓
+┌──────────────────────────────────────────────────────────────────────┐
+│ FLUENT FORMAT                                                        │
+├──────────────────────────────────────────────────────────────────────┤
+│ {                                                                    │
+│   locationRef: "WH-01",                                              │
+│   skuRef: "SKU-001",                                                 │
+│   qty: 100                                                           │
+│ }                                                                    │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Debugging Guide
+
+### How to Figure Out What Paths to Use
+
+#### Step 1: Log the Parsed Structure
+
+```typescript
+import { XMLParserService } from '@fluentcommerce/fc-connect-sdk';
+
+const xmlParser = new XMLParserService();
+const parsed = await xmlParser.parse(xmlContent);
+
+// Log the ENTIRE parsed structure
+console.log('Parsed structure:', JSON.stringify(parsed, null, 2));
+```
+
+This shows you the exact JavaScript object structure.
+
+#### Step 2: Identify What You Need
+
+Look at the output and find:
+- Where is the array of items you need to process?
+- What are the property names in the JavaScript object?
+- Are there any `@` prefixes (XML attributes)?
+
+#### Step 3: Test Your Extraction
+
+```typescript
+// Try to extract the array
+const items = parsed.inventory?.item;
+console.log('Extracted items:', items);
+
+// Check if it's an array
+console.log('Is array?', Array.isArray(items));
+
+// Normalize if needed
+const records = Array.isArray(items) ? items : items ? [items] : [];
+console.log('Normalized records:', records);
+```
+
+#### Step 4: Check a Single Record
+
+```typescript
+// Look at one record
+const firstRecord = records[0];
+console.log('First record:', JSON.stringify(firstRecord, null, 2));
+```
+
+This shows you exactly what structure the mapper will receive.
+
+#### Step 5: Match Mapping Config to Structure
+
+```typescript
+// Your mapping config paths must match the JavaScript object
+const mappingConfig = {
+  fields: {
+    // If you see: { "sku": "SKU-001" }
+    skuRef: { source: "sku" },
+
+    // If you see: { "@sku": "SKU-001" }
+    skuRef: { source: "@sku" },
+
+    // If you see: { "product": { "sku": "SKU-001" } }
+    skuRef: { source: "product.sku" }
+  }
+};
+```
+
+#### Step 6: Test Mapping on One Record
+
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const mapper = new UniversalMapper(mappingConfig);
+const result = await mapper.map(firstRecord);
+
+if (result.success) {
+  console.log('Mapping succeeded:', result.data);
+} else {
+  console.error('Mapping failed:', result.errors);
+
+  // Check each error
+  result.errors.forEach(error => {
+    console.error('Field:', error.field);
+    console.error('Message:', error.message);
+    console.error('Path:', error.path);
+  });
+}
+```
+
+### Common Debugging Mistakes
+
+#### Mistake 1: Using File Structure Instead of Object Structure
+
+**WRONG:**
+```typescript
+// CSV file has column "sku_id"
+const mappingConfig = {
+  fields: {
+    skuRef: { source: "columns.sku_id" }  // WRONG!
+  }
+};
+```
+
+**CORRECT:**
+```typescript
+// Parsed CSV gives you { sku_id: "SKU-001" }
+const mappingConfig = {
+  fields: {
+    skuRef: { source: "sku_id" }  // CORRECT
+  }
+};
+```
+
+#### Mistake 2: Using XPath for XML
+
+**WRONG:**
+```typescript
+// XML has <product><sku>SKU-001</sku></product>
+const mappingConfig = {
+  fields: {
+    skuRef: { source: "//product/sku" }  // WRONG! Not XPath
+  }
+};
+```
+
+**CORRECT:**
+```typescript
+// Parsed XML gives you { product: { sku: "SKU-001" } }
+const mappingConfig = {
+  fields: {
+    skuRef: { source: "product.sku" }  // CORRECT: JavaScript path
+  }
+};
+```
+
+#### Mistake 3: Forgetting to Normalize XML Arrays
+
+**WRONG:**
+```typescript
+const items = parsed.products.product;
+
+// If there's only one <product>, this breaks!
+for (const item of items) {  // ERROR: items is not iterable
+  await mapper.map(item);
+}
+```
+
+**CORRECT:**
+```typescript
+const items = parsed.products?.product;
+const records = Array.isArray(items) ? items : items ? [items] : [];
+
+// Now always works
+for (const record of records) {
+  await mapper.map(record);
+}
+```
+
+#### Mistake 4: Missing @ Prefix for XML Attributes
+
+**WRONG:**
+```typescript
+// XML: <item locationRef="LOC-A">
+const mappingConfig = {
+  fields: {
+    locationRef: { source: "locationRef" }  // WRONG: Missing @
+  }
+};
+```
+
+**CORRECT:**
+```typescript
+// Parsed: { "@locationRef": "LOC-A" }
+const mappingConfig = {
+  fields: {
+    locationRef: { source: "@locationRef" }  // CORRECT
+  }
+};
+```
+
+### Debugging Checklist
+
+When your mapping fails, check:
+
+- [ ] Did you log the parsed structure with `JSON.stringify(parsed, null, 2)`?
+- [ ] Did you check what gets passed to `mapper.map()` at line X?
+- [ ] Are you using JavaScript object paths, not file format paths?
+- [ ] Did you normalize XML arrays? (`Array.isArray() ? : []:[]`)
+- [ ] Are you using `@` prefix for XML attributes?
+- [ ] Did you check for typos in property names?
+- [ ] Did you verify the property actually exists in the object?
+- [ ] Are you mapping nested properties with dot notation correctly?
+
+---
+
+## Real-World Example: InventoryStatus
+
+This is a real user case that demonstrates the XML parent data enrichment pattern.
+
+### The Problem
+
+User has XML with a parent-level `FacilityId` that needs to be added to each child `Item`:
+
+```xml
+<InventoryStatus>
+  <ItemInventory>
+    <FacilityId>WAREHOUSE-01</FacilityId>
+    <Item>
+      <SKU>SKU-001</SKU>
+      <Quantity>100</Quantity>
+    </Item>
+    <Item>
+      <SKU>SKU-002</SKU>
+      <Quantity>50</Quantity>
+    </Item>
+  </ItemInventory>
+</InventoryStatus>
+```
+
+**Challenge:** Each `Item` needs the `FacilityId` for the Fluent `locationRef` field, but it's at the parent `ItemInventory` level.
+
+### The Solution
+
+**Step 1: Parse XML**
+```typescript
+import { XMLParserService } from '@fluentcommerce/fc-connect-sdk';
+
+const xmlParser = new XMLParserService();
+const parsed = await xmlParser.parse(xmlContent);
+
+// Result:
+// {
+//   InventoryStatus: {
+//     ItemInventory: {
+//       FacilityId: "WAREHOUSE-01",
+//       Item: [
+//         { SKU: "SKU-001", Quantity: 100 },
+//         { SKU: "SKU-002", Quantity: 50 }
+//       ]
+//     }
+//   }
+// }
+```
+
+**Step 2: Extract Parent and Child Data**
+```typescript
+const itemInventory = parsed.InventoryStatus.ItemInventory;
+const facilityId = itemInventory.FacilityId;
+
+// Normalize array (handle single vs multiple Items)
+const items = itemInventory.Item;
+const normalizedItems = Array.isArray(items) ? items : items ? [items] : [];
+```
+
+**Step 3: Transform - Wrap Each Item with Parent Context**
+```typescript
+const enrichedRecords = normalizedItems.map(item => ({
+  itemInventory: {
+    FacilityId: facilityId,  // Parent data
+    ...item                   // Child data
+  }
+}));
+
+// Result:
+// [
+//   {
+//     itemInventory: {
+//       FacilityId: "WAREHOUSE-01",
+//       SKU: "SKU-001",
+//       Quantity: 100
+//     }
+//   },
+//   ...
+// ]
+```
+
+**Step 4: Mapping Configuration**
+```json
+{
+  "fields": {
+    "locationRef": {
+      "source": "itemInventory.FacilityId",
+      "required": true,
+      "resolver": "sdk.trim"
+    },
+    "skuRef": {
+      "source": "itemInventory.SKU",
+      "required": true,
+      "resolver": "sdk.trim"
+    },
+    "qty": {
+      "source": "itemInventory.Quantity",
+      "required": true,
+      "resolver": "sdk.parseInt"
+    }
+  }
+}
+```
+
+**Step 5: Map Each Record**
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const mapper = new UniversalMapper(mappingConfig);
+
+for (const record of enrichedRecords) {
+  const result = await mapper.map(record);
+
+  if (result.success) {
+    console.log('Mapped record:', result.data);
+    // {
+    //   locationRef: "WAREHOUSE-01",
+    //   skuRef: "SKU-001",
+    //   qty: 100
+    // }
+  } else {
+    console.error('Mapping failed:', result.errors);
+  }
+}
+```
+
+### Why This Works
+
+1. **Parsing creates JavaScript object** - XML → `{ InventoryStatus: { ItemInventory: { ... } } }`
+2. **Transformation wraps each item** - Added `FacilityId` to each item's structure
+3. **Mapping uses transformed structure** - Paths like `itemInventory.FacilityId` exist in the JavaScript object
+4. **Not XPath, not XML structure** - Pure JavaScript object property access
+
+### Complete Working Example
+
+```typescript
+import {
+  XMLParserService,
+  UniversalMapper,
+  createClient
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function processInventoryStatus(xmlContent: string) {
+  // Parse XML
+  const xmlParser = new XMLParserService();
+  const parsed = await xmlParser.parse(xmlContent);
+
+  // Extract parent data
+  const itemInventory = parsed.InventoryStatus.ItemInventory;
+  const facilityId = itemInventory.FacilityId;
+
+  // Extract and normalize items
+  const items = itemInventory.Item;
+  const normalizedItems = Array.isArray(items) ? items : items ? [items] : [];
+
+  // Transform: wrap each item with parent context
+  const enrichedRecords = normalizedItems.map(item => ({
+    itemInventory: {
+      FacilityId: facilityId,
+      ...item
+    }
+  }));
+
+  // Mapping configuration
+  const mappingConfig = {
+    fields: {
+      locationRef: {
+        source: "itemInventory.FacilityId",
+        required: true,
+        resolver: "sdk.trim"
+      },
+      skuRef: {
+        source: "itemInventory.SKU",
+        required: true,
+        resolver: "sdk.trim"
+      },
+      qty: {
+        source: "itemInventory.Quantity",
+        required: true,
+        resolver: "sdk.parseInt"
+      }
+    }
+  };
+
+  // Map each record
+  const mapper = new UniversalMapper(mappingConfig);
+  const mappedRecords = [];
+
+  for (const record of enrichedRecords) {
+    const result = await mapper.map(record);
+
+    if (result.success) {
+      mappedRecords.push(result.data);
+    } else {
+      console.error('Mapping failed for record:', record);
+      console.error('Errors:', result.errors);
+    }
+  }
+
+  // Send to Fluent Commerce
+  const client = await createClient({ config });
+
+  const job = await client.createJob({
+    name: 'inventory-status-update',
+    retailerId: process.env.FLUENT_RETAILER_ID!
+  });
+
+  await client.sendBatch(job.id, {
+    action: 'UPSERT',
+    entityType: 'INVENTORY',
+    entities: mappedRecords
+  });
+
+  console.log(`Processed ${mappedRecords.length} inventory records`);
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Always Log Parsed Structure First
+
+```typescript
+const parsed = await parser.parse(content);
+console.log('Parsed structure:', JSON.stringify(parsed, null, 2));
+```
+
+This eliminates guesswork about object structure.
+
+### 2. Normalize XML Arrays Immediately
+
+```typescript
+// Always do this for XML
+const items = parsed.inventory?.item;
+const records = Array.isArray(items) ? items : items ? [items] : [];
+```
+
+Prevents runtime errors when XML has only one element.
+
+### 3. Use External JSON for Mapping Configs
+
+```typescript
+// GOOD: External JSON file
+import mappingConfig from './config/inventory.json' with { type: 'json' };
+const mapper = new UniversalMapper(mappingConfig);
+```
+
+Keeps code clean and configs maintainable.
+
+### 4. Transform Before Mapping
+
+```typescript
+// Extract parent data
+const facilityId = parsed.warehouse.id;
+
+// Transform records to include parent data
+const enrichedRecords = items.map(item => ({
+  ...item,
+  facilityId: facilityId
+}));
+
+// Now mapping can reference facilityId
+```
+
+Don't try to access parent data during mapping - transform first.
+
+### 5. Test Mapping on One Record First
+
+```typescript
+// Test with first record
+const testRecord = records[0];
+const result = await mapper.map(testRecord);
+
+if (!result.success) {
+  console.error('Mapping errors:', result.errors);
+  // Fix mapping config before processing all records
+}
+```
+
+Catch mapping errors early.
+
+### 6. Use Descriptive Property Names in Transformations
+
+```typescript
+// GOOD: Clear structure
+const enrichedRecords = items.map(item => ({
+  itemInventory: {
+    FacilityId: facilityId,
+    ...item
+  }
+}));
+
+// BAD: Unclear structure
+const enrichedRecords = items.map(item => ({
+  ...item,
+  f: facilityId  // What is 'f'?
+}));
+```
+
+Makes mapping configs easier to understand.
+
+### 7. Document Your Transformation Logic
+
+```typescript
+// Transform XML structure to include parent FacilityId in each item
+// Original: { ItemInventory: { FacilityId, Item: [...] } }
+// Result: [{ itemInventory: { FacilityId, SKU, Qty } }]
+const enrichedRecords = normalizedItems.map(item => ({
+  itemInventory: {
+    FacilityId: facilityId,
+    ...item
+  }
+}));
+```
+
+Future you (or your team) will thank you.
+
+### 8. Parse First, Then Decide on Transformation
+
+1. **Parse the file format**
+   - Use the appropriate parser service
+   - Log the parsed structure
+
+2. **Inspect the parsed structure**
+   - Understand the data hierarchy
+   - Identify shared parent data
+   - Check for array normalization needs
+
+3. **Decide if transformation is needed**
+   - Can you map directly?
+   - Do you need to enrich child records with parent data?
+   - Is the structure compatible with your mapping config?
+
+### 9. Keep Transformation Minimal
+
+- Only transform when necessary
+- Use resolvers for simple transformations when possible
+- Prefer code transformation for complex restructuring
+
+### 10. Handle Edge Cases
+
+- Single vs multiple elements (XML)
+- Missing fields
+- Null/undefined values
+- Empty arrays
+
+---
+
+## Common Mistakes to Avoid
+
+### Mistake 1: Using File Format Syntax in Mapping Config
+
+**WRONG:**
+```typescript
+// Trying to use XPath in mapping config
+const mappingConfig = {
+  fields: {
+    skuRef: { source: "//product/sku" }  // This is XPath, not JavaScript
+  }
+};
+```
+
+**CORRECT:**
+```typescript
+// Use JavaScript object path
+const mappingConfig = {
+  fields: {
+    skuRef: { source: "product.sku" }  // JavaScript property access
+  }
+};
+```
+
+### Mistake 2: Mapping Before Transforming
+
+**WRONG:**
+```typescript
+// Trying to access parent data in mapping config
+const mappingConfig = {
+  fields: {
+    // This won't work - FacilityId is at parent level
+    locationRef: { source: "FacilityId" }  // Item doesn't have FacilityId
+  }
+};
+
+for (const item of items) {
+  await mapper.map(item);  // Fails - item doesn't have FacilityId
+}
+```
+
+**CORRECT:**
+```typescript
+// Transform FIRST to add parent data
+const enrichedRecords = items.map(item => ({
+  ...item,
+  FacilityId: facilityId  // Add parent data
+}));
+
+// NOW mapping can access FacilityId
+const mappingConfig = {
+  fields: {
+    locationRef: { source: "FacilityId" }  // Now it exists!
+  }
+};
+```
+
+### Mistake 3: Not Normalizing XML Arrays
+
+**WRONG:**
+```typescript
+const items = parsed.products.product;
+
+for (const item of items) {  // Breaks if only one <product>!
+  await mapper.map(item);
+}
+```
+
+**CORRECT:**
+```typescript
+const items = parsed.products?.product;
+const records = Array.isArray(items) ? items : items ? [items] : [];
+
+for (const record of records) {  // Always works
+  await mapper.map(record);
+}
+```
+
+### Mistake 4: Forgetting @ Prefix for XML Attributes
+
+**WRONG:**
+```typescript
+// XML: <item locationRef="LOC-A" skuRef="SKU-001">
+const mappingConfig = {
+  fields: {
+    locationRef: { source: "locationRef" },  // Missing @
+    skuRef: { source: "skuRef" }             // Missing @
+  }
+};
+```
+
+**CORRECT:**
+```typescript
+// Parsed object has: { "@locationRef": "LOC-A", "@skuRef": "SKU-001" }
+const mappingConfig = {
+  fields: {
+    locationRef: { source: "@locationRef" },  // @ prefix required
+    skuRef: { source: "@skuRef" }
+  }
+};
+```
+
+### Mistake 5: Mapping Nested Source to Flat Target Without Extraction
+
+**WRONG:**
+```typescript
+// Source: { warehouse: { inventory: { items: [...] } } }
+const items = parsed.warehouse.inventory.items;
+
+// Mapping without extraction
+const mappingConfig = {
+  fields: {
+    skuRef: { source: "warehouse.inventory.items.sku" }  // Path too long
+  }
+};
+```
+
+**CORRECT:**
+```typescript
+// Extract the array first
+const items = parsed.warehouse.inventory.items;
+
+// Now map each item directly
+const mappingConfig = {
+  fields: {
+    skuRef: { source: "sku" }  // Clean path
+  }
+};
+
+for (const item of items) {
+  await mapper.map(item);
+}
+```
+
+### Mistake 6: Assuming Parsed Data Matches File Structure
+
+**WRONG:**
+```typescript
+// CSV has columns: sku_id, quantity, location
+// Assuming mapping uses column positions
+const mappingConfig = {
+  fields: {
+    skuRef: { source: "columns[0]" }  // WRONG! Not how it works
+  }
+};
+```
+
+**CORRECT:**
+```typescript
+// CSV parser creates: { sku_id: "...", quantity: "...", location: "..." }
+const mappingConfig = {
+  fields: {
+    skuRef: { source: "sku_id" }  // Use property name
+  }
+};
+```
+
+---
+
+## Related Documentation
+
+- [Mapping Foundations](../auto-pagination/modules/auto-pagination-01-foundations.md) - Core mapping concepts
+- [Universal Mapper Guide](mapping-readme.md) - Complete mapping patterns
+- [SDK Resolvers](./resolvers/mapping-resolvers-readme.md) - Built-in field transformations
+- [XML Parser Guide](../parsers/modules/02-core-guides-parsers-04-xml-parser.md) - XML parsing details
+- [CSV Parser Guide](../parsers/modules/02-core-guides-parsers-02-csv-parser.md) - CSV parsing details
+- [JSON Parser Guide](../parsers/modules/02-core-guides-parsers-03-json-parser.md) - JSON parsing details
+
+---
+
+## FAQ
+
+**Q: Do I need to know XPath/JSONPath/SQL to write mapping configs?**
+
+A: No! You only need to know JavaScript object property access. Use dot notation for nested properties and `@` prefix for XML attributes.
+
+**Q: Why does my XML mapping fail when there's only one element?**
+
+A: XML parsers return an object for a single element and an array for multiple elements. Always normalize with: `Array.isArray(items) ? items : items ? [items] : []`
+
+**Q: Can I use the same mapping config for CSV, JSON, and XML?**
+
+A: Only if they produce the same JavaScript object structure after parsing. Usually, you need different configs because each format has different property names.
+
+**Q: How do I map parent data to child records?**
+
+A: Transform the data BEFORE mapping. Extract parent data, then wrap each child record with the parent data. See the [InventoryStatus example](#real-world-example-inventorystatus).
+
+**Q: What's the difference between `"source": "sku"` and `"source": "@sku"`?**
+
+A: `"sku"` is a child element in XML (or object property). `"@sku"` is an XML attribute. The XML parser adds the `@` prefix to attributes in the JavaScript object.
+
+**Q: Can I access nested properties with bracket notation?**
+
+A: Use dot notation for paths: `"source": "product.details.sku"`. The mapper handles the property access internally.
+
+**Q: How do I debug mapping errors?**
+
+A: Log the exact object you pass to `mapper.map()` with `JSON.stringify(object, null, 2)`. Compare property names in the log to your mapping config `source` paths.
+
+---
+
+**Last Updated:** 2025-11-03
+
+**Related Guides:**
+- [Universal Mapping Guide](mapping-readme.md)
+- [SDK Resolvers](./resolvers/mapping-resolvers-readme.md)
+- [Parsers Guide](../parsers/parsers-readme.md)