@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/04-REFERENCE/resolver-signature/modules/resolver-signature-02-parameter-reference.md

@@ -1,643 +1,643 @@
-# Module 2: Parameter Reference
-
-**Level:** Beginner
-**Estimated Time:** 20 minutes
-
-## Overview
-
-This module provides a detailed breakdown of each parameter in the standard 4-parameter resolver signature. You'll learn what each parameter contains, when to use it, and common patterns.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Understand what each parameter contains
-- ✅ Know when to use each parameter
-- ✅ Recognize common patterns for each parameter
-- ✅ Write resolvers that leverage all 4 parameters effectively
-
-## The Four Parameters
-
-```typescript
-type ResolverFunction = (
-  value: any,              // ← Parameter 1
-  sourceData: any,         // ← Parameter 2
-  config: any,             // ← Parameter 3
-  helpers: ResolverHelpers // ← Parameter 4
-) => any | Promise<any>;
-```
-
----
-
-## Parameter 1: `value`
-
-### What It Is
-
-The extracted field value that needs to be transformed.
-
-```typescript
-// For this mapping:
-{ source: "price", resolver: "custom.addTax" }
-
-// If sourceData = { price: 19.99, quantity: 5 }
-// Then value = 19.99
-```
-
-### Where It Comes From
-
-| Mapping Config | value Parameter |
-|----------------|-----------------|
-| `{ source: "price" }` | `sourceData.price` |
-| `{ value: "ACTIVE" }` | `"ACTIVE"` (literal) |
-| `{ source: "product.name" }` | Nested value from `sourceData.product.name` |
-| `{ resolver: "custom.gen" }` | `undefined` (generator resolver) |
-
-### Common Use Cases
-
-**1. Direct Transformation**
-```typescript
-'custom.uppercase': (value, sourceData, config, helpers) => {
-  return String(value).toUpperCase();
-}
-
-// Input: value = "widget"
-// Output: "WIDGET"
-```
-
-**2. Type Conversion**
-```typescript
-'custom.toNumber': (value, sourceData, config, helpers) => {
-  return helpers.parseFloatSafe(value, 0);
-}
-
-// Input: value = "19.99"
-// Output: 19.99
-```
-
-**3. Validation**
-```typescript
-'custom.validateEmail': (value, sourceData, config, helpers) => {
-  if (!helpers.isValidEmail(value)) {
-    helpers.log.warn(`Invalid email: ${value}`);
-    return null;
-  }
-  return value;
-}
-
-// Input: value = "user@example.com"
-// Output: "user@example.com" (if valid) or null (if invalid)
-```
-
-**4. Generator Resolvers**
-```typescript
-'custom.generateUUID': (value, sourceData, config, helpers) => {
-  // value is undefined for generators
-  return helpers.uuid();
-}
-
-// Input: value = undefined
-// Output: "550e8400-e29b-41d4-a716-446655440000"
-```
-
----
-
-## Parameter 2: `sourceData`
-
-### What It Is
-
-The complete source data object. Allows resolvers to access sibling fields and make context-aware transformations.
-
-```typescript
-// For this mapping:
-{ source: "price", resolver: "custom.calculateTotal" }
-
-// If source document is:
-{
-  price: 19.99,
-  quantity: 5,
-  discount: 10,
-  customer: { tier: "gold" }
-}
-
-// Then sourceData = entire object above
-```
-
-### Why It Matters
-
-Without `sourceData`, resolvers can only transform the single field value. With `sourceData`, resolvers can make decisions based on other fields:
-
-```typescript
-// ❌ LIMITED: Can only use price
-'custom.basic': (value, sourceData, config, helpers) => {
-  return value * 1.1;  // Always add 10%
-}
-
-// ✅ POWERFUL: Can use price AND customer tier
-'custom.smart': (value, sourceData, config, helpers) => {
-  const tier = helpers.get(sourceData, 'customer.tier');
-  const multiplier = tier === 'gold' ? 1.05 : 1.1;
-  return value * multiplier;  // 5% for gold, 10% for others
-}
-```
-
-### Common Use Cases
-
-**1. Multi-Field Calculations**
-```typescript
-'custom.calculateTotal': (basePrice, sourceData, config, helpers) => {
-  // Access sibling fields
-  const quantity = helpers.get(sourceData, 'quantity') || 1;
-  const discount = helpers.get(sourceData, 'discount') || 0;
-
-  // Calculate using multiple fields
-  const subtotal = basePrice * quantity;
-  const afterDiscount = subtotal * (1 - discount / 100);
-
-  return helpers.parseFloatSafe(afterDiscount, 0);
-}
-
-// sourceData: { price: 19.99, quantity: 5, discount: 10 }
-// value: 19.99
-// Output: 89.955 (19.99 * 5 * 0.9)
-```
-
-**2. Conditional Logic Based on Context**
-```typescript
-'custom.calculateTax': (price, sourceData, config, helpers) => {
-  // Tax rate depends on customer region
-  const region = helpers.get(sourceData, 'customer.region');
-
-  const taxRates = {
-    'CA': 0.0975,
-    'NY': 0.08875,
-    'TX': 0.0625
-  };
-
-  const taxRate = taxRates[region] || 0.08;
-  return price * taxRate;
-}
-
-// sourceData: { price: 100, customer: { region: 'CA' } }
-// value: 100
-// Output: 9.75
-```
-
-**3. Accessing Nested Fields**
-```typescript
-'custom.formatAddress': (value, sourceData, config, helpers) => {
-  // Access deeply nested fields
-  const street = helpers.get(sourceData, 'customer.address.street');
-  const city = helpers.get(sourceData, 'customer.address.city');
-  const state = helpers.get(sourceData, 'customer.address.state');
-  const zip = helpers.get(sourceData, 'customer.address.zip');
-
-  return `${street}, ${city}, ${state} ${zip}`;
-}
-
-// sourceData: { customer: { address: { street: "123 Main St", ... } } }
-// Output: "123 Main St, Springfield, IL 62701"
-```
-
-**4. Array Processing**
-```typescript
-'custom.countItems': (value, sourceData, config, helpers) => {
-  // Count items in an array
-  const items = helpers.get(sourceData, 'items') || [];
-  return helpers.ensureArray(items).length;
-}
-
-// sourceData: { items: [{}, {}, {}] }
-// Output: 3
-```
-
----
-
-## Parameter 3: `config`
-
-### What It Is
-
-Business rules and configuration passed to the mapper via the `context` option.
-
-```typescript
-// When creating mapper:
-const mapper = new UniversalMapper(mapping, {
-  customResolvers: { 'custom.tax': myResolver },
-  context: {                    // ← This becomes 'config' parameter
-    taxRate: 0.1,
-    skuPrefix: 'PROD',
-    currency: 'USD'
-  }
-});
-
-// In resolver:
-'custom.addTax': (value, sourceData, config, helpers) => {
-  const rate = config.taxRate;  // ← Access context here
-  return value * (1 + rate);
-}
-```
-
-### Why It Matters
-
-Configuration allows you to write reusable resolvers that behave differently based on runtime settings:
-
-```typescript
-// ✅ GOOD: Configurable behavior
-'custom.formatSKU': (value, sourceData, config, helpers) => {
-  const prefix = config.skuPrefix || 'SKU';
-  return `${prefix}-${value}`;
-}
-
-// Use with different prefixes:
-const csvMapper = new UniversalMapper(mapping, {
-  context: { skuPrefix: 'CSV' }
-});
-// Output: "CSV-123"
-
-const xmlMapper = new UniversalMapper(mapping, {
-  context: { skuPrefix: 'XML' }
-});
-// Output: "XML-123"
-```
-
-### Common Use Cases
-
-**1. Environment-Specific Settings**
-```typescript
-'custom.formatPrice': (value, sourceData, config, helpers) => {
-  const currency = config.currency || 'USD';
-  const locale = config.locale || 'en-US';
-
-  return helpers.formatCurrency(value, currency, locale);
-}
-
-// Development: USD
-const devMapper = new UniversalMapper(mapping, {
-  context: { currency: 'USD', locale: 'en-US' }
-});
-
-// Production (EU): EUR
-const prodMapper = new UniversalMapper(mapping, {
-  context: { currency: 'EUR', locale: 'de-DE' }
-});
-```
-
-**2. Business Rule Configuration**
-```typescript
-'custom.applyDiscount': (price, sourceData, config, helpers) => {
-  const discountRules = config.discountRules || {};
-
-  const quantity = helpers.get(sourceData, 'quantity') || 1;
-
-  // Apply volume discounts based on rules
-  if (quantity >= 100 && discountRules.bulk) {
-    return price * (1 - discountRules.bulk);
-  } else if (quantity >= 10 && discountRules.volume) {
-    return price * (1 - discountRules.volume);
-  }
-
-  return price;
-}
-
-// Mapper with discount rules
-const mapper = new UniversalMapper(mapping, {
-  context: {
-    discountRules: {
-      volume: 0.05,  // 5% off for 10+
-      bulk: 0.15     // 15% off for 100+
-    }
-  }
-});
-```
-
-**3. Feature Flags**
-```typescript
-'custom.enrichData': async (value, sourceData, config, helpers) => {
-  // Check feature flag
-  if (!config.enableEnrichment) {
-    return value;  // Skip enrichment if disabled
-  }
-
-  // Perform expensive enrichment
-  const enriched = await helpers.fluentClient.graphql({ ... });
-  return enriched;
-}
-
-// Development: enrichment disabled
-const devMapper = new UniversalMapper(mapping, {
-  context: { enableEnrichment: false }
-});
-
-// Production: enrichment enabled
-const prodMapper = new UniversalMapper(mapping, {
-  context: { enableEnrichment: true }
-});
-```
-
-**4. Lookup Tables**
-```typescript
-'custom.mapCategory': (value, sourceData, config, helpers) => {
-  const categoryMap = config.categoryMapping || {};
-
-  // Map external category to internal category
-  return categoryMap[value] || value;
-}
-
-// Mapper with category mapping
-const mapper = new UniversalMapper(mapping, {
-  context: {
-    categoryMapping: {
-      'ELEC': 'Electronics',
-      'CLTH': 'Clothing',
-      'FOOD': 'Groceries'
-    }
-  }
-});
-```
-
----
-
-## Parameter 4: `helpers`
-
-### What It Is
-
-SDK utilities and user-provided context. Contains 54 helper functions plus access to logger and FluentClient.
-
-```typescript
-interface ResolverHelpers {
-  // Core utilities (54 helper functions)
-  get, set, formatDate, formatCurrency, parseFloatSafe, parseIntSafe,
-  extractCustomAttribute, safeJsonParse, mapValue, isValidEmail,
-  requireField, fullName, truncate, normalizeWhitespace,
-
-  // Data transformation
-  toCamelCase, toSnakeCase, deepClone, deepMerge,
-
-  // Array operations
-  ensureArray, coalesce, groupBy, keyBy, chunk, flatten, unique,
-  sortBy, compact, sum, avg, min, max, clamp, merge,
-
-  // String operations
-  template, slugify, uuid, hashString,
-
-  // Date operations
-  addDays, subtractDays, dateDiff, parseDate,
-
-  // Performance
-  memoize, batchProcess, retry, debounce, throttle,
-
-  // Type checks
-  isString, isNumber, isArray, isObject, isDate,
-
-  // Additional context
-  log: Logger,              // Logger instance
-  fluentClient?: any,       // Fluent API client (for async operations)
-  context?: any             // User-provided shared config (use config parameter instead)
-}
-```
-
-### Why It Matters
-
-Helpers provide safe, tested utilities so you don't have to reinvent common operations:
-
-> **⚠️ IMPORTANT: Common Mistake**
->
-> `toString()` is NOT a helper function. Use native `String(value)` instead.
->
-> ```typescript
-> // ❌ WRONG - helpers.toString() doesn't exist
-> const str = helpers.toString(value);
->
-> // ✅ CORRECT - Use native String()
-> const str = String(value);
->
-> // ✅ ALSO CORRECT - Use sdk.toString resolver for mapping config
-> "field": { source: "value", resolver: "sdk.toString" }
-> ```
-
-```typescript
-// ❌ BAD: Unsafe operations
-'custom.unsafe': (value, sourceData, config, helpers) => {
-  return parseFloat(value);  // NaN if value is "abc"
-}
-
-// ✅ GOOD: Safe operations with helpers
-'custom.safe': (value, sourceData, config, helpers) => {
-  return helpers.parseFloatSafe(value, 0);  // Returns 0 if value is "abc"
-}
-```
-
-### Common Use Cases
-
-**1. Safe Type Conversion**
-```typescript
-'custom.safeConvert': (value, sourceData, config, helpers) => {
-  const numeric = helpers.parseFloatSafe(value, 0);
-  const integer = helpers.parseIntSafe(value, 0);
-  const string = String(value);  // Use native String() for conversion
-  const boolean = helpers.isString(value) && value.toLowerCase() === 'true';
-
-  return { numeric, integer, string, boolean };
-}
-```
-
-**2. Date Formatting**
-```typescript
-'custom.formatDate': (value, sourceData, config, helpers) => {
-  // formatDate() returns ISO8601 string
-  return helpers.formatDate(value);  // Returns ISO8601 format
-}
-
-// Input: value = "2025-01-15T10:30:00Z"
-// Output: "2025-01-15"
-```
-
-**3. Nested Field Access**
-```typescript
-'custom.getNestedField': (value, sourceData, config, helpers) => {
-  // Safely access nested fields
-  const name = helpers.get(sourceData, 'customer.contact.name', 'Unknown');
-
-  // Returns 'Unknown' if path doesn't exist
-  return name;
-}
-```
-
-**4. Array Operations**
-```typescript
-'custom.processArray': (value, sourceData, config, helpers) => {
-  const items = helpers.ensureArray(value);
-
-  // Array utilities
-  const unique = helpers.unique(items);
-  const sorted = helpers.sortBy(unique, 'price');
-  const summed = helpers.sum(sorted.map(i => i.price));
-
-  return { unique, sorted, total: summed };
-}
-```
-
-**5. Logging**
-```typescript
-'custom.debugTransform': (value, sourceData, config, helpers) => {
-  helpers.log.debug(`Transforming value: ${value}`);
-
-  const result = String(value).toUpperCase();  // Use native String()
-
-  helpers.log.debug(`Result: ${result}`);
-
-  return result;
-}
-```
-
-**6. Async API Calls**
-```typescript
-'custom.fetchData': async (id, sourceData, config, helpers) => {
-  if (!helpers.fluentClient) {
-    helpers.log.warn('FluentClient not available');
-    return null;
-  }
-
-  try {
-    const result = await helpers.fluentClient.graphql({
-      query: `query { product(id: "${id}") { name } }`
-    });
-
-    return result.data.product;
-  } catch (error) {
-    helpers.log.error('API call failed', error);
-    return null;
-  }
-}
-```
-
----
-
-## Using All 4 Parameters Together
-
-### Complex Real-World Example
-
-```typescript
-'custom.complexTransform': (value, sourceData, config, helpers) => {
-  // 1. Use VALUE - the field being transformed
-  const basePrice = helpers.parseFloatSafe(value, 0);
-
-  // 2. Use SOURCEDATA - access related fields
-  const quantity = helpers.get(sourceData, 'quantity') || 1;
-  const category = helpers.get(sourceData, 'product.category');
-  const customerTier = helpers.get(sourceData, 'customer.tier');
-
-  // 3. Use CONFIG - business rules
-  const categoryMultipliers = config.categoryMultipliers || {};
-  const tierDiscounts = config.tierDiscounts || {};
-
-  // 4. Use HELPERS - utilities
-  const multiplier = categoryMultipliers[category] || 1;
-  const discount = tierDiscounts[customerTier] || 0;
-
-  // Complex calculation
-  const subtotal = basePrice * quantity * multiplier;
-  const afterDiscount = subtotal * (1 - discount);
-  const final = helpers.parseFloatSafe(afterDiscount, 0);
-
-  helpers.log.debug(`Calculated price: ${final}`);
-
-  return final;
-}
-
-// Usage with full context
-const mapper = new UniversalMapper(mapping, {
-  customResolvers: { 'custom.complexTransform': complexTransform },
-  context: {
-    categoryMultipliers: {
-      'electronics': 1.5,
-      'books': 1.2,
-      'clothing': 1.3
-    },
-    tierDiscounts: {
-      'gold': 0.15,
-      'silver': 0.10,
-      'bronze': 0.05
-    }
-  },
-  logger: myLogger
-});
-```
-
-## Parameter Naming Convention
-
-Always use these exact parameter names:
-
-```typescript
-// ✅ CORRECT - Standard names
-(value, sourceData, config, helpers) => { ... }
-
-// ❌ WRONG - Non-standard names
-(val, src, cfg, hlp) => { ... }
-(v, data, c, h) => { ... }
-(fieldValue, record, options, utils) => { ... }
-```
-
-Standard names improve:
-- Code readability
-- Documentation clarity
-- Team collaboration
-- Error message clarity
-
-## Key Takeaways
-
-- 🎯 **value** - The extracted field value to transform
-- 🎯 **sourceData** - Complete source object for context-aware transformations
-- 🎯 **config** - Business rules passed via mapper `context` option
-- 🎯 **helpers** - 54 SDK utility functions + logger + fluentClient
-- 🎯 **Use all 4** - Even if you only need one, include all four parameters
-- 🎯 **Standard names** - Always use `value`, `sourceData`, `config`, `helpers`
-
-## Practice Exercise
-
-Write a resolver that uses all 4 parameters to calculate a shipping cost:
-
-**Requirements:**
-- Base shipping rate from `value`
-- Weight from `sourceData.weight`
-- Shipping zone from `config.shippingZones`
-- Use `helpers.parseFloatSafe` for safety
-
-<details>
-<summary>Show Solution</summary>
-
-```typescript
-'custom.calculateShipping': (baseRate, sourceData, config, helpers) => {
-  // 1. VALUE: Base shipping rate
-  const rate = helpers.parseFloatSafe(baseRate, 5.00);
-
-  // 2. SOURCEDATA: Get weight from source
-  const weight = helpers.get(sourceData, 'weight') || 1;
-  const zone = helpers.get(sourceData, 'address.zone');
-
-  // 3. CONFIG: Zone multipliers
-  const zoneMultipliers = config.shippingZones || {};
-  const multiplier = zoneMultipliers[zone] || 1;
-
-  // 4. HELPERS: Safe calculations
-  const shipping = rate * weight * multiplier;
-
-  return helpers.parseFloatSafe(shipping, rate);
-}
-
-// Usage
-const mapper = new UniversalMapper(mapping, {
-  customResolvers: { 'custom.calculateShipping': calculateShipping },
-  context: {
-    shippingZones: {
-      'local': 1.0,
-      'regional': 1.5,
-      'national': 2.0,
-      'international': 3.0
-    }
-  }
-});
-```
-</details>
-
-## Next Steps
-
-Continue to [Module 3: Basic Examples](./resolver-signature-03-basic-examples.md) to see simple, practical examples you can use immediately.
+# Module 2: Parameter Reference
+
+**Level:** Beginner
+**Estimated Time:** 20 minutes
+
+## Overview
+
+This module provides a detailed breakdown of each parameter in the standard 4-parameter resolver signature. You'll learn what each parameter contains, when to use it, and common patterns.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Understand what each parameter contains
+- ✅ Know when to use each parameter
+- ✅ Recognize common patterns for each parameter
+- ✅ Write resolvers that leverage all 4 parameters effectively
+
+## The Four Parameters
+
+```typescript
+type ResolverFunction = (
+  value: any,              // ← Parameter 1
+  sourceData: any,         // ← Parameter 2
+  config: any,             // ← Parameter 3
+  helpers: ResolverHelpers // ← Parameter 4
+) => any | Promise<any>;
+```
+
+---
+
+## Parameter 1: `value`
+
+### What It Is
+
+The extracted field value that needs to be transformed.
+
+```typescript
+// For this mapping:
+{ source: "price", resolver: "custom.addTax" }
+
+// If sourceData = { price: 19.99, quantity: 5 }
+// Then value = 19.99
+```
+
+### Where It Comes From
+
+| Mapping Config | value Parameter |
+|----------------|-----------------|
+| `{ source: "price" }` | `sourceData.price` |
+| `{ value: "ACTIVE" }` | `"ACTIVE"` (literal) |
+| `{ source: "product.name" }` | Nested value from `sourceData.product.name` |
+| `{ resolver: "custom.gen" }` | `undefined` (generator resolver) |
+
+### Common Use Cases
+
+**1. Direct Transformation**
+```typescript
+'custom.uppercase': (value, sourceData, config, helpers) => {
+  return String(value).toUpperCase();
+}
+
+// Input: value = "widget"
+// Output: "WIDGET"
+```
+
+**2. Type Conversion**
+```typescript
+'custom.toNumber': (value, sourceData, config, helpers) => {
+  return helpers.parseFloatSafe(value, 0);
+}
+
+// Input: value = "19.99"
+// Output: 19.99
+```
+
+**3. Validation**
+```typescript
+'custom.validateEmail': (value, sourceData, config, helpers) => {
+  if (!helpers.isValidEmail(value)) {
+    helpers.log.warn(`Invalid email: ${value}`);
+    return null;
+  }
+  return value;
+}
+
+// Input: value = "user@example.com"
+// Output: "user@example.com" (if valid) or null (if invalid)
+```
+
+**4. Generator Resolvers**
+```typescript
+'custom.generateUUID': (value, sourceData, config, helpers) => {
+  // value is undefined for generators
+  return helpers.uuid();
+}
+
+// Input: value = undefined
+// Output: "550e8400-e29b-41d4-a716-446655440000"
+```
+
+---
+
+## Parameter 2: `sourceData`
+
+### What It Is
+
+The complete source data object. Allows resolvers to access sibling fields and make context-aware transformations.
+
+```typescript
+// For this mapping:
+{ source: "price", resolver: "custom.calculateTotal" }
+
+// If source document is:
+{
+  price: 19.99,
+  quantity: 5,
+  discount: 10,
+  customer: { tier: "gold" }
+}
+
+// Then sourceData = entire object above
+```
+
+### Why It Matters
+
+Without `sourceData`, resolvers can only transform the single field value. With `sourceData`, resolvers can make decisions based on other fields:
+
+```typescript
+// ❌ LIMITED: Can only use price
+'custom.basic': (value, sourceData, config, helpers) => {
+  return value * 1.1;  // Always add 10%
+}
+
+// ✅ POWERFUL: Can use price AND customer tier
+'custom.smart': (value, sourceData, config, helpers) => {
+  const tier = helpers.get(sourceData, 'customer.tier');
+  const multiplier = tier === 'gold' ? 1.05 : 1.1;
+  return value * multiplier;  // 5% for gold, 10% for others
+}
+```
+
+### Common Use Cases
+
+**1. Multi-Field Calculations**
+```typescript
+'custom.calculateTotal': (basePrice, sourceData, config, helpers) => {
+  // Access sibling fields
+  const quantity = helpers.get(sourceData, 'quantity') || 1;
+  const discount = helpers.get(sourceData, 'discount') || 0;
+
+  // Calculate using multiple fields
+  const subtotal = basePrice * quantity;
+  const afterDiscount = subtotal * (1 - discount / 100);
+
+  return helpers.parseFloatSafe(afterDiscount, 0);
+}
+
+// sourceData: { price: 19.99, quantity: 5, discount: 10 }
+// value: 19.99
+// Output: 89.955 (19.99 * 5 * 0.9)
+```
+
+**2. Conditional Logic Based on Context**
+```typescript
+'custom.calculateTax': (price, sourceData, config, helpers) => {
+  // Tax rate depends on customer region
+  const region = helpers.get(sourceData, 'customer.region');
+
+  const taxRates = {
+    'CA': 0.0975,
+    'NY': 0.08875,
+    'TX': 0.0625
+  };
+
+  const taxRate = taxRates[region] || 0.08;
+  return price * taxRate;
+}
+
+// sourceData: { price: 100, customer: { region: 'CA' } }
+// value: 100
+// Output: 9.75
+```
+
+**3. Accessing Nested Fields**
+```typescript
+'custom.formatAddress': (value, sourceData, config, helpers) => {
+  // Access deeply nested fields
+  const street = helpers.get(sourceData, 'customer.address.street');
+  const city = helpers.get(sourceData, 'customer.address.city');
+  const state = helpers.get(sourceData, 'customer.address.state');
+  const zip = helpers.get(sourceData, 'customer.address.zip');
+
+  return `${street}, ${city}, ${state} ${zip}`;
+}
+
+// sourceData: { customer: { address: { street: "123 Main St", ... } } }
+// Output: "123 Main St, Springfield, IL 62701"
+```
+
+**4. Array Processing**
+```typescript
+'custom.countItems': (value, sourceData, config, helpers) => {
+  // Count items in an array
+  const items = helpers.get(sourceData, 'items') || [];
+  return helpers.ensureArray(items).length;
+}
+
+// sourceData: { items: [{}, {}, {}] }
+// Output: 3
+```
+
+---
+
+## Parameter 3: `config`
+
+### What It Is
+
+Business rules and configuration passed to the mapper via the `context` option.
+
+```typescript
+// When creating mapper:
+const mapper = new UniversalMapper(mapping, {
+  customResolvers: { 'custom.tax': myResolver },
+  context: {                    // ← This becomes 'config' parameter
+    taxRate: 0.1,
+    skuPrefix: 'PROD',
+    currency: 'USD'
+  }
+});
+
+// In resolver:
+'custom.addTax': (value, sourceData, config, helpers) => {
+  const rate = config.taxRate;  // ← Access context here
+  return value * (1 + rate);
+}
+```
+
+### Why It Matters
+
+Configuration allows you to write reusable resolvers that behave differently based on runtime settings:
+
+```typescript
+// ✅ GOOD: Configurable behavior
+'custom.formatSKU': (value, sourceData, config, helpers) => {
+  const prefix = config.skuPrefix || 'SKU';
+  return `${prefix}-${value}`;
+}
+
+// Use with different prefixes:
+const csvMapper = new UniversalMapper(mapping, {
+  context: { skuPrefix: 'CSV' }
+});
+// Output: "CSV-123"
+
+const xmlMapper = new UniversalMapper(mapping, {
+  context: { skuPrefix: 'XML' }
+});
+// Output: "XML-123"
+```
+
+### Common Use Cases
+
+**1. Environment-Specific Settings**
+```typescript
+'custom.formatPrice': (value, sourceData, config, helpers) => {
+  const currency = config.currency || 'USD';
+  const locale = config.locale || 'en-US';
+
+  return helpers.formatCurrency(value, currency, locale);
+}
+
+// Development: USD
+const devMapper = new UniversalMapper(mapping, {
+  context: { currency: 'USD', locale: 'en-US' }
+});
+
+// Production (EU): EUR
+const prodMapper = new UniversalMapper(mapping, {
+  context: { currency: 'EUR', locale: 'de-DE' }
+});
+```
+
+**2. Business Rule Configuration**
+```typescript
+'custom.applyDiscount': (price, sourceData, config, helpers) => {
+  const discountRules = config.discountRules || {};
+
+  const quantity = helpers.get(sourceData, 'quantity') || 1;
+
+  // Apply volume discounts based on rules
+  if (quantity >= 100 && discountRules.bulk) {
+    return price * (1 - discountRules.bulk);
+  } else if (quantity >= 10 && discountRules.volume) {
+    return price * (1 - discountRules.volume);
+  }
+
+  return price;
+}
+
+// Mapper with discount rules
+const mapper = new UniversalMapper(mapping, {
+  context: {
+    discountRules: {
+      volume: 0.05,  // 5% off for 10+
+      bulk: 0.15     // 15% off for 100+
+    }
+  }
+});
+```
+
+**3. Feature Flags**
+```typescript
+'custom.enrichData': async (value, sourceData, config, helpers) => {
+  // Check feature flag
+  if (!config.enableEnrichment) {
+    return value;  // Skip enrichment if disabled
+  }
+
+  // Perform expensive enrichment
+  const enriched = await helpers.fluentClient.graphql({ ... });
+  return enriched;
+}
+
+// Development: enrichment disabled
+const devMapper = new UniversalMapper(mapping, {
+  context: { enableEnrichment: false }
+});
+
+// Production: enrichment enabled
+const prodMapper = new UniversalMapper(mapping, {
+  context: { enableEnrichment: true }
+});
+```
+
+**4. Lookup Tables**
+```typescript
+'custom.mapCategory': (value, sourceData, config, helpers) => {
+  const categoryMap = config.categoryMapping || {};
+
+  // Map external category to internal category
+  return categoryMap[value] || value;
+}
+
+// Mapper with category mapping
+const mapper = new UniversalMapper(mapping, {
+  context: {
+    categoryMapping: {
+      'ELEC': 'Electronics',
+      'CLTH': 'Clothing',
+      'FOOD': 'Groceries'
+    }
+  }
+});
+```
+
+---
+
+## Parameter 4: `helpers`
+
+### What It Is
+
+SDK utilities and user-provided context. Contains 54 helper functions plus access to logger and FluentClient.
+
+```typescript
+interface ResolverHelpers {
+  // Core utilities (54 helper functions)
+  get, set, formatDate, formatCurrency, parseFloatSafe, parseIntSafe,
+  extractCustomAttribute, safeJsonParse, mapValue, isValidEmail,
+  requireField, fullName, truncate, normalizeWhitespace,
+
+  // Data transformation
+  toCamelCase, toSnakeCase, deepClone, deepMerge,
+
+  // Array operations
+  ensureArray, coalesce, groupBy, keyBy, chunk, flatten, unique,
+  sortBy, compact, sum, avg, min, max, clamp, merge,
+
+  // String operations
+  template, slugify, uuid, hashString,
+
+  // Date operations
+  addDays, subtractDays, dateDiff, parseDate,
+
+  // Performance
+  memoize, batchProcess, retry, debounce, throttle,
+
+  // Type checks
+  isString, isNumber, isArray, isObject, isDate,
+
+  // Additional context
+  log: Logger,              // Logger instance
+  fluentClient?: any,       // Fluent API client (for async operations)
+  context?: any             // User-provided shared config (use config parameter instead)
+}
+```
+
+### Why It Matters
+
+Helpers provide safe, tested utilities so you don't have to reinvent common operations:
+
+> **⚠️ IMPORTANT: Common Mistake**
+>
+> `toString()` is NOT a helper function. Use native `String(value)` instead.
+>
+> ```typescript
+> // ❌ WRONG - helpers.toString() doesn't exist
+> const str = helpers.toString(value);
+>
+> // ✅ CORRECT - Use native String()
+> const str = String(value);
+>
+> // ✅ ALSO CORRECT - Use sdk.toString resolver for mapping config
+> "field": { source: "value", resolver: "sdk.toString" }
+> ```
+
+```typescript
+// ❌ BAD: Unsafe operations
+'custom.unsafe': (value, sourceData, config, helpers) => {
+  return parseFloat(value);  // NaN if value is "abc"
+}
+
+// ✅ GOOD: Safe operations with helpers
+'custom.safe': (value, sourceData, config, helpers) => {
+  return helpers.parseFloatSafe(value, 0);  // Returns 0 if value is "abc"
+}
+```
+
+### Common Use Cases
+
+**1. Safe Type Conversion**
+```typescript
+'custom.safeConvert': (value, sourceData, config, helpers) => {
+  const numeric = helpers.parseFloatSafe(value, 0);
+  const integer = helpers.parseIntSafe(value, 0);
+  const string = String(value);  // Use native String() for conversion
+  const boolean = helpers.isString(value) && value.toLowerCase() === 'true';
+
+  return { numeric, integer, string, boolean };
+}
+```
+
+**2. Date Formatting**
+```typescript
+'custom.formatDate': (value, sourceData, config, helpers) => {
+  // formatDate() returns ISO8601 string
+  return helpers.formatDate(value);  // Returns ISO8601 format
+}
+
+// Input: value = "2025-01-15T10:30:00Z"
+// Output: "2025-01-15"
+```
+
+**3. Nested Field Access**
+```typescript
+'custom.getNestedField': (value, sourceData, config, helpers) => {
+  // Safely access nested fields
+  const name = helpers.get(sourceData, 'customer.contact.name', 'Unknown');
+
+  // Returns 'Unknown' if path doesn't exist
+  return name;
+}
+```
+
+**4. Array Operations**
+```typescript
+'custom.processArray': (value, sourceData, config, helpers) => {
+  const items = helpers.ensureArray(value);
+
+  // Array utilities
+  const unique = helpers.unique(items);
+  const sorted = helpers.sortBy(unique, 'price');
+  const summed = helpers.sum(sorted.map(i => i.price));
+
+  return { unique, sorted, total: summed };
+}
+```
+
+**5. Logging**
+```typescript
+'custom.debugTransform': (value, sourceData, config, helpers) => {
+  helpers.log.debug(`Transforming value: ${value}`);
+
+  const result = String(value).toUpperCase();  // Use native String()
+
+  helpers.log.debug(`Result: ${result}`);
+
+  return result;
+}
+```
+
+**6. Async API Calls**
+```typescript
+'custom.fetchData': async (id, sourceData, config, helpers) => {
+  if (!helpers.fluentClient) {
+    helpers.log.warn('FluentClient not available');
+    return null;
+  }
+
+  try {
+    const result = await helpers.fluentClient.graphql({
+      query: `query { product(id: "${id}") { name } }`
+    });
+
+    return result.data.product;
+  } catch (error) {
+    helpers.log.error('API call failed', error);
+    return null;
+  }
+}
+```
+
+---
+
+## Using All 4 Parameters Together
+
+### Complex Real-World Example
+
+```typescript
+'custom.complexTransform': (value, sourceData, config, helpers) => {
+  // 1. Use VALUE - the field being transformed
+  const basePrice = helpers.parseFloatSafe(value, 0);
+
+  // 2. Use SOURCEDATA - access related fields
+  const quantity = helpers.get(sourceData, 'quantity') || 1;
+  const category = helpers.get(sourceData, 'product.category');
+  const customerTier = helpers.get(sourceData, 'customer.tier');
+
+  // 3. Use CONFIG - business rules
+  const categoryMultipliers = config.categoryMultipliers || {};
+  const tierDiscounts = config.tierDiscounts || {};
+
+  // 4. Use HELPERS - utilities
+  const multiplier = categoryMultipliers[category] || 1;
+  const discount = tierDiscounts[customerTier] || 0;
+
+  // Complex calculation
+  const subtotal = basePrice * quantity * multiplier;
+  const afterDiscount = subtotal * (1 - discount);
+  const final = helpers.parseFloatSafe(afterDiscount, 0);
+
+  helpers.log.debug(`Calculated price: ${final}`);
+
+  return final;
+}
+
+// Usage with full context
+const mapper = new UniversalMapper(mapping, {
+  customResolvers: { 'custom.complexTransform': complexTransform },
+  context: {
+    categoryMultipliers: {
+      'electronics': 1.5,
+      'books': 1.2,
+      'clothing': 1.3
+    },
+    tierDiscounts: {
+      'gold': 0.15,
+      'silver': 0.10,
+      'bronze': 0.05
+    }
+  },
+  logger: myLogger
+});
+```
+
+## Parameter Naming Convention
+
+Always use these exact parameter names:
+
+```typescript
+// ✅ CORRECT - Standard names
+(value, sourceData, config, helpers) => { ... }
+
+// ❌ WRONG - Non-standard names
+(val, src, cfg, hlp) => { ... }
+(v, data, c, h) => { ... }
+(fieldValue, record, options, utils) => { ... }
+```
+
+Standard names improve:
+- Code readability
+- Documentation clarity
+- Team collaboration
+- Error message clarity
+
+## Key Takeaways
+
+- 🎯 **value** - The extracted field value to transform
+- 🎯 **sourceData** - Complete source object for context-aware transformations
+- 🎯 **config** - Business rules passed via mapper `context` option
+- 🎯 **helpers** - 54 SDK utility functions + logger + fluentClient
+- 🎯 **Use all 4** - Even if you only need one, include all four parameters
+- 🎯 **Standard names** - Always use `value`, `sourceData`, `config`, `helpers`
+
+## Practice Exercise
+
+Write a resolver that uses all 4 parameters to calculate a shipping cost:
+
+**Requirements:**
+- Base shipping rate from `value`
+- Weight from `sourceData.weight`
+- Shipping zone from `config.shippingZones`
+- Use `helpers.parseFloatSafe` for safety
+
+<details>
+<summary>Show Solution</summary>
+
+```typescript
+'custom.calculateShipping': (baseRate, sourceData, config, helpers) => {
+  // 1. VALUE: Base shipping rate
+  const rate = helpers.parseFloatSafe(baseRate, 5.00);
+
+  // 2. SOURCEDATA: Get weight from source
+  const weight = helpers.get(sourceData, 'weight') || 1;
+  const zone = helpers.get(sourceData, 'address.zone');
+
+  // 3. CONFIG: Zone multipliers
+  const zoneMultipliers = config.shippingZones || {};
+  const multiplier = zoneMultipliers[zone] || 1;
+
+  // 4. HELPERS: Safe calculations
+  const shipping = rate * weight * multiplier;
+
+  return helpers.parseFloatSafe(shipping, rate);
+}
+
+// Usage
+const mapper = new UniversalMapper(mapping, {
+  customResolvers: { 'custom.calculateShipping': calculateShipping },
+  context: {
+    shippingZones: {
+      'local': 1.0,
+      'regional': 1.5,
+      'national': 2.0,
+      'international': 3.0
+    }
+  }
+});
+```
+</details>
+
+## Next Steps
+
+Continue to [Module 3: Basic Examples](./resolver-signature-03-basic-examples.md) to see simple, practical examples you can use immediately.