@fluentcommerce/fc-connect-sdk 0.1.48 → 0.1.52

package/docs/02-CORE-GUIDES/mapping/modules/mapping-05-advanced-patterns.md

@@ -1,1364 +1,1366 @@
-# Module 5: Advanced Patterns
-
-**Master complex transformations**
-
-**Level:** Advanced
-**Time:** 40 minutes
-**Prerequisites:** [Module 4: Use Cases](./mapping-04-use-cases.md)
-
----
-
-## Learning Objectives
-
-After completing this module, you will:
-- ✅ Map complex nested object structures
-- ✅ Process arrays with `isArray` configuration
-- ✅ Implement conditional transformations
-- ✅ Use async resolvers for external lookups
-- ✅ Chain multiple transformations
-- ✅ Handle GraphQL edges/nodes pagination patterns
-
----
-
-## Nested Objects
-
-Map nested structures using dot notation or nested `fields` configuration.
-
-### Method 1: Dot Notation (Flat Mapping)
-
-```json
-{
-  "fields": {
-    "customer.id": {
-      "source": "customerId",
-      "resolver": "sdk.parseInt"
-    },
-    "customer.email": {
-      "source": "email",
-      "resolver": "sdk.lowercase"
-    },
-    "customer.address.city": {
-      "source": "city"
-    },
-    "customer.address.state": {
-      "source": "state"
-    },
-    "customer.address.zipCode": {
-      "source": "zip"
-    }
-  }
-}
-```
-
-**Output:**
-```json
-{
-  "customer": {
-    "id": 12345,
-    "email": "john@example.com",
-    "address": {
-      "city": "New York",
-      "state": "NY",
-      "zipCode": "10001"
-    }
-  }
-}
-```
-
-### Method 2: Nested Fields (Structured Mapping)
-
-```json
-{
-  "fields": {
-    "customer": {
-      "fields": {
-        "id": {
-          "source": "customerId",
-          "resolver": "sdk.parseInt"
-        },
-        "email": {
-          "source": "email",
-          "resolver": "sdk.lowercase"
-        },
-        "address": {
-          "fields": {
-            "city": {
-              "source": "city"
-            },
-            "state": {
-              "source": "state"
-            },
-            "zipCode": {
-              "source": "zip"
-            }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-**Same output** as Method 1, but more structured and easier to read for complex objects.
-
-### When to Use Each Method
-
-| Method | Best For | Advantages | Disadvantages |
-|--------|----------|------------|---------------|
-| **Dot Notation** | Simple nesting (2-3 levels) | Concise, flat structure | Hard to read for deep nesting |
-| **Nested Fields** | Complex objects, reusable components | Clear hierarchy, organized | More verbose |
-
-### Deep Nesting Example
-
-```json
-{
-  "fields": {
-    "order": {
-      "fields": {
-        "ref": {
-          "source": "orderRef"
-        },
-        "customer": {
-          "fields": {
-            "id": {
-              "source": "customerId"
-            },
-            "profile": {
-              "fields": {
-                "firstName": {
-                  "source": "firstName"
-                },
-                "lastName": {
-                  "source": "lastName"
-                },
-                "preferences": {
-                  "fields": {
-                    "language": {
-                      "source": "lang",
-                      "defaultValue": "en"
-                    },
-                    "currency": {
-                      "source": "currency",
-                      "defaultValue": "USD"
-                    }
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
----
-
-## Static Values
-
-Provide constant values at any nesting level.
-
-### Simple Static Values
-
-```json
-{
-  "fields": {
-    "type": {
-      "value": "STANDARD"
-    },
-    "retailerId": {
-      "value": 1
-    },
-    "source": {
-      "value": "CSV_IMPORT"
-    },
-    "status": {
-      "value": "ACTIVE"
-    }
-  }
-}
-```
-
-### Static Values in Nested Objects
-
-```json
-{
-  "fields": {
-    "retailer": {
-      "fields": {
-        "id": {
-          "value": "1",
-          "comment": "Static retailer ID"
-        }
-      }
-    },
-    "metadata": {
-      "fields": {
-        "importSource": {
-          "value": "SFCC"
-        },
-        "importVersion": {
-          "value": "2.0"
-        },
-        "importTimestamp": {
-          "resolver": "custom.currentTimestamp"
-        }
-      }
-    }
-  }
-}
-```
-
----
-
-## Conditional Transformations
-
-Use custom resolvers for complex business logic and conditional mapping.
-
-### Simple Conditional Mapping
-
-```json
-{
-  "fields": {
-    "shippingMethod": {
-      "source": "deliverySpeed",
-      "resolver": "custom.mapShipping"
-    },
-    "priority": {
-      "source": "orderType",
-      "resolver": "custom.calculatePriority"
-    }
-  }
-}
-```
-
-**Custom Resolvers:**
-```typescript
-const customResolvers = {
-  'custom.mapShipping': (value: string) => {
-    // Map delivery speed to shipping method
-    const shippingMap: Record<string, string> = {
-      'express': 'OVERNIGHT',
-      'fast': 'TWO_DAY',
-      'standard': 'GROUND',
-      'economy': 'STANDARD'
-    };
-    return shippingMap[value.toLowerCase()] || 'STANDARD';
-  },
-
-  'custom.calculatePriority': (value: string, sourceData: any) => {
-    // Calculate priority based on order type and total
-    const isPremium = sourceData.customerTier === 'PREMIUM';
-    const isUrgent = value === 'EXPRESS';
-    const isLargeOrder = sourceData.total > 1000;
-
-    if (isUrgent || isPremium) return 'HIGH';
-    if (isLargeOrder) return 'MEDIUM';
-    return 'LOW';
-  }
-};
-```
-
-### Multi-Condition Resolver
-
-```typescript
-const customResolvers = {
-  'custom.determineOrderType': (value: any, sourceData: any, config: any, helpers: any) => {
-    const total = helpers.parseFloatSafe(sourceData.total, 0);
-    const itemCount = helpers.parseIntSafe(sourceData.itemCount, 0);
-    const isInternational = sourceData.country !== 'US';
-
-    // Complex business rules
-    if (isInternational && total > 500) {
-      return 'INTERNATIONAL_PREMIUM';
-    }
-
-    if (itemCount > 20 || total > 1000) {
-      return 'BULK';
-    }
-
-    if (sourceData.expedited === true) {
-      return 'EXPRESS';
-    }
-
-    return 'STANDARD';
-  }
-};
-```
-
----
-
-## Arrays
-
-Map arrays of items using the `isArray` field configuration.
-
-### Array Mapping with `isArray`
-
-```json
-{
-  "fields": {
-    "items": {
-      "source": "orderItems",
-      "isArray": true,
-      "fields": {
-        "ref": {
-          "source": "id"
-        },
-        "productRef": {
-          "source": "sku"
-        },
-        "quantity": {
-          "source": "qty",
-          "resolver": "sdk.parseInt"
-        },
-        "price": {
-          "source": "unitPrice",
-          "resolver": "sdk.parseFloat"
-        },
-        "totalPrice": {
-          "resolver": "custom.calculateItemTotal"
-        }
-      }
-    }
-  }
-}
-```
-
-### How `isArray` Works
-
-1. **Extract Array:** `source: "orderItems"` extracts the array from source data
-2. **Iterate:** `isArray: true` tells mapper to iterate over array elements
-3. **Map Each Item:** `fields: {...}` defines mappings for each array element
-4. **Context Switch:** ⚠️ **THIS IS THE KEY CONCEPT**
-
-   Once inside `fields` of an `isArray` mapping, the context changes:
-
-   ```mermaid
-   flowchart TD
-       A[Root Context<br/>orderItems: [...],<br/>customerId: 123] -->|Iterate Array| B[Array Item Context<br/>id: 'ITEM-1'<br/>sku: 'PROD-001'<br/>qty: '2']
-       B -->|Map Fields| C[Field Mappings<br/>source: 'id'<br/>→ Reads from item,<br/>NOT root]
-       
-       style A fill:#e1f5ff
-       style B fill:#fff4e1
-       style C fill:#e8f5e9
-   ```
-
-   **Text Version:**
-   ```
-   Root Context:     { orderItems: [...], customerId: 123 }
-                              ↓ iterate
-   Array Item:       { id: "ITEM-1", sku: "PROD-001", qty: "2" }  ← NEW CONTEXT!
-                              ↓ map fields
-   Field Mappings:   "source": "id" reads from THIS object, not root
-   ```
-
-   **In other words:**
-   - `"source": "id"` → reads `currentArrayItem.id`
-   - `"source": "sku"` → reads `currentArrayItem.sku`
-   - NOT `sourceData.id` or `sourceData.sku`
-
-**Source Data:**
-```json
-{
-  "orderItems": [
-    { "id": "ITEM-1", "sku": "PROD-001", "qty": "2", "unitPrice": "49.99" },
-    { "id": "ITEM-2", "sku": "PROD-002", "qty": "1", "unitPrice": "99.99" }
-  ]
-}
-```
-
-**Mapped Output:**
-```json
-{
-  "items": [
-    { "ref": "ITEM-1", "productRef": "PROD-001", "quantity": 2, "price": 49.99, "totalPrice": 99.98 },
-    { "ref": "ITEM-2", "productRef": "PROD-002", "quantity": 1, "price": 99.99, "totalPrice": 99.99 }
-  ]
-}
-```
-
-### Common Mistake: Don't Repeat Array Path
-
-**❌ WRONG - Repeating array path in nested fields:**
-```json
-{
-  "items": {
-    "source": "orderItems",
-    "isArray": true,
-    "fields": {
-      "ref": {
-        "source": "orderItems[0].id"  // ❌ Already inside array context!
-      }
-    }
-  }
-}
-```
-
-**✅ CORRECT - Use paths relative to array item:**
-```json
-{
-  "items": {
-    "source": "orderItems",
-    "isArray": true,
-    "fields": {
-      "ref": {
-        "source": "id"  // ✅ Reads from current array item
-      }
-    }
-  }
-}
-```
-
-### Accessing Array Item Context
-
-Within array field mappings, use `source` paths relative to the array item:
-
-```json
-{
-  "items": {
-    "source": "orderItems",
-    "isArray": true,
-    "fields": {
-      "ref": {
-        "source": "id"  // ← Reads from current array item's 'id' field
-      },
-      "productRef": {
-        "source": "sku"  // ← Reads from current array item's 'sku' field
-      }
-    }
-  }
-}
-```
-
-### GraphQL Edges/Nodes Pattern
-
-**IMPORTANT:** The asterisk `[*]` is optional. Both patterns work:
-
-**Option 1: With wildcard (extracts nodes directly)**
-```json
-{
-  "fields": {
-    "products": {
-      "source": "products.edges[*].node",  // Wildcard extracts nodes
-      "isArray": true,
-      "fields": {
-        "id": { "source": "id" },         // Direct access (no "node." prefix)
-        "ref": { "source": "ref" },
-        "name": { "source": "name" },
-        "price": { "source": "price", "resolver": "sdk.parseFloat" }
-      }
-    }
-  }
-}
-```
-
-**Option 2: Without wildcard (extracts edges)**
-```json
-{
-  "fields": {
-    "products": {
-      "source": "products.edges",          // Direct array access
-      "isArray": true,
-      "fields": {
-        "id": { "source": "node.id" },     // Need "node." prefix
-        "ref": { "source": "node.ref" },
-        "name": { "source": "node.name" },
-        "price": { "source": "node.price", "resolver": "sdk.parseFloat" }
-      }
-    }
-  }
-}
-```
-
-**Option 3: Auto-detection (SDK detects GraphQL structure)**
-```json
-{
-  "fields": {
-    "products": {
-      "source": "products",                // SDK auto-detects { edges: [...] }
-      "isArray": true,
-      "fields": {
-        "id": { "source": "id" },         // Direct access (nodes auto-extracted)
-        "ref": { "source": "ref" },
-        "name": { "source": "name" },
-        "price": { "source": "price", "resolver": "sdk.parseFloat" }
-      }
-    }
-  }
-}
-```
-
-**All three produce the same result** - choose based on clarity for your use case
-
-**Source Data (GraphQL):**
-```json
-{
-  "products": {
-    "edges": [
-      { "cursor": "abc123", "node": { "id": "1", "ref": "PROD-001", "name": "Widget", "price": 19.99 } },
-      { "cursor": "def456", "node": { "id": "2", "ref": "PROD-002", "name": "Gadget", "price": 29.99 } }
-    ]
-  }
-}
-```
-
-**Mapped Output:**
-```json
-{
-  "products": [
-    { "id": "1", "ref": "PROD-001", "name": "Widget", "price": 19.99 },
-    { "id": "2", "ref": "PROD-002", "name": "Gadget", "price": 29.99 }
-  ]
-}
-```
-
-### Nested Arrays
-
-Arrays within arrays require nested `isArray` configuration. This is common when parsing XML with complex nested structures.
-
-#### XML Example with Nested Arrays
-
-**Sample XML:**
-```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>
-        <attributes>
-          <attribute name="color" value="Blue"/>
-          <attribute name="size" value="M"/>
-        </attributes>
-      </item>
-      <item sku="PROD-002" qty="1">
-        <price>49.99</price>
-        <attributes>
-          <attribute name="color" value="Red"/>
-          <attribute name="size" value="L"/>
-        </attributes>
-      </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>
-        <attributes>
-          <attribute name="color" value="Green"/>
-        </attributes>
-      </item>
-    </items>
-  </Order>
-</Orders>
-```
-
-**After XML Parsing (fast-xml-parser):**
-```json
-{
-  "Orders": {
-    "Order": [
-      {
-        "@id": "ORD-001",
-        "@orderDate": "2025-01-22",
-        "customer": {
-          "name": "John Doe",
-          "email": "John@Example.com"
-        },
-        "items": {
-          "item": [
-            {
-              "@sku": "PROD-001",
-              "@qty": "2",
-              "price": "29.99",
-              "attributes": {
-                "attribute": [
-                  { "@name": "color", "@value": "Blue" },
-                  { "@name": "size", "@value": "M" }
-                ]
-              }
-            },
-            {
-              "@sku": "PROD-002",
-              "@qty": "1",
-              "price": "49.99",
-              "attributes": {
-                "attribute": [
-                  { "@name": "color", "@value": "Red" },
-                  { "@name": "size", "@value": "L" }
-                ]
-              }
-            }
-          ]
-        }
-      }
-    ]
-  }
-}
-```
-
-**Mapping Configuration:**
-```json
-{
-  "fields": {
-    "orders": {
-      "source": "Orders.Order",
-      "isArray": true,
-      "fields": {
-        "orderRef": {
-          "source": "@id",
-          "required": true
-        },
-        "orderDate": {
-          "source": "@orderDate",
-          "resolver": "sdk.parseDate"
-        },
-        "customerName": {
-          "source": "customer.name",
-          "resolver": "sdk.trim"
-        },
-        "customerEmail": {
-          "source": "customer.email",
-          "resolver": "sdk.lowercase"
-        },
-        "items": {
-          "source": "items.item",
-          "isArray": true,
-          "comment": "Nested array: items within orders",
-          "fields": {
-            "productRef": {
-              "source": "@sku",
-              "required": true
-            },
-            "quantity": {
-              "source": "@qty",
-              "resolver": "sdk.parseInt"
-            },
-            "price": {
-              "source": "price",
-              "resolver": "sdk.parseFloat"
-            },
-            "attributes": {
-              "source": "attributes.attribute",
-              "isArray": true,
-              "comment": "Nested array: attributes within items",
-              "fields": {
-                "name": {
-                  "source": "@name",
-                  "resolver": "sdk.trim"
-                },
-                "value": {
-                  "source": "@value",
-                  "resolver": "sdk.trim"
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-**TypeScript Implementation:**
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-import { XMLParserService } from '@fluentcommerce/fc-connect-sdk';
-
-// Parse XML
-const parser = new XMLParserService();
-const parsedXml = await parser.parse(xmlContent);
-
-// Normalize array (XML parser returns object for single element, array for multiple)
-const ordersData = Array.isArray(parsedXml?.Orders?.Order)
-  ? parsedXml.Orders.Order
-  : parsedXml?.Orders?.Order
-  ? [parsedXml.Orders.Order]
-  : [];
-
-// Create mapper
-const mapper = new UniversalMapper(mappingConfig);
-
-// Map each order
-const mappedOrders = [];
-for (const order of ordersData) {
-  const result = await mapper.map({ Order: order });
-  mappedOrders.push(result.data);
-}
-```
-
-**Mapped Output:**
-```json
-{
-  "orders": [
-    {
-      "orderRef": "ORD-001",
-      "orderDate": "2025-01-22T00:00:00.000Z",
-      "customerName": "John Doe",
-      "customerEmail": "john@example.com",
-      "items": [
-        {
-          "productRef": "PROD-001",
-          "quantity": 2,
-          "price": 29.99,
-          "attributes": [
-            { "name": "color", "value": "Blue" },
-            { "name": "size", "value": "M" }
-          ]
-        },
-        {
-          "productRef": "PROD-002",
-          "quantity": 1,
-          "price": 49.99,
-          "attributes": [
-            { "name": "color", "value": "Red" },
-            { "name": "size", "value": "L" }
-          ]
-        }
-      ]
-    },
-    {
-      "orderRef": "ORD-002",
-      "orderDate": "2025-01-23T00:00:00.000Z",
-      "customerName": "Jane Smith",
-      "customerEmail": "jane@example.com",
-      "items": [
-        {
-          "productRef": "PROD-003",
-          "quantity": 3,
-          "price": 19.99,
-          "attributes": [
-            { "name": "color", "value": "Green" }
-          ]
-        }
-      ]
-    }
-  ]
-}
-```
-
-**Key Points:**
-1. **XML Attributes**: Use `@` prefix (`@id`, `@sku`, `@name`, `@value`)
-2. **Nested Arrays**: Each level requires `isArray: true` with nested `fields`
-3. **Resolvers**: Apply appropriate resolvers (`sdk.parseInt`, `sdk.parseFloat`, `sdk.parseDate`, `sdk.lowercase`, `sdk.trim`)
-4. **Context Switching**: Within array `fields`, `source` paths are relative to each array item
-5. **Array Normalization**: Always normalize XML arrays before mapping (single element → object, multiple → array)
-
----
-
-## Async Resolvers
-
-Resolvers can be async for external lookups and API calls.
-
-### Customer Lookup Example
-
-```typescript
-const customResolvers = {
-  'custom.lookupCustomer': async (email: string, sourceData: any, config: any, helpers: any) => {
-    // Ensure fluentClient is available
-    if (!helpers.fluentClient) {
-      throw new Error('fluentClient not available - pass via UniversalMapper options');
-    }
-
-    // Query Fluent API to find customer by email
-    const query = `
-      query GetCustomerByEmail($email: String!) {
-        customers(email: $email) {
-          edges {
-            node {
-              id
-            }
-          }
-        }
-      }
-    `;
-
-    const result = await helpers.fluentClient.graphql({
-      query,
-      variables: { email }
-    });
-
-    const customerId = result.data.customers.edges[0]?.node.id;
-
-    if (!customerId) {
-      throw new Error(`Customer not found for email: ${email}`);
-    }
-
-    return customerId;
-  }
-};
-
-// Create mapper with fluentClient option
-const mapper = new UniversalMapper(mappingConfig, {
-  customResolvers,
-  fluentClient: fluentClient  // ✅ Makes client available in helpers
-});
-```
-
-### Product Enrichment Example
-
-```typescript
-const customResolvers = {
-  'custom.enrichProduct': async (sku: string, sourceData: any, config: any, helpers: any) => {
-    // Fetch product details from external API
-    const response = await fetch(`https://api.example.com/products/${sku}`);
-    const product = await response.json();
-
-    return {
-      sku: product.sku,
-      name: product.name,
-      description: product.description,
-      category: product.category,
-      price: product.price
-    };
-  }
-};
-```
-
-### Memoized Async Resolver
-
-For repeated lookups, use memoization to cache results:
-
-```typescript
-const customResolvers = {
-  'custom.getCategoryName': helpers.memoize(async (categoryId: string) => {
-    // This will only be called once per unique categoryId
-    const response = await fetch(`https://api.example.com/categories/${categoryId}`);
-    const category = await response.json();
-    return category.name;
-  })
-};
-```
-
-### Performance Consideration
-
-**❌ Avoid:** Individual async calls in batch processing loops
-
-```typescript
-// ❌ Bad - Makes N API calls for N records
-for (const record of records) {
-  const result = await mapper.map(record);  // Each calls async resolver
-}
-```
-
-**✅ Better:** Pre-fetch data, then map synchronously
-
-```typescript
-// ✅ Good - Single batch API call, then fast mapping
-const customerIds = records.map(r => r.customerId);
-const customers = await api.getCustomersBatch(customerIds);
-const customersMap = new Map(customers.map(c => [c.id, c]));
-
-const customResolvers = {
-  'custom.getCustomer': (id: string) => customersMap.get(id)  // Synchronous lookup
-};
-
-for (const record of records) {
-  const result = await mapper.map(record);  // Fast - no API calls
-}
-```
-
----
-
-## Chaining Transformations
-
-Combine multiple transformations via custom resolvers.
-
-### Method 1: Manual Chaining
-
-```typescript
-const customResolvers = {
-  'custom.cleanAndFormat': (value: string, sourceData: any, config: any, helpers: any) => {
-    // Chain: trim → lowercase → capitalize first letter
-    const trimmed = helpers.normalizeWhitespace(value);
-    const lower = trimmed.toLowerCase();
-    return lower.charAt(0).toUpperCase() + lower.slice(1);
-  }
-};
-```
-
-### Method 2: Using SDK Resolvers Within Custom
-
-```typescript
-import { getSdkResolver } from '@fluentcommerce/fc-connect-sdk';
-
-const trim = getSdkResolver('sdk.trim');
-const uppercase = getSdkResolver('sdk.uppercase');
-
-const customResolvers = {
-  'custom.cleanAndUpper': (value: any, sourceData: any, config: any, helpers: any) => {
-    // Chain SDK resolvers
-    const trimmed = trim(value, sourceData, config, helpers);
-    return uppercase(trimmed, sourceData, config, helpers);
-  }
-};
-```
-
-### Complex Chaining Example
-
-```typescript
-const customResolvers = {
-  'custom.processOrderRef': (value: string, sourceData: any, config: any, helpers: any) => {
-    // Step 1: Trim whitespace
-    const cleaned = helpers.normalizeWhitespace(value);
-
-    // Step 2: Uppercase
-    const upper = cleaned.toUpperCase();
-
-    // Step 3: Add prefix if not present
-    const withPrefix = upper.startsWith('ORD-') ? upper : `ORD-${upper}`;
-
-    // Step 4: Validate format
-    if (!/^ORD-[A-Z0-9]+$/.test(withPrefix)) {
-      throw new Error(`Invalid order ref format: ${withPrefix}`);
-    }
-
-    return withPrefix;
-  }
-};
-```
-
-### Resolver Composition
-
-Create reusable resolver building blocks:
-
-```typescript
-// Utility functions
-const cleanString = (value: string) => value.trim().replace(/\s+/g, ' ');
-const normalizeEmail = (value: string) => value.toLowerCase().trim();
-const validateEmail = (value: string) => {
-  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-  if (!emailRegex.test(value)) {
-    throw new Error(`Invalid email: ${value}`);
-  }
-  return value;
-};
-
-// Composed resolvers
-const customResolvers = {
-  'custom.processEmail': (value: string) => {
-    return validateEmail(normalizeEmail(cleanString(value)));
-  },
-
-  'custom.processPhone': (value: string) => {
-    const cleaned = cleanString(value);
-    const digitsOnly = cleaned.replace(/\D/g, '');
-    return `(${digitsOnly.slice(0,3)}) ${digitsOnly.slice(3,6)}-${digitsOnly.slice(6)}`;
-  }
-};
-```
-
----
-
-## Advanced Context Usage
-
-Access workflow-specific data via `helpers.context`.
-
-### Passing Context to Mapper
-
-```typescript
-// Create mapper with context
-const mapper = new UniversalMapper(mappingConfig, {
-  customResolvers,
-  context: {
-    orderId: 'ORD-2025-001',
-    userId: '999',
-    importDate: new Date().toISOString(),
-    retailerId: '1'
-  }
-});
-```
-
-### Using Context in Resolvers
-
-```typescript
-const customResolvers = {
-  'custom.addOrderContext': (value: any, sourceData: any, config: any, helpers: any) => {
-    const orderId = helpers.context?.orderId;
-    return `${value}_${orderId}`;
-  },
-
-  'custom.setRetailer': (value: any, sourceData: any, config: any, helpers: any) => {
-    return helpers.context?.retailerId || '1';
-  },
-
-  'custom.auditTrail': (value: any, sourceData: any, config: any, helpers: any) => {
-    return {
-      value,
-      importedBy: helpers.context?.userId,
-      importedAt: helpers.context?.importDate
-    };
-  }
-};
-```
-
----
-
-## Versori Platform: File Processing with KV State Tracking
-
-**Problem:** Prevent duplicate file processing in scheduled workflows
-
-**Solution:** Use VersoriKVAdapter for state management
-
-### Complete Implementation
-
-```typescript
-import { schedule } from '@versori/run';
-import {
-  SftpDataSource,
-  UniversalMapper,
-  VersoriKVAdapter,
-  XMLParserService,
-  createClient
-} from '@fluentcommerce/fc-connect-sdk';
-
-export const inventorySync = schedule('inventory-sync', '0 */6 * * *', async (ctx) => {
-  const { log, openKv, activation, credentials } = ctx;
-
-  // 1. Initialize KV state tracking
-  const kv = new VersoriKVAdapter(openKv(':project:'));
-  const processedFilesKey = ['inventory-sync', 'processed-files'];
-
-  // Get list of previously processed files
-  const processed = (await kv.get(processedFilesKey))?.value || [];
-  log.info('Previously processed files', { count: processed.length });
-
-  // 2. Connect to SFTP
-  const sftpCreds = await credentials().getAccessToken('SFTP');
-  const [username, password] = Buffer.from(sftpCreds.accessToken, 'base64')
-    .toString('utf-8')
-    .split(':');
-
-  const sftp = new SftpDataSource({
-    type: 'SFTP_XML',
-    sftpConfig: {
-      host: activation.getVariable('SFTP_HOST'),
-      port: 22,
-      username,
-      password,
-      remotePath: '/inbound/inventory/',
-      filePattern: '*.xml'
-    }
-  }, log);
-
-  await sftp.connect();
-
-  // 3. List files and filter out already processed
-  const allFiles = await sftp.listFiles({
-    remotePath: '/inbound/inventory/',
-    filePattern: '*.xml'
-  });
-
-  const newFiles = allFiles.filter(f => !processed.includes(f.name));
-  log.info('New files to process', {
-    total: allFiles.length,
-    new: newFiles.length
-  });
-
-  // 4. Process each new file
-  const mapper = new UniversalMapper({
-    name: 'inventory.xml.mapping',
-    fields: {
-      retailerId: { source: '$context.retailerId', resolver: 'sdk.parseInt' },
-      locationRef: { source: 'facilityId', resolver: 'sdk.trim' },
-      productRef: { source: 'sku', resolver: 'sdk.trim' },
-      quantity: { source: 'qty', resolver: 'sdk.parseInt' }
-    }
-  }, log);
-
-  const client = await createClient({ ...ctx, log });
-  const retailerId = activation.getVariable('fluentRetailerId');
-  if (!retailerId) {
-    throw new Error('fluentRetailerId required in activation variables');
-  }
-  client.setRetailerId(retailerId);
-
-  const results = [];
-
-  for (const file of newFiles) {
-    try {
-      // Download and parse
-      const content = await sftp.downloadFile(file.path, { encoding: 'utf8' });
-      const parser = new XMLParserService(log);
-      const doc = await parser.parse(content);
-
-      // Map records
-      const records = Array.isArray(doc.inventory.item)
-        ? doc.inventory.item
-        : [doc.inventory.item];
-
-      const mappedRecords = [];
-      for (const rec of records) {
-        const result = await mapper.map({
-          ...rec,
-          $context: { retailerId }
-        });
-        if (result.success) {
-          mappedRecords.push(result.data);
-        }
-      }
-
-      // Send to Fluent Batch API
-      await client.batch.submit('INVENTORY_QUANTITY', mappedRecords);
-
-      // Mark as processed
-      processed.push(file.name);
-      await kv.set(processedFilesKey, processed);
-
-      // Archive file
-      await sftp.moveFile(
-        file.path,
-        `/archive/inventory/${file.name}`,
-        true
-      );
-
-      results.push({ file: file.name, status: 'success', records: mappedRecords.length });
-      log.info('File processed successfully', { file: file.name });
-
-    } catch (error) {
-      log.error('File processing failed', { file: file.name, error });
-      results.push({ file: file.name, status: 'failed', error: error.message });
-    }
-  }
-
-  await sftp.disconnect();
-
-  return {
-    success: true,
-    filesProcessed: newFiles.length,
-    results
-  };
-});
-```
-
-### Key Points
-
-- **VersoriKVAdapter:** Persistent state management across workflow runs
-- **Credential Access:** Use `ctx.credentials()` for secure credential retrieval
-- **Environment Variables:** Access via `activation.getVariable()`
-- **File Tracking:** Prevent duplicate processing with KV storage
-- **Error Handling:** Per-file error handling prevents workflow failure
-- **Resource Cleanup:** Always call `sftp.disconnect()` to prevent leaks
-- **Schedule Timeout:** 5 minutes default (adjustable up to 30 minutes)
-
-### Platform Constraints
-
-| Resource | Limit | Impact | Mitigation |
-|----------|-------|--------|------------|
-| **Schedule Timeout** | 5 minutes (default) | Large file batches may timeout | Process in chunks, use continuation |
-| **Memory** | ~512MB | Large files may cause OOM | Use streaming parsers, batch processing |
-| **Concurrent Requests** | ~10 | Parallel API calls limited | Use SDK batch methods, queue processing |
-
-### State Management Pattern
-
-```typescript
-// KV Key Structure
-['workflow-name', 'state-type']
-// Examples:
-['inventory-sync', 'processed-files']    // File tracking
-['order-import', 'last-cursor']          // Pagination cursor
-['daily-extract', 'last-run-timestamp']  // Execution tracking
-```
-
-### Testing in Versori
-
-```bash
-# Trigger schedule manually in Versori UI
-# OR use CLI:
-versori schedule trigger inventory-sync
-
-# Check logs for:
-# - Previously processed files count
-# - New files detected
-# - Processing results
-# - KV state updates
-```
-
----
-
-## Key Takeaways
-
-1. **Nested Objects:** Use dot notation for simple nesting, nested `fields` for complex structures
-2. **Static Values:** Use `value` property for constants at any nesting level
-3. **Conditional Logic:** Custom resolvers enable complex business rules
-4. **Arrays:** Use `isArray: true` to process array elements
-5. **Async Resolvers:** Enable external lookups but use sparingly for performance
-6. **Chaining:** Combine transformations via custom resolvers or SDK resolver composition
-7. **Context:** Pass workflow-specific data via `context` option
-8. **Versori State Management:** Use VersoriKVAdapter for persistent state across runs
-9. **Versori Credentials:** Use `ctx.credentials()` for secure access to connection credentials
-10. **Resource Cleanup:** Always dispose SFTP/database connections to prevent leaks
-
----
-
-## Practice Exercise
-
-**Task:** Create a mapping for complex order data with nested customer, multiple addresses, and line items.
-
-**Source Data:**
-```json
-{
-  "order_id": "12345",
-  "customer_email": "  JOHN@EXAMPLE.COM  ",
-  "customer_tier": "premium",
-  "billing_address": {
-    "street": "123 Main St",
-    "city": "New York",
-    "state": "NY",
-    "zip": "10001"
-  },
-  "shipping_address": {
-    "street": "456 Oak Ave",
-    "city": "Boston",
-    "state": "MA",
-    "zip": "02101"
-  },
-  "line_items": [
-    { "sku": "PROD-001", "qty": "2", "price": "49.99" },
-    { "sku": "PROD-002", "qty": "1", "price": "99.99" }
-  ]
-}
-```
-
-**Requirements:**
-1. Clean and normalize customer email
-2. Map both billing and shipping addresses
-3. Process line items array
-4. Calculate item totals
-5. Determine priority based on customer tier
-
-<details>
-<summary>Click to see solution</summary>
-
-```json
-{
-  "fields": {
-    "ref": {
-      "source": "order_id"
-    },
-    "customer": {
-      "fields": {
-        "email": {
-          "source": "customer_email",
-          "resolver": "custom.cleanEmail"
-        }
-      }
-    },
-    "priority": {
-      "source": "customer_tier",
-      "resolver": "custom.calculatePriority"
-    },
-    "billingAddress": {
-      "fields": {
-        "street": {
-          "source": "billing_address.street"
-        },
-        "city": {
-          "source": "billing_address.city"
-        },
-        "state": {
-          "source": "billing_address.state"
-        },
-        "zipCode": {
-          "source": "billing_address.zip"
-        }
-      }
-    },
-    "shippingAddress": {
-      "fields": {
-        "street": {
-          "source": "shipping_address.street"
-        },
-        "city": {
-          "source": "shipping_address.city"
-        },
-        "state": {
-          "source": "shipping_address.state"
-        },
-        "zipCode": {
-          "source": "shipping_address.zip"
-        }
-      }
-    },
-    "items": {
-      "source": "line_items",
-      "isArray": true,
-      "fields": {
-        "productRef": {
-          "source": "sku"
-        },
-        "quantity": {
-          "source": "qty",
-          "resolver": "sdk.parseInt"
-        },
-        "price": {
-          "source": "price",
-          "resolver": "sdk.parseFloat"
-        },
-        "totalPrice": {
-          "resolver": "custom.calculateItemTotal"
-        }
-      }
-    }
-  }
-}
-```
-
-**Custom Resolvers:**
-```typescript
-const customResolvers = {
-  'custom.cleanEmail': (value: string, sourceData: any, config: any, helpers: any) => {
-    return helpers.normalizeWhitespace(value).toLowerCase();
-  },
-
-  'custom.calculatePriority': (tier: string) => {
-    return tier === 'premium' ? 'HIGH' : 'NORMAL';
-  },
-
-  'custom.calculateItemTotal': (value: any, sourceData: any, config: any, helpers: any) => {
-    const qty = helpers.parseIntSafe(sourceData.qty, 0);
-    const price = helpers.parseFloatSafe(sourceData.price, 0);
-    return qty * price;
-  }
-};
-```
-
-</details>
-
----
-
-## Next Steps
-
-Now that you've mastered advanced patterns, explore the helper functions available:
-
-→ Continue to [Module 6: Helpers & Resolvers](./mapping-06-helpers-resolvers.md)
-
-**Alternative paths:**
-- Jump to [API Reference](../../auto-pagination/modules/auto-pagination-07-api-reference.md) for TypeScript usage
-- Review [GraphQL Mutation Mapping Quick Reference](../graphql-mutation-mapping/graphql-mutation-mapping-quick-reference.md) for a comprehensive cheat sheet
-
----
-
-[← Back to Use Cases](./mapping-04-use-cases.md) | [Next: Helpers & Resolvers →](./mapping-06-helpers-resolvers.md)
-
-
-
-
-
-
-
-
-
-
-
-
+# Module 5: Advanced Patterns
+
+**Master complex transformations**
+
+**Level:** Advanced
+**Time:** 40 minutes
+**Prerequisites:** [Module 4: Use Cases](./mapping-04-use-cases.md)
+
+---
+
+## Learning Objectives
+
+After completing this module, you will:
+- ✅ Map complex nested object structures
+- ✅ Process arrays with `isArray` configuration
+- ✅ Implement conditional transformations
+- ✅ Use async resolvers for external lookups
+- ✅ Chain multiple transformations
+- ✅ Handle GraphQL edges/nodes pagination patterns
+
+---
+
+## Nested Objects
+
+Map nested structures using dot notation or nested `fields` configuration.
+
+### Method 1: Dot Notation (Flat Mapping)
+
+```json
+{
+  "fields": {
+    "customer.id": {
+      "source": "customerId",
+      "resolver": "sdk.parseInt"
+    },
+    "customer.email": {
+      "source": "email",
+      "resolver": "sdk.lowercase"
+    },
+    "customer.address.city": {
+      "source": "city"
+    },
+    "customer.address.state": {
+      "source": "state"
+    },
+    "customer.address.zipCode": {
+      "source": "zip"
+    }
+  }
+}
+```
+
+**Output:**
+```json
+{
+  "customer": {
+    "id": 12345,
+    "email": "john@example.com",
+    "address": {
+      "city": "New York",
+      "state": "NY",
+      "zipCode": "10001"
+    }
+  }
+}
+```
+
+### Method 2: Nested Fields (Structured Mapping)
+
+```json
+{
+  "fields": {
+    "customer": {
+      "fields": {
+        "id": {
+          "source": "customerId",
+          "resolver": "sdk.parseInt"
+        },
+        "email": {
+          "source": "email",
+          "resolver": "sdk.lowercase"
+        },
+        "address": {
+          "fields": {
+            "city": {
+              "source": "city"
+            },
+            "state": {
+              "source": "state"
+            },
+            "zipCode": {
+              "source": "zip"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Same output** as Method 1, but more structured and easier to read for complex objects.
+
+### When to Use Each Method
+
+| Method | Best For | Advantages | Disadvantages |
+|--------|----------|------------|---------------|
+| **Dot Notation** | Simple nesting (2-3 levels) | Concise, flat structure | Hard to read for deep nesting |
+| **Nested Fields** | Complex objects, reusable components | Clear hierarchy, organized | More verbose |
+
+### Deep Nesting Example
+
+```json
+{
+  "fields": {
+    "order": {
+      "fields": {
+        "ref": {
+          "source": "orderRef"
+        },
+        "customer": {
+          "fields": {
+            "id": {
+              "source": "customerId"
+            },
+            "profile": {
+              "fields": {
+                "firstName": {
+                  "source": "firstName"
+                },
+                "lastName": {
+                  "source": "lastName"
+                },
+                "preferences": {
+                  "fields": {
+                    "language": {
+                      "source": "lang",
+                      "defaultValue": "en"
+                    },
+                    "currency": {
+                      "source": "currency",
+                      "defaultValue": "USD"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Static Values
+
+Provide constant values at any nesting level.
+
+### Simple Static Values
+
+```json
+{
+  "fields": {
+    "type": {
+      "value": "STANDARD"
+    },
+    "retailerId": {
+      "value": 1
+    },
+    "source": {
+      "value": "CSV_IMPORT"
+    },
+    "status": {
+      "value": "ACTIVE"
+    }
+  }
+}
+```
+
+### Static Values in Nested Objects
+
+```json
+{
+  "fields": {
+    "retailer": {
+      "fields": {
+        "id": {
+          "value": "1",
+          "comment": "Static retailer ID"
+        }
+      }
+    },
+    "metadata": {
+      "fields": {
+        "importSource": {
+          "value": "SFCC"
+        },
+        "importVersion": {
+          "value": "2.0"
+        },
+        "importTimestamp": {
+          "resolver": "custom.currentTimestamp"
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Conditional Transformations
+
+Use custom resolvers for complex business logic and conditional mapping.
+
+### Simple Conditional Mapping
+
+```json
+{
+  "fields": {
+    "shippingMethod": {
+      "source": "deliverySpeed",
+      "resolver": "custom.mapShipping"
+    },
+    "priority": {
+      "source": "orderType",
+      "resolver": "custom.calculatePriority"
+    }
+  }
+}
+```
+
+**Custom Resolvers:**
+```typescript
+const customResolvers = {
+  'custom.mapShipping': (value: string) => {
+    // Map delivery speed to shipping method
+    const shippingMap: Record<string, string> = {
+      'express': 'OVERNIGHT',
+      'fast': 'TWO_DAY',
+      'standard': 'GROUND',
+      'economy': 'STANDARD'
+    };
+    return shippingMap[value.toLowerCase()] || 'STANDARD';
+  },
+
+  'custom.calculatePriority': (value: string, sourceData: any) => {
+    // Calculate priority based on order type and total
+    const isPremium = sourceData.customerTier === 'PREMIUM';
+    const isUrgent = value === 'EXPRESS';
+    const isLargeOrder = sourceData.total > 1000;
+
+    if (isUrgent || isPremium) return 'HIGH';
+    if (isLargeOrder) return 'MEDIUM';
+    return 'LOW';
+  }
+};
+```
+
+### Multi-Condition Resolver
+
+```typescript
+const customResolvers = {
+  'custom.determineOrderType': (value: any, sourceData: any, config: any, helpers: any) => {
+    const total = helpers.parseFloatSafe(sourceData.total, 0);
+    const itemCount = helpers.parseIntSafe(sourceData.itemCount, 0);
+    const isInternational = sourceData.country !== 'US';
+
+    // Complex business rules
+    if (isInternational && total > 500) {
+      return 'INTERNATIONAL_PREMIUM';
+    }
+
+    if (itemCount > 20 || total > 1000) {
+      return 'BULK';
+    }
+
+    if (sourceData.expedited === true) {
+      return 'EXPRESS';
+    }
+
+    return 'STANDARD';
+  }
+};
+```
+
+---
+
+## Arrays
+
+Map arrays of items using the `isArray` field configuration.
+
+### Array Mapping with `isArray`
+
+```json
+{
+  "fields": {
+    "items": {
+      "source": "orderItems",
+      "isArray": true,
+      "fields": {
+        "ref": {
+          "source": "id"
+        },
+        "productRef": {
+          "source": "sku"
+        },
+        "quantity": {
+          "source": "qty",
+          "resolver": "sdk.parseInt"
+        },
+        "price": {
+          "source": "unitPrice",
+          "resolver": "sdk.parseFloat"
+        },
+        "totalPrice": {
+          "resolver": "custom.calculateItemTotal"
+        }
+      }
+    }
+  }
+}
+```
+
+### How `isArray` Works
+
+1. **Extract Array:** `source: "orderItems"` extracts the array from source data
+2. **Iterate:** `isArray: true` tells mapper to iterate over array elements
+3. **Map Each Item:** `fields: {...}` defines mappings for each array element
+4. **Context Switch:** ⚠️ **THIS IS THE KEY CONCEPT**
+
+   Once inside `fields` of an `isArray` mapping, the context changes:
+
+   ```mermaid
+   flowchart TD
+       A[Root Context<br/>orderItems: [...],<br/>customerId: 123] -->|Iterate Array| B[Array Item Context<br/>id: 'ITEM-1'<br/>sku: 'PROD-001'<br/>qty: '2']
+       B -->|Map Fields| C[Field Mappings<br/>source: 'id'<br/>→ Reads from item,<br/>NOT root]
+       
+       style A fill:#e1f5ff
+       style B fill:#fff4e1
+       style C fill:#e8f5e9
+   ```
+
+   **Text Version:**
+   ```
+   Root Context:     { orderItems: [...], customerId: 123 }
+                              ↓ iterate
+   Array Item:       { id: "ITEM-1", sku: "PROD-001", qty: "2" }  ← NEW CONTEXT!
+                              ↓ map fields
+   Field Mappings:   "source": "id" reads from THIS object, not root
+   ```
+
+   **In other words:**
+   - `"source": "id"` → reads `currentArrayItem.id`
+   - `"source": "sku"` → reads `currentArrayItem.sku`
+   - NOT `sourceData.id` or `sourceData.sku`
+
+**Source Data:**
+```json
+{
+  "orderItems": [
+    { "id": "ITEM-1", "sku": "PROD-001", "qty": "2", "unitPrice": "49.99" },
+    { "id": "ITEM-2", "sku": "PROD-002", "qty": "1", "unitPrice": "99.99" }
+  ]
+}
+```
+
+**Mapped Output:**
+```json
+{
+  "items": [
+    { "ref": "ITEM-1", "productRef": "PROD-001", "quantity": 2, "price": 49.99, "totalPrice": 99.98 },
+    { "ref": "ITEM-2", "productRef": "PROD-002", "quantity": 1, "price": 99.99, "totalPrice": 99.99 }
+  ]
+}
+```
+
+### Common Mistake: Don't Repeat Array Path
+
+**❌ WRONG - Repeating array path in nested fields:**
+```json
+{
+  "items": {
+    "source": "orderItems",
+    "isArray": true,
+    "fields": {
+      "ref": {
+        "source": "orderItems[0].id"  // ❌ Already inside array context!
+      }
+    }
+  }
+}
+```
+
+**✅ CORRECT - Use paths relative to array item:**
+```json
+{
+  "items": {
+    "source": "orderItems",
+    "isArray": true,
+    "fields": {
+      "ref": {
+        "source": "id"  // ✅ Reads from current array item
+      }
+    }
+  }
+}
+```
+
+### Accessing Array Item Context
+
+Within array field mappings, use `source` paths relative to the array item:
+
+```json
+{
+  "items": {
+    "source": "orderItems",
+    "isArray": true,
+    "fields": {
+      "ref": {
+        "source": "id"  // ← Reads from current array item's 'id' field
+      },
+      "productRef": {
+        "source": "sku"  // ← Reads from current array item's 'sku' field
+      }
+    }
+  }
+}
+```
+
+### GraphQL Edges/Nodes Pattern
+
+**IMPORTANT:** The asterisk `[*]` is optional. Both patterns work:
+
+**Option 1: With wildcard (extracts nodes directly)**
+```json
+{
+  "fields": {
+    "products": {
+      "source": "products.edges[*].node",  // Wildcard extracts nodes
+      "isArray": true,
+      "fields": {
+        "id": { "source": "id" },         // Direct access (no "node." prefix)
+        "ref": { "source": "ref" },
+        "name": { "source": "name" },
+        "price": { "source": "price", "resolver": "sdk.parseFloat" }
+      }
+    }
+  }
+}
+```
+
+**Option 2: Without wildcard (extracts edges)**
+```json
+{
+  "fields": {
+    "products": {
+      "source": "products.edges",          // Direct array access
+      "isArray": true,
+      "fields": {
+        "id": { "source": "node.id" },     // Need "node." prefix
+        "ref": { "source": "node.ref" },
+        "name": { "source": "node.name" },
+        "price": { "source": "node.price", "resolver": "sdk.parseFloat" }
+      }
+    }
+  }
+}
+```
+
+**Option 3: Auto-detection (SDK detects GraphQL structure)**
+```json
+{
+  "fields": {
+    "products": {
+      "source": "products",                // SDK auto-detects { edges: [...] }
+      "isArray": true,
+      "fields": {
+        "id": { "source": "id" },         // Direct access (nodes auto-extracted)
+        "ref": { "source": "ref" },
+        "name": { "source": "name" },
+        "price": { "source": "price", "resolver": "sdk.parseFloat" }
+      }
+    }
+  }
+}
+```
+
+**All three produce the same result** - choose based on clarity for your use case
+
+**Source Data (GraphQL):**
+```json
+{
+  "products": {
+    "edges": [
+      { "cursor": "abc123", "node": { "id": "1", "ref": "PROD-001", "name": "Widget", "price": 19.99 } },
+      { "cursor": "def456", "node": { "id": "2", "ref": "PROD-002", "name": "Gadget", "price": 29.99 } }
+    ]
+  }
+}
+```
+
+**Mapped Output:**
+```json
+{
+  "products": [
+    { "id": "1", "ref": "PROD-001", "name": "Widget", "price": 19.99 },
+    { "id": "2", "ref": "PROD-002", "name": "Gadget", "price": 29.99 }
+  ]
+}
+```
+
+### Nested Arrays
+
+Arrays within arrays require nested `isArray` configuration. This is common when parsing XML with complex nested structures.
+
+#### XML Example with Nested Arrays
+
+**Sample XML:**
+```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>
+        <attributes>
+          <attribute name="color" value="Blue"/>
+          <attribute name="size" value="M"/>
+        </attributes>
+      </item>
+      <item sku="PROD-002" qty="1">
+        <price>49.99</price>
+        <attributes>
+          <attribute name="color" value="Red"/>
+          <attribute name="size" value="L"/>
+        </attributes>
+      </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>
+        <attributes>
+          <attribute name="color" value="Green"/>
+        </attributes>
+      </item>
+    </items>
+  </Order>
+</Orders>
+```
+
+**After XML Parsing (fast-xml-parser):**
+```json
+{
+  "Orders": {
+    "Order": [
+      {
+        "@id": "ORD-001",
+        "@orderDate": "2025-01-22",
+        "customer": {
+          "name": "John Doe",
+          "email": "John@Example.com"
+        },
+        "items": {
+          "item": [
+            {
+              "@sku": "PROD-001",
+              "@qty": "2",
+              "price": "29.99",
+              "attributes": {
+                "attribute": [
+                  { "@name": "color", "@value": "Blue" },
+                  { "@name": "size", "@value": "M" }
+                ]
+              }
+            },
+            {
+              "@sku": "PROD-002",
+              "@qty": "1",
+              "price": "49.99",
+              "attributes": {
+                "attribute": [
+                  { "@name": "color", "@value": "Red" },
+                  { "@name": "size", "@value": "L" }
+                ]
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+**Mapping Configuration:**
+```json
+{
+  "fields": {
+    "orders": {
+      "source": "Orders.Order",
+      "isArray": true,
+      "fields": {
+        "orderRef": {
+          "source": "@id",
+          "required": true
+        },
+        "orderDate": {
+          "source": "@orderDate",
+          "resolver": "sdk.parseDate"
+        },
+        "customerName": {
+          "source": "customer.name",
+          "resolver": "sdk.trim"
+        },
+        "customerEmail": {
+          "source": "customer.email",
+          "resolver": "sdk.lowercase"
+        },
+        "items": {
+          "source": "items.item",
+          "isArray": true,
+          "comment": "Nested array: items within orders",
+          "fields": {
+            "productRef": {
+              "source": "@sku",
+              "required": true
+            },
+            "quantity": {
+              "source": "@qty",
+              "resolver": "sdk.parseInt"
+            },
+            "price": {
+              "source": "price",
+              "resolver": "sdk.parseFloat"
+            },
+            "attributes": {
+              "source": "attributes.attribute",
+              "isArray": true,
+              "comment": "Nested array: attributes within items",
+              "fields": {
+                "name": {
+                  "source": "@name",
+                  "resolver": "sdk.trim"
+                },
+                "value": {
+                  "source": "@value",
+                  "resolver": "sdk.trim"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**TypeScript Implementation:**
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+import { XMLParserService } from '@fluentcommerce/fc-connect-sdk';
+
+// Parse XML
+const parser = new XMLParserService();
+const parsedXml = await parser.parse(xmlContent);
+
+// Normalize array (XML parser returns object for single element, array for multiple)
+const ordersData = Array.isArray(parsedXml?.Orders?.Order)
+  ? parsedXml.Orders.Order
+  : parsedXml?.Orders?.Order
+  ? [parsedXml.Orders.Order]
+  : [];
+
+// Create mapper
+const mapper = new UniversalMapper(mappingConfig);
+
+// Map each order
+const mappedOrders = [];
+for (const order of ordersData) {
+  const result = await mapper.map({ Order: order });
+  mappedOrders.push(result.data);
+}
+```
+
+**Mapped Output:**
+```json
+{
+  "orders": [
+    {
+      "orderRef": "ORD-001",
+      "orderDate": "2025-01-22T00:00:00.000Z",
+      "customerName": "John Doe",
+      "customerEmail": "john@example.com",
+      "items": [
+        {
+          "productRef": "PROD-001",
+          "quantity": 2,
+          "price": 29.99,
+          "attributes": [
+            { "name": "color", "value": "Blue" },
+            { "name": "size", "value": "M" }
+          ]
+        },
+        {
+          "productRef": "PROD-002",
+          "quantity": 1,
+          "price": 49.99,
+          "attributes": [
+            { "name": "color", "value": "Red" },
+            { "name": "size", "value": "L" }
+          ]
+        }
+      ]
+    },
+    {
+      "orderRef": "ORD-002",
+      "orderDate": "2025-01-23T00:00:00.000Z",
+      "customerName": "Jane Smith",
+      "customerEmail": "jane@example.com",
+      "items": [
+        {
+          "productRef": "PROD-003",
+          "quantity": 3,
+          "price": 19.99,
+          "attributes": [
+            { "name": "color", "value": "Green" }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Key Points:**
+1. **XML Attributes**: Use `@` prefix (`@id`, `@sku`, `@name`, `@value`)
+2. **Nested Arrays**: Each level requires `isArray: true` with nested `fields`
+3. **Resolvers**: Apply appropriate resolvers (`sdk.parseInt`, `sdk.parseFloat`, `sdk.parseDate`, `sdk.lowercase`, `sdk.trim`)
+4. **Context Switching**: Within array `fields`, `source` paths are relative to each array item
+5. **Array Normalization**: Always normalize XML arrays before mapping (single element → object, multiple → array)
+
+---
+
+## Async Resolvers
+
+Resolvers can be async for external lookups and API calls.
+
+### Customer Lookup Example
+
+```typescript
+const customResolvers = {
+  'custom.lookupCustomer': async (email: string, sourceData: any, config: any, helpers: any) => {
+    // Ensure fluentClient is available
+    if (!helpers.fluentClient) {
+      throw new Error('fluentClient not available - pass via UniversalMapper options');
+    }
+
+    // Query Fluent API to find customer by email
+    const query = `
+      query GetCustomerByEmail($email: String!) {
+        customers(email: $email) {
+          edges {
+            node {
+              id
+            }
+          }
+        }
+      }
+    `;
+
+    const result = await helpers.fluentClient.graphql({
+      query,
+      variables: { email }
+    });
+
+    const customerId = result.data.customers.edges[0]?.node.id;
+
+    if (!customerId) {
+      throw new Error(`Customer not found for email: ${email}`);
+    }
+
+    return customerId;
+  }
+};
+
+// Create mapper with fluentClient option
+const mapper = new UniversalMapper(mappingConfig, {
+  customResolvers,
+  fluentClient: fluentClient  // ✅ Makes client available in helpers
+});
+```
+
+### Product Enrichment Example
+
+```typescript
+const customResolvers = {
+  'custom.enrichProduct': async (sku: string, sourceData: any, config: any, helpers: any) => {
+    // Fetch product details from external API
+    const response = await fetch(`https://api.example.com/products/${sku}`);
+    const product = await response.json();
+
+    return {
+      sku: product.sku,
+      name: product.name,
+      description: product.description,
+      category: product.category,
+      price: product.price
+    };
+  }
+};
+```
+
+### Memoized Async Resolver
+
+For repeated lookups, use memoization to cache results:
+
+```typescript
+const customResolvers = {
+  'custom.getCategoryName': helpers.memoize(async (categoryId: string) => {
+    // This will only be called once per unique categoryId
+    const response = await fetch(`https://api.example.com/categories/${categoryId}`);
+    const category = await response.json();
+    return category.name;
+  })
+};
+```
+
+### Performance Consideration
+
+**❌ Avoid:** Individual async calls in batch processing loops
+
+```typescript
+// ❌ Bad - Makes N API calls for N records
+for (const record of records) {
+  const result = await mapper.map(record);  // Each calls async resolver
+}
+```
+
+**✅ Better:** Pre-fetch data, then map synchronously
+
+```typescript
+// ✅ Good - Single batch API call, then fast mapping
+const customerIds = records.map(r => r.customerId);
+const customers = await api.getCustomersBatch(customerIds);
+const customersMap = new Map(customers.map(c => [c.id, c]));
+
+const customResolvers = {
+  'custom.getCustomer': (id: string) => customersMap.get(id)  // Synchronous lookup
+};
+
+for (const record of records) {
+  const result = await mapper.map(record);  // Fast - no API calls
+}
+```
+
+---
+
+## Chaining Transformations
+
+Combine multiple transformations via custom resolvers.
+
+### Method 1: Manual Chaining
+
+```typescript
+const customResolvers = {
+  'custom.cleanAndFormat': (value: string, sourceData: any, config: any, helpers: any) => {
+    // Chain: trim → lowercase → capitalize first letter
+    const trimmed = helpers.normalizeWhitespace(value);
+    const lower = trimmed.toLowerCase();
+    return lower.charAt(0).toUpperCase() + lower.slice(1);
+  }
+};
+```
+
+### Method 2: Using SDK Resolvers Within Custom
+
+```typescript
+import { getSdkResolver } from '@fluentcommerce/fc-connect-sdk';
+
+const trim = getSdkResolver('sdk.trim');
+const uppercase = getSdkResolver('sdk.uppercase');
+
+const customResolvers = {
+  'custom.cleanAndUpper': (value: any, sourceData: any, config: any, helpers: any) => {
+    // Chain SDK resolvers
+    const trimmed = trim(value, sourceData, config, helpers);
+    return uppercase(trimmed, sourceData, config, helpers);
+  }
+};
+```
+
+### Complex Chaining Example
+
+```typescript
+const customResolvers = {
+  'custom.processOrderRef': (value: string, sourceData: any, config: any, helpers: any) => {
+    // Step 1: Trim whitespace
+    const cleaned = helpers.normalizeWhitespace(value);
+
+    // Step 2: Uppercase
+    const upper = cleaned.toUpperCase();
+
+    // Step 3: Add prefix if not present
+    const withPrefix = upper.startsWith('ORD-') ? upper : `ORD-${upper}`;
+
+    // Step 4: Validate format
+    if (!/^ORD-[A-Z0-9]+$/.test(withPrefix)) {
+      throw new Error(`Invalid order ref format: ${withPrefix}`);
+    }
+
+    return withPrefix;
+  }
+};
+```
+
+### Resolver Composition
+
+Create reusable resolver building blocks:
+
+```typescript
+// Utility functions
+const cleanString = (value: string) => value.trim().replace(/\s+/g, ' ');
+const normalizeEmail = (value: string) => value.toLowerCase().trim();
+const validateEmail = (value: string) => {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  if (!emailRegex.test(value)) {
+    throw new Error(`Invalid email: ${value}`);
+  }
+  return value;
+};
+
+// Composed resolvers
+const customResolvers = {
+  'custom.processEmail': (value: string) => {
+    return validateEmail(normalizeEmail(cleanString(value)));
+  },
+
+  'custom.processPhone': (value: string) => {
+    const cleaned = cleanString(value);
+    const digitsOnly = cleaned.replace(/\D/g, '');
+    return `(${digitsOnly.slice(0,3)}) ${digitsOnly.slice(3,6)}-${digitsOnly.slice(6)}`;
+  }
+};
+```
+
+---
+
+## Advanced Context Usage
+
+Access workflow-specific data via `helpers.context`.
+
+### Passing Context to Mapper
+
+```typescript
+// Create mapper with context
+const mapper = new UniversalMapper(mappingConfig, {
+  customResolvers,
+  context: {
+    orderId: 'ORD-2025-001',
+    userId: '999',
+    importDate: new Date().toISOString(),
+    retailerId: '1'
+  }
+});
+```
+
+### Using Context in Resolvers
+
+```typescript
+const customResolvers = {
+  'custom.addOrderContext': (value: any, sourceData: any, config: any, helpers: any) => {
+    const orderId = helpers.context?.orderId;
+    return `${value}_${orderId}`;
+  },
+
+  'custom.setRetailer': (value: any, sourceData: any, config: any, helpers: any) => {
+    return helpers.context?.retailerId || '1';
+  },
+
+  'custom.auditTrail': (value: any, sourceData: any, config: any, helpers: any) => {
+    return {
+      value,
+      importedBy: helpers.context?.userId,
+      importedAt: helpers.context?.importDate
+    };
+  }
+};
+```
+
+---
+
+## Versori Platform: File Processing with KV State Tracking
+
+**Problem:** Prevent duplicate file processing in scheduled workflows
+
+**Solution:** Use VersoriKVAdapter for state management
+
+### Complete Implementation
+
+```typescript
+import { schedule } from '@versori/run';
+import {
+  SftpDataSource,
+  UniversalMapper,
+  VersoriKVAdapter,
+  XMLParserService,
+  createClient
+} from '@fluentcommerce/fc-connect-sdk';
+
+export const inventorySync = schedule('inventory-sync', '0 */6 * * *', async (ctx) => {
+  const { log, openKv, activation, credentials } = ctx;
+
+  // 1. Initialize KV state tracking
+  const kv = new VersoriKVAdapter(openKv(':project:'));
+  const processedFilesKey = ['inventory-sync', 'processed-files'];
+
+  // Get list of previously processed files
+  const processed = (await kv.get(processedFilesKey))?.value || [];
+  log.info('Previously processed files', { count: processed.length });
+
+  // 2. Connect to SFTP
+  const sftpCreds = await credentials().getAccessToken('SFTP');
+  const [username, password] = Buffer.from(sftpCreds.accessToken, 'base64')
+    .toString('utf-8')
+    .split(':');
+
+  const sftp = new SftpDataSource({
+    type: 'SFTP_XML',
+    sftpConfig: {
+      host: activation.getVariable('SFTP_HOST'),
+      port: 22,
+      username,
+      password,
+      remotePath: '/inbound/inventory/',
+      filePattern: '*.xml'
+    }
+  }, log);
+
+  await sftp.connect();
+
+  // 3. List files and filter out already processed
+  const allFiles = await sftp.listFiles({
+    remotePath: '/inbound/inventory/',
+    filePattern: '*.xml'
+  });
+
+  const newFiles = allFiles.filter(f => !processed.includes(f.name));
+  log.info('New files to process', {
+    total: allFiles.length,
+    new: newFiles.length
+  });
+
+  // 4. Process each new file
+  const mapper = new UniversalMapper({
+    name: 'inventory.xml.mapping',
+    fields: {
+      retailerId: { source: '$context.retailerId', resolver: 'sdk.parseInt' },
+      locationRef: { source: 'facilityId', resolver: 'sdk.trim' },
+      productRef: { source: 'sku', resolver: 'sdk.trim' },
+      quantity: { source: 'qty', resolver: 'sdk.parseInt' }
+    }
+  }, log);
+
+  const client = await createClient({ ...ctx, log });
+  const retailerId = activation.getVariable('fluentRetailerId');
+  if (!retailerId) {
+    throw new Error('fluentRetailerId required in activation variables');
+  }
+  client.setRetailerId(retailerId);
+
+  const results = [];
+
+  for (const file of newFiles) {
+    try {
+      // Download and parse
+      const content = await sftp.downloadFile(file.path, { encoding: 'utf8' });
+      const parser = new XMLParserService(log);
+      const doc = await parser.parse(content);
+
+      // Map records
+      const records = Array.isArray(doc.inventory.item)
+        ? doc.inventory.item
+        : [doc.inventory.item];
+
+      const mappedRecords = [];
+      for (const rec of records) {
+        const result = await mapper.map({
+          ...rec,
+          $context: { retailerId }
+        });
+        if (result.success) {
+          mappedRecords.push(result.data);
+        }
+      }
+
+      // Send to Fluent Batch API
+      await client.batch.submit('INVENTORY_QUANTITY', mappedRecords);
+
+      // Mark as processed
+      processed.push(file.name);
+      await kv.set(processedFilesKey, processed);
+
+      // Archive file
+      await sftp.moveFile(
+        file.path,
+        `/archive/inventory/${file.name}`,
+        true
+      );
+
+      results.push({ file: file.name, status: 'success', records: mappedRecords.length });
+      log.info('File processed successfully', { file: file.name });
+
+    } catch (error) {
+      log.error('File processing failed', { file: file.name, error });
+      results.push({ file: file.name, status: 'failed', error: error.message });
+    }
+  }
+
+  await sftp.disconnect();
+
+  return {
+    success: true,
+    filesProcessed: newFiles.length,
+    results
+  };
+});
+```
+
+### Key Points
+
+- **VersoriKVAdapter:** Persistent state management across workflow runs
+- **Credential Access:** Use `ctx.credentials()` for secure credential retrieval
+- **Environment Variables:** Access via `activation.getVariable()`
+- **File Tracking:** Prevent duplicate processing with KV storage
+- **Error Handling:** Per-file error handling prevents workflow failure
+- **Resource Cleanup:** Always call `sftp.disconnect()` to prevent leaks
+- **Schedule Timeout:** 5 minutes default (adjustable up to 30 minutes)
+
+### Platform Constraints
+
+| Resource | Limit | Impact | Mitigation |
+|----------|-------|--------|------------|
+| **Schedule Timeout** | 5 minutes (default) | Large file batches may timeout | Process in chunks, use continuation |
+| **Memory** | ~512MB | Large files may cause OOM | Use streaming parsers, batch processing |
+| **Concurrent Requests** | ~10 | Parallel API calls limited | Use SDK batch methods, queue processing |
+
+### State Management Pattern
+
+```typescript
+// KV Key Structure
+['workflow-name', 'state-type']
+// Examples:
+['inventory-sync', 'processed-files']    // File tracking
+['order-import', 'last-cursor']          // Pagination cursor
+['daily-extract', 'last-run-timestamp']  // Execution tracking
+```
+
+### Testing in Versori
+
+```bash
+# Trigger schedule manually in Versori UI
+# OR use CLI:
+versori schedule trigger inventory-sync
+
+# Check logs for:
+# - Previously processed files count
+# - New files detected
+# - Processing results
+# - KV state updates
+```
+
+---
+
+## Key Takeaways
+
+1. **Nested Objects:** Use dot notation for simple nesting, nested `fields` for complex structures
+2. **Static Values:** Use `value` property for constants at any nesting level
+3. **Conditional Logic:** Custom resolvers enable complex business rules
+4. **Arrays:** Use `isArray: true` to process array elements
+5. **Async Resolvers:** Enable external lookups but use sparingly for performance
+6. **Chaining:** Combine transformations via custom resolvers or SDK resolver composition
+7. **Context:** Pass workflow-specific data via `context` option
+8. **Versori State Management:** Use VersoriKVAdapter for persistent state across runs
+9. **Versori Credentials:** Use `ctx.credentials()` for secure access to connection credentials
+10. **Resource Cleanup:** Always dispose SFTP/database connections to prevent leaks
+
+---
+
+## Practice Exercise
+
+**Task:** Create a mapping for complex order data with nested customer, multiple addresses, and line items.
+
+**Source Data:**
+```json
+{
+  "order_id": "12345",
+  "customer_email": "  JOHN@EXAMPLE.COM  ",
+  "customer_tier": "premium",
+  "billing_address": {
+    "street": "123 Main St",
+    "city": "New York",
+    "state": "NY",
+    "zip": "10001"
+  },
+  "shipping_address": {
+    "street": "456 Oak Ave",
+    "city": "Boston",
+    "state": "MA",
+    "zip": "02101"
+  },
+  "line_items": [
+    { "sku": "PROD-001", "qty": "2", "price": "49.99" },
+    { "sku": "PROD-002", "qty": "1", "price": "99.99" }
+  ]
+}
+```
+
+**Requirements:**
+1. Clean and normalize customer email
+2. Map both billing and shipping addresses
+3. Process line items array
+4. Calculate item totals
+5. Determine priority based on customer tier
+
+<details>
+<summary>Click to see solution</summary>
+
+```json
+{
+  "fields": {
+    "ref": {
+      "source": "order_id"
+    },
+    "customer": {
+      "fields": {
+        "email": {
+          "source": "customer_email",
+          "resolver": "custom.cleanEmail"
+        }
+      }
+    },
+    "priority": {
+      "source": "customer_tier",
+      "resolver": "custom.calculatePriority"
+    },
+    "billingAddress": {
+      "fields": {
+        "street": {
+          "source": "billing_address.street"
+        },
+        "city": {
+          "source": "billing_address.city"
+        },
+        "state": {
+          "source": "billing_address.state"
+        },
+        "zipCode": {
+          "source": "billing_address.zip"
+        }
+      }
+    },
+    "shippingAddress": {
+      "fields": {
+        "street": {
+          "source": "shipping_address.street"
+        },
+        "city": {
+          "source": "shipping_address.city"
+        },
+        "state": {
+          "source": "shipping_address.state"
+        },
+        "zipCode": {
+          "source": "shipping_address.zip"
+        }
+      }
+    },
+    "items": {
+      "source": "line_items",
+      "isArray": true,
+      "fields": {
+        "productRef": {
+          "source": "sku"
+        },
+        "quantity": {
+          "source": "qty",
+          "resolver": "sdk.parseInt"
+        },
+        "price": {
+          "source": "price",
+          "resolver": "sdk.parseFloat"
+        },
+        "totalPrice": {
+          "resolver": "custom.calculateItemTotal"
+        }
+      }
+    }
+  }
+}
+```
+
+**Custom Resolvers:**
+```typescript
+const customResolvers = {
+  'custom.cleanEmail': (value: string, sourceData: any, config: any, helpers: any) => {
+    return helpers.normalizeWhitespace(value).toLowerCase();
+  },
+
+  'custom.calculatePriority': (tier: string) => {
+    return tier === 'premium' ? 'HIGH' : 'NORMAL';
+  },
+
+  'custom.calculateItemTotal': (value: any, sourceData: any, config: any, helpers: any) => {
+    const qty = helpers.parseIntSafe(sourceData.qty, 0);
+    const price = helpers.parseFloatSafe(sourceData.price, 0);
+    return qty * price;
+  }
+};
+```
+
+</details>
+
+---
+
+## Next Steps
+
+Now that you've mastered advanced patterns, explore the helper functions available:
+
+→ Continue to [Module 6: Helpers & Resolvers](./mapping-06-helpers-resolvers.md)
+
+**Alternative paths:**
+- Jump to [API Reference](../../auto-pagination/modules/auto-pagination-07-api-reference.md) for TypeScript usage
+- Review [GraphQL Mutation Mapping Quick Reference](../graphql-mutation-mapping/graphql-mutation-mapping-quick-reference.md) for a comprehensive cheat sheet
+
+---
+
+[← Back to Use Cases](./mapping-04-use-cases.md) | [Next: Helpers & Resolvers →](./mapping-06-helpers-resolvers.md)
+
+
+
+
+
+
+
+
+
+
+
+
+
+