@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/04-REFERENCE/resolver-signature/modules/resolver-signature-04-advanced-patterns.md

@@ -1,739 +1,739 @@
-# Module 4: Advanced Patterns
-
-**Level:** Advanced
-**Estimated Time:** 30 minutes
-
-## Overview
-
-This module covers advanced resolver patterns that leverage all 4 parameters to create powerful, context-aware transformations. You'll learn async patterns, multi-field calculations, and production-ready error handling.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Write context-aware resolvers using sourceData
-- ✅ Implement async resolvers with API calls
-- ✅ Use all 4 parameters in complex transformations
-- ✅ Handle errors gracefully in production resolvers
-- ✅ Optimize performance with memoization and caching
-
-## Context-Aware Transformations
-
-### Multi-Field Price Calculation
-
-```typescript
-'custom.calculateFinalPrice': (basePrice, sourceData, config, helpers) => {
-  // 1. VALUE: Base price to transform
-  const price = helpers.parseFloatSafe(basePrice, 0);
-
-  // 2. SOURCEDATA: Access related fields
-  const quantity = helpers.get(sourceData, 'quantity') || 1;
-  const discountPercent = helpers.get(sourceData, 'discountPercent') || 0;
-  const customerTier = helpers.get(sourceData, 'customer.tier');
-
-  // 3. CONFIG: Business rules
-  const tierDiscounts = config.tierDiscounts || {};
-  const taxRate = config.taxRate || 0;
-
-  // 4. HELPERS: Safe calculations
-  const subtotal = price * quantity;
-  const itemDiscount = subtotal * (discountPercent / 100);
-  const tierDiscount = subtotal * (tierDiscounts[customerTier] || 0);
-  const afterDiscount = subtotal - itemDiscount - tierDiscount;
-  const withTax = afterDiscount * (1 + taxRate);
-
-  helpers.log.debug(`Price calculation: ${price} × ${quantity} = ${withTax}`);
-
-  return helpers.parseFloatSafe(withTax, 0);
-}
-
-// Usage
-const mapper = new UniversalMapper(mapping, {
-  customResolvers: { 'custom.calculateFinalPrice': calculateFinalPrice },
-  context: {
-    tierDiscounts: {
-      'gold': 0.15,
-      'silver': 0.10,
-      'bronze': 0.05
-    },
-    taxRate: 0.0975
-  },
-  logger: myLogger
-});
-
-// Input:
-// {
-//   price: 100,
-//   quantity: 5,
-//   discountPercent: 10,
-//   customer: { tier: 'gold' }
-// }
-
-// Output: 386.8125
-// Calculation:
-// - Subtotal: 100 × 5 = 500
-// - Item discount: 500 × 0.10 = 50
-// - Tier discount: 500 × 0.15 = 75
-// - After discounts: 500 - 50 - 75 = 375
-// - With tax: 375 × 1.0975 = 411.5625
-```
-
-### Conditional Field Mapping
-
-```typescript
-'custom.mapOrderType': (value, sourceData, config, helpers) => {
-  // Use sourceData to determine order type
-  const itemCount = helpers.get(sourceData, 'items.length') || 0;
-  const totalValue = helpers.get(sourceData, 'totalPrice') || 0;
-  const priority = helpers.get(sourceData, 'priority');
-
-  // Apply business rules from config
-  const thresholds = config.orderTypeThresholds || {
-    bulkItems: 50,
-    bulkValue: 10000
-  };
-
-  if (priority === 'URGENT') {
-    return 'EXPRESS';
-  } else if (itemCount >= thresholds.bulkItems || totalValue >= thresholds.bulkValue) {
-    return 'BULK';
-  } else if (totalValue < 100) {
-    return 'SMALL';
-  }
-
-  return 'STANDARD';
-}
-
-// Usage
-const mapper = new UniversalMapper(mapping, {
-  customResolvers: { 'custom.mapOrderType': mapOrderType },
-  context: {
-    orderTypeThresholds: {
-      bulkItems: 50,
-      bulkValue: 10000
-    }
-  }
-});
-```
-
-### Dynamic Field Selection
-
-```typescript
-'custom.selectAddress': (value, sourceData, config, helpers) => {
-  // Select shipping vs billing address based on context
-  const useShipping = helpers.get(sourceData, 'useShippingAddress');
-  const shippingAddr = helpers.get(sourceData, 'shippingAddress');
-  const billingAddr = helpers.get(sourceData, 'billingAddress');
-
-  const selectedAddr = useShipping ? shippingAddr : billingAddr;
-
-  // Format address using helper
-  const street = helpers.get(selectedAddr, 'street', '');
-  const city = helpers.get(selectedAddr, 'city', '');
-  const state = helpers.get(selectedAddr, 'state', '');
-  const zip = helpers.get(selectedAddr, 'zip', '');
-
-  return `${street}, ${city}, ${state} ${zip}`.trim();
-}
-```
-
-## Async Resolvers with API Calls
-
-### Fetch and Enrich Data
-
-```typescript
-'custom.enrichWithProduct': async (sku, sourceData, config, helpers) => {
-  // Check if FluentClient is available
-  if (!helpers.fluentClient) {
-    helpers.log.warn('FluentClient not available, skipping enrichment');
-    return { sku };
-  }
-
-  try {
-    // Query Fluent API
-    const result = await helpers.fluentClient.graphql({
-      query: `
-        query GetProduct($ref: String!) {
-          product(ref: $ref) {
-            id
-            ref
-            name
-            gtin
-            status
-            attributes {
-              name
-              value
-            }
-          }
-        }
-      `,
-      variables: { ref: sku }
-    });
-
-    if (!result.data?.product) {
-      helpers.log.warn(`Product not found: ${sku}`);
-      return { sku, found: false };
-    }
-
-    return {
-      sku,
-      found: true,
-      ...result.data.product
-    };
-
-  } catch (error) {
-    helpers.log.error(`Failed to fetch product ${sku}`, error);
-    return { sku, error: error.message };
-  }
-}
-
-// Usage
-const mapper = new UniversalMapper(mapping, {
-  customResolvers: { 'custom.enrichWithProduct': enrichWithProduct },
-  fluentClient: myFluentClient,
-  logger: myLogger
-});
-```
-
-### Batch API Calls with Memoization
-
-```typescript
-'custom.lookupCustomer': helpers.memoize(
-  async (customerId, sourceData, config, helpers) => {
-    if (!helpers.fluentClient) {
-      return null;
-    }
-
-    try {
-      const result = await helpers.fluentClient.graphql({
-        query: `
-          query GetCustomer($id: ID!) {
-            customer(id: $id) {
-              id
-              firstName
-              lastName
-              email
-              tier
-            }
-          }
-        `,
-        variables: { id: customerId }
-      });
-
-      return result.data?.customer;
-
-    } catch (error) {
-      helpers.log.error(`Customer lookup failed: ${customerId}`, error);
-      return null;
-    }
-  },
-  // Memoization key function
-  (customerId) => customerId
-);
-
-// This resolver will cache results by customerId
-// Subsequent calls with same ID return cached result
-```
-
-### Retry Pattern for Resilience
-
-```typescript
-'custom.fetchWithRetry': async (id, sourceData, config, helpers) => {
-  const maxRetries = config.maxRetries || 3;
-  const retryDelay = config.retryDelay || 1000;
-
-  const fetchData = async () => {
-    const result = await helpers.fluentClient.graphql({
-      query: `query { data(id: "${id}") { value } }`
-    });
-
-    if (!result.data) {
-      throw new Error('No data returned');
-    }
-
-    return result.data;
-  };
-
-  // Use helper's retry utility
-  try {
-    return await helpers.retry(fetchData, {
-      maxAttempts: maxRetries,
-      delayMs: retryDelay,
-      backoffMultiplier: 2
-    });
-  } catch (error) {
-    helpers.log.error(`Failed after ${maxRetries} retries`, error);
-    return null;
-  }
-}
-
-// Usage
-const mapper = new UniversalMapper(mapping, {
-  customResolvers: { 'custom.fetchWithRetry': fetchWithRetry },
-  context: {
-    maxRetries: 3,
-    retryDelay: 1000
-  },
-  fluentClient: myFluentClient,
-  logger: myLogger
-});
-```
-
-## Complex Data Transformations
-
-### Nested Object Construction
-
-```typescript
-'custom.buildAddress': (value, sourceData, config, helpers) => {
-  // Extract address components from flat structure
-  const street = helpers.get(sourceData, 'addr_line1');
-  const street2 = helpers.get(sourceData, 'addr_line2');
-  const city = helpers.get(sourceData, 'addr_city');
-  const state = helpers.get(sourceData, 'addr_state');
-  const zip = helpers.get(sourceData, 'addr_zip');
-  const country = helpers.get(sourceData, 'addr_country') || config.defaultCountry;
-
-  // Build nested structure
-  return {
-    street1: street,
-    street2: street2 || null,
-    city,
-    state,
-    postalCode: zip,
-    country,
-    formatted: helpers.compact([street, street2, city, `${state} ${zip}`, country])
-      .join(', ')
-  };
-}
-
-// Output:
-// {
-//   street1: "123 Main St",
-//   street2: "Apt 4B",
-//   city: "Springfield",
-//   state: "IL",
-//   postalCode: "62701",
-//   country: "USA",
-//   formatted: "123 Main St, Apt 4B, Springfield, IL 62701, USA"
-// }
-```
-
-### Array Transformation with Filtering
-
-```typescript
-'custom.processItems': (items, sourceData, config, helpers) => {
-  const arr = helpers.ensureArray(items);
-
-  // Filter, transform, and aggregate
-  const processed = arr
-    .filter(item => {
-      const qty = helpers.get(item, 'quantity') || 0;
-      return qty > 0; // Exclude zero-quantity items
-    })
-    .map(item => {
-      const price = helpers.parseFloatSafe(item.price, 0);
-      const qty = helpers.parseIntSafe(item.quantity, 1);
-      const taxRate = config.itemTaxRate || 0.08;
-
-      return {
-        sku: item.sku,
-        quantity: qty,
-        unitPrice: price,
-        subtotal: price * qty,
-        tax: price * qty * taxRate,
-        total: price * qty * (1 + taxRate)
-      };
-    });
-
-  // Calculate totals
-  const summary = {
-    items: processed,
-    itemCount: processed.length,
-    subtotal: helpers.sum(processed.map(i => i.subtotal)),
-    tax: helpers.sum(processed.map(i => i.tax)),
-    total: helpers.sum(processed.map(i => i.total))
-  };
-
-  return summary;
-}
-```
-
-### Conditional Transformation Pipeline
-
-```typescript
-'custom.transformWithPipeline': (value, sourceData, config, helpers) => {
-  let result = value;
-
-  // Apply transformations based on config
-  const pipeline = config.transformPipeline || [];
-
-  for (const step of pipeline) {
-    switch (step.type) {
-      case 'uppercase':
-        result = String(result).toUpperCase();
-        break;
-
-      case 'trim':
-        result = String(result).trim();
-        break;
-
-      case 'prefix':
-        result = `${step.value || ''}${result}`;
-        break;
-
-      case 'replace':
-        result = String(result).replace(
-          new RegExp(step.pattern, step.flags || 'g'),
-          step.replacement || ''
-        );
-        break;
-
-      case 'validate':
-        if (!new RegExp(step.pattern).test(result)) {
-          helpers.log.error(`Validation failed: ${result}`);
-          return null;
-        }
-        break;
-
-      default:
-        helpers.log.warn(`Unknown pipeline step: ${step.type}`);
-    }
-  }
-
-  return result;
-}
-
-// Usage
-const mapper = new UniversalMapper(mapping, {
-  customResolvers: { 'custom.transformWithPipeline': transformWithPipeline },
-  context: {
-    transformPipeline: [
-      { type: 'trim' },
-      { type: 'uppercase' },
-      { type: 'replace', pattern: '[^A-Z0-9]', replacement: '-' },
-      { type: 'prefix', value: 'SKU-' },
-      { type: 'validate', pattern: '^SKU-[A-Z0-9-]+$' }
-    ]
-  },
-  logger: myLogger
-});
-```
-
-## Error Handling Patterns
-
-### Graceful Degradation
-
-```typescript
-'custom.safeTransform': (value, sourceData, config, helpers) => {
-  try {
-    // Attempt complex transformation
-    const result = complexTransformation(value);
-
-    // Validate result
-    if (!result || !result.isValid) {
-      throw new Error('Invalid transformation result');
-    }
-
-    return result.value;
-
-  } catch (error) {
-    // Log error but don't fail
-    helpers.log.error('Transformation failed, using fallback', error);
-
-    // Return safe fallback value
-    return config.fallbackValue || value;
-  }
-}
-```
-
-### Validation with Detailed Errors
-
-```typescript
-'custom.validateAndTransform': (value, sourceData, config, helpers) => {
-  const errors = [];
-
-  // Validate required fields
-  if (!value) {
-    errors.push('Value is required');
-  }
-
-  const quantity = helpers.get(sourceData, 'quantity');
-  if (!quantity || quantity <= 0) {
-    errors.push('Quantity must be positive');
-  }
-
-  const price = helpers.get(sourceData, 'price');
-  if (!price || price <= 0) {
-    errors.push('Price must be positive');
-  }
-
-  // If validation fails, log and return null
-  if (errors.length > 0) {
-    helpers.log.error('Validation failed', {
-      value,
-      errors,
-      sourceData
-    });
-
-    if (config.throwOnValidationError) {
-      throw new Error(`Validation failed: ${errors.join(', ')}`);
-    }
-
-    return null;
-  }
-
-  // Perform transformation
-  return helpers.parseFloatSafe(price, 0) * helpers.parseIntSafe(quantity, 1);
-}
-```
-
-## Performance Optimization
-
-### Memoization for Expensive Operations
-
-```typescript
-'custom.expensiveCalc': helpers.memoize(
-  (value, sourceData, config, helpers) => {
-    // Expensive calculation that should be cached
-    let result = 0;
-    for (let i = 0; i < 1000000; i++) {
-      result += Math.sqrt(i * value);
-    }
-    return result;
-  },
-  // Memoization key
-  (value) => value
-);
-
-// First call with value=5 calculates and caches
-// Subsequent calls with value=5 return cached result instantly
-```
-
-### Batch Processing for Arrays
-
-```typescript
-'custom.batchProcess': async (items, sourceData, config, helpers) => {
-  const arr = helpers.ensureArray(items);
-  const batchSize = config.batchSize || 10;
-
-  // Process in batches to avoid overwhelming API
-  const results = await helpers.batchProcess(
-    arr,
-    async (batch) => {
-      // Process each batch
-      const promises = batch.map(item =>
-        helpers.fluentClient.graphql({
-          query: `query { data(id: "${item.id}") { value } }`
-        })
-      );
-
-      return await Promise.all(promises);
-    },
-    batchSize
-  );
-
-  return results.flat();
-}
-```
-
-## Complete Real-World Example
-
-```typescript
-export const customResolvers = {
-  'custom.processOrder': async (orderId, sourceData, config, helpers) => {
-    // 1. VALUE: Order ID to process
-    if (!orderId) {
-      helpers.log.error('Order ID is required');
-      return null;
-    }
-
-    // 2. SOURCEDATA: Get related data
-    const items = helpers.get(sourceData, 'items', []);
-    const customerTier = helpers.get(sourceData, 'customer.tier', 'standard');
-    const shippingZone = helpers.get(sourceData, 'shipping.zone');
-
-    // 3. CONFIG: Business rules
-    const tierDiscounts = config.tierDiscounts || {};
-    const shippingRates = config.shippingRates || {};
-    const taxRate = config.taxRate || 0.08;
-
-    // 4. HELPERS: Utilities and API calls
-    try {
-      // Validate items
-      if (items.length === 0) {
-        helpers.log.warn(`No items in order ${orderId}`);
-        return null;
-      }
-
-      // Calculate item totals
-      const itemTotals = items.map(item => {
-        const price = helpers.parseFloatSafe(item.price, 0);
-        const qty = helpers.parseIntSafe(item.quantity, 1);
-        return price * qty;
-      });
-
-      // Calculate subtotal
-      const subtotal = helpers.sum(itemTotals);
-
-      // Apply tier discount
-      const discount = subtotal * (tierDiscounts[customerTier] || 0);
-      const afterDiscount = subtotal - discount;
-
-      // Calculate shipping
-      const shipping = shippingRates[shippingZone] || shippingRates.default || 0;
-
-      // Calculate tax
-      const tax = afterDiscount * taxRate;
-
-      // Calculate total
-      const total = afterDiscount + shipping + tax;
-
-      // Enrich with customer data if available
-      let customerData = null;
-      if (helpers.fluentClient && config.enrichWithCustomer) {
-        try {
-          const result = await helpers.fluentClient.graphql({
-            query: `
-              query GetCustomer($tier: String!) {
-                customers(tier: $tier, first: 1) {
-                  edges {
-                    node {
-                      id
-                      firstName
-                      lastName
-                    }
-                  }
-                }
-              }
-            `,
-            variables: { tier: customerTier }
-          });
-
-          customerData = result.data?.customers?.edges[0]?.node;
-        } catch (error) {
-          helpers.log.error('Customer enrichment failed', error);
-        }
-      }
-
-      // Return complete order summary
-      return {
-        orderId,
-        itemCount: items.length,
-        subtotal: helpers.parseFloatSafe(subtotal, 0),
-        discount: helpers.parseFloatSafe(discount, 0),
-        shipping: helpers.parseFloatSafe(shipping, 0),
-        tax: helpers.parseFloatSafe(tax, 0),
-        total: helpers.parseFloatSafe(total, 0),
-        customerTier,
-        customerData
-      };
-
-    } catch (error) {
-      helpers.log.error(`Order processing failed: ${orderId}`, error);
-      return null;
-    }
-  }
-};
-
-// Usage
-const mapper = new UniversalMapper(mapping, {
-  customResolvers,
-  context: {
-    tierDiscounts: {
-      'platinum': 0.20,
-      'gold': 0.15,
-      'silver': 0.10,
-      'standard': 0.0
-    },
-    shippingRates: {
-      'local': 5.00,
-      'regional': 10.00,
-      'national': 15.00,
-      'default': 20.00
-    },
-    taxRate: 0.0975,
-    enrichWithCustomer: true
-  },
-  fluentClient: myFluentClient,
-  logger: myLogger
-});
-```
-
-## Key Takeaways
-
-- 🎯 **Use all 4 parameters** - Each serves a distinct purpose
-- 🎯 **sourceData for context** - Access related fields for smart transformations
-- 🎯 **config for business rules** - Keep logic configurable and testable
-- 🎯 **helpers for utilities** - Use 48+ functions + FluentClient
-- 🎯 **Handle errors gracefully** - Always provide fallbacks
-- 🎯 **Optimize performance** - Use memoization and batch processing
-
-## Practice Exercise
-
-Create a resolver that calculates order priority:
-
-**Requirements:**
-- Use value as base priority
-- Check if order has express shipping (sourceData)
-- Apply priority multipliers from config
-- Use helpers for safe calculations
-- Return object with priority score and reasoning
-
-<details>
-<summary>Show Solution</summary>
-
-```typescript
-'custom.calculatePriority': (basePriority, sourceData, config, helpers) => {
-  // 1. VALUE: Base priority score
-  let score = helpers.parseIntSafe(basePriority, 50);
-
-  const reasons = [];
-
-  // 2. SOURCEDATA: Check order details
-  const isExpress = helpers.get(sourceData, 'shipping.express', false);
-  const customerTier = helpers.get(sourceData, 'customer.tier');
-  const orderValue = helpers.get(sourceData, 'totalValue', 0);
-
-  // 3. CONFIG: Priority multipliers
-  const multipliers = config.priorityMultipliers || {
-    express: 2.0,
-    platinum: 1.5,
-    gold: 1.3,
-    highValue: 1.2
-  };
-
-  // Calculate priority
-  if (isExpress) {
-    score *= multipliers.express;
-    reasons.push('express shipping');
-  }
-
-  if (customerTier === 'platinum') {
-    score *= multipliers.platinum;
-    reasons.push('platinum customer');
-  } else if (customerTier === 'gold') {
-    score *= multipliers.gold;
-    reasons.push('gold customer');
-  }
-
-  if (orderValue > 1000) {
-    score *= multipliers.highValue;
-    reasons.push('high value order');
-  }
-
-  // 4. HELPERS: Safe calculations and logging
-  score = helpers.parseIntSafe(score, basePriority);
-
-  helpers.log.debug(`Priority: ${score} (${reasons.join(', ')})`);
-
-  return {
-    score,
-    level: score > 150 ? 'HIGH' : score > 100 ? 'MEDIUM' : 'LOW',
-    reasons
-  };
-}
-```
-</details>
-
-## Next Steps
-
-Continue to [Module 5: SDK Resolvers](./resolver-signature-05-sdk-resolvers.md) to understand how built-in resolvers use the same 4-parameter signature.
+# Module 4: Advanced Patterns
+
+**Level:** Advanced
+**Estimated Time:** 30 minutes
+
+## Overview
+
+This module covers advanced resolver patterns that leverage all 4 parameters to create powerful, context-aware transformations. You'll learn async patterns, multi-field calculations, and production-ready error handling.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Write context-aware resolvers using sourceData
+- ✅ Implement async resolvers with API calls
+- ✅ Use all 4 parameters in complex transformations
+- ✅ Handle errors gracefully in production resolvers
+- ✅ Optimize performance with memoization and caching
+
+## Context-Aware Transformations
+
+### Multi-Field Price Calculation
+
+```typescript
+'custom.calculateFinalPrice': (basePrice, sourceData, config, helpers) => {
+  // 1. VALUE: Base price to transform
+  const price = helpers.parseFloatSafe(basePrice, 0);
+
+  // 2. SOURCEDATA: Access related fields
+  const quantity = helpers.get(sourceData, 'quantity') || 1;
+  const discountPercent = helpers.get(sourceData, 'discountPercent') || 0;
+  const customerTier = helpers.get(sourceData, 'customer.tier');
+
+  // 3. CONFIG: Business rules
+  const tierDiscounts = config.tierDiscounts || {};
+  const taxRate = config.taxRate || 0;
+
+  // 4. HELPERS: Safe calculations
+  const subtotal = price * quantity;
+  const itemDiscount = subtotal * (discountPercent / 100);
+  const tierDiscount = subtotal * (tierDiscounts[customerTier] || 0);
+  const afterDiscount = subtotal - itemDiscount - tierDiscount;
+  const withTax = afterDiscount * (1 + taxRate);
+
+  helpers.log.debug(`Price calculation: ${price} × ${quantity} = ${withTax}`);
+
+  return helpers.parseFloatSafe(withTax, 0);
+}
+
+// Usage
+const mapper = new UniversalMapper(mapping, {
+  customResolvers: { 'custom.calculateFinalPrice': calculateFinalPrice },
+  context: {
+    tierDiscounts: {
+      'gold': 0.15,
+      'silver': 0.10,
+      'bronze': 0.05
+    },
+    taxRate: 0.0975
+  },
+  logger: myLogger
+});
+
+// Input:
+// {
+//   price: 100,
+//   quantity: 5,
+//   discountPercent: 10,
+//   customer: { tier: 'gold' }
+// }
+
+// Output: 386.8125
+// Calculation:
+// - Subtotal: 100 × 5 = 500
+// - Item discount: 500 × 0.10 = 50
+// - Tier discount: 500 × 0.15 = 75
+// - After discounts: 500 - 50 - 75 = 375
+// - With tax: 375 × 1.0975 = 411.5625
+```
+
+### Conditional Field Mapping
+
+```typescript
+'custom.mapOrderType': (value, sourceData, config, helpers) => {
+  // Use sourceData to determine order type
+  const itemCount = helpers.get(sourceData, 'items.length') || 0;
+  const totalValue = helpers.get(sourceData, 'totalPrice') || 0;
+  const priority = helpers.get(sourceData, 'priority');
+
+  // Apply business rules from config
+  const thresholds = config.orderTypeThresholds || {
+    bulkItems: 50,
+    bulkValue: 10000
+  };
+
+  if (priority === 'URGENT') {
+    return 'EXPRESS';
+  } else if (itemCount >= thresholds.bulkItems || totalValue >= thresholds.bulkValue) {
+    return 'BULK';
+  } else if (totalValue < 100) {
+    return 'SMALL';
+  }
+
+  return 'STANDARD';
+}
+
+// Usage
+const mapper = new UniversalMapper(mapping, {
+  customResolvers: { 'custom.mapOrderType': mapOrderType },
+  context: {
+    orderTypeThresholds: {
+      bulkItems: 50,
+      bulkValue: 10000
+    }
+  }
+});
+```
+
+### Dynamic Field Selection
+
+```typescript
+'custom.selectAddress': (value, sourceData, config, helpers) => {
+  // Select shipping vs billing address based on context
+  const useShipping = helpers.get(sourceData, 'useShippingAddress');
+  const shippingAddr = helpers.get(sourceData, 'shippingAddress');
+  const billingAddr = helpers.get(sourceData, 'billingAddress');
+
+  const selectedAddr = useShipping ? shippingAddr : billingAddr;
+
+  // Format address using helper
+  const street = helpers.get(selectedAddr, 'street', '');
+  const city = helpers.get(selectedAddr, 'city', '');
+  const state = helpers.get(selectedAddr, 'state', '');
+  const zip = helpers.get(selectedAddr, 'zip', '');
+
+  return `${street}, ${city}, ${state} ${zip}`.trim();
+}
+```
+
+## Async Resolvers with API Calls
+
+### Fetch and Enrich Data
+
+```typescript
+'custom.enrichWithProduct': async (sku, sourceData, config, helpers) => {
+  // Check if FluentClient is available
+  if (!helpers.fluentClient) {
+    helpers.log.warn('FluentClient not available, skipping enrichment');
+    return { sku };
+  }
+
+  try {
+    // Query Fluent API
+    const result = await helpers.fluentClient.graphql({
+      query: `
+        query GetProduct($ref: String!) {
+          product(ref: $ref) {
+            id
+            ref
+            name
+            gtin
+            status
+            attributes {
+              name
+              value
+            }
+          }
+        }
+      `,
+      variables: { ref: sku }
+    });
+
+    if (!result.data?.product) {
+      helpers.log.warn(`Product not found: ${sku}`);
+      return { sku, found: false };
+    }
+
+    return {
+      sku,
+      found: true,
+      ...result.data.product
+    };
+
+  } catch (error) {
+    helpers.log.error(`Failed to fetch product ${sku}`, error);
+    return { sku, error: error.message };
+  }
+}
+
+// Usage
+const mapper = new UniversalMapper(mapping, {
+  customResolvers: { 'custom.enrichWithProduct': enrichWithProduct },
+  fluentClient: myFluentClient,
+  logger: myLogger
+});
+```
+
+### Batch API Calls with Memoization
+
+```typescript
+'custom.lookupCustomer': helpers.memoize(
+  async (customerId, sourceData, config, helpers) => {
+    if (!helpers.fluentClient) {
+      return null;
+    }
+
+    try {
+      const result = await helpers.fluentClient.graphql({
+        query: `
+          query GetCustomer($id: ID!) {
+            customer(id: $id) {
+              id
+              firstName
+              lastName
+              email
+              tier
+            }
+          }
+        `,
+        variables: { id: customerId }
+      });
+
+      return result.data?.customer;
+
+    } catch (error) {
+      helpers.log.error(`Customer lookup failed: ${customerId}`, error);
+      return null;
+    }
+  },
+  // Memoization key function
+  (customerId) => customerId
+);
+
+// This resolver will cache results by customerId
+// Subsequent calls with same ID return cached result
+```
+
+### Retry Pattern for Resilience
+
+```typescript
+'custom.fetchWithRetry': async (id, sourceData, config, helpers) => {
+  const maxRetries = config.maxRetries || 3;
+  const retryDelay = config.retryDelay || 1000;
+
+  const fetchData = async () => {
+    const result = await helpers.fluentClient.graphql({
+      query: `query { data(id: "${id}") { value } }`
+    });
+
+    if (!result.data) {
+      throw new Error('No data returned');
+    }
+
+    return result.data;
+  };
+
+  // Use helper's retry utility
+  try {
+    return await helpers.retry(fetchData, {
+      maxAttempts: maxRetries,
+      delayMs: retryDelay,
+      backoffMultiplier: 2
+    });
+  } catch (error) {
+    helpers.log.error(`Failed after ${maxRetries} retries`, error);
+    return null;
+  }
+}
+
+// Usage
+const mapper = new UniversalMapper(mapping, {
+  customResolvers: { 'custom.fetchWithRetry': fetchWithRetry },
+  context: {
+    maxRetries: 3,
+    retryDelay: 1000
+  },
+  fluentClient: myFluentClient,
+  logger: myLogger
+});
+```
+
+## Complex Data Transformations
+
+### Nested Object Construction
+
+```typescript
+'custom.buildAddress': (value, sourceData, config, helpers) => {
+  // Extract address components from flat structure
+  const street = helpers.get(sourceData, 'addr_line1');
+  const street2 = helpers.get(sourceData, 'addr_line2');
+  const city = helpers.get(sourceData, 'addr_city');
+  const state = helpers.get(sourceData, 'addr_state');
+  const zip = helpers.get(sourceData, 'addr_zip');
+  const country = helpers.get(sourceData, 'addr_country') || config.defaultCountry;
+
+  // Build nested structure
+  return {
+    street1: street,
+    street2: street2 || null,
+    city,
+    state,
+    postalCode: zip,
+    country,
+    formatted: helpers.compact([street, street2, city, `${state} ${zip}`, country])
+      .join(', ')
+  };
+}
+
+// Output:
+// {
+//   street1: "123 Main St",
+//   street2: "Apt 4B",
+//   city: "Springfield",
+//   state: "IL",
+//   postalCode: "62701",
+//   country: "USA",
+//   formatted: "123 Main St, Apt 4B, Springfield, IL 62701, USA"
+// }
+```
+
+### Array Transformation with Filtering
+
+```typescript
+'custom.processItems': (items, sourceData, config, helpers) => {
+  const arr = helpers.ensureArray(items);
+
+  // Filter, transform, and aggregate
+  const processed = arr
+    .filter(item => {
+      const qty = helpers.get(item, 'quantity') || 0;
+      return qty > 0; // Exclude zero-quantity items
+    })
+    .map(item => {
+      const price = helpers.parseFloatSafe(item.price, 0);
+      const qty = helpers.parseIntSafe(item.quantity, 1);
+      const taxRate = config.itemTaxRate || 0.08;
+
+      return {
+        sku: item.sku,
+        quantity: qty,
+        unitPrice: price,
+        subtotal: price * qty,
+        tax: price * qty * taxRate,
+        total: price * qty * (1 + taxRate)
+      };
+    });
+
+  // Calculate totals
+  const summary = {
+    items: processed,
+    itemCount: processed.length,
+    subtotal: helpers.sum(processed.map(i => i.subtotal)),
+    tax: helpers.sum(processed.map(i => i.tax)),
+    total: helpers.sum(processed.map(i => i.total))
+  };
+
+  return summary;
+}
+```
+
+### Conditional Transformation Pipeline
+
+```typescript
+'custom.transformWithPipeline': (value, sourceData, config, helpers) => {
+  let result = value;
+
+  // Apply transformations based on config
+  const pipeline = config.transformPipeline || [];
+
+  for (const step of pipeline) {
+    switch (step.type) {
+      case 'uppercase':
+        result = String(result).toUpperCase();
+        break;
+
+      case 'trim':
+        result = String(result).trim();
+        break;
+
+      case 'prefix':
+        result = `${step.value || ''}${result}`;
+        break;
+
+      case 'replace':
+        result = String(result).replace(
+          new RegExp(step.pattern, step.flags || 'g'),
+          step.replacement || ''
+        );
+        break;
+
+      case 'validate':
+        if (!new RegExp(step.pattern).test(result)) {
+          helpers.log.error(`Validation failed: ${result}`);
+          return null;
+        }
+        break;
+
+      default:
+        helpers.log.warn(`Unknown pipeline step: ${step.type}`);
+    }
+  }
+
+  return result;
+}
+
+// Usage
+const mapper = new UniversalMapper(mapping, {
+  customResolvers: { 'custom.transformWithPipeline': transformWithPipeline },
+  context: {
+    transformPipeline: [
+      { type: 'trim' },
+      { type: 'uppercase' },
+      { type: 'replace', pattern: '[^A-Z0-9]', replacement: '-' },
+      { type: 'prefix', value: 'SKU-' },
+      { type: 'validate', pattern: '^SKU-[A-Z0-9-]+$' }
+    ]
+  },
+  logger: myLogger
+});
+```
+
+## Error Handling Patterns
+
+### Graceful Degradation
+
+```typescript
+'custom.safeTransform': (value, sourceData, config, helpers) => {
+  try {
+    // Attempt complex transformation
+    const result = complexTransformation(value);
+
+    // Validate result
+    if (!result || !result.isValid) {
+      throw new Error('Invalid transformation result');
+    }
+
+    return result.value;
+
+  } catch (error) {
+    // Log error but don't fail
+    helpers.log.error('Transformation failed, using fallback', error);
+
+    // Return safe fallback value
+    return config.fallbackValue || value;
+  }
+}
+```
+
+### Validation with Detailed Errors
+
+```typescript
+'custom.validateAndTransform': (value, sourceData, config, helpers) => {
+  const errors = [];
+
+  // Validate required fields
+  if (!value) {
+    errors.push('Value is required');
+  }
+
+  const quantity = helpers.get(sourceData, 'quantity');
+  if (!quantity || quantity <= 0) {
+    errors.push('Quantity must be positive');
+  }
+
+  const price = helpers.get(sourceData, 'price');
+  if (!price || price <= 0) {
+    errors.push('Price must be positive');
+  }
+
+  // If validation fails, log and return null
+  if (errors.length > 0) {
+    helpers.log.error('Validation failed', {
+      value,
+      errors,
+      sourceData
+    });
+
+    if (config.throwOnValidationError) {
+      throw new Error(`Validation failed: ${errors.join(', ')}`);
+    }
+
+    return null;
+  }
+
+  // Perform transformation
+  return helpers.parseFloatSafe(price, 0) * helpers.parseIntSafe(quantity, 1);
+}
+```
+
+## Performance Optimization
+
+### Memoization for Expensive Operations
+
+```typescript
+'custom.expensiveCalc': helpers.memoize(
+  (value, sourceData, config, helpers) => {
+    // Expensive calculation that should be cached
+    let result = 0;
+    for (let i = 0; i < 1000000; i++) {
+      result += Math.sqrt(i * value);
+    }
+    return result;
+  },
+  // Memoization key
+  (value) => value
+);
+
+// First call with value=5 calculates and caches
+// Subsequent calls with value=5 return cached result instantly
+```
+
+### Batch Processing for Arrays
+
+```typescript
+'custom.batchProcess': async (items, sourceData, config, helpers) => {
+  const arr = helpers.ensureArray(items);
+  const batchSize = config.batchSize || 10;
+
+  // Process in batches to avoid overwhelming API
+  const results = await helpers.batchProcess(
+    arr,
+    async (batch) => {
+      // Process each batch
+      const promises = batch.map(item =>
+        helpers.fluentClient.graphql({
+          query: `query { data(id: "${item.id}") { value } }`
+        })
+      );
+
+      return await Promise.all(promises);
+    },
+    batchSize
+  );
+
+  return results.flat();
+}
+```
+
+## Complete Real-World Example
+
+```typescript
+export const customResolvers = {
+  'custom.processOrder': async (orderId, sourceData, config, helpers) => {
+    // 1. VALUE: Order ID to process
+    if (!orderId) {
+      helpers.log.error('Order ID is required');
+      return null;
+    }
+
+    // 2. SOURCEDATA: Get related data
+    const items = helpers.get(sourceData, 'items', []);
+    const customerTier = helpers.get(sourceData, 'customer.tier', 'standard');
+    const shippingZone = helpers.get(sourceData, 'shipping.zone');
+
+    // 3. CONFIG: Business rules
+    const tierDiscounts = config.tierDiscounts || {};
+    const shippingRates = config.shippingRates || {};
+    const taxRate = config.taxRate || 0.08;
+
+    // 4. HELPERS: Utilities and API calls
+    try {
+      // Validate items
+      if (items.length === 0) {
+        helpers.log.warn(`No items in order ${orderId}`);
+        return null;
+      }
+
+      // Calculate item totals
+      const itemTotals = items.map(item => {
+        const price = helpers.parseFloatSafe(item.price, 0);
+        const qty = helpers.parseIntSafe(item.quantity, 1);
+        return price * qty;
+      });
+
+      // Calculate subtotal
+      const subtotal = helpers.sum(itemTotals);
+
+      // Apply tier discount
+      const discount = subtotal * (tierDiscounts[customerTier] || 0);
+      const afterDiscount = subtotal - discount;
+
+      // Calculate shipping
+      const shipping = shippingRates[shippingZone] || shippingRates.default || 0;
+
+      // Calculate tax
+      const tax = afterDiscount * taxRate;
+
+      // Calculate total
+      const total = afterDiscount + shipping + tax;
+
+      // Enrich with customer data if available
+      let customerData = null;
+      if (helpers.fluentClient && config.enrichWithCustomer) {
+        try {
+          const result = await helpers.fluentClient.graphql({
+            query: `
+              query GetCustomer($tier: String!) {
+                customers(tier: $tier, first: 1) {
+                  edges {
+                    node {
+                      id
+                      firstName
+                      lastName
+                    }
+                  }
+                }
+              }
+            `,
+            variables: { tier: customerTier }
+          });
+
+          customerData = result.data?.customers?.edges[0]?.node;
+        } catch (error) {
+          helpers.log.error('Customer enrichment failed', error);
+        }
+      }
+
+      // Return complete order summary
+      return {
+        orderId,
+        itemCount: items.length,
+        subtotal: helpers.parseFloatSafe(subtotal, 0),
+        discount: helpers.parseFloatSafe(discount, 0),
+        shipping: helpers.parseFloatSafe(shipping, 0),
+        tax: helpers.parseFloatSafe(tax, 0),
+        total: helpers.parseFloatSafe(total, 0),
+        customerTier,
+        customerData
+      };
+
+    } catch (error) {
+      helpers.log.error(`Order processing failed: ${orderId}`, error);
+      return null;
+    }
+  }
+};
+
+// Usage
+const mapper = new UniversalMapper(mapping, {
+  customResolvers,
+  context: {
+    tierDiscounts: {
+      'platinum': 0.20,
+      'gold': 0.15,
+      'silver': 0.10,
+      'standard': 0.0
+    },
+    shippingRates: {
+      'local': 5.00,
+      'regional': 10.00,
+      'national': 15.00,
+      'default': 20.00
+    },
+    taxRate: 0.0975,
+    enrichWithCustomer: true
+  },
+  fluentClient: myFluentClient,
+  logger: myLogger
+});
+```
+
+## Key Takeaways
+
+- 🎯 **Use all 4 parameters** - Each serves a distinct purpose
+- 🎯 **sourceData for context** - Access related fields for smart transformations
+- 🎯 **config for business rules** - Keep logic configurable and testable
+- 🎯 **helpers for utilities** - Use 48+ functions + FluentClient
+- 🎯 **Handle errors gracefully** - Always provide fallbacks
+- 🎯 **Optimize performance** - Use memoization and batch processing
+
+## Practice Exercise
+
+Create a resolver that calculates order priority:
+
+**Requirements:**
+- Use value as base priority
+- Check if order has express shipping (sourceData)
+- Apply priority multipliers from config
+- Use helpers for safe calculations
+- Return object with priority score and reasoning
+
+<details>
+<summary>Show Solution</summary>
+
+```typescript
+'custom.calculatePriority': (basePriority, sourceData, config, helpers) => {
+  // 1. VALUE: Base priority score
+  let score = helpers.parseIntSafe(basePriority, 50);
+
+  const reasons = [];
+
+  // 2. SOURCEDATA: Check order details
+  const isExpress = helpers.get(sourceData, 'shipping.express', false);
+  const customerTier = helpers.get(sourceData, 'customer.tier');
+  const orderValue = helpers.get(sourceData, 'totalValue', 0);
+
+  // 3. CONFIG: Priority multipliers
+  const multipliers = config.priorityMultipliers || {
+    express: 2.0,
+    platinum: 1.5,
+    gold: 1.3,
+    highValue: 1.2
+  };
+
+  // Calculate priority
+  if (isExpress) {
+    score *= multipliers.express;
+    reasons.push('express shipping');
+  }
+
+  if (customerTier === 'platinum') {
+    score *= multipliers.platinum;
+    reasons.push('platinum customer');
+  } else if (customerTier === 'gold') {
+    score *= multipliers.gold;
+    reasons.push('gold customer');
+  }
+
+  if (orderValue > 1000) {
+    score *= multipliers.highValue;
+    reasons.push('high value order');
+  }
+
+  // 4. HELPERS: Safe calculations and logging
+  score = helpers.parseIntSafe(score, basePriority);
+
+  helpers.log.debug(`Priority: ${score} (${reasons.join(', ')})`);
+
+  return {
+    score,
+    level: score > 150 ? 'HIGH' : score > 100 ? 'MEDIUM' : 'LOW',
+    reasons
+  };
+}
+```
+</details>
+
+## Next Steps
+
+Continue to [Module 5: SDK Resolvers](./resolver-signature-05-sdk-resolvers.md) to understand how built-in resolvers use the same 4-parameter signature.