@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-resolver-parameters-reference.md

@@ -1,553 +1,553 @@
-# Resolver Parameters Reference
-
-**Quick reference for the four resolver parameters**
-
-Version: 2.0.0
-Last Updated: 2025-01-14
-
----
-
-## Overview
-
-Every resolver function receives **four parameters** in this exact order:
-
-```typescript
-type ResolverFunction = (
-  value: unknown,      // Extracted value from 'source' path
-  data: unknown,       // Full data context with named nodes
-  config: unknown,     // Configuration object
-  helpers: Helpers     // Utility functions
-) => unknown | Promise<unknown>;
-```
-
-**You don't have to use all four!** Use only what you need for your transformation.
-
----
-
-## Quick Reference Table
-
-| Parameter | When to Use | Common Use Cases |
-|-----------|-------------|------------------|
-| `value` | Field has a `source` path | Transform extracted value, add prefix/suffix |
-| `data` | Need to access multiple paths or named nodes | Calculations from multiple sources, cross-referencing |
-| `config` | Need defaults or environment settings | Fallback values, API tokens, retailer IDs |
-| `helpers` | Almost always! | Safe path access, parsing, formatting, validation |
-
----
-
-## Parameter 1: `value`
-
-### What Is It?
-
-The value extracted from the `source` path in your mapping configuration.
-
-### When Defined?
-
-- ✅ **Defined:** When your field has a `source` property
-- ❌ **Undefined:** When your field only has a `resolver` (resolver-only field)
-
-### Quick Example
-
-**With source:**
-```typescript
-// Mapping
-{
-  "ref": {
-    "source": "orders.order@order-no",
-    "resolver": "custom.addPrefix"
-  }
-}
-
-// Resolver
-'custom.addPrefix': (value, data, config, helpers) => {
-  // value = "ORD-2025-001"
-  return `ORDER-${value}`;
-}
-```
-
-**Without source (resolver-only):**
-```typescript
-// Mapping
-{
-  "totalDiscount": {
-    "resolver": "custom.calculateDiscount"
-  }
-}
-
-// Resolver
-'custom.calculateDiscount': (value, data, config, helpers) => {
-  // value = undefined
-  // Use 'data' instead
-  const adjustment = helpers.get(data, 'orders.order.totals.adjustment-total.gross-price');
-  return Math.abs(helpers.parseFloatSafe(adjustment, 0));
-}
-```
-
-###Special Case: Array Items
-
-**Important:** For resolvers inside array mappings, `value` contains the **entire source item** with all fields.
-
-```typescript
-// Mapping
-{
-  "items": {
-    "source": "orders.order.product-lineitems.product-lineitem",
-    "isArray": true,
-    "fields": {
-      "totalPrice": {
-        "resolver": "custom.calculateItemTotal"
-      }
-    }
-  }
-}
-
-// Resolver
-'custom.calculateItemTotal': (value, data, config, helpers) => {
-  // value = THE ENTIRE ITEM OBJECT
-  // {
-  //   "@lineitem-id": "ITEM-001",
-  //   "product-id": "SKU-WM-001",
-  //   "quantity": "2",
-  //   "base-price": "29.99",
-  //   ...
-  // }
-
-  const item = value;
-  const unitPrice = helpers.parseFloatSafe(item['base-price'], 0);
-  const quantity = helpers.parseIntSafe(item.quantity, 1);
-  return unitPrice * quantity;
-}
-```
-
----
-
-## Parameter 2: `data`
-
-### What Is It?
-
-The complete data context, including:
-- Original source data
-- All named nodes from your mapping's `nodes` config
-
-### Structure
-
-```typescript
-{
-  [nodeName]: parsedNodeData,  // Each node you defined
-  ...originalRootData           // Plus the original root data
-}
-```
-
-### When to Use
-
-- Accessing data from multiple paths
-- Using named nodes (parsed XML/JSON within payload)
-- Cross-referencing between data structures
-- Calculations requiring multiple sources
-
-### Example: Named Nodes
-
-**Mapping with nodes:**
-```json
-{
-  "nodes": {
-    "radialXml": {
-      "extract": "orders.order.custom-attributes.custom-attribute[attribute-id=RadialData]",
-      "parse": "xml"
-    }
-  },
-  "fields": {
-    "specialInstructions": {
-      "resolver": "custom.extractInstructions"
-    }
-  }
-}
-```
-
-**Resolver:**
-```typescript
-'custom.extractInstructions': (value, data, config, helpers) => {
-  // data contains:
-  // {
-  //   radialXml: { Order: { SpecialInstructions: {...} } },  // Named node
-  //   orders: { order: {...} }                                // Original root
-  // }
-
-  // Access the named node
-  const radialData = data.radialXml;
-  return helpers.get(radialData, 'Order.SpecialInstructions.Text');
-}
-```
-
-### Example: Cross-Referencing
-
-```typescript
-'custom.findShipGroupForItem': (value, data, config, helpers) => {
-  const item = value;  // Current item
-  const itemId = item['@id'];
-
-  // Access full context to find related data
-  const radialData = data.radial || data;
-  const shipGroups = helpers.ensureArray(
-    helpers.get(radialData, 'OrderCreateRequest.Order.Shipping.ShipGroups.ShipGroup')
-  );
-
-  // Find which shipment contains this item
-  for (const shipGroup of shipGroups) {
-    const items = helpers.ensureArray(shipGroup.OrderItems?.Item);
-    if (items.some(i => i['@ref'] === itemId)) {
-      return shipGroup['@id'];
-    }
-  }
-
-  return 'DEFAULT-SHIPGROUP';
-}
-```
-
----
-
-## Parameter 3: `config`
-
-### What Is It?
-
-Configuration object passed when calling `mapWithNodes()` or executing resolvers. Contains:
-- Environment-specific settings
-- Default values
-- API credentials
-- Business rules
-
-### Typical Structure
-
-```typescript
-{
-  // Defaults
-  defaultRetailerId: '1',
-  defaultCurrency: 'USD',
-  defaultOrderType: 'HD',
-
-  // API credentials
-  apiToken: process.env.EXTERNAL_API_TOKEN,
-
-  // Business rules
-  discountRules: { ... },
-  shippingRates: { ... },
-
-  // Optional: FluentClient for API calls
-  fluentClient?: FluentClient
-}
-```
-
-### When to Use
-
-- Need fallback/default values
-- Accessing environment-specific settings
-- Making API calls (via `config.fluentClient` or `helpers.fluentClient`)
-- Applying business rules
-
-### Examples
-
-**Config with fallbacks:**
-```typescript
-const config = {
-  defaultRetailerId: '1',
-  defaultCurrency: 'USD'
-};
-
-builder.withConfigFallback(
-  'input.retailer.id',
-  'orders.order.retailerId',
-  'defaultRetailerId'  // Falls back to config.defaultRetailerId
-);
-```
-
-**Custom resolver using config:**
-```typescript
-builder.field('input.shippingCost', (data, config, helpers) => {
-  const weight = helpers.get(data, 'order.totalWeight', 0);
-  const zone = helpers.get(data, 'order.shippingZone', 'domestic');
-
-  // Use business rules from config
-  const rate = config.shippingRates[zone] || config.defaultShippingRate;
-  return weight * rate;
-});
-```
-
-**Making API calls:**
-```typescript
-builder.field('input.customer.id', async (data, config, helpers) => {
-  const customerId = helpers.get(data, 'orders.order.customer.customer-no');
-
-  // FluentClient available via helpers (or config)
-  if (!helpers.fluentClient) {
-    throw new Error('FluentClient required');
-  }
-
-  const result = await helpers.fluentClient.graphql({
-    query: `query GetCustomer($username: [String]) {
-      customers(username: $username, first: 1) {
-        edges { node { id } }
-      }
-    }`,
-    variables: { username: [customerId] }
-  });
-
-  return result.data?.customers?.edges?.[0]?.node?.id;
-});
-```
-
----
-
-## Parameter 4: `helpers`
-
-### What Is It?
-
-Collection of 58+ utility functions for common transformations.
-
-### Categories
-
-1. **Data Access** (2) - `get()`, `ensureArray()`
-2. **Parsing** (3) - `parseFloatSafe()`, `parseIntSafe()`, `safeJsonParse()`
-3. **Formatting** (2) - `formatDate()`, `formatCurrency()`
-4. **Validation** (3) - `isValidEmail()`, `requireField()`, `mapValue()`
-5. **String** (8) - `fullName()`, `truncate()`, `slugify()`, `template()`, etc.
-6. **Object** (7) - `isEmpty()`, `pick()`, `omit()`, `deepClone()`, etc.
-7. **Array Transform** (8) - `groupBy()`, `chunk()`, `flatten()`, `unique()`, etc.
-8. **Array Aggregation** (5) - `sum()`, `avg()`, `min()`, `max()`, `clamp()`
-9. **Date/Time** (5) - `addDays()`, `subtractDays()`, `dateDiff()`, `parseDate()`
-10. **Performance** (3) - `memoize()`, `retry()`, `batchProcess()`
-11. **More...** - Type guards, XML/JSON utilities, function utilities
-
-📖 **[Complete Helper Reference](./mapping-resolvers-resolver-helpers-reference.md)**
-
-### When to Use
-
-**Almost always!** Helpers make your code cleaner, safer, and more readable.
-
-### Common Patterns
-
-**Safe path access:**
-```typescript
-// ❌ Unsafe
-const email = data.orders?.order?.customer?.['customer-email'];
-
-// ✅ Safe with helpers
-const email = helpers.get(data, 'orders.order.customer.customer-email');
-```
-
-**Safe parsing:**
-```typescript
-// ❌ Unsafe
-const price = parseFloat(priceString);  // NaN if invalid
-
-// ✅ Safe with helpers
-const price = helpers.parseFloatSafe(priceString, 0);  // 0 if invalid
-```
-
-**Handle XML arrays:**
-```typescript
-// ❌ Breaks with single item
-const items = data.order.items.item;
-items.forEach(item => { ... });  // ERROR if single object
-
-// ✅ Safe with helpers
-const items = helpers.ensureArray(data.order.items.item);
-items.forEach(item => { ... });  // Always works
-```
-
-**Array operations:**
-```typescript
-// ❌ Manual calculation
-let total = 0;
-for (const item of items) {
-  total += parseFloat(item.price || 0);
-}
-
-// ✅ Clean with helpers
-const total = helpers.sum(items, item => helpers.parseFloatSafe(item.price, 0));
-```
-
----
-
-## When to Use Each Parameter
-
-### Decision Tree
-
-```
-Need to transform extracted value?
-  └─> Use `value` (if source exists)
-
-Need data from multiple paths?
-  └─> Use `data` (with helpers.get())
-
-Need defaults or environment settings?
-  └─> Use `config`
-
-Need utilities (parsing, validation, etc.)?
-  └─> Use `helpers` (almost always!)
-
-Need to make API calls?
-  └─> Use `helpers.fluentClient` (or `config.fluentClient`)
-```
-
-### Common Combinations
-
-**Pattern 1: Simple transformation (value + helpers)**
-```typescript
-'custom.formatPrice': (value, data, config, helpers) => {
-  return helpers.formatCurrency(helpers.parseFloatSafe(value, 0), 2);
-}
-```
-
-**Pattern 2: Calculation (data + helpers)**
-```typescript
-'custom.calculateTotal': (value, data, config, helpers) => {
-  const items = helpers.ensureArray(helpers.get(data, 'order.items'));
-  return helpers.sum(items, item => helpers.parseFloatSafe(item.price, 0));
-}
-```
-
-**Pattern 3: With fallback (value + config + helpers)**
-```typescript
-'custom.getCurrency': (value, data, config, helpers) => {
-  return value || helpers.get(data, 'order.currency') || config.defaultCurrency;
-}
-```
-
-**Pattern 4: Async API call (all four parameters)**
-```typescript
-'custom.lookupCustomer': async (value, data, config, helpers) => {
-  const customerId = value || helpers.get(data, 'order.customerId');
-
-  if (!helpers.fluentClient) {
-    return config.defaultCustomerId;
-  }
-
-  const result = await helpers.retry(
-    async () => await helpers.fluentClient.graphql({ ... })
-  );
-
-  return result.data?.customer?.id || config.defaultCustomerId;
-}
-```
-
----
-
-## Complete Example
-
-Here's a resolver that uses all four parameters effectively:
-
-```typescript
-import { createResolverBuilder } from '@fluentcommerce/fc-connect-sdk';
-
-const builder = createResolverBuilder();
-
-// Configuration
-const config = {
-  defaultRetailerId: '1',
-  defaultCurrency: 'USD',
-  defaultShippingRate: 9.99,
-  taxRates: {
-    'US': 0.08,
-    'CA': 0.13,
-    'UK': 0.20
-  }
-};
-
-const resolvers = builder
-  // Uses: value + helpers
-  .field('input.ref', (value, data, config, helpers) => {
-    const orderNo = value || helpers.get(data, 'orders.order@order-no');
-    return `ORDER-${orderNo}`;
-  })
-
-  // Uses: data + helpers
-  .field('input.totalPrice', (value, data, config, helpers) => {
-    const items = helpers.ensureArray(
-      helpers.get(data, 'orders.order.product-lineitems.product-lineitem')
-    );
-    const subtotal = helpers.sum(items, item =>
-      helpers.parseFloatSafe(item['gross-price'], 0)
-    );
-    const shipping = helpers.parseFloatSafe(
-      helpers.get(data, 'orders.order.totals.shipping-total.gross-price'),
-      0
-    );
-    return subtotal + shipping;
-  })
-
-  // Uses: data + config + helpers
-  .field('input.taxAmount', (value, data, config, helpers) => {
-    const country = helpers.get(data, 'orders.order.customer.billing-address.country-code');
-    const taxRate = config.taxRates[country] || 0;
-    const subtotal = helpers.get(data, 'orders.order.totals.merchandize-total.net-price');
-    return helpers.parseFloatSafe(subtotal, 0) * taxRate;
-  })
-
-  // Uses: all four (async with API call)
-  .field('input.customer.id', async (value, data, config, helpers) => {
-    const customerId = value || helpers.get(data, 'orders.order.customer.customer-no');
-
-    if (!helpers.fluentClient) {
-      helpers.log?.warn('FluentClient not available, using default');
-      return config.defaultCustomerId;
-    }
-
-    return await helpers.retry(async () => {
-      const result = await helpers.fluentClient.graphql({
-        query: `query GetCustomer($username: [String]) {
-          customers(username: $username, first: 1) {
-            edges { node { id } }
-          }
-        }`,
-        variables: { username: [customerId] }
-      });
-
-      return result.data?.customers?.edges?.[0]?.node?.id || config.defaultCustomerId;
-    });
-  })
-
-  .build();
-
-export default resolvers;
-```
-
----
-
-## Best Practices
-
-### ✅ Do's
-
-1. **Use helpers for safety** - Avoid direct property access
-2. **Leverage config for defaults** - Never hardcode environment values
-3. **Log important decisions** - Use `helpers.log` for debugging
-4. **Handle async properly** - Always await async operations
-5. **Validate inputs** - Check for null/undefined before processing
-
-### ❌ Don'ts
-
-1. **Don't assume value exists** - It's undefined for resolver-only fields
-2. **Don't mutate data** - Treat all parameters as immutable
-3. **Don't skip error handling** - Wrap risky operations in try-catch
-4. **Don't hardcode values** - Use config instead
-5. **Don't forget to await** - Async resolvers must be awaited
-
----
-
-## See Also
-
-- [Main Resolver Guide](./mapping-resolvers-resolver-guide.md) - Getting started and examples
-- [API Reference](./mapping-resolvers-resolver-api-reference.md) - ResolverBuilder methods
-- [Helper Functions Reference](./mapping-resolvers-resolver-helpers-reference.md) - All 54 helper functions
-- [Troubleshooting](./mapping-resolvers-resolver-troubleshooting.md) - Common issues
-- [Cookbook](./mapping-resolvers-resolver-cookbook.md) - Advanced patterns
-
----
-
-**Document Version:** 2.0.0
-**SDK Version:** 1.5.0+
-**Last Updated:** 2025-01-14
-
----
-
-**License:** MIT
-**Copyright:** © 2025 Fluent Commerce
+# Resolver Parameters Reference
+
+**Quick reference for the four resolver parameters**
+
+Version: 2.0.0
+Last Updated: 2025-01-14
+
+---
+
+## Overview
+
+Every resolver function receives **four parameters** in this exact order:
+
+```typescript
+type ResolverFunction = (
+  value: unknown,      // Extracted value from 'source' path
+  data: unknown,       // Full data context with named nodes
+  config: unknown,     // Configuration object
+  helpers: Helpers     // Utility functions
+) => unknown | Promise<unknown>;
+```
+
+**You don't have to use all four!** Use only what you need for your transformation.
+
+---
+
+## Quick Reference Table
+
+| Parameter | When to Use | Common Use Cases |
+|-----------|-------------|------------------|
+| `value` | Field has a `source` path | Transform extracted value, add prefix/suffix |
+| `data` | Need to access multiple paths or named nodes | Calculations from multiple sources, cross-referencing |
+| `config` | Need defaults or environment settings | Fallback values, API tokens, retailer IDs |
+| `helpers` | Almost always! | Safe path access, parsing, formatting, validation |
+
+---
+
+## Parameter 1: `value`
+
+### What Is It?
+
+The value extracted from the `source` path in your mapping configuration.
+
+### When Defined?
+
+- ✅ **Defined:** When your field has a `source` property
+- ❌ **Undefined:** When your field only has a `resolver` (resolver-only field)
+
+### Quick Example
+
+**With source:**
+```typescript
+// Mapping
+{
+  "ref": {
+    "source": "orders.order@order-no",
+    "resolver": "custom.addPrefix"
+  }
+}
+
+// Resolver
+'custom.addPrefix': (value, data, config, helpers) => {
+  // value = "ORD-2025-001"
+  return `ORDER-${value}`;
+}
+```
+
+**Without source (resolver-only):**
+```typescript
+// Mapping
+{
+  "totalDiscount": {
+    "resolver": "custom.calculateDiscount"
+  }
+}
+
+// Resolver
+'custom.calculateDiscount': (value, data, config, helpers) => {
+  // value = undefined
+  // Use 'data' instead
+  const adjustment = helpers.get(data, 'orders.order.totals.adjustment-total.gross-price');
+  return Math.abs(helpers.parseFloatSafe(adjustment, 0));
+}
+```
+
+###Special Case: Array Items
+
+**Important:** For resolvers inside array mappings, `value` contains the **entire source item** with all fields.
+
+```typescript
+// Mapping
+{
+  "items": {
+    "source": "orders.order.product-lineitems.product-lineitem",
+    "isArray": true,
+    "fields": {
+      "totalPrice": {
+        "resolver": "custom.calculateItemTotal"
+      }
+    }
+  }
+}
+
+// Resolver
+'custom.calculateItemTotal': (value, data, config, helpers) => {
+  // value = THE ENTIRE ITEM OBJECT
+  // {
+  //   "@lineitem-id": "ITEM-001",
+  //   "product-id": "SKU-WM-001",
+  //   "quantity": "2",
+  //   "base-price": "29.99",
+  //   ...
+  // }
+
+  const item = value;
+  const unitPrice = helpers.parseFloatSafe(item['base-price'], 0);
+  const quantity = helpers.parseIntSafe(item.quantity, 1);
+  return unitPrice * quantity;
+}
+```
+
+---
+
+## Parameter 2: `data`
+
+### What Is It?
+
+The complete data context, including:
+- Original source data
+- All named nodes from your mapping's `nodes` config
+
+### Structure
+
+```typescript
+{
+  [nodeName]: parsedNodeData,  // Each node you defined
+  ...originalRootData           // Plus the original root data
+}
+```
+
+### When to Use
+
+- Accessing data from multiple paths
+- Using named nodes (parsed XML/JSON within payload)
+- Cross-referencing between data structures
+- Calculations requiring multiple sources
+
+### Example: Named Nodes
+
+**Mapping with nodes:**
+```json
+{
+  "nodes": {
+    "radialXml": {
+      "extract": "orders.order.custom-attributes.custom-attribute[attribute-id=RadialData]",
+      "parse": "xml"
+    }
+  },
+  "fields": {
+    "specialInstructions": {
+      "resolver": "custom.extractInstructions"
+    }
+  }
+}
+```
+
+**Resolver:**
+```typescript
+'custom.extractInstructions': (value, data, config, helpers) => {
+  // data contains:
+  // {
+  //   radialXml: { Order: { SpecialInstructions: {...} } },  // Named node
+  //   orders: { order: {...} }                                // Original root
+  // }
+
+  // Access the named node
+  const radialData = data.radialXml;
+  return helpers.get(radialData, 'Order.SpecialInstructions.Text');
+}
+```
+
+### Example: Cross-Referencing
+
+```typescript
+'custom.findShipGroupForItem': (value, data, config, helpers) => {
+  const item = value;  // Current item
+  const itemId = item['@id'];
+
+  // Access full context to find related data
+  const radialData = data.radial || data;
+  const shipGroups = helpers.ensureArray(
+    helpers.get(radialData, 'OrderCreateRequest.Order.Shipping.ShipGroups.ShipGroup')
+  );
+
+  // Find which shipment contains this item
+  for (const shipGroup of shipGroups) {
+    const items = helpers.ensureArray(shipGroup.OrderItems?.Item);
+    if (items.some(i => i['@ref'] === itemId)) {
+      return shipGroup['@id'];
+    }
+  }
+
+  return 'DEFAULT-SHIPGROUP';
+}
+```
+
+---
+
+## Parameter 3: `config`
+
+### What Is It?
+
+Configuration object passed when calling `mapWithNodes()` or executing resolvers. Contains:
+- Environment-specific settings
+- Default values
+- API credentials
+- Business rules
+
+### Typical Structure
+
+```typescript
+{
+  // Defaults
+  defaultRetailerId: '1',
+  defaultCurrency: 'USD',
+  defaultOrderType: 'HD',
+
+  // API credentials
+  apiToken: process.env.EXTERNAL_API_TOKEN,
+
+  // Business rules
+  discountRules: { ... },
+  shippingRates: { ... },
+
+  // Optional: FluentClient for API calls
+  fluentClient?: FluentClient
+}
+```
+
+### When to Use
+
+- Need fallback/default values
+- Accessing environment-specific settings
+- Making API calls (via `config.fluentClient` or `helpers.fluentClient`)
+- Applying business rules
+
+### Examples
+
+**Config with fallbacks:**
+```typescript
+const config = {
+  defaultRetailerId: '1',
+  defaultCurrency: 'USD'
+};
+
+builder.withConfigFallback(
+  'input.retailer.id',
+  'orders.order.retailerId',
+  'defaultRetailerId'  // Falls back to config.defaultRetailerId
+);
+```
+
+**Custom resolver using config:**
+```typescript
+builder.field('input.shippingCost', (data, config, helpers) => {
+  const weight = helpers.get(data, 'order.totalWeight', 0);
+  const zone = helpers.get(data, 'order.shippingZone', 'domestic');
+
+  // Use business rules from config
+  const rate = config.shippingRates[zone] || config.defaultShippingRate;
+  return weight * rate;
+});
+```
+
+**Making API calls:**
+```typescript
+builder.field('input.customer.id', async (data, config, helpers) => {
+  const customerId = helpers.get(data, 'orders.order.customer.customer-no');
+
+  // FluentClient available via helpers (or config)
+  if (!helpers.fluentClient) {
+    throw new Error('FluentClient required');
+  }
+
+  const result = await helpers.fluentClient.graphql({
+    query: `query GetCustomer($username: [String]) {
+      customers(username: $username, first: 1) {
+        edges { node { id } }
+      }
+    }`,
+    variables: { username: [customerId] }
+  });
+
+  return result.data?.customers?.edges?.[0]?.node?.id;
+});
+```
+
+---
+
+## Parameter 4: `helpers`
+
+### What Is It?
+
+Collection of 58+ utility functions for common transformations.
+
+### Categories
+
+1. **Data Access** (2) - `get()`, `ensureArray()`
+2. **Parsing** (3) - `parseFloatSafe()`, `parseIntSafe()`, `safeJsonParse()`
+3. **Formatting** (2) - `formatDate()`, `formatCurrency()`
+4. **Validation** (3) - `isValidEmail()`, `requireField()`, `mapValue()`
+5. **String** (8) - `fullName()`, `truncate()`, `slugify()`, `template()`, etc.
+6. **Object** (7) - `isEmpty()`, `pick()`, `omit()`, `deepClone()`, etc.
+7. **Array Transform** (8) - `groupBy()`, `chunk()`, `flatten()`, `unique()`, etc.
+8. **Array Aggregation** (5) - `sum()`, `avg()`, `min()`, `max()`, `clamp()`
+9. **Date/Time** (5) - `addDays()`, `subtractDays()`, `dateDiff()`, `parseDate()`
+10. **Performance** (3) - `memoize()`, `retry()`, `batchProcess()`
+11. **More...** - Type guards, XML/JSON utilities, function utilities
+
+📖 **[Complete Helper Reference](./mapping-resolvers-resolver-helpers-reference.md)**
+
+### When to Use
+
+**Almost always!** Helpers make your code cleaner, safer, and more readable.
+
+### Common Patterns
+
+**Safe path access:**
+```typescript
+// ❌ Unsafe
+const email = data.orders?.order?.customer?.['customer-email'];
+
+// ✅ Safe with helpers
+const email = helpers.get(data, 'orders.order.customer.customer-email');
+```
+
+**Safe parsing:**
+```typescript
+// ❌ Unsafe
+const price = parseFloat(priceString);  // NaN if invalid
+
+// ✅ Safe with helpers
+const price = helpers.parseFloatSafe(priceString, 0);  // 0 if invalid
+```
+
+**Handle XML arrays:**
+```typescript
+// ❌ Breaks with single item
+const items = data.order.items.item;
+items.forEach(item => { ... });  // ERROR if single object
+
+// ✅ Safe with helpers
+const items = helpers.ensureArray(data.order.items.item);
+items.forEach(item => { ... });  // Always works
+```
+
+**Array operations:**
+```typescript
+// ❌ Manual calculation
+let total = 0;
+for (const item of items) {
+  total += parseFloat(item.price || 0);
+}
+
+// ✅ Clean with helpers
+const total = helpers.sum(items, item => helpers.parseFloatSafe(item.price, 0));
+```
+
+---
+
+## When to Use Each Parameter
+
+### Decision Tree
+
+```
+Need to transform extracted value?
+  └─> Use `value` (if source exists)
+
+Need data from multiple paths?
+  └─> Use `data` (with helpers.get())
+
+Need defaults or environment settings?
+  └─> Use `config`
+
+Need utilities (parsing, validation, etc.)?
+  └─> Use `helpers` (almost always!)
+
+Need to make API calls?
+  └─> Use `helpers.fluentClient` (or `config.fluentClient`)
+```
+
+### Common Combinations
+
+**Pattern 1: Simple transformation (value + helpers)**
+```typescript
+'custom.formatPrice': (value, data, config, helpers) => {
+  return helpers.formatCurrency(helpers.parseFloatSafe(value, 0), 2);
+}
+```
+
+**Pattern 2: Calculation (data + helpers)**
+```typescript
+'custom.calculateTotal': (value, data, config, helpers) => {
+  const items = helpers.ensureArray(helpers.get(data, 'order.items'));
+  return helpers.sum(items, item => helpers.parseFloatSafe(item.price, 0));
+}
+```
+
+**Pattern 3: With fallback (value + config + helpers)**
+```typescript
+'custom.getCurrency': (value, data, config, helpers) => {
+  return value || helpers.get(data, 'order.currency') || config.defaultCurrency;
+}
+```
+
+**Pattern 4: Async API call (all four parameters)**
+```typescript
+'custom.lookupCustomer': async (value, data, config, helpers) => {
+  const customerId = value || helpers.get(data, 'order.customerId');
+
+  if (!helpers.fluentClient) {
+    return config.defaultCustomerId;
+  }
+
+  const result = await helpers.retry(
+    async () => await helpers.fluentClient.graphql({ ... })
+  );
+
+  return result.data?.customer?.id || config.defaultCustomerId;
+}
+```
+
+---
+
+## Complete Example
+
+Here's a resolver that uses all four parameters effectively:
+
+```typescript
+import { createResolverBuilder } from '@fluentcommerce/fc-connect-sdk';
+
+const builder = createResolverBuilder();
+
+// Configuration
+const config = {
+  defaultRetailerId: '1',
+  defaultCurrency: 'USD',
+  defaultShippingRate: 9.99,
+  taxRates: {
+    'US': 0.08,
+    'CA': 0.13,
+    'UK': 0.20
+  }
+};
+
+const resolvers = builder
+  // Uses: value + helpers
+  .field('input.ref', (value, data, config, helpers) => {
+    const orderNo = value || helpers.get(data, 'orders.order@order-no');
+    return `ORDER-${orderNo}`;
+  })
+
+  // Uses: data + helpers
+  .field('input.totalPrice', (value, data, config, helpers) => {
+    const items = helpers.ensureArray(
+      helpers.get(data, 'orders.order.product-lineitems.product-lineitem')
+    );
+    const subtotal = helpers.sum(items, item =>
+      helpers.parseFloatSafe(item['gross-price'], 0)
+    );
+    const shipping = helpers.parseFloatSafe(
+      helpers.get(data, 'orders.order.totals.shipping-total.gross-price'),
+      0
+    );
+    return subtotal + shipping;
+  })
+
+  // Uses: data + config + helpers
+  .field('input.taxAmount', (value, data, config, helpers) => {
+    const country = helpers.get(data, 'orders.order.customer.billing-address.country-code');
+    const taxRate = config.taxRates[country] || 0;
+    const subtotal = helpers.get(data, 'orders.order.totals.merchandize-total.net-price');
+    return helpers.parseFloatSafe(subtotal, 0) * taxRate;
+  })
+
+  // Uses: all four (async with API call)
+  .field('input.customer.id', async (value, data, config, helpers) => {
+    const customerId = value || helpers.get(data, 'orders.order.customer.customer-no');
+
+    if (!helpers.fluentClient) {
+      helpers.log?.warn('FluentClient not available, using default');
+      return config.defaultCustomerId;
+    }
+
+    return await helpers.retry(async () => {
+      const result = await helpers.fluentClient.graphql({
+        query: `query GetCustomer($username: [String]) {
+          customers(username: $username, first: 1) {
+            edges { node { id } }
+          }
+        }`,
+        variables: { username: [customerId] }
+      });
+
+      return result.data?.customers?.edges?.[0]?.node?.id || config.defaultCustomerId;
+    });
+  })
+
+  .build();
+
+export default resolvers;
+```
+
+---
+
+## Best Practices
+
+### ✅ Do's
+
+1. **Use helpers for safety** - Avoid direct property access
+2. **Leverage config for defaults** - Never hardcode environment values
+3. **Log important decisions** - Use `helpers.log` for debugging
+4. **Handle async properly** - Always await async operations
+5. **Validate inputs** - Check for null/undefined before processing
+
+### ❌ Don'ts
+
+1. **Don't assume value exists** - It's undefined for resolver-only fields
+2. **Don't mutate data** - Treat all parameters as immutable
+3. **Don't skip error handling** - Wrap risky operations in try-catch
+4. **Don't hardcode values** - Use config instead
+5. **Don't forget to await** - Async resolvers must be awaited
+
+---
+
+## See Also
+
+- [Main Resolver Guide](./mapping-resolvers-resolver-guide.md) - Getting started and examples
+- [API Reference](./mapping-resolvers-resolver-api-reference.md) - ResolverBuilder methods
+- [Helper Functions Reference](./mapping-resolvers-resolver-helpers-reference.md) - All 54 helper functions
+- [Troubleshooting](./mapping-resolvers-resolver-troubleshooting.md) - Common issues
+- [Cookbook](./mapping-resolvers-resolver-cookbook.md) - Advanced patterns
+
+---
+
+**Document Version:** 2.0.0
+**SDK Version:** 1.5.0+
+**Last Updated:** 2025-01-14
+
+---
+
+**License:** MIT
+**Copyright:** © 2025 Fluent Commerce