@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-04-mapping-patterns.md

@@ -1,471 +1,471 @@
-# Mapping Patterns: map() vs mapWithNodes()
-
-[← Back to GraphQL Mutation Mapping Guide](../graphql-mutation-mapping-readme.md)
-
-**Module 4 of 13** | **Level**: Intermediate | **Time**: 10 minutes
-
----
-
-## Overview
-
-The GraphQL Mutation Mapper supports **TWO distinct mapping patterns** for different use cases:
-
-1. **Simple Pattern (`map()`)** - Direct source-to-GraphQL mapping
-2. **Advanced Pattern (`mapWithNodes()`)** - Extract nested/encoded data first, then map
-
-This module explains when to use each pattern and how they differ.
-
----
-
-## Pattern 1: Simple Mapping (`map()`)
-
-### When to Use
-- ✅ Source data structure closely matches GraphQL schema
-- ✅ Direct field-to-field mapping (no complex extraction)
-- ✅ Source format is JSON or simple XML
-- ✅ **No custom resolvers needed** - `map()` does NOT accept custom resolvers parameter
-- ✅ Only built-in SDK resolvers (`sdk.parseFloat`, `sdk.parseInt`, etc.)
-
-### Usage
-
-```typescript
-const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
-const payload = await mapper.map(sourceData);
-
-// Execute mutation
-const result = await client.graphql(payload);
-```
-
-### Configuration
-
-```json
-{
-  "version": "1.0",
-  "mutation": "createOrder",
-  "sourceFormat": "json",
-  "arguments": {
-    "input": {
-      "ref": { "source": "order.orderNo" },
-      "type": { "value": "STANDARD" },
-      "totalPrice": { "source": "order.total", "resolver": "sdk.parseFloat" },
-      "items": {
-        "_array": true,
-        "source": "order.lineItems",
-        "ref": { "source": "productId" },
-        "quantity": { "source": "qty", "resolver": "sdk.parseInt" }
-      }
-    }
-  }
-}
-```
-
-### Example
-
-**Source Data (JSON):**
-```json
-{
-  "order": {
-    "orderNo": "ORD-12345",
-    "total": "249.99",
-    "lineItems": [
-      { "productId": "SKU-001", "qty": "2" },
-      { "productId": "SKU-002", "qty": "1" }
-    ]
-  }
-}
-```
-
-**Output (GraphQL Payload):**
-```typescript
-{
-  query: `mutation CreateOrder($input: CreateOrderInput!) {
-    createOrder(input: $input) {
-      id
-      ref
-      status
-    }
-  }`,
-  variables: {
-    input: {
-      ref: "ORD-12345",
-      type: "STANDARD",
-      totalPrice: 249.99,
-      items: [
-        { ref: "SKU-001", quantity: 2 },
-        { ref: "SKU-002", quantity: 1 }
-      ]
-    }
-  }
-}
-```
-
----
-
-## Pattern 2: Advanced Mapping with Nodes (`mapWithNodes()`)
-
-### When to Use
-- ✅ Source contains nested/encoded data that needs extraction first
-- ✅ XML data with embedded XML strings (common in SFCC)
-- ✅ Custom resolvers need access to unmapped source fields
-- ✅ Multiple levels of data transformation required
-- ✅ HTML-encoded content needs unescaping
-
-### Usage
-
-```typescript
-const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
-const result = await mapper.mapWithNodes(sourceData, customResolvers);
-
-// Execute mutation (query is now included in result - consistent with map()!)
-const mutationResult = await client.graphql({
-  query: result.query,
-  variables: result.variables  // ✅ Use variables (wrapped if fields pattern)
-});
-```
-
-### Configuration
-
-```json
-{
-  "version": "1.0",
-  "mutation": "createOrder",
-  "sourceFormat": "xml",
-
-  "nodes": {
-    "orderDetails": {
-      "extract": "order.custom-attributes.custom-attribute@attribute-id=orderData",
-      "unescape": true,
-      "parse": "xml",
-      "required": true
-    }
-  },
-
-  "fields": {
-    "ref": { "source": "order@order-no" },
-    "type": { "source": "nodes.orderDetails.orderType" },
-    "totalPrice": {
-      "source": "order.totals.order-total",
-      "resolver": "sdk.parseFloat"
-    }
-  }
-}
-```
-
-### Example
-
-**Source Data (XML with encoded XML):**
-```xml
-<order order-no="ORD-12345">
-  <custom-attributes>
-    <custom-attribute attribute-id="orderData">
-      &lt;orderData&gt;
-        &lt;orderType&gt;STANDARD&lt;/orderType&gt;
-        &lt;priority&gt;HIGH&lt;/priority&gt;
-      &lt;/orderData&gt;
-    </custom-attribute>
-  </custom-attributes>
-  <totals>
-    <order-total>249.99</order-total>
-  </totals>
-</order>
-```
-
-**Phase 1 - Node Extraction:**
-```typescript
-{
-  nodes: {
-    orderDetails: {
-      orderType: "STANDARD",
-      priority: "HIGH"
-    }
-  }
-}
-```
-
-**Phase 2 - Field Mapping:**
-```typescript
-{
-  variables: {
-    input: {
-      ref: "ORD-12345",
-      type: "STANDARD",  // From extracted node
-      totalPrice: 249.99
-    }
-  }
-}
-```
-
----
-
-## Key Differences
-
-| Feature | Simple (`map()`) | Advanced (`mapWithNodes()`) |
-|---------|------------------|------------------------------|
-| **Configuration** | `arguments` only | `nodes` + `fields` |
-| **Extraction** | Direct path resolution | Two-phase extraction |
-| **Node Support** | ❌ No | ✅ Yes |
-| **HTML Unescape** | ❌ No | ✅ Yes |
-| **Nested Parsing** | ❌ No | ✅ Yes (XML/JSON) |
-| **Custom Resolvers** | ❌ **NOT SUPPORTED** - `map()` doesn't accept resolvers parameter | ✅ **REQUIRED** - `mapWithNodes()` accepts resolvers parameter |
-| **Return Value** | `GraphQLPayload` | `MapWithNodesResult` |
-| **Use Case** | Simple JSON → GraphQL | Complex XML with encoding |
-
----
-
-## Node Configuration Explained
-
-### Node Definition
-
-```typescript
-interface NodeConfig {
-  /** Path to extract data from source */
-  extract: string;
-
-  /** Decode HTML entities in extracted content */
-  unescape?: boolean;
-
-  /** Parse extracted string as XML or JSON */
-  parse?: 'xml' | 'json';
-
-  /** Throw error if extraction returns null/undefined */
-  required?: boolean;
-}
-```
-
-### Example Node Configurations
-
-**Extract and parse nested XML:**
-```json
-{
-  "nodes": {
-    "customData": {
-      "extract": "custom-attributes.custom-attribute@attribute-id=xmlData",
-      "unescape": true,
-      "parse": "xml"
-    }
-  }
-}
-```
-
-**Extract and parse nested JSON:**
-```json
-{
-  "nodes": {
-    "metadata": {
-      "extract": "order.custom-attributes.metadata",
-      "parse": "json"
-    }
-  }
-}
-```
-
-**Extract without parsing:**
-```json
-{
-  "nodes": {
-    "rawData": {
-      "extract": "order.data",
-      "unescape": true
-    }
-  }
-}
-```
-
----
-
-## Custom Resolvers with Nodes
-
-### Pattern 1 (Simple) - Limited Context
-
-```typescript
-const customResolvers = {
-  'custom.calculateTotal': (value, sourceData) => {
-    // Only has access to MAPPED fields
-    // Cannot access unmapped source fields
-    return sourceData.totalPrice * 1.1;
-  }
-};
-```
-
-### Pattern 2 (Advanced) - Full Context
-
-```typescript
-const customResolvers = {
-  'custom.calculateTotal': (value, sourceData, config, helpers) => {
-    // Has access to:
-    // - Original source data
-    // - Extracted nodes (sourceData.nodes)
-    // - All source fields (mapped or unmapped)
-    // - Helper functions
-
-    const subtotal = helpers.get(sourceData, 'order.totals.subtotal');
-    const tax = helpers.get(sourceData, 'order.totals.tax');
-    const shipping = helpers.get(sourceData.nodes, 'shipping.cost');
-
-    return parseFloat(subtotal) + parseFloat(tax) + parseFloat(shipping);
-  }
-};
-
-const result = await mapper.mapWithNodes(sourceData, customResolvers);
-```
-
----
-
-## Migration Guide
-
-### From Simple to Advanced
-
-If you need to add node extraction to an existing simple mapping:
-
-**Before (Simple):**
-```json
-{
-  "version": "1.0",
-  "mutation": "createOrder",
-  "sourceFormat": "xml",
-  "arguments": {
-    "input": {
-      "ref": { "source": "order@order-no" },
-      "type": { "value": "STANDARD" }
-    }
-  }
-}
-```
-
-**After (Advanced with Nodes):**
-```json
-{
-  "version": "1.0",
-  "mutation": "createOrder",
-  "sourceFormat": "xml",
-
-  "nodes": {
-    "orderData": {
-      "extract": "order.custom-data",
-      "unescape": true,
-      "parse": "xml"
-    }
-  },
-
-  "fields": {
-    "ref": { "source": "order@order-no" },
-    "type": { "source": "nodes.orderData.orderType" }
-  }
-}
-```
-
-**Code Change:**
-```typescript
-// Before
-const payload = await mapper.map(sourceData);
-const result = await client.graphql(payload);
-
-// After
-const result = await mapper.mapWithNodes(sourceData, customResolvers);
-// Check success (errors are returned, not thrown)
-if (!result.success) {
-  console.error('Mapping failed:', result.errors);
-  return;
-}
-// Execute mutation (query is auto-generated in result)
-const mutationResult = await client.graphql({
-  query: result.query,
-  variables: result.variables  // ✅ Use variables (wrapped if fields pattern)
-});
-
-// Access mapped fields directly (unwrapped)
-const orderRef = result.data.ref;  // ✅ Use data for direct field access
-```
-
----
-
-## Decision Tree: Which Pattern to Use?
-
-```
-Start Here
-    │
-    ├─ Source has encoded/nested XML strings? ──────► Use mapWithNodes()
-    │                                                   (Extract with nodes first)
-    │
-    ├─ Need custom resolvers? ────────────────────► Use mapWithNodes()
-    │                                                   (map() doesn't support custom resolvers)
-    │
-    ├─ Simple JSON → GraphQL? ─────────────────────► Use map()
-    │                                                   (Direct mapping)
-    │
-    └─ Simple XML → GraphQL (no encoding)? ────────► Use map()
-                                                        (Direct mapping)
-```
-
----
-
-## Common Use Cases
-
-### Use Simple Pattern (`map()`)
-
-✅ **Shopify webhook → Fluent GraphQL**
-- JSON source, direct field mapping
-- No nested encoding
-
-✅ **REST API → Fluent GraphQL**
-- JSON response, straightforward transformation
-- Standard resolvers (parseFloat, parseInt)
-
-✅ **Simple XML feed → GraphQL**
-- No encoded content
-- Direct element/attribute access
-
-### Use Advanced Pattern (`mapWithNodes()`)
-
-✅ **SFCC order XML → Fluent GraphQL**
-- Custom attributes contain encoded XML
-- Needs HTML entity decoding
-- Resolvers need access to all source fields
-
-✅ **Complex XML with embedded data**
-- Multiple layers of encoded content
-- Requires pre-extraction and parsing
-
-✅ **Data requiring multi-step transformation**
-- Extract nested data first
-- Parse as XML/JSON
-- Then map to GraphQL
-
----
-
-## Best Practices
-
-### ✅ DO
-
-- Use `map()` for simple, straightforward mappings
-- Use `mapWithNodes()` when you need node extraction
-- Start with `map()`, migrate to `mapWithNodes()` only if needed
-- Document which pattern you're using in config comments
-
-### ❌ DON'T
-
-- Don't use `mapWithNodes()` if you don't need nodes
-- Don't mix `arguments` and `fields` patterns in same config
-- Don't nest nodes more than 2 levels deep (performance)
-
----
-
-## Key Takeaways
-
-✅ **Two patterns** - Simple (`map()`) and Advanced (`mapWithNodes()`)
-✅ **Simple for most cases** - Direct JSON/XML → GraphQL mapping
-✅ **Advanced for complex** - Nested/encoded data extraction
-✅ **Custom resolvers** - mapWithNodes() provides full source context
-✅ **Configuration differs** - `arguments` vs `nodes` + `fields`
-
----
-
-## Navigation
-
-[← Previous: Schema Validation](./graphql-mutation-mapping-03-schema-validation.md) | [Back to Guide](../graphql-mutation-mapping-readme.md) | [Next: Configuration Reference →](./graphql-mutation-mapping-05-configuration-reference.md)
-
-## Related Documentation
-
-- [Module 05: Configuration Reference](./graphql-mutation-mapping-05-configuration-reference.md) - Complete mapping configuration
-- [Module 08: Custom Resolvers](./graphql-mutation-mapping-08-custom-resolvers.md) - Custom transformation logic
-- [Module 09: Advanced Patterns](./graphql-mutation-mapping-09-advanced-patterns.md) - Complex mapping scenarios
+# Mapping Patterns: map() vs mapWithNodes()
+
+[← Back to GraphQL Mutation Mapping Guide](../graphql-mutation-mapping-readme.md)
+
+**Module 4 of 13** | **Level**: Intermediate | **Time**: 10 minutes
+
+---
+
+## Overview
+
+The GraphQL Mutation Mapper supports **TWO distinct mapping patterns** for different use cases:
+
+1. **Simple Pattern (`map()`)** - Direct source-to-GraphQL mapping
+2. **Advanced Pattern (`mapWithNodes()`)** - Extract nested/encoded data first, then map
+
+This module explains when to use each pattern and how they differ.
+
+---
+
+## Pattern 1: Simple Mapping (`map()`)
+
+### When to Use
+- ✅ Source data structure closely matches GraphQL schema
+- ✅ Direct field-to-field mapping (no complex extraction)
+- ✅ Source format is JSON or simple XML
+- ✅ **No custom resolvers needed** - `map()` does NOT accept custom resolvers parameter
+- ✅ Only built-in SDK resolvers (`sdk.parseFloat`, `sdk.parseInt`, etc.)
+
+### Usage
+
+```typescript
+const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
+const payload = await mapper.map(sourceData);
+
+// Execute mutation
+const result = await client.graphql(payload);
+```
+
+### Configuration
+
+```json
+{
+  "version": "1.0",
+  "mutation": "createOrder",
+  "sourceFormat": "json",
+  "arguments": {
+    "input": {
+      "ref": { "source": "order.orderNo" },
+      "type": { "value": "STANDARD" },
+      "totalPrice": { "source": "order.total", "resolver": "sdk.parseFloat" },
+      "items": {
+        "_array": true,
+        "source": "order.lineItems",
+        "ref": { "source": "productId" },
+        "quantity": { "source": "qty", "resolver": "sdk.parseInt" }
+      }
+    }
+  }
+}
+```
+
+### Example
+
+**Source Data (JSON):**
+```json
+{
+  "order": {
+    "orderNo": "ORD-12345",
+    "total": "249.99",
+    "lineItems": [
+      { "productId": "SKU-001", "qty": "2" },
+      { "productId": "SKU-002", "qty": "1" }
+    ]
+  }
+}
+```
+
+**Output (GraphQL Payload):**
+```typescript
+{
+  query: `mutation CreateOrder($input: CreateOrderInput!) {
+    createOrder(input: $input) {
+      id
+      ref
+      status
+    }
+  }`,
+  variables: {
+    input: {
+      ref: "ORD-12345",
+      type: "STANDARD",
+      totalPrice: 249.99,
+      items: [
+        { ref: "SKU-001", quantity: 2 },
+        { ref: "SKU-002", quantity: 1 }
+      ]
+    }
+  }
+}
+```
+
+---
+
+## Pattern 2: Advanced Mapping with Nodes (`mapWithNodes()`)
+
+### When to Use
+- ✅ Source contains nested/encoded data that needs extraction first
+- ✅ XML data with embedded XML strings (common in SFCC)
+- ✅ Custom resolvers need access to unmapped source fields
+- ✅ Multiple levels of data transformation required
+- ✅ HTML-encoded content needs unescaping
+
+### Usage
+
+```typescript
+const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
+const result = await mapper.mapWithNodes(sourceData, customResolvers);
+
+// Execute mutation (query is now included in result - consistent with map()!)
+const mutationResult = await client.graphql({
+  query: result.query,
+  variables: result.variables  // ✅ Use variables (wrapped if fields pattern)
+});
+```
+
+### Configuration
+
+```json
+{
+  "version": "1.0",
+  "mutation": "createOrder",
+  "sourceFormat": "xml",
+
+  "nodes": {
+    "orderDetails": {
+      "extract": "order.custom-attributes.custom-attribute@attribute-id=orderData",
+      "unescape": true,
+      "parse": "xml",
+      "required": true
+    }
+  },
+
+  "fields": {
+    "ref": { "source": "order@order-no" },
+    "type": { "source": "nodes.orderDetails.orderType" },
+    "totalPrice": {
+      "source": "order.totals.order-total",
+      "resolver": "sdk.parseFloat"
+    }
+  }
+}
+```
+
+### Example
+
+**Source Data (XML with encoded XML):**
+```xml
+<order order-no="ORD-12345">
+  <custom-attributes>
+    <custom-attribute attribute-id="orderData">
+      &lt;orderData&gt;
+        &lt;orderType&gt;STANDARD&lt;/orderType&gt;
+        &lt;priority&gt;HIGH&lt;/priority&gt;
+      &lt;/orderData&gt;
+    </custom-attribute>
+  </custom-attributes>
+  <totals>
+    <order-total>249.99</order-total>
+  </totals>
+</order>
+```
+
+**Phase 1 - Node Extraction:**
+```typescript
+{
+  nodes: {
+    orderDetails: {
+      orderType: "STANDARD",
+      priority: "HIGH"
+    }
+  }
+}
+```
+
+**Phase 2 - Field Mapping:**
+```typescript
+{
+  variables: {
+    input: {
+      ref: "ORD-12345",
+      type: "STANDARD",  // From extracted node
+      totalPrice: 249.99
+    }
+  }
+}
+```
+
+---
+
+## Key Differences
+
+| Feature | Simple (`map()`) | Advanced (`mapWithNodes()`) |
+|---------|------------------|------------------------------|
+| **Configuration** | `arguments` only | `nodes` + `fields` |
+| **Extraction** | Direct path resolution | Two-phase extraction |
+| **Node Support** | ❌ No | ✅ Yes |
+| **HTML Unescape** | ❌ No | ✅ Yes |
+| **Nested Parsing** | ❌ No | ✅ Yes (XML/JSON) |
+| **Custom Resolvers** | ❌ **NOT SUPPORTED** - `map()` doesn't accept resolvers parameter | ✅ **REQUIRED** - `mapWithNodes()` accepts resolvers parameter |
+| **Return Value** | `GraphQLPayload` | `MapWithNodesResult` |
+| **Use Case** | Simple JSON → GraphQL | Complex XML with encoding |
+
+---
+
+## Node Configuration Explained
+
+### Node Definition
+
+```typescript
+interface NodeConfig {
+  /** Path to extract data from source */
+  extract: string;
+
+  /** Decode HTML entities in extracted content */
+  unescape?: boolean;
+
+  /** Parse extracted string as XML or JSON */
+  parse?: 'xml' | 'json';
+
+  /** Throw error if extraction returns null/undefined */
+  required?: boolean;
+}
+```
+
+### Example Node Configurations
+
+**Extract and parse nested XML:**
+```json
+{
+  "nodes": {
+    "customData": {
+      "extract": "custom-attributes.custom-attribute@attribute-id=xmlData",
+      "unescape": true,
+      "parse": "xml"
+    }
+  }
+}
+```
+
+**Extract and parse nested JSON:**
+```json
+{
+  "nodes": {
+    "metadata": {
+      "extract": "order.custom-attributes.metadata",
+      "parse": "json"
+    }
+  }
+}
+```
+
+**Extract without parsing:**
+```json
+{
+  "nodes": {
+    "rawData": {
+      "extract": "order.data",
+      "unescape": true
+    }
+  }
+}
+```
+
+---
+
+## Custom Resolvers with Nodes
+
+### Pattern 1 (Simple) - Limited Context
+
+```typescript
+const customResolvers = {
+  'custom.calculateTotal': (value, sourceData) => {
+    // Only has access to MAPPED fields
+    // Cannot access unmapped source fields
+    return sourceData.totalPrice * 1.1;
+  }
+};
+```
+
+### Pattern 2 (Advanced) - Full Context
+
+```typescript
+const customResolvers = {
+  'custom.calculateTotal': (value, sourceData, config, helpers) => {
+    // Has access to:
+    // - Original source data
+    // - Extracted nodes (sourceData.nodes)
+    // - All source fields (mapped or unmapped)
+    // - Helper functions
+
+    const subtotal = helpers.get(sourceData, 'order.totals.subtotal');
+    const tax = helpers.get(sourceData, 'order.totals.tax');
+    const shipping = helpers.get(sourceData.nodes, 'shipping.cost');
+
+    return parseFloat(subtotal) + parseFloat(tax) + parseFloat(shipping);
+  }
+};
+
+const result = await mapper.mapWithNodes(sourceData, customResolvers);
+```
+
+---
+
+## Migration Guide
+
+### From Simple to Advanced
+
+If you need to add node extraction to an existing simple mapping:
+
+**Before (Simple):**
+```json
+{
+  "version": "1.0",
+  "mutation": "createOrder",
+  "sourceFormat": "xml",
+  "arguments": {
+    "input": {
+      "ref": { "source": "order@order-no" },
+      "type": { "value": "STANDARD" }
+    }
+  }
+}
+```
+
+**After (Advanced with Nodes):**
+```json
+{
+  "version": "1.0",
+  "mutation": "createOrder",
+  "sourceFormat": "xml",
+
+  "nodes": {
+    "orderData": {
+      "extract": "order.custom-data",
+      "unescape": true,
+      "parse": "xml"
+    }
+  },
+
+  "fields": {
+    "ref": { "source": "order@order-no" },
+    "type": { "source": "nodes.orderData.orderType" }
+  }
+}
+```
+
+**Code Change:**
+```typescript
+// Before
+const payload = await mapper.map(sourceData);
+const result = await client.graphql(payload);
+
+// After
+const result = await mapper.mapWithNodes(sourceData, customResolvers);
+// Check success (errors are returned, not thrown)
+if (!result.success) {
+  console.error('Mapping failed:', result.errors);
+  return;
+}
+// Execute mutation (query is auto-generated in result)
+const mutationResult = await client.graphql({
+  query: result.query,
+  variables: result.variables  // ✅ Use variables (wrapped if fields pattern)
+});
+
+// Access mapped fields directly (unwrapped)
+const orderRef = result.data.ref;  // ✅ Use data for direct field access
+```
+
+---
+
+## Decision Tree: Which Pattern to Use?
+
+```
+Start Here
+    │
+    ├─ Source has encoded/nested XML strings? ──────► Use mapWithNodes()
+    │                                                   (Extract with nodes first)
+    │
+    ├─ Need custom resolvers? ────────────────────► Use mapWithNodes()
+    │                                                   (map() doesn't support custom resolvers)
+    │
+    ├─ Simple JSON → GraphQL? ─────────────────────► Use map()
+    │                                                   (Direct mapping)
+    │
+    └─ Simple XML → GraphQL (no encoding)? ────────► Use map()
+                                                        (Direct mapping)
+```
+
+---
+
+## Common Use Cases
+
+### Use Simple Pattern (`map()`)
+
+✅ **Shopify webhook → Fluent GraphQL**
+- JSON source, direct field mapping
+- No nested encoding
+
+✅ **REST API → Fluent GraphQL**
+- JSON response, straightforward transformation
+- Standard resolvers (parseFloat, parseInt)
+
+✅ **Simple XML feed → GraphQL**
+- No encoded content
+- Direct element/attribute access
+
+### Use Advanced Pattern (`mapWithNodes()`)
+
+✅ **SFCC order XML → Fluent GraphQL**
+- Custom attributes contain encoded XML
+- Needs HTML entity decoding
+- Resolvers need access to all source fields
+
+✅ **Complex XML with embedded data**
+- Multiple layers of encoded content
+- Requires pre-extraction and parsing
+
+✅ **Data requiring multi-step transformation**
+- Extract nested data first
+- Parse as XML/JSON
+- Then map to GraphQL
+
+---
+
+## Best Practices
+
+### ✅ DO
+
+- Use `map()` for simple, straightforward mappings
+- Use `mapWithNodes()` when you need node extraction
+- Start with `map()`, migrate to `mapWithNodes()` only if needed
+- Document which pattern you're using in config comments
+
+### ❌ DON'T
+
+- Don't use `mapWithNodes()` if you don't need nodes
+- Don't mix `arguments` and `fields` patterns in same config
+- Don't nest nodes more than 2 levels deep (performance)
+
+---
+
+## Key Takeaways
+
+✅ **Two patterns** - Simple (`map()`) and Advanced (`mapWithNodes()`)
+✅ **Simple for most cases** - Direct JSON/XML → GraphQL mapping
+✅ **Advanced for complex** - Nested/encoded data extraction
+✅ **Custom resolvers** - mapWithNodes() provides full source context
+✅ **Configuration differs** - `arguments` vs `nodes` + `fields`
+
+---
+
+## Navigation
+
+[← Previous: Schema Validation](./graphql-mutation-mapping-03-schema-validation.md) | [Back to Guide](../graphql-mutation-mapping-readme.md) | [Next: Configuration Reference →](./graphql-mutation-mapping-05-configuration-reference.md)
+
+## Related Documentation
+
+- [Module 05: Configuration Reference](./graphql-mutation-mapping-05-configuration-reference.md) - Complete mapping configuration
+- [Module 08: Custom Resolvers](./graphql-mutation-mapping-08-custom-resolvers.md) - Custom transformation logic
+- [Module 09: Advanced Patterns](./graphql-mutation-mapping-09-advanced-patterns.md) - Complex mapping scenarios