@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/04-REFERENCE/resolver-signature/modules/resolver-signature-06-migration-guide.md

@@ -1,650 +1,650 @@
-# Module 6: Migration Guide
-
-**Level:** Intermediate
-**Estimated Time:** 20 minutes
-
-## Overview
-
-This module provides a complete guide for migrating from the old 3-parameter resolver signature to the new standard 4-parameter signature. You'll learn what changed, why it changed, and how to update your resolvers safely.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Understand the differences between 3-arg and 4-arg signatures
-- ✅ Know how to identify resolvers that need migration
-- ✅ Follow a step-by-step migration process
-- ✅ Test migrated resolvers for correctness
-- ✅ Apply best practices for future resolver development
-
-## What Changed?
-
-### Old Signature (3 Parameters)
-
-```typescript
-// ❌ OLD: 3 parameters
-type OldResolverFunction = (
-  value: any,
-  sourceData: any,
-  helpers: ResolverHelpers
-) => any | Promise<any>;
-
-// Configuration accessed via helpers.context
-'custom.addTax': (value, sourceData, helpers) => {
-  const taxRate = helpers.context?.taxRate || 0.1;
-  return value * (1 + taxRate);
-}
-```
-
-### New Signature (4 Parameters)
-
-```typescript
-// ✅ NEW: 4 parameters
-type ResolverFunction = (
-  value: any,
-  sourceData: any,
-  config: any,              // ← NEW: Dedicated config parameter
-  helpers: ResolverHelpers
-) => any | Promise<any>;
-
-// Configuration accessed via config parameter
-'custom.addTax': (value, sourceData, config, helpers) => {
-  const taxRate = config.taxRate || 0.1;
-  return value * (1 + taxRate);
-}
-```
-
-## Why the Change?
-
-### 1. Separation of Concerns
-
-**Before:**
-```typescript
-// ❌ Mixed: Configuration and utilities in same object
-(value, sourceData, helpers) => {
-  const config = helpers.context;     // Configuration
-  const parsed = helpers.parseFloat(value);  // Utility
-}
-```
-
-**After:**
-```typescript
-// ✅ Separated: Clear distinction
-(value, sourceData, config, helpers) => {
-  const rate = config.taxRate;       // Configuration
-  const parsed = helpers.parseFloat(value);  // Utility
-}
-```
-
-### 2. Better Type Safety
-
-```typescript
-// ❌ OLD: helpers.context is loosely typed
-interface ResolverHelpers {
-  context?: any;  // Could be anything
-}
-
-// ✅ NEW: config has dedicated type
-type ResolverFunction = (
-  value: any,
-  sourceData: any,
-  config: MyConfigType,  // Can be strongly typed
-  helpers: ResolverHelpers
-) => any;
-```
-
-### 3. Consistency with Mappers
-
-Both UniversalMapper and GraphQLMutationMapper now use the same pattern:
-
-```typescript
-// UniversalMapper
-const mapper1 = new UniversalMapper(mapping, {
-  customResolvers,
-  context: { ... }  // → config parameter
-});
-
-// GraphQLMutationMapper
-const mapper2 = new GraphQLMutationMapper(mapping, {
-  customResolvers,
-  context: { ... }  // → config parameter
-});
-```
-
-## Migration Process
-
-### Step 1: Identify Resolvers to Migrate
-
-Look for resolvers with 3 parameters:
-
-```typescript
-// ❌ NEEDS MIGRATION
-const oldResolvers = {
-  'custom.transform': (value, sourceData, helpers) => {
-    // ...
-  }
-};
-```
-
-### Step 2: Add Config Parameter
-
-Add `config` as the third parameter:
-
-```typescript
-// ✅ SIGNATURE UPDATED
-const newResolvers = {
-  'custom.transform': (value, sourceData, config, helpers) => {
-    // ...
-  }
-};
-```
-
-### Step 3: Update Context Access
-
-Change `helpers.context` to `config`:
-
-```typescript
-// ❌ OLD
-'custom.addPrefix': (value, sourceData, helpers) => {
-  const prefix = helpers.context?.prefix || 'SKU';
-  return `${prefix}-${value}`;
-}
-
-// ✅ NEW
-'custom.addPrefix': (value, sourceData, config, helpers) => {
-  const prefix = config.prefix || 'SKU';
-  return `${prefix}-${value}`;
-}
-```
-
-### Step 4: Test Migration
-
-Write tests to verify behavior is unchanged:
-
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-describe('Migrated Resolvers', () => {
-  it('should work with new signature', async () => {
-    const newResolvers = {
-      'custom.addPrefix': (value, sourceData, config, helpers) => {
-        const prefix = config.prefix || 'SKU';
-        return `${prefix}-${value}`;
-      }
-    };
-
-    const mapper = new UniversalMapper(
-      {
-        fields: {
-          sku: { source: 'id', resolver: 'custom.addPrefix' }
-        }
-      },
-      {
-        customResolvers: newResolvers,
-        context: { prefix: 'PROD' }
-      }
-    );
-
-    const result = await mapper.map({ id: '12345' });
-
-    expect(result.success).toBe(true);
-    expect(result.data.sku).toBe('PROD-12345');
-  });
-});
-```
-
-## Common Migration Scenarios
-
-### Scenario 1: Simple Context Access
-
-```typescript
-// ❌ BEFORE
-'custom.formatDate': (value, sourceData, helpers) => {
-  const format = helpers.context?.dateFormat || 'YYYY-MM-DD';
-  return helpers.formatDate(value, format);
-}
-
-// ✅ AFTER
-'custom.formatDate': (value, sourceData, config, helpers) => {
-  const format = config.dateFormat || 'YYYY-MM-DD';
-  return helpers.formatDate(value, format);
-}
-```
-
-### Scenario 2: Nested Context Access
-
-```typescript
-// ❌ BEFORE
-'custom.calculateTax': (value, sourceData, helpers) => {
-  const region = helpers.get(sourceData, 'customer.region');
-  const taxRates = helpers.context?.taxRates || {};
-  return value * (taxRates[region] || 0.08);
-}
-
-// ✅ AFTER
-'custom.calculateTax': (value, sourceData, config, helpers) => {
-  const region = helpers.get(sourceData, 'customer.region');
-  const taxRates = config.taxRates || {};
-  return value * (taxRates[region] || 0.08);
-}
-```
-
-### Scenario 3: Multiple Context Values
-
-```typescript
-// ❌ BEFORE
-'custom.formatSKU': (value, sourceData, helpers) => {
-  const prefix = helpers.context?.skuPrefix || 'SKU';
-  const separator = helpers.context?.separator || '-';
-  const includeTimestamp = helpers.context?.includeTimestamp || false;
-
-  let result = `${prefix}${separator}${value}`;
-
-  if (includeTimestamp) {
-    const timestamp = helpers.formatDate(new Date(), 'YYYYMMDD');
-    result += `${separator}${timestamp}`;
-  }
-
-  return result;
-}
-
-// ✅ AFTER
-'custom.formatSKU': (value, sourceData, config, helpers) => {
-  const prefix = config.skuPrefix || 'SKU';
-  const separator = config.separator || '-';
-  const includeTimestamp = config.includeTimestamp || false;
-
-  let result = `${prefix}${separator}${value}`;
-
-  if (includeTimestamp) {
-    const timestamp = helpers.formatDate(new Date(), 'YYYYMMDD');
-    result += `${separator}${timestamp}`;
-  }
-
-  return result;
-}
-```
-
-### Scenario 4: Async Resolvers
-
-```typescript
-// ❌ BEFORE
-'custom.enrichData': async (value, sourceData, helpers) => {
-  if (!helpers.fluentClient) {
-    return value;
-  }
-
-  const enableEnrichment = helpers.context?.enableEnrichment;
-  if (!enableEnrichment) {
-    return value;
-  }
-
-  const result = await helpers.fluentClient.graphql({ ... });
-  return result.data;
-}
-
-// ✅ AFTER
-'custom.enrichData': async (value, sourceData, config, helpers) => {
-  if (!helpers.fluentClient) {
-    return value;
-  }
-
-  const enableEnrichment = config.enableEnrichment;
-  if (!enableEnrichment) {
-    return value;
-  }
-
-  const result = await helpers.fluentClient.graphql({ ... });
-  return result.data;
-}
-```
-
-### Scenario 5: No Context Used
-
-```typescript
-// ❌ BEFORE (3 parameters)
-'custom.uppercase': (value, sourceData, helpers) => {
-  return String(value).toUpperCase();
-}
-
-// ✅ AFTER (4 parameters, even if config unused)
-'custom.uppercase': (value, sourceData, config, helpers) => {
-  return String(value).toUpperCase();
-}
-```
-
-## Migration Checklist
-
-Use this checklist for each resolver:
-
-- [ ] **Add config parameter** as 3rd parameter
-- [ ] **Replace `helpers.context`** with `config`
-- [ ] **Update parameter names** (no underscores: `config` not `_config`)
-- [ ] **Test with sample data** to verify behavior
-- [ ] **Update TypeScript types** if using typed resolvers
-- [ ] **Check for any remaining `helpers.context` references**
-- [ ] **Run lint and type checks**
-- [ ] **Update documentation/comments**
-
-## Automated Migration Script
-
-You can use this script to help identify resolvers needing migration:
-
-```bash
-#!/bin/bash
-# find-old-resolvers.sh
-
-# Find files with potential 3-arg resolvers
-grep -r "=> {" src/ | \
-  grep -E "\(value,.*sourceData,.*helpers\)" | \
-  grep -v "config," | \
-  while read -r line; do
-    echo "Potential 3-arg resolver: $line"
-  done
-```
-
-## Testing Strategy
-
-### Unit Tests
-
-```typescript
-describe('Resolver Migration', () => {
-  const helpers = createMockHelpers();
-
-  it('should use config instead of helpers.context', () => {
-    const resolver = (value, sourceData, config, helpers) => {
-      const prefix = config.prefix || 'DEFAULT';
-      return `${prefix}-${value}`;
-    };
-
-    const result = resolver(
-      'test',
-      {},
-      { prefix: 'PROD' },
-      helpers
-    );
-
-    expect(result).toBe('PROD-test');
-  });
-
-  it('should handle missing config gracefully', () => {
-    const resolver = (value, sourceData, config, helpers) => {
-      const prefix = config?.prefix || 'DEFAULT';
-      return `${prefix}-${value}`;
-    };
-
-    const result = resolver('test', {}, {}, helpers);
-
-    expect(result).toBe('DEFAULT-test');
-  });
-});
-```
-
-### Integration Tests
-
-```typescript
-describe('Resolver Integration', () => {
-  it('should work with UniversalMapper', async () => {
-    const customResolvers = {
-      'custom.format': (value, sourceData, config, helpers) => {
-        return `${config.prefix || 'X'}-${value}`;
-      }
-    };
-
-    const mapper = new UniversalMapper(
-      {
-        fields: {
-          result: { source: 'input', resolver: 'custom.format' }
-        }
-      },
-      {
-        customResolvers,
-        context: { prefix: 'TEST' }
-      }
-    );
-
-    const result = await mapper.map({ input: 'value' });
-
-    expect(result.success).toBe(true);
-    expect(result.data.result).toBe('TEST-value');
-  });
-
-  it('should work with GraphQLMutationMapper', async () => {
-    const customResolvers = {
-      'custom.format': (value, sourceData, config, helpers) => {
-        return `${config.prefix || 'X'}-${value}`;
-      }
-    };
-
-    const mapper = new GraphQLMutationMapper(
-      {
-        mutation: 'createOrder',
-        fields: {
-          ref: { source: 'orderId', resolver: 'custom.format' }
-        }
-      },
-      {
-        customResolvers,
-        context: { prefix: 'ORD' }
-      }
-    );
-
-    const result = await mapper.mapWithNodes({ orderId: '12345' });
-
-    expect(result.success).toBe(true);
-    expect(result.data.ref).toBe('ORD-12345');
-  });
-});
-```
-
-## Common Pitfalls
-
-### Pitfall 1: Forgetting to Add Parameter
-
-```typescript
-// ❌ WRONG: Still 3 parameters
-'custom.resolver': (value, sourceData, helpers) => {
-  const rate = config.taxRate;  // ← ReferenceError: config is not defined
-  return value * rate;
-}
-
-// ✅ CORRECT: 4 parameters
-'custom.resolver': (value, sourceData, config, helpers) => {
-  const rate = config.taxRate;
-  return value * rate;
-}
-```
-
-### Pitfall 2: Wrong Parameter Order
-
-```typescript
-// ❌ WRONG: config and helpers swapped
-'custom.resolver': (value, sourceData, helpers, config) => {
-  return value * config.rate;
-}
-
-// ✅ CORRECT: Standard order
-'custom.resolver': (value, sourceData, config, helpers) => {
-  return value * config.rate;
-}
-```
-
-### Pitfall 3: Still Using helpers.context
-
-```typescript
-// ❌ WRONG: Using old pattern
-'custom.resolver': (value, sourceData, config, helpers) => {
-  const rate = helpers.context?.taxRate || 0.1;  // ← Old pattern
-  return value * rate;
-}
-
-// ✅ CORRECT: Use config parameter
-'custom.resolver': (value, sourceData, config, helpers) => {
-  const rate = config.taxRate || 0.1;
-  return value * rate;
-}
-```
-
-### Pitfall 4: Not Handling Undefined Config
-
-```typescript
-// ❌ RISKY: May throw if config is undefined
-'custom.resolver': (value, sourceData, config, helpers) => {
-  return value * config.taxRate;  // ← Error if config is undefined
-}
-
-// ✅ SAFE: Handle undefined config
-'custom.resolver': (value, sourceData, config, helpers) => {
-  return value * (config?.taxRate || 0.1);
-}
-```
-
-## Best Practices After Migration
-
-### 1. Always Use All 4 Parameters
-
-```typescript
-// ✅ GOOD: Include all 4 even if unused
-'custom.simple': (value, sourceData, config, helpers) => {
-  return String(value).toUpperCase();
-}
-```
-
-### 2. Use Standard Parameter Names
-
-```typescript
-// ✅ GOOD: Standard names
-(value, sourceData, config, helpers) => { ... }
-
-// ❌ BAD: Non-standard names
-(val, src, cfg, hlp) => { ... }
-```
-
-### 3. Provide Safe Defaults
-
-```typescript
-// ✅ GOOD: Safe defaults for config
-'custom.format': (value, sourceData, config, helpers) => {
-  const prefix = config?.prefix || 'DEFAULT';
-  const separator = config?.separator || '-';
-  return `${prefix}${separator}${value}`;
-}
-```
-
-### 4. Document Config Requirements
-
-```typescript
-/**
- * Formats SKU with configurable prefix and separator
- *
- * @param value - SKU value to format
- * @param sourceData - Full source object
- * @param config - Configuration object
- * @param config.prefix - SKU prefix (default: 'SKU')
- * @param config.separator - Separator character (default: '-')
- * @param helpers - SDK utilities
- */
-'custom.formatSKU': (value, sourceData, config, helpers) => {
-  const prefix = config?.prefix || 'SKU';
-  const separator = config?.separator || '-';
-  return `${prefix}${separator}${value}`;
-}
-```
-
-### 5. Type Your Resolvers
-
-```typescript
-import type { FieldResolverFunction } from '@fluentcommerce/fc-connect-sdk';
-
-interface MyConfig {
-  prefix?: string;
-  separator?: string;
-}
-
-const resolver: FieldResolverFunction = (
-  value: any,
-  sourceData: any,
-  config: MyConfig,
-  helpers: any
-) => {
-  const prefix = config?.prefix || 'SKU';
-  return `${prefix}-${value}`;
-};
-```
-
-## Complete Migration Example
-
-### Before
-
-```typescript
-// old-resolvers.ts (3-parameter signature)
-export const oldResolvers = {
-  'custom.formatSKU': (value, sourceData, helpers) => {
-    const prefix = helpers.context?.skuPrefix || 'SKU';
-    return `${prefix}-${String(value).toUpperCase()}`;
-  },
-
-  'custom.calculateTax': (value, sourceData, helpers) => {
-    const region = helpers.get(sourceData, 'customer.region');
-    const taxRates = helpers.context?.taxRates || {};
-    return value * (taxRates[region] || 0.08);
-  },
-
-  'custom.enrichProduct': async (sku, sourceData, helpers) => {
-    if (!helpers.fluentClient || !helpers.context?.enableEnrichment) {
-      return { sku };
-    }
-
-    const result = await helpers.fluentClient.graphql({ ... });
-    return result.data.product;
-  }
-};
-```
-
-### After
-
-```typescript
-// new-resolvers.ts (4-parameter signature)
-export const newResolvers = {
-  'custom.formatSKU': (value, sourceData, config, helpers) => {
-    const prefix = config.skuPrefix || 'SKU';
-    return `${prefix}-${String(value).toUpperCase()}`;
-  },
-
-  'custom.calculateTax': (value, sourceData, config, helpers) => {
-    const region = helpers.get(sourceData, 'customer.region');
-    const taxRates = config.taxRates || {};
-    return value * (taxRates[region] || 0.08);
-  },
-
-  'custom.enrichProduct': async (sku, sourceData, config, helpers) => {
-    if (!helpers.fluentClient || !config.enableEnrichment) {
-      return { sku };
-    }
-
-    const result = await helpers.fluentClient.graphql({ ... });
-    return result.data.product;
-  }
-};
-```
-
-## Key Takeaways
-
-- 🎯 **Add config parameter** - Always include it as 3rd parameter
-- 🎯 **Replace helpers.context** - Use config instead
-- 🎯 **Test thoroughly** - Verify behavior unchanged
-- 🎯 **Use standard names** - value, sourceData, config, helpers
-- 🎯 **Handle undefined** - Use safe defaults (config?.prop || default)
-
-## Migration Completion
-
-You've successfully migrated when:
-
-- ✅ All resolvers have 4 parameters
-- ✅ No references to `helpers.context` remain
-- ✅ All tests pass
-- ✅ TypeScript type checks pass
-- ✅ Lint checks pass
-
-## Next Steps
-
-Continue to [Module 7: API Reference](../../../02-CORE-GUIDES/auto-pagination/modules/auto-pagination-07-api-reference.md) for complete TypeScript types, interfaces, and testing utilities.
+# Module 6: Migration Guide
+
+**Level:** Intermediate
+**Estimated Time:** 20 minutes
+
+## Overview
+
+This module provides a complete guide for migrating from the old 3-parameter resolver signature to the new standard 4-parameter signature. You'll learn what changed, why it changed, and how to update your resolvers safely.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Understand the differences between 3-arg and 4-arg signatures
+- ✅ Know how to identify resolvers that need migration
+- ✅ Follow a step-by-step migration process
+- ✅ Test migrated resolvers for correctness
+- ✅ Apply best practices for future resolver development
+
+## What Changed?
+
+### Old Signature (3 Parameters)
+
+```typescript
+// ❌ OLD: 3 parameters
+type OldResolverFunction = (
+  value: any,
+  sourceData: any,
+  helpers: ResolverHelpers
+) => any | Promise<any>;
+
+// Configuration accessed via helpers.context
+'custom.addTax': (value, sourceData, helpers) => {
+  const taxRate = helpers.context?.taxRate || 0.1;
+  return value * (1 + taxRate);
+}
+```
+
+### New Signature (4 Parameters)
+
+```typescript
+// ✅ NEW: 4 parameters
+type ResolverFunction = (
+  value: any,
+  sourceData: any,
+  config: any,              // ← NEW: Dedicated config parameter
+  helpers: ResolverHelpers
+) => any | Promise<any>;
+
+// Configuration accessed via config parameter
+'custom.addTax': (value, sourceData, config, helpers) => {
+  const taxRate = config.taxRate || 0.1;
+  return value * (1 + taxRate);
+}
+```
+
+## Why the Change?
+
+### 1. Separation of Concerns
+
+**Before:**
+```typescript
+// ❌ Mixed: Configuration and utilities in same object
+(value, sourceData, helpers) => {
+  const config = helpers.context;     // Configuration
+  const parsed = helpers.parseFloat(value);  // Utility
+}
+```
+
+**After:**
+```typescript
+// ✅ Separated: Clear distinction
+(value, sourceData, config, helpers) => {
+  const rate = config.taxRate;       // Configuration
+  const parsed = helpers.parseFloat(value);  // Utility
+}
+```
+
+### 2. Better Type Safety
+
+```typescript
+// ❌ OLD: helpers.context is loosely typed
+interface ResolverHelpers {
+  context?: any;  // Could be anything
+}
+
+// ✅ NEW: config has dedicated type
+type ResolverFunction = (
+  value: any,
+  sourceData: any,
+  config: MyConfigType,  // Can be strongly typed
+  helpers: ResolverHelpers
+) => any;
+```
+
+### 3. Consistency with Mappers
+
+Both UniversalMapper and GraphQLMutationMapper now use the same pattern:
+
+```typescript
+// UniversalMapper
+const mapper1 = new UniversalMapper(mapping, {
+  customResolvers,
+  context: { ... }  // → config parameter
+});
+
+// GraphQLMutationMapper
+const mapper2 = new GraphQLMutationMapper(mapping, {
+  customResolvers,
+  context: { ... }  // → config parameter
+});
+```
+
+## Migration Process
+
+### Step 1: Identify Resolvers to Migrate
+
+Look for resolvers with 3 parameters:
+
+```typescript
+// ❌ NEEDS MIGRATION
+const oldResolvers = {
+  'custom.transform': (value, sourceData, helpers) => {
+    // ...
+  }
+};
+```
+
+### Step 2: Add Config Parameter
+
+Add `config` as the third parameter:
+
+```typescript
+// ✅ SIGNATURE UPDATED
+const newResolvers = {
+  'custom.transform': (value, sourceData, config, helpers) => {
+    // ...
+  }
+};
+```
+
+### Step 3: Update Context Access
+
+Change `helpers.context` to `config`:
+
+```typescript
+// ❌ OLD
+'custom.addPrefix': (value, sourceData, helpers) => {
+  const prefix = helpers.context?.prefix || 'SKU';
+  return `${prefix}-${value}`;
+}
+
+// ✅ NEW
+'custom.addPrefix': (value, sourceData, config, helpers) => {
+  const prefix = config.prefix || 'SKU';
+  return `${prefix}-${value}`;
+}
+```
+
+### Step 4: Test Migration
+
+Write tests to verify behavior is unchanged:
+
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+describe('Migrated Resolvers', () => {
+  it('should work with new signature', async () => {
+    const newResolvers = {
+      'custom.addPrefix': (value, sourceData, config, helpers) => {
+        const prefix = config.prefix || 'SKU';
+        return `${prefix}-${value}`;
+      }
+    };
+
+    const mapper = new UniversalMapper(
+      {
+        fields: {
+          sku: { source: 'id', resolver: 'custom.addPrefix' }
+        }
+      },
+      {
+        customResolvers: newResolvers,
+        context: { prefix: 'PROD' }
+      }
+    );
+
+    const result = await mapper.map({ id: '12345' });
+
+    expect(result.success).toBe(true);
+    expect(result.data.sku).toBe('PROD-12345');
+  });
+});
+```
+
+## Common Migration Scenarios
+
+### Scenario 1: Simple Context Access
+
+```typescript
+// ❌ BEFORE
+'custom.formatDate': (value, sourceData, helpers) => {
+  const format = helpers.context?.dateFormat || 'YYYY-MM-DD';
+  return helpers.formatDate(value, format);
+}
+
+// ✅ AFTER
+'custom.formatDate': (value, sourceData, config, helpers) => {
+  const format = config.dateFormat || 'YYYY-MM-DD';
+  return helpers.formatDate(value, format);
+}
+```
+
+### Scenario 2: Nested Context Access
+
+```typescript
+// ❌ BEFORE
+'custom.calculateTax': (value, sourceData, helpers) => {
+  const region = helpers.get(sourceData, 'customer.region');
+  const taxRates = helpers.context?.taxRates || {};
+  return value * (taxRates[region] || 0.08);
+}
+
+// ✅ AFTER
+'custom.calculateTax': (value, sourceData, config, helpers) => {
+  const region = helpers.get(sourceData, 'customer.region');
+  const taxRates = config.taxRates || {};
+  return value * (taxRates[region] || 0.08);
+}
+```
+
+### Scenario 3: Multiple Context Values
+
+```typescript
+// ❌ BEFORE
+'custom.formatSKU': (value, sourceData, helpers) => {
+  const prefix = helpers.context?.skuPrefix || 'SKU';
+  const separator = helpers.context?.separator || '-';
+  const includeTimestamp = helpers.context?.includeTimestamp || false;
+
+  let result = `${prefix}${separator}${value}`;
+
+  if (includeTimestamp) {
+    const timestamp = helpers.formatDate(new Date(), 'YYYYMMDD');
+    result += `${separator}${timestamp}`;
+  }
+
+  return result;
+}
+
+// ✅ AFTER
+'custom.formatSKU': (value, sourceData, config, helpers) => {
+  const prefix = config.skuPrefix || 'SKU';
+  const separator = config.separator || '-';
+  const includeTimestamp = config.includeTimestamp || false;
+
+  let result = `${prefix}${separator}${value}`;
+
+  if (includeTimestamp) {
+    const timestamp = helpers.formatDate(new Date(), 'YYYYMMDD');
+    result += `${separator}${timestamp}`;
+  }
+
+  return result;
+}
+```
+
+### Scenario 4: Async Resolvers
+
+```typescript
+// ❌ BEFORE
+'custom.enrichData': async (value, sourceData, helpers) => {
+  if (!helpers.fluentClient) {
+    return value;
+  }
+
+  const enableEnrichment = helpers.context?.enableEnrichment;
+  if (!enableEnrichment) {
+    return value;
+  }
+
+  const result = await helpers.fluentClient.graphql({ ... });
+  return result.data;
+}
+
+// ✅ AFTER
+'custom.enrichData': async (value, sourceData, config, helpers) => {
+  if (!helpers.fluentClient) {
+    return value;
+  }
+
+  const enableEnrichment = config.enableEnrichment;
+  if (!enableEnrichment) {
+    return value;
+  }
+
+  const result = await helpers.fluentClient.graphql({ ... });
+  return result.data;
+}
+```
+
+### Scenario 5: No Context Used
+
+```typescript
+// ❌ BEFORE (3 parameters)
+'custom.uppercase': (value, sourceData, helpers) => {
+  return String(value).toUpperCase();
+}
+
+// ✅ AFTER (4 parameters, even if config unused)
+'custom.uppercase': (value, sourceData, config, helpers) => {
+  return String(value).toUpperCase();
+}
+```
+
+## Migration Checklist
+
+Use this checklist for each resolver:
+
+- [ ] **Add config parameter** as 3rd parameter
+- [ ] **Replace `helpers.context`** with `config`
+- [ ] **Update parameter names** (no underscores: `config` not `_config`)
+- [ ] **Test with sample data** to verify behavior
+- [ ] **Update TypeScript types** if using typed resolvers
+- [ ] **Check for any remaining `helpers.context` references**
+- [ ] **Run lint and type checks**
+- [ ] **Update documentation/comments**
+
+## Automated Migration Script
+
+You can use this script to help identify resolvers needing migration:
+
+```bash
+#!/bin/bash
+# find-old-resolvers.sh
+
+# Find files with potential 3-arg resolvers
+grep -r "=> {" src/ | \
+  grep -E "\(value,.*sourceData,.*helpers\)" | \
+  grep -v "config," | \
+  while read -r line; do
+    echo "Potential 3-arg resolver: $line"
+  done
+```
+
+## Testing Strategy
+
+### Unit Tests
+
+```typescript
+describe('Resolver Migration', () => {
+  const helpers = createMockHelpers();
+
+  it('should use config instead of helpers.context', () => {
+    const resolver = (value, sourceData, config, helpers) => {
+      const prefix = config.prefix || 'DEFAULT';
+      return `${prefix}-${value}`;
+    };
+
+    const result = resolver(
+      'test',
+      {},
+      { prefix: 'PROD' },
+      helpers
+    );
+
+    expect(result).toBe('PROD-test');
+  });
+
+  it('should handle missing config gracefully', () => {
+    const resolver = (value, sourceData, config, helpers) => {
+      const prefix = config?.prefix || 'DEFAULT';
+      return `${prefix}-${value}`;
+    };
+
+    const result = resolver('test', {}, {}, helpers);
+
+    expect(result).toBe('DEFAULT-test');
+  });
+});
+```
+
+### Integration Tests
+
+```typescript
+describe('Resolver Integration', () => {
+  it('should work with UniversalMapper', async () => {
+    const customResolvers = {
+      'custom.format': (value, sourceData, config, helpers) => {
+        return `${config.prefix || 'X'}-${value}`;
+      }
+    };
+
+    const mapper = new UniversalMapper(
+      {
+        fields: {
+          result: { source: 'input', resolver: 'custom.format' }
+        }
+      },
+      {
+        customResolvers,
+        context: { prefix: 'TEST' }
+      }
+    );
+
+    const result = await mapper.map({ input: 'value' });
+
+    expect(result.success).toBe(true);
+    expect(result.data.result).toBe('TEST-value');
+  });
+
+  it('should work with GraphQLMutationMapper', async () => {
+    const customResolvers = {
+      'custom.format': (value, sourceData, config, helpers) => {
+        return `${config.prefix || 'X'}-${value}`;
+      }
+    };
+
+    const mapper = new GraphQLMutationMapper(
+      {
+        mutation: 'createOrder',
+        fields: {
+          ref: { source: 'orderId', resolver: 'custom.format' }
+        }
+      },
+      {
+        customResolvers,
+        context: { prefix: 'ORD' }
+      }
+    );
+
+    const result = await mapper.mapWithNodes({ orderId: '12345' });
+
+    expect(result.success).toBe(true);
+    expect(result.data.ref).toBe('ORD-12345');
+  });
+});
+```
+
+## Common Pitfalls
+
+### Pitfall 1: Forgetting to Add Parameter
+
+```typescript
+// ❌ WRONG: Still 3 parameters
+'custom.resolver': (value, sourceData, helpers) => {
+  const rate = config.taxRate;  // ← ReferenceError: config is not defined
+  return value * rate;
+}
+
+// ✅ CORRECT: 4 parameters
+'custom.resolver': (value, sourceData, config, helpers) => {
+  const rate = config.taxRate;
+  return value * rate;
+}
+```
+
+### Pitfall 2: Wrong Parameter Order
+
+```typescript
+// ❌ WRONG: config and helpers swapped
+'custom.resolver': (value, sourceData, helpers, config) => {
+  return value * config.rate;
+}
+
+// ✅ CORRECT: Standard order
+'custom.resolver': (value, sourceData, config, helpers) => {
+  return value * config.rate;
+}
+```
+
+### Pitfall 3: Still Using helpers.context
+
+```typescript
+// ❌ WRONG: Using old pattern
+'custom.resolver': (value, sourceData, config, helpers) => {
+  const rate = helpers.context?.taxRate || 0.1;  // ← Old pattern
+  return value * rate;
+}
+
+// ✅ CORRECT: Use config parameter
+'custom.resolver': (value, sourceData, config, helpers) => {
+  const rate = config.taxRate || 0.1;
+  return value * rate;
+}
+```
+
+### Pitfall 4: Not Handling Undefined Config
+
+```typescript
+// ❌ RISKY: May throw if config is undefined
+'custom.resolver': (value, sourceData, config, helpers) => {
+  return value * config.taxRate;  // ← Error if config is undefined
+}
+
+// ✅ SAFE: Handle undefined config
+'custom.resolver': (value, sourceData, config, helpers) => {
+  return value * (config?.taxRate || 0.1);
+}
+```
+
+## Best Practices After Migration
+
+### 1. Always Use All 4 Parameters
+
+```typescript
+// ✅ GOOD: Include all 4 even if unused
+'custom.simple': (value, sourceData, config, helpers) => {
+  return String(value).toUpperCase();
+}
+```
+
+### 2. Use Standard Parameter Names
+
+```typescript
+// ✅ GOOD: Standard names
+(value, sourceData, config, helpers) => { ... }
+
+// ❌ BAD: Non-standard names
+(val, src, cfg, hlp) => { ... }
+```
+
+### 3. Provide Safe Defaults
+
+```typescript
+// ✅ GOOD: Safe defaults for config
+'custom.format': (value, sourceData, config, helpers) => {
+  const prefix = config?.prefix || 'DEFAULT';
+  const separator = config?.separator || '-';
+  return `${prefix}${separator}${value}`;
+}
+```
+
+### 4. Document Config Requirements
+
+```typescript
+/**
+ * Formats SKU with configurable prefix and separator
+ *
+ * @param value - SKU value to format
+ * @param sourceData - Full source object
+ * @param config - Configuration object
+ * @param config.prefix - SKU prefix (default: 'SKU')
+ * @param config.separator - Separator character (default: '-')
+ * @param helpers - SDK utilities
+ */
+'custom.formatSKU': (value, sourceData, config, helpers) => {
+  const prefix = config?.prefix || 'SKU';
+  const separator = config?.separator || '-';
+  return `${prefix}${separator}${value}`;
+}
+```
+
+### 5. Type Your Resolvers
+
+```typescript
+import type { FieldResolverFunction } from '@fluentcommerce/fc-connect-sdk';
+
+interface MyConfig {
+  prefix?: string;
+  separator?: string;
+}
+
+const resolver: FieldResolverFunction = (
+  value: any,
+  sourceData: any,
+  config: MyConfig,
+  helpers: any
+) => {
+  const prefix = config?.prefix || 'SKU';
+  return `${prefix}-${value}`;
+};
+```
+
+## Complete Migration Example
+
+### Before
+
+```typescript
+// old-resolvers.ts (3-parameter signature)
+export const oldResolvers = {
+  'custom.formatSKU': (value, sourceData, helpers) => {
+    const prefix = helpers.context?.skuPrefix || 'SKU';
+    return `${prefix}-${String(value).toUpperCase()}`;
+  },
+
+  'custom.calculateTax': (value, sourceData, helpers) => {
+    const region = helpers.get(sourceData, 'customer.region');
+    const taxRates = helpers.context?.taxRates || {};
+    return value * (taxRates[region] || 0.08);
+  },
+
+  'custom.enrichProduct': async (sku, sourceData, helpers) => {
+    if (!helpers.fluentClient || !helpers.context?.enableEnrichment) {
+      return { sku };
+    }
+
+    const result = await helpers.fluentClient.graphql({ ... });
+    return result.data.product;
+  }
+};
+```
+
+### After
+
+```typescript
+// new-resolvers.ts (4-parameter signature)
+export const newResolvers = {
+  'custom.formatSKU': (value, sourceData, config, helpers) => {
+    const prefix = config.skuPrefix || 'SKU';
+    return `${prefix}-${String(value).toUpperCase()}`;
+  },
+
+  'custom.calculateTax': (value, sourceData, config, helpers) => {
+    const region = helpers.get(sourceData, 'customer.region');
+    const taxRates = config.taxRates || {};
+    return value * (taxRates[region] || 0.08);
+  },
+
+  'custom.enrichProduct': async (sku, sourceData, config, helpers) => {
+    if (!helpers.fluentClient || !config.enableEnrichment) {
+      return { sku };
+    }
+
+    const result = await helpers.fluentClient.graphql({ ... });
+    return result.data.product;
+  }
+};
+```
+
+## Key Takeaways
+
+- 🎯 **Add config parameter** - Always include it as 3rd parameter
+- 🎯 **Replace helpers.context** - Use config instead
+- 🎯 **Test thoroughly** - Verify behavior unchanged
+- 🎯 **Use standard names** - value, sourceData, config, helpers
+- 🎯 **Handle undefined** - Use safe defaults (config?.prop || default)
+
+## Migration Completion
+
+You've successfully migrated when:
+
+- ✅ All resolvers have 4 parameters
+- ✅ No references to `helpers.context` remain
+- ✅ All tests pass
+- ✅ TypeScript type checks pass
+- ✅ Lint checks pass
+
+## Next Steps
+
+Continue to [Module 7: API Reference](../../../02-CORE-GUIDES/auto-pagination/modules/auto-pagination-07-api-reference.md) for complete TypeScript types, interfaces, and testing utilities.