@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/02-CORE-GUIDES/mapping/modules/mapping-06-helpers-resolvers.md

@@ -1,1126 +1,1126 @@
-# Module 6: Helpers & Resolvers
-
-**Leverage 54 Built-in Utilities**
-
-**Level:** Advanced
-**Time:** 35 minutes
-**Prerequisites:** [Module 5: Advanced Patterns](./mapping-05-advanced-patterns.md)
-
----
-
-## Learning Objectives
-
-After completing this module, you will:
-
-- ✅ Understand all 16 SDK resolvers
-- ✅ Use 57 helper functions in custom resolvers
-- ✅ Write efficient custom resolvers
-- ✅ Implement async resolvers for API lookups
-- ✅ Apply resolver best practices
-- ✅ Optimize resolver performance
-
----
-
-## Table of Contents
-
-1. [SDK Resolvers Overview](#sdk-resolvers-overview)
-2. [String Resolvers](#string-resolvers)
-3. [Number Resolvers](#number-resolvers)
-4. [Date Resolvers](#date-resolvers)
-5. [Type Conversion Resolvers](#type-conversion-resolvers)
-6. [Utility Resolvers](#utility-resolvers)
-7. [Helper Functions Reference](#helper-functions-reference)
-8. [Custom Resolvers](#custom-resolvers)
-9. [Async Resolvers](#async-resolvers)
-10. [Best Practices](#best-practices)
-11. [Performance Optimization](#performance-optimization)
-
----
-
-## SDK Resolvers Overview
-
-The SDK provides **16 built-in resolvers** for common transformations. All SDK resolvers:
-
-- ✅ Follow naming convention: `sdk.<functionName>`
-- ✅ Are null-safe (never throw errors)
-- ✅ Return safe defaults for invalid input
-- ✅ Work with all mappers (UniversalMapper, GraphQLMutationMapper)
-
-### Complete SDK Resolver List
-
-| Category    | Resolvers                              | Count |
-| ----------- | -------------------------------------- | ----- |
-| **String**  | uppercase, lowercase, trim, toString   | 4     |
-| **Number**  | parseInt, parseFloat, number           | 3     |
-| **Date**    | formatDate, formatDateShort, parseDate | 3     |
-| **Type**    | boolean, parseJson, toJson             | 3     |
-| **Utility** | identity, coalesce, default            | 3     |
-
-**Total**: 16 SDK resolvers
-
-### Accessing SDK Resolvers Programmatically (NEW)
-
-You can access SDK resolvers directly or test resolver names at runtime.
-
-```typescript
-import {
-  sdkResolvers,
-  getSdkResolver,
-  isSdkResolver,
-  getSdkResolverNames,
-  UniversalMapper,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Get all SDK resolver names
-const allResolvers = getSdkResolverNames();
-console.log(allResolvers);
-// SDK resolvers: ['sdk.uppercase', 'sdk.lowercase', 'sdk.trim', 'sdk.parseInt', ...]
-
-// Retrieve a resolver function by name
-const resolverFn = getSdkResolver('sdk.parseInt'); // (value) => number
-console.log(isSdkResolver('sdk.parseInt')); // true
-console.log(isSdkResolver('custom.myResolver')); // false
-
-// Use sdkResolvers inside custom resolvers
-const mapper = new UniversalMapper(mappingConfig, {
-  customResolvers: {
-    'custom.upperTrim': (value: any) => {
-      const upper = sdkResolvers\['sdk.uppercase'](value, null, null, {});
-      return sdkResolvers\['sdk.trim'](upper, null, null, {});
-    },
-  },
-});
-```
-
-**Utility Functions:**
-
-- `getSdkResolverNames()` - Returns array of all SDK resolver names (useful for validation, autocomplete)
-- `getSdkResolver(name)` - Returns resolver function by name or undefined
-- `isSdkResolver(name)` - Checks if a resolver name starts with 'sdk.'
-
----
-
-## String Resolvers
-
-### sdk.uppercase
-
-Convert string to uppercase.
-
-**Use case**: Normalize SKU codes, status values, country codes
-
-```json
-{
-  "fields": {
-    "status": {
-      "source": "order_status",
-      "resolver": "sdk.uppercase"
-    }
-  }
-}
-```
-
-**Examples**:
-
-```typescript
-"active" → "ACTIVE"
-"pending" → "PENDING"
-123 → 123 (non-strings pass through)
-null → null (null-safe)
-```
-
-**Null-safe behavior**: Returns non-strings unchanged
-
----
-
-### sdk.lowercase
-
-Convert string to lowercase.
-
-**Use case**: Normalize email addresses, usernames, tags
-
-```json
-{
-  "fields": {
-    "email": {
-      "source": "customer_email",
-      "resolver": "sdk.lowercase"
-    }
-  }
-}
-```
-
-**Examples**:
-
-```typescript
-"John@EXAMPLE.COM" → "john@example.com"
-"SKU-001" → "sku-001"
-123 → 123 (non-strings pass through)
-null → null (null-safe)
-```
-
----
-
-### sdk.trim
-
-Remove leading and trailing whitespace.
-
-**Use case**: Clean CSV fields, remove spaces from user input
-
-```json
-{
-  "fields": {
-    "sku": {
-      "source": "product_code",
-      "resolver": "sdk.trim"
-    }
-  }
-}
-```
-
-**Examples**:
-
-```typescript
-"  SKU123  " → "SKU123"
-"\tSKU456\n" → "SKU456"
-"  " → "" (empty after trim)
-123 → 123 (non-strings pass through)
-```
-
----
-
-### sdk.toString
-
-Convert value to string.
-
-**Use case**: Ensure value is string type, prevent "null" strings
-
-```json
-{
-  "fields": {
-    "productRef": {
-      "source": "product_id",
-      "resolver": "sdk.toString"
-    }
-  }
-}
-```
-
-**Examples**:
-
-```typescript
-123 → "123"
-true → "true"
-null → "" (empty string, NOT "null")
-undefined → "" (empty string, NOT "undefined")
-{ foo: "bar" } → "[object Object]"
-```
-
-**Critical**: Returns empty string for null/undefined (prevents literal "null"/"undefined" strings)
-
----
-
-## Number Resolvers
-
-### sdk.parseInt
-
-Parse value as integer.
-
-**Use case**: Convert quantity strings to numbers, parse IDs
-
-```json
-{
-  "fields": {
-    "quantity": {
-      "source": "qty",
-      "resolver": "sdk.parseInt"
-    }
-  }
-}
-```
-
-**Examples**:
-
-```typescript
-"123" → 123
-"123.99" → 123 (truncates decimals)
-"$45" → 0 (invalid → default)
-"abc" → 0 (invalid → default)
-null → 0 (null-safe default)
-```
-
-**Important**: Returns `0` for invalid values (NOT `NaN`). This prevents breaking Fluent API calls.
-
----
-
-### sdk.parseFloat
-
-Parse value as floating-point number.
-
-**Use case**: Convert price/weight strings to numbers
-
-```json
-{
-  "fields": {
-    "price": {
-      "source": "total_price",
-      "resolver": "sdk.parseFloat"
-    }
-  }
-}
-```
-
-**Examples**:
-
-```typescript
-"123.99" → 123.99
-"$45.50" → 45.5 (strips currency symbols)
-"1,234.56" → 1234.56 (removes commas)
-"  99.99  " → 99.99 (trims whitespace)
-"abc" → 0 (invalid → default)
-```
-
-**Advanced**: Handles currency symbols ($, €, £), commas, and whitespace automatically.
-
----
-
-### sdk.number
-
-Parse value as number (alias for parseFloat).
-
-**Use case**: Generic number parsing when integer vs float doesn't matter
-
-```json
-{
-  "fields": {
-    "weight": {
-      "source": "product_weight",
-      "resolver": "sdk.number"
-    }
-  }
-}
-```
-
-Same behavior as `sdk.parseFloat`.
-
----
-
-## Date Resolvers
-
-### sdk.formatDate
-
-Format date to ISO8601 (Fluent Commerce API format).
-
-**Use case**: Convert dates to Fluent API format
-
-```json
-{
-  "fields": {
-    "expectedOn": {
-      "source": "delivery_date",
-      "resolver": "sdk.formatDate"
-    }
-  }
-}
-```
-
-**Examples**:
-
-```typescript
-"2025-01-15" → "2025-01-15T00:00:00.000Z"
-"01/15/2025" → "2025-01-15T00:00:00.000Z"
-Date object → "2025-01-15T10:30:00.000Z"
-null → null (null-safe)
-"invalid" → "invalid" (passes through)
-```
-
-**Critical**: Fluent Commerce API requires ISO8601 format for date fields.
-
----
-
-### sdk.formatDateShort
-
-Format date to YYYY-MM-DD (short format).
-
-**Use case**: Convert dates to short format for reports, CSV exports
-
-```json
-{
-  "fields": {
-    "orderDate": {
-      "source": "created_at",
-      "resolver": "sdk.formatDateShort"
-    }
-  }
-}
-```
-
-**Examples**:
-
-```typescript
-"2025-01-15T10:30:00Z" → "2025-01-15"
-Date object → "2025-01-15"
-"invalid" → "invalid" (invalid dates pass through)
-null → null (null-safe)
-```
-
-**Note**: Strips time component—useful for date-only fields.
-
----
-
-### sdk.parseDate
-
-Parse various date formats to Date object.
-
-**Use case**: Convert multiple date formats to standardized Date
-
-```json
-{
-  "fields": {
-    "orderDate": {
-      "source": "order_date",
-      "resolver": "sdk.parseDate"
-    }
-  }
-}
-```
-
-**Examples**:
-
-```typescript
-"2025-01-15" → Date("2025-01-15T00:00:00.000Z")
-"01/15/2025" → Date (US format)
-"15/01/2025" → Date (EU format)
-1737763200000 → Date (Unix timestamp)
-null → null (null-safe)
-```
-
-**Handles**: ISO8601, US format, EU format, Unix timestamps.
-
----
-
-## Type Conversion Resolvers
-
-### sdk.boolean
-
-Convert value to boolean.
-
-**Use case**: Parse boolean flags from CSV, XML
-
-```json
-{
-  "fields": {
-    "isActive": {
-      "source": "active_flag",
-      "resolver": "sdk.boolean"
-    }
-  }
-}
-```
-
-**Examples**:
-
-```typescript
-"true" → true
-"false" → false
-"1" → true
-"0" → false
-"yes" → true
-"no" → false
-"y" → true
-"n" → false
-"TRUE" → true (case-insensitive)
-"True" → true
-null → false (null-safe)
-undefined → false
-```
-
-**Case-insensitive**: "TRUE", "True", "true" all return `true`.
-
----
-
-### sdk.parseJson
-
-Parse JSON string to object.
-
-**Use case**: Parse JSON-encoded fields from CSV, XML attributes
-
-```json
-{
-  "fields": {
-    "metadata": {
-      "source": "custom_data",
-      "resolver": "sdk.parseJson"
-    }
-  }
-}
-```
-
-**Examples**:
-
-```typescript
-'{"name":"John","age":30}' → { name: "John", age: 30 }
-'["a","b","c"]' → ["a", "b", "c"]
-"invalid json" → "invalid json" (passes through)
-123 → 123 (non-strings pass through)
-```
-
-**Null-safe**: Returns original value if parse fails (never throws).
-
----
-
-### sdk.toJson
-
-Stringify value as JSON.
-
-**Use case**: Convert objects to JSON strings for storage in text fields
-
-```json
-{
-  "fields": {
-    "customAttributes": {
-      "source": "attributes_obj",
-      "resolver": "sdk.toJson"
-    }
-  }
-}
-```
-
-**Examples**:
-
-```typescript
-{ name: "John" } → '{"name":"John"}'
-["a", "b", "c"] → '["a","b","c"]'
-123 → "123"
-"string" → '"string"' (double-quoted)
-```
-
-**Use case**: Storing complex objects in Fluent Commerce custom attributes.
-
----
-
-## Utility Resolvers
-
-### sdk.identity
-
-Return value unchanged (no-op resolver).
-
-**Use case**: Explicitly pass value through without transformation
-
-```json
-{
-  "fields": {
-    "ref": {
-      "source": "order_id",
-      "resolver": "sdk.identity"
-    }
-  }
-}
-```
-
-**Why this exists**: Some mapping scenarios require a resolver to be specified, but no transformation is needed.
-
----
-
-### sdk.coalesce
-
-Return first non-null value.
-
-**Use case**: Provide fallback when value is null/undefined
-
-```json
-{
-  "fields": {
-    "email": {
-      "source": "primary_email",
-      "resolver": "sdk.coalesce",
-      "defaultValue": "noreply@example.com"
-    }
-  }
-}
-```
-
-**Note**: Typically handled by mapping engine checking `defaultValue`. This resolver exists for complex scenarios.
-
----
-
-### sdk.default
-
-Use the `defaultValue` field configuration property instead.
-
-This resolver provides default value if source is null/undefined/empty, but `defaultValue` in field config is the preferred approach.
-
-```json
-{
-  "fields": {
-    "status": {
-      "source": "order_status",
-      "defaultValue": "ACTIVE",
-      "resolver": "sdk.default"
-    }
-  }
-}
-```
-
-**Note**: The `defaultValue` field configuration property is preferred. This resolver applies after `config.defaultValue` is processed.
-
-**Examples**:
-
-```typescript
-"PENDING" → "PENDING" (value exists, pass through)
-null → null (defaultValue applied by mapper before resolver)
-undefined → undefined (defaultValue applied by mapper before resolver)
-```
-
-**Note**: Prefer using the `defaultValue` field configuration property instead of this resolver.
-
----
-
-## Helper Functions Reference
-
-Custom resolvers receive a `helpers` object with 57 utility functions.
-
-### Resolver Signature
-
-```typescript
-(value: any, sourceData: any, config: any, helpers: ResolverHelpers) => any | Promise<any>;
-```
-
-**Parameters**:
-
-1. `value` - The extracted field value (may be undefined for generator resolvers)
-2. `sourceData` - The complete source object (for context-aware transformations)
-3. `config` - Resolver-specific configuration object
-4. `helpers` - 57 utility functions
-
-### Helper Categories
-
-| Category                | Count | Examples                                                |
-| ----------------------- | ----- | ------------------------------------------------------- |
-| **Data Access**         | 4     | get, set, ensureArray, coalesce                         |
-| **String Manipulation** | 8     | toCamelCase, toSnakeCase, truncate, normalizeWhitespace |
-| **Number Operations**   | 3     | parseIntSafe, parseFloatSafe, formatCurrency            |
-| **Date/Time**           | 4     | formatDate, parseDate, addDays, subtractDays            |
-| **Validation**          | 3     | isValidEmail, requireField, isEmpty                     |
-| **Object Utilities**    | 6     | deepClone, deepMerge, pick, omit, merge, template       |
-| **Array Operations**    | 9     | unique, groupBy, sortBy, chunk, flatten, compact, sum, avg, min |
-| **Performance**         | 3     | memoize, batchProcess, retry                            |
-| **Type Guards**         | 5     | isString, isNumber, isArray, isObject, isDate           |
-| **Utilities**           | 9     | defaultTo, range, clamp, slugify, uuid, hashString, debounce, throttle, safeJsonParse |
-
-**Total**: 57 helpers
-
-### Core Data Access Helpers
-
-```typescript
-helpers.get(obj, 'customer.address.city'); // Safe nested access
-helpers.set(obj, 'customer.address.city', 'NYC'); // Safe nested set
-helpers.ensureArray(value); // Wrap singles in array
-helpers.coalesce(val1, val2, val3); // First non-null
-```
-
-### String Helpers
-
-```typescript
-helpers.toCamelCase('first_name'); // → "firstName"
-helpers.toSnakeCase('firstName'); // → "first_name"
-helpers.truncate('Long text...', 10); // → "Long te..."
-helpers.normalizeWhitespace('  a  b  '); // → "a b"
-helpers.fullName('John', 'Doe'); // → "John Doe"
-```
-
-### Number Helpers
-
-```typescript
-helpers.parseIntSafe('123', 0); // → 123 (or default 0)
-helpers.parseFloatSafe('$99.99', 0); // → 99.99
-helpers.formatCurrency(99.99, 2); // → "99.99"
-```
-
-### Date Helpers
-
-```typescript
-helpers.formatDate('2025-01-15'); // → ISO8601
-helpers.parseDate('01/15/2025'); // → Date object
-helpers.addDays(new Date(), 7); // → Date + 7 days
-helpers.diffDays(date1, date2); // → number of days
-```
-
-### Validation Helpers
-
-```typescript
-helpers.isValidEmail('test@example.com'); // → true
-helpers.requireField(value, 'email'); // Throws if null
-helpers.isEmpty(value); // → true if null/undefined/empty
-```
-
-### Object Helpers
-
-```typescript
-helpers.deepClone(obj); // Deep copy
-helpers.deepMerge(obj1, obj2); // Merge objects
-helpers.pick(obj, ['name', 'email']); // Extract fields
-helpers.omit(obj, ['password']); // Remove fields
-helpers.flatten(nestedObj); // Flatten to dot notation
-```
-
-### Array Helpers
-
-```typescript
-helpers.unique([1, 2, 2, 3]); // → [1, 2, 3]
-helpers.groupBy(items, 'category'); // Group by field
-helpers.sortBy(items, 'name'); // Sort by field
-helpers.chunk([1, 2, 3, 4, 5], 2); // → [[1,2], [3,4], [5]]
-helpers.findBy(items, 'id', '123'); // Find by field value
-```
-
-### Performance Helpers
-
-```typescript
-await helpers.retry(() => apiCall(), 3, 1000); // Retry with backoff
-await helpers.batchProcess(items, processFn, 100); // Process in batches
-const memoized = helpers.memoize(expensiveFn); // Cache results
-```
-
-### Utilities
-
-```typescript
-const hash = helpers.hashString('data'); // Simple hash
-const id = helpers.uuid(); // Generate UUID
-const slug = helpers.slugify('Product Name'); // → "product-name"
-helpers.debounce(fn, 300); // Debounce function calls
-helpers.throttle(fn, 1000); // Throttle function calls
-```
-
----
-
-## Custom Resolvers
-
-### Basic Custom Resolver
-
-```typescript
-const customResolvers = {
-  'custom.buildRef': (value, sourceData, config, helpers) => {
-    const sku = sourceData.sku;
-    const location = sourceData.location;
-    return `${sku}-${location}`;
-  },
-};
-
-// Use in mapping
-const mapper = new UniversalMapper(mappingConfig, { customResolvers });
-```
-
-### Using Helpers in Custom Resolvers
-
-```typescript
-const customResolvers = {
-  'custom.formatCustomerName': (value, sourceData, config, helpers) => {
-    const firstName = helpers.get(sourceData, 'customer.firstName');
-    const lastName = helpers.get(sourceData, 'customer.lastName');
-    return helpers.fullName(firstName, lastName);
-  },
-
-  'custom.calculateTotal': (value, sourceData, config, helpers) => {
-    const price = helpers.parseFloatSafe(sourceData.price, 0);
-    const qty = helpers.parseIntSafe(sourceData.quantity, 0);
-    const tax = helpers.parseFloatSafe(sourceData.tax, 0);
-    return price * qty + tax;
-  },
-
-  'custom.normalizeEmail': (value, sourceData, config, helpers) => {
-    if (!value || typeof value !== 'string') return null;
-
-    const email = helpers.normalizeWhitespace(value.toLowerCase().trim());
-
-    if (!helpers.isValidEmail(email)) {
-      helpers.logger?.warn('Invalid email', { email });
-      return null;
-    }
-
-    return email;
-  },
-};
-```
-
-### Context-Aware Resolvers
-
-```typescript
-const customResolvers = {
-  'custom.mapOrderType': (value, sourceData, config, helpers) => {
-    // Access shared configuration from context
-    const environment = helpers.context.environment || 'production';
-
-    const mapping: Record<string, string> = {
-      online: 'HD', // Home Delivery
-      store: 'CC', // Click & Collect
-    };
-
-    const orderType = mapping[value] || 'HD';
-
-    // In non-production, append test suffix
-    if (environment !== 'production') {
-      return `${orderType}_TEST`;
-    }
-
-    return orderType;
-  },
-};
-
-// Pass context when mapping
-const mapper = new UniversalMapper(mappingConfig, {
-  customResolvers,
-  fluentClient: client,
-});
-const result = await mapper.map(data);
-```
-
----
-
-## Async Resolvers
-
-Custom resolvers can be asynchronous for external API calls, database lookups, etc.
-
-### Async Lookup Example
-
-```typescript
-const customResolvers = {
-  'custom.lookupCustomer': async (value, sourceData, config, helpers) => {
-    const email = sourceData.customer_email;
-
-    if (!email) {
-      return null;
-    }
-
-    // Query Fluent API for existing customer
-    const result = await helpers.fluentClient.graphql({
-      query: `
-        query GetCustomer($email: String) {
-          customers(primaryEmail: $email, first: 1) {
-            edges {
-              node {
-                id
-                username
-              }
-            }
-          }
-        }
-      `,
-      variables: { email },
-    });
-
-    const existingCustomer = result?.customers?.edges?.[0]?.node;
-
-    if (existingCustomer) {
-      helpers.logger?.info('Found existing customer', { customerId: existingCustomer.id });
-      return existingCustomer.id;
-    }
-
-    // Customer not found - create new
-    const createResult = await helpers.fluentClient.graphql({
-      query: `
-        mutation CreateCustomer($input: CreateCustomerInput!) {
-          createCustomer(input: $input) {
-            id
-          }
-        }
-      `,
-      variables: {
-        input: {
-          username: email,
-          primaryEmail: email,
-          firstName: sourceData.first_name || 'Guest',
-          lastName: sourceData.last_name || 'Customer',
-          retailer: { id: '2' },
-        },
-      },
-    });
-
-    helpers.logger?.info('Created new customer', { customerId: createResult.id });
-
-    return createResult.id;
-  },
-};
-```
-
-**Important**: When using async resolvers, you must `await` the mapping:
-
-```typescript
-const result = await mapper.map(data, {
-  fluentClient: client,
-  helpers: { fluentClient: client },
-});
-```
-
-### Async with Retry
-
-```typescript
-const customResolvers = {
-  'custom.fetchProductPrice': async (value, sourceData, config, helpers) => {
-    const sku = sourceData.sku;
-
-    // Retry API call up to 3 times with 1s delay
-    const price = await helpers.retry(
-      async () => {
-        const response = await fetch(`https://api.example.com/products/${sku}/price`);
-
-        if (!response.ok) {
-          throw new Error(`HTTP ${response.status}`);
-        }
-
-        const data = await response.json();
-        return data.price;
-      },
-      3,
-      1000
-    );
-
-    return price;
-  },
-};
-```
-
-### Batch Processing (Performance Optimization)
-
-```typescript
-// ❌ BAD: Sequential API calls (slow for 1000 records)
-'custom.lookupCustomerSlow': async (value, sourceData, config, helpers) => {
-  const email = sourceData.email;
-  const result = await helpers.fluentClient.graphql({ query, variables: { email } });
-  return result?.customers?.edges?.[0]?.node?.id;
-}
-
-// ✅ GOOD: Batch cache to reduce API calls
-const customerCache = new Map();
-
-const customResolvers = {
-  'custom.lookupCustomerFast': async (value, sourceData, config, helpers) => {
-    const email = sourceData.email;
-
-    // Check cache first
-    if (customerCache.has(email)) {
-      return customerCache.get(email);
-    }
-
-    // Query API
-    const result = await helpers.fluentClient.graphql({
-      query,
-      variables: { email }
-    });
-
-    const customerId = result?.customers?.edges?.[0]?.node?.id;
-
-    // Cache result
-    customerCache.set(email, customerId);
-
-    return customerId;
-  }
-};
-```
-
----
-
-## Best Practices
-
-### 1. Use SDK Resolvers First
-
-Before writing custom resolvers, check if SDK resolvers can handle the transformation:
-
-```typescript
-// ❌ NOT NEEDED
-'custom.toUppercase': (value) => value?.toUpperCase()
-
-// ✅ USE SDK RESOLVER
-{ "resolver": "sdk.uppercase" }
-```
-
-### 2. Keep Resolvers Pure
-
-Resolvers should be pure functions (same input → same output, no side effects):
-
-```typescript
-// ❌ BAD: Side effects (modifies external state)
-let counter = 0;
-'custom.increment': (value) => {
-  counter++; // Side effect!
-  return value;
-}
-
-// ✅ GOOD: Pure function
-'custom.incrementValue': (value) => {
-  return (value || 0) + 1;
-}
-```
-
-### 3. Handle Null/Undefined
-
-Always handle null/undefined gracefully:
-
-```typescript
-// ❌ BAD: Throws on null
-'custom.getLength': (value) => value.length // Throws if value is null
-
-// ✅ GOOD: Null-safe
-'custom.getLength': (value) => value?.length || 0
-```
-
-### 4. Use Helpers for Common Operations
-
-Don't reinvent the wheel—use helpers:
-
-```typescript
-// ❌ BAD: Manual parsing
-'custom.parsePrice': (value) => {
-  const num = parseFloat(value.replace(/[^0-9.]/g, ''));
-  return isNaN(num) ? 0 : num;
-}
-
-// ✅ GOOD: Use helper
-'custom.parsePrice': (value, sourceData, config, helpers) => {
-  return helpers.parseFloatSafe(value, 0);
-}
-```
-
-### 5. Document Custom Resolvers
-
-Add comments to explain complex logic:
-
-```typescript
-const customResolvers = {
-  /**
-   * Calculate item total: (price * qty) + tax + shipping
-   * Returns 0 if any values are invalid
-   */
-  'custom.calculateItemTotal': (value, sourceData, config, helpers) => {
-    const price = helpers.parseFloatSafe(sourceData.price, 0);
-    const qty = helpers.parseIntSafe(sourceData.quantity, 0);
-    const tax = helpers.parseFloatSafe(sourceData.tax, 0);
-    const shipping = helpers.parseFloatSafe(sourceData.shipping, 0);
-
-    return price * qty + tax + shipping;
-  },
-};
-```
-
-### 6. Use Logging for Debugging
-
-Use `helpers.logger` for debugging complex resolvers:
-
-```typescript
-'custom.mapOrderType': (value, sourceData, config, helpers) => {
-  helpers.logger?.debug('Mapping order type', {
-    inputValue: value,
-    sourceOrderType: sourceData.order_type
-  });
-
-  const mapped = orderTypeMapping[value] || 'HD';
-
-  helpers.logger?.debug('Mapped order type', {
-    input: value,
-    output: mapped
-  });
-
-  return mapped;
-}
-```
-
----
-
-## Performance Optimization
-
-### 1. Memoize Expensive Operations
-
-```typescript
-const expensiveCalculation = helpers.memoize((value) => {
-  // Complex calculation here
-  return result;
-});
-
-'custom.calculate': (value) => expensiveCalculation(value)
-```
-
-### 2. Cache API Lookups
-
-```typescript
-const cache = new Map();
-
-'custom.lookup': async (value, sourceData, config, helpers) => {
-  if (cache.has(value)) {
-    return cache.get(value);
-  }
-
-  const result = await apiCall(value);
-  cache.set(value, result);
-  return result;
-}
-```
-
-### 3. Batch Process Arrays
-
-```typescript
-'custom.processItems': async (value, sourceData, config, helpers) => {
-  const items = helpers.ensureArray(value);
-
-  // Process 100 items at a time
-  const results = await helpers.batchProcess(
-    items,
-    async (item) => await processItem(item),
-    100
-  );
-
-  return results;
-}
-```
-
-### 4. Avoid Nested Loops
-
-```typescript
-// ❌ BAD: O(n²) complexity
-'custom.findMatch': (value, sourceData) => {
-  for (const item of sourceData.items) {
-    for (const match of sourceData.matches) {
-      if (item.id === match.id) return match;
-    }
-  }
-}
-
-// ✅ GOOD: O(n) complexity
-'custom.findMatch': (value, sourceData, config, helpers) => {
-  const matchMap = new Map(sourceData.matches.map(m => [m.id, m]));
-  return matchMap.get(value);
-}
-```
-
----
-
-## Next Steps
-
-You've mastered all SDK resolvers and helper functions! Next:
-
-**Continue to:** [Module 7: API Reference →](../../auto-pagination/modules/auto-pagination-07-api-reference.md)
-
-Or explore:
-
-- [GraphQL Mutation Mapping Quick Reference](../graphql-mutation-mapping/graphql-mutation-mapping-quick-reference.md) - Comprehensive cheat sheet
-- [Examples](../examples/) - Complete working examples
-- [Module 5: Advanced Patterns](./mapping-05-advanced-patterns.md) - Review complex patterns
-
----
-
-## Additional Resources
-
-- [SDK Resolvers Source Code](../../../../src/services/resolvers/sdk-resolvers.ts)
-- [Resolver Engine Source](../../../../src/services/resolvers/resolver-engine.ts)
-- [Helper Functions Reference](../../../../src/services/resolvers/resolver-helpers.ts)
-
----
-
-[← Back to Index](../mapping-readme.md) | [Previous: Advanced Patterns](./mapping-05-advanced-patterns.md) | [Next: API Reference →](../../auto-pagination/modules/auto-pagination-07-api-reference.md)
-
-
-
-
-
-
-
-
-
+# Module 6: Helpers & Resolvers
+
+**Leverage 54 Built-in Utilities**
+
+**Level:** Advanced
+**Time:** 35 minutes
+**Prerequisites:** [Module 5: Advanced Patterns](./mapping-05-advanced-patterns.md)
+
+---
+
+## Learning Objectives
+
+After completing this module, you will:
+
+- ✅ Understand all 16 SDK resolvers
+- ✅ Use 57 helper functions in custom resolvers
+- ✅ Write efficient custom resolvers
+- ✅ Implement async resolvers for API lookups
+- ✅ Apply resolver best practices
+- ✅ Optimize resolver performance
+
+---
+
+## Table of Contents
+
+1. [SDK Resolvers Overview](#sdk-resolvers-overview)
+2. [String Resolvers](#string-resolvers)
+3. [Number Resolvers](#number-resolvers)
+4. [Date Resolvers](#date-resolvers)
+5. [Type Conversion Resolvers](#type-conversion-resolvers)
+6. [Utility Resolvers](#utility-resolvers)
+7. [Helper Functions Reference](#helper-functions-reference)
+8. [Custom Resolvers](#custom-resolvers)
+9. [Async Resolvers](#async-resolvers)
+10. [Best Practices](#best-practices)
+11. [Performance Optimization](#performance-optimization)
+
+---
+
+## SDK Resolvers Overview
+
+The SDK provides **16 built-in resolvers** for common transformations. All SDK resolvers:
+
+- ✅ Follow naming convention: `sdk.<functionName>`
+- ✅ Are null-safe (never throw errors)
+- ✅ Return safe defaults for invalid input
+- ✅ Work with all mappers (UniversalMapper, GraphQLMutationMapper)
+
+### Complete SDK Resolver List
+
+| Category    | Resolvers                              | Count |
+| ----------- | -------------------------------------- | ----- |
+| **String**  | uppercase, lowercase, trim, toString   | 4     |
+| **Number**  | parseInt, parseFloat, number           | 3     |
+| **Date**    | formatDate, formatDateShort, parseDate | 3     |
+| **Type**    | boolean, parseJson, toJson             | 3     |
+| **Utility** | identity, coalesce, default            | 3     |
+
+**Total**: 16 SDK resolvers
+
+### Accessing SDK Resolvers Programmatically (NEW)
+
+You can access SDK resolvers directly or test resolver names at runtime.
+
+```typescript
+import {
+  sdkResolvers,
+  getSdkResolver,
+  isSdkResolver,
+  getSdkResolverNames,
+  UniversalMapper,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Get all SDK resolver names
+const allResolvers = getSdkResolverNames();
+console.log(allResolvers);
+// SDK resolvers: ['sdk.uppercase', 'sdk.lowercase', 'sdk.trim', 'sdk.parseInt', ...]
+
+// Retrieve a resolver function by name
+const resolverFn = getSdkResolver('sdk.parseInt'); // (value) => number
+console.log(isSdkResolver('sdk.parseInt')); // true
+console.log(isSdkResolver('custom.myResolver')); // false
+
+// Use sdkResolvers inside custom resolvers
+const mapper = new UniversalMapper(mappingConfig, {
+  customResolvers: {
+    'custom.upperTrim': (value: any) => {
+      const upper = sdkResolvers\['sdk.uppercase'](value, null, null, {});
+      return sdkResolvers\['sdk.trim'](upper, null, null, {});
+    },
+  },
+});
+```
+
+**Utility Functions:**
+
+- `getSdkResolverNames()` - Returns array of all SDK resolver names (useful for validation, autocomplete)
+- `getSdkResolver(name)` - Returns resolver function by name or undefined
+- `isSdkResolver(name)` - Checks if a resolver name starts with 'sdk.'
+
+---
+
+## String Resolvers
+
+### sdk.uppercase
+
+Convert string to uppercase.
+
+**Use case**: Normalize SKU codes, status values, country codes
+
+```json
+{
+  "fields": {
+    "status": {
+      "source": "order_status",
+      "resolver": "sdk.uppercase"
+    }
+  }
+}
+```
+
+**Examples**:
+
+```typescript
+"active" → "ACTIVE"
+"pending" → "PENDING"
+123 → 123 (non-strings pass through)
+null → null (null-safe)
+```
+
+**Null-safe behavior**: Returns non-strings unchanged
+
+---
+
+### sdk.lowercase
+
+Convert string to lowercase.
+
+**Use case**: Normalize email addresses, usernames, tags
+
+```json
+{
+  "fields": {
+    "email": {
+      "source": "customer_email",
+      "resolver": "sdk.lowercase"
+    }
+  }
+}
+```
+
+**Examples**:
+
+```typescript
+"John@EXAMPLE.COM" → "john@example.com"
+"SKU-001" → "sku-001"
+123 → 123 (non-strings pass through)
+null → null (null-safe)
+```
+
+---
+
+### sdk.trim
+
+Remove leading and trailing whitespace.
+
+**Use case**: Clean CSV fields, remove spaces from user input
+
+```json
+{
+  "fields": {
+    "sku": {
+      "source": "product_code",
+      "resolver": "sdk.trim"
+    }
+  }
+}
+```
+
+**Examples**:
+
+```typescript
+"  SKU123  " → "SKU123"
+"\tSKU456\n" → "SKU456"
+"  " → "" (empty after trim)
+123 → 123 (non-strings pass through)
+```
+
+---
+
+### sdk.toString
+
+Convert value to string.
+
+**Use case**: Ensure value is string type, prevent "null" strings
+
+```json
+{
+  "fields": {
+    "productRef": {
+      "source": "product_id",
+      "resolver": "sdk.toString"
+    }
+  }
+}
+```
+
+**Examples**:
+
+```typescript
+123 → "123"
+true → "true"
+null → "" (empty string, NOT "null")
+undefined → "" (empty string, NOT "undefined")
+{ foo: "bar" } → "[object Object]"
+```
+
+**Critical**: Returns empty string for null/undefined (prevents literal "null"/"undefined" strings)
+
+---
+
+## Number Resolvers
+
+### sdk.parseInt
+
+Parse value as integer.
+
+**Use case**: Convert quantity strings to numbers, parse IDs
+
+```json
+{
+  "fields": {
+    "quantity": {
+      "source": "qty",
+      "resolver": "sdk.parseInt"
+    }
+  }
+}
+```
+
+**Examples**:
+
+```typescript
+"123" → 123
+"123.99" → 123 (truncates decimals)
+"$45" → 0 (invalid → default)
+"abc" → 0 (invalid → default)
+null → 0 (null-safe default)
+```
+
+**Important**: Returns `0` for invalid values (NOT `NaN`). This prevents breaking Fluent API calls.
+
+---
+
+### sdk.parseFloat
+
+Parse value as floating-point number.
+
+**Use case**: Convert price/weight strings to numbers
+
+```json
+{
+  "fields": {
+    "price": {
+      "source": "total_price",
+      "resolver": "sdk.parseFloat"
+    }
+  }
+}
+```
+
+**Examples**:
+
+```typescript
+"123.99" → 123.99
+"$45.50" → 45.5 (strips currency symbols)
+"1,234.56" → 1234.56 (removes commas)
+"  99.99  " → 99.99 (trims whitespace)
+"abc" → 0 (invalid → default)
+```
+
+**Advanced**: Handles currency symbols ($, €, £), commas, and whitespace automatically.
+
+---
+
+### sdk.number
+
+Parse value as number (alias for parseFloat).
+
+**Use case**: Generic number parsing when integer vs float doesn't matter
+
+```json
+{
+  "fields": {
+    "weight": {
+      "source": "product_weight",
+      "resolver": "sdk.number"
+    }
+  }
+}
+```
+
+Same behavior as `sdk.parseFloat`.
+
+---
+
+## Date Resolvers
+
+### sdk.formatDate
+
+Format date to ISO8601 (Fluent Commerce API format).
+
+**Use case**: Convert dates to Fluent API format
+
+```json
+{
+  "fields": {
+    "expectedOn": {
+      "source": "delivery_date",
+      "resolver": "sdk.formatDate"
+    }
+  }
+}
+```
+
+**Examples**:
+
+```typescript
+"2025-01-15" → "2025-01-15T00:00:00.000Z"
+"01/15/2025" → "2025-01-15T00:00:00.000Z"
+Date object → "2025-01-15T10:30:00.000Z"
+null → null (null-safe)
+"invalid" → "invalid" (passes through)
+```
+
+**Critical**: Fluent Commerce API requires ISO8601 format for date fields.
+
+---
+
+### sdk.formatDateShort
+
+Format date to YYYY-MM-DD (short format).
+
+**Use case**: Convert dates to short format for reports, CSV exports
+
+```json
+{
+  "fields": {
+    "orderDate": {
+      "source": "created_at",
+      "resolver": "sdk.formatDateShort"
+    }
+  }
+}
+```
+
+**Examples**:
+
+```typescript
+"2025-01-15T10:30:00Z" → "2025-01-15"
+Date object → "2025-01-15"
+"invalid" → "invalid" (invalid dates pass through)
+null → null (null-safe)
+```
+
+**Note**: Strips time component—useful for date-only fields.
+
+---
+
+### sdk.parseDate
+
+Parse various date formats to Date object.
+
+**Use case**: Convert multiple date formats to standardized Date
+
+```json
+{
+  "fields": {
+    "orderDate": {
+      "source": "order_date",
+      "resolver": "sdk.parseDate"
+    }
+  }
+}
+```
+
+**Examples**:
+
+```typescript
+"2025-01-15" → Date("2025-01-15T00:00:00.000Z")
+"01/15/2025" → Date (US format)
+"15/01/2025" → Date (EU format)
+1737763200000 → Date (Unix timestamp)
+null → null (null-safe)
+```
+
+**Handles**: ISO8601, US format, EU format, Unix timestamps.
+
+---
+
+## Type Conversion Resolvers
+
+### sdk.boolean
+
+Convert value to boolean.
+
+**Use case**: Parse boolean flags from CSV, XML
+
+```json
+{
+  "fields": {
+    "isActive": {
+      "source": "active_flag",
+      "resolver": "sdk.boolean"
+    }
+  }
+}
+```
+
+**Examples**:
+
+```typescript
+"true" → true
+"false" → false
+"1" → true
+"0" → false
+"yes" → true
+"no" → false
+"y" → true
+"n" → false
+"TRUE" → true (case-insensitive)
+"True" → true
+null → false (null-safe)
+undefined → false
+```
+
+**Case-insensitive**: "TRUE", "True", "true" all return `true`.
+
+---
+
+### sdk.parseJson
+
+Parse JSON string to object.
+
+**Use case**: Parse JSON-encoded fields from CSV, XML attributes
+
+```json
+{
+  "fields": {
+    "metadata": {
+      "source": "custom_data",
+      "resolver": "sdk.parseJson"
+    }
+  }
+}
+```
+
+**Examples**:
+
+```typescript
+'{"name":"John","age":30}' → { name: "John", age: 30 }
+'["a","b","c"]' → ["a", "b", "c"]
+"invalid json" → "invalid json" (passes through)
+123 → 123 (non-strings pass through)
+```
+
+**Null-safe**: Returns original value if parse fails (never throws).
+
+---
+
+### sdk.toJson
+
+Stringify value as JSON.
+
+**Use case**: Convert objects to JSON strings for storage in text fields
+
+```json
+{
+  "fields": {
+    "customAttributes": {
+      "source": "attributes_obj",
+      "resolver": "sdk.toJson"
+    }
+  }
+}
+```
+
+**Examples**:
+
+```typescript
+{ name: "John" } → '{"name":"John"}'
+["a", "b", "c"] → '["a","b","c"]'
+123 → "123"
+"string" → '"string"' (double-quoted)
+```
+
+**Use case**: Storing complex objects in Fluent Commerce custom attributes.
+
+---
+
+## Utility Resolvers
+
+### sdk.identity
+
+Return value unchanged (no-op resolver).
+
+**Use case**: Explicitly pass value through without transformation
+
+```json
+{
+  "fields": {
+    "ref": {
+      "source": "order_id",
+      "resolver": "sdk.identity"
+    }
+  }
+}
+```
+
+**Why this exists**: Some mapping scenarios require a resolver to be specified, but no transformation is needed.
+
+---
+
+### sdk.coalesce
+
+Return first non-null value.
+
+**Use case**: Provide fallback when value is null/undefined
+
+```json
+{
+  "fields": {
+    "email": {
+      "source": "primary_email",
+      "resolver": "sdk.coalesce",
+      "defaultValue": "noreply@example.com"
+    }
+  }
+}
+```
+
+**Note**: Typically handled by mapping engine checking `defaultValue`. This resolver exists for complex scenarios.
+
+---
+
+### sdk.default
+
+Use the `defaultValue` field configuration property instead.
+
+This resolver provides default value if source is null/undefined/empty, but `defaultValue` in field config is the preferred approach.
+
+```json
+{
+  "fields": {
+    "status": {
+      "source": "order_status",
+      "defaultValue": "ACTIVE",
+      "resolver": "sdk.default"
+    }
+  }
+}
+```
+
+**Note**: The `defaultValue` field configuration property is preferred. This resolver applies after `config.defaultValue` is processed.
+
+**Examples**:
+
+```typescript
+"PENDING" → "PENDING" (value exists, pass through)
+null → null (defaultValue applied by mapper before resolver)
+undefined → undefined (defaultValue applied by mapper before resolver)
+```
+
+**Note**: Prefer using the `defaultValue` field configuration property instead of this resolver.
+
+---
+
+## Helper Functions Reference
+
+Custom resolvers receive a `helpers` object with 57 utility functions.
+
+### Resolver Signature
+
+```typescript
+(value: any, sourceData: any, config: any, helpers: ResolverHelpers) => any | Promise<any>;
+```
+
+**Parameters**:
+
+1. `value` - The extracted field value (may be undefined for generator resolvers)
+2. `sourceData` - The complete source object (for context-aware transformations)
+3. `config` - Resolver-specific configuration object
+4. `helpers` - 57 utility functions
+
+### Helper Categories
+
+| Category                | Count | Examples                                                |
+| ----------------------- | ----- | ------------------------------------------------------- |
+| **Data Access**         | 4     | get, set, ensureArray, coalesce                         |
+| **String Manipulation** | 8     | toCamelCase, toSnakeCase, truncate, normalizeWhitespace |
+| **Number Operations**   | 3     | parseIntSafe, parseFloatSafe, formatCurrency            |
+| **Date/Time**           | 4     | formatDate, parseDate, addDays, subtractDays            |
+| **Validation**          | 3     | isValidEmail, requireField, isEmpty                     |
+| **Object Utilities**    | 6     | deepClone, deepMerge, pick, omit, merge, template       |
+| **Array Operations**    | 9     | unique, groupBy, sortBy, chunk, flatten, compact, sum, avg, min |
+| **Performance**         | 3     | memoize, batchProcess, retry                            |
+| **Type Guards**         | 5     | isString, isNumber, isArray, isObject, isDate           |
+| **Utilities**           | 9     | defaultTo, range, clamp, slugify, uuid, hashString, debounce, throttle, safeJsonParse |
+
+**Total**: 57 helpers
+
+### Core Data Access Helpers
+
+```typescript
+helpers.get(obj, 'customer.address.city'); // Safe nested access
+helpers.set(obj, 'customer.address.city', 'NYC'); // Safe nested set
+helpers.ensureArray(value); // Wrap singles in array
+helpers.coalesce(val1, val2, val3); // First non-null
+```
+
+### String Helpers
+
+```typescript
+helpers.toCamelCase('first_name'); // → "firstName"
+helpers.toSnakeCase('firstName'); // → "first_name"
+helpers.truncate('Long text...', 10); // → "Long te..."
+helpers.normalizeWhitespace('  a  b  '); // → "a b"
+helpers.fullName('John', 'Doe'); // → "John Doe"
+```
+
+### Number Helpers
+
+```typescript
+helpers.parseIntSafe('123', 0); // → 123 (or default 0)
+helpers.parseFloatSafe('$99.99', 0); // → 99.99
+helpers.formatCurrency(99.99, 2); // → "99.99"
+```
+
+### Date Helpers
+
+```typescript
+helpers.formatDate('2025-01-15'); // → ISO8601
+helpers.parseDate('01/15/2025'); // → Date object
+helpers.addDays(new Date(), 7); // → Date + 7 days
+helpers.diffDays(date1, date2); // → number of days
+```
+
+### Validation Helpers
+
+```typescript
+helpers.isValidEmail('test@example.com'); // → true
+helpers.requireField(value, 'email'); // Throws if null
+helpers.isEmpty(value); // → true if null/undefined/empty
+```
+
+### Object Helpers
+
+```typescript
+helpers.deepClone(obj); // Deep copy
+helpers.deepMerge(obj1, obj2); // Merge objects
+helpers.pick(obj, ['name', 'email']); // Extract fields
+helpers.omit(obj, ['password']); // Remove fields
+helpers.flatten(nestedObj); // Flatten to dot notation
+```
+
+### Array Helpers
+
+```typescript
+helpers.unique([1, 2, 2, 3]); // → [1, 2, 3]
+helpers.groupBy(items, 'category'); // Group by field
+helpers.sortBy(items, 'name'); // Sort by field
+helpers.chunk([1, 2, 3, 4, 5], 2); // → [[1,2], [3,4], [5]]
+helpers.findBy(items, 'id', '123'); // Find by field value
+```
+
+### Performance Helpers
+
+```typescript
+await helpers.retry(() => apiCall(), 3, 1000); // Retry with backoff
+await helpers.batchProcess(items, processFn, 100); // Process in batches
+const memoized = helpers.memoize(expensiveFn); // Cache results
+```
+
+### Utilities
+
+```typescript
+const hash = helpers.hashString('data'); // Simple hash
+const id = helpers.uuid(); // Generate UUID
+const slug = helpers.slugify('Product Name'); // → "product-name"
+helpers.debounce(fn, 300); // Debounce function calls
+helpers.throttle(fn, 1000); // Throttle function calls
+```
+
+---
+
+## Custom Resolvers
+
+### Basic Custom Resolver
+
+```typescript
+const customResolvers = {
+  'custom.buildRef': (value, sourceData, config, helpers) => {
+    const sku = sourceData.sku;
+    const location = sourceData.location;
+    return `${sku}-${location}`;
+  },
+};
+
+// Use in mapping
+const mapper = new UniversalMapper(mappingConfig, { customResolvers });
+```
+
+### Using Helpers in Custom Resolvers
+
+```typescript
+const customResolvers = {
+  'custom.formatCustomerName': (value, sourceData, config, helpers) => {
+    const firstName = helpers.get(sourceData, 'customer.firstName');
+    const lastName = helpers.get(sourceData, 'customer.lastName');
+    return helpers.fullName(firstName, lastName);
+  },
+
+  'custom.calculateTotal': (value, sourceData, config, helpers) => {
+    const price = helpers.parseFloatSafe(sourceData.price, 0);
+    const qty = helpers.parseIntSafe(sourceData.quantity, 0);
+    const tax = helpers.parseFloatSafe(sourceData.tax, 0);
+    return price * qty + tax;
+  },
+
+  'custom.normalizeEmail': (value, sourceData, config, helpers) => {
+    if (!value || typeof value !== 'string') return null;
+
+    const email = helpers.normalizeWhitespace(value.toLowerCase().trim());
+
+    if (!helpers.isValidEmail(email)) {
+      helpers.logger?.warn('Invalid email', { email });
+      return null;
+    }
+
+    return email;
+  },
+};
+```
+
+### Context-Aware Resolvers
+
+```typescript
+const customResolvers = {
+  'custom.mapOrderType': (value, sourceData, config, helpers) => {
+    // Access shared configuration from context
+    const environment = helpers.context.environment || 'production';
+
+    const mapping: Record<string, string> = {
+      online: 'HD', // Home Delivery
+      store: 'CC', // Click & Collect
+    };
+
+    const orderType = mapping[value] || 'HD';
+
+    // In non-production, append test suffix
+    if (environment !== 'production') {
+      return `${orderType}_TEST`;
+    }
+
+    return orderType;
+  },
+};
+
+// Pass context when mapping
+const mapper = new UniversalMapper(mappingConfig, {
+  customResolvers,
+  fluentClient: client,
+});
+const result = await mapper.map(data);
+```
+
+---
+
+## Async Resolvers
+
+Custom resolvers can be asynchronous for external API calls, database lookups, etc.
+
+### Async Lookup Example
+
+```typescript
+const customResolvers = {
+  'custom.lookupCustomer': async (value, sourceData, config, helpers) => {
+    const email = sourceData.customer_email;
+
+    if (!email) {
+      return null;
+    }
+
+    // Query Fluent API for existing customer
+    const result = await helpers.fluentClient.graphql({
+      query: `
+        query GetCustomer($email: String) {
+          customers(primaryEmail: $email, first: 1) {
+            edges {
+              node {
+                id
+                username
+              }
+            }
+          }
+        }
+      `,
+      variables: { email },
+    });
+
+    const existingCustomer = result?.customers?.edges?.[0]?.node;
+
+    if (existingCustomer) {
+      helpers.logger?.info('Found existing customer', { customerId: existingCustomer.id });
+      return existingCustomer.id;
+    }
+
+    // Customer not found - create new
+    const createResult = await helpers.fluentClient.graphql({
+      query: `
+        mutation CreateCustomer($input: CreateCustomerInput!) {
+          createCustomer(input: $input) {
+            id
+          }
+        }
+      `,
+      variables: {
+        input: {
+          username: email,
+          primaryEmail: email,
+          firstName: sourceData.first_name || 'Guest',
+          lastName: sourceData.last_name || 'Customer',
+          retailer: { id: '2' },
+        },
+      },
+    });
+
+    helpers.logger?.info('Created new customer', { customerId: createResult.id });
+
+    return createResult.id;
+  },
+};
+```
+
+**Important**: When using async resolvers, you must `await` the mapping:
+
+```typescript
+const result = await mapper.map(data, {
+  fluentClient: client,
+  helpers: { fluentClient: client },
+});
+```
+
+### Async with Retry
+
+```typescript
+const customResolvers = {
+  'custom.fetchProductPrice': async (value, sourceData, config, helpers) => {
+    const sku = sourceData.sku;
+
+    // Retry API call up to 3 times with 1s delay
+    const price = await helpers.retry(
+      async () => {
+        const response = await fetch(`https://api.example.com/products/${sku}/price`);
+
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}`);
+        }
+
+        const data = await response.json();
+        return data.price;
+      },
+      3,
+      1000
+    );
+
+    return price;
+  },
+};
+```
+
+### Batch Processing (Performance Optimization)
+
+```typescript
+// ❌ BAD: Sequential API calls (slow for 1000 records)
+'custom.lookupCustomerSlow': async (value, sourceData, config, helpers) => {
+  const email = sourceData.email;
+  const result = await helpers.fluentClient.graphql({ query, variables: { email } });
+  return result?.customers?.edges?.[0]?.node?.id;
+}
+
+// ✅ GOOD: Batch cache to reduce API calls
+const customerCache = new Map();
+
+const customResolvers = {
+  'custom.lookupCustomerFast': async (value, sourceData, config, helpers) => {
+    const email = sourceData.email;
+
+    // Check cache first
+    if (customerCache.has(email)) {
+      return customerCache.get(email);
+    }
+
+    // Query API
+    const result = await helpers.fluentClient.graphql({
+      query,
+      variables: { email }
+    });
+
+    const customerId = result?.customers?.edges?.[0]?.node?.id;
+
+    // Cache result
+    customerCache.set(email, customerId);
+
+    return customerId;
+  }
+};
+```
+
+---
+
+## Best Practices
+
+### 1. Use SDK Resolvers First
+
+Before writing custom resolvers, check if SDK resolvers can handle the transformation:
+
+```typescript
+// ❌ NOT NEEDED
+'custom.toUppercase': (value) => value?.toUpperCase()
+
+// ✅ USE SDK RESOLVER
+{ "resolver": "sdk.uppercase" }
+```
+
+### 2. Keep Resolvers Pure
+
+Resolvers should be pure functions (same input → same output, no side effects):
+
+```typescript
+// ❌ BAD: Side effects (modifies external state)
+let counter = 0;
+'custom.increment': (value) => {
+  counter++; // Side effect!
+  return value;
+}
+
+// ✅ GOOD: Pure function
+'custom.incrementValue': (value) => {
+  return (value || 0) + 1;
+}
+```
+
+### 3. Handle Null/Undefined
+
+Always handle null/undefined gracefully:
+
+```typescript
+// ❌ BAD: Throws on null
+'custom.getLength': (value) => value.length // Throws if value is null
+
+// ✅ GOOD: Null-safe
+'custom.getLength': (value) => value?.length || 0
+```
+
+### 4. Use Helpers for Common Operations
+
+Don't reinvent the wheel—use helpers:
+
+```typescript
+// ❌ BAD: Manual parsing
+'custom.parsePrice': (value) => {
+  const num = parseFloat(value.replace(/[^0-9.]/g, ''));
+  return isNaN(num) ? 0 : num;
+}
+
+// ✅ GOOD: Use helper
+'custom.parsePrice': (value, sourceData, config, helpers) => {
+  return helpers.parseFloatSafe(value, 0);
+}
+```
+
+### 5. Document Custom Resolvers
+
+Add comments to explain complex logic:
+
+```typescript
+const customResolvers = {
+  /**
+   * Calculate item total: (price * qty) + tax + shipping
+   * Returns 0 if any values are invalid
+   */
+  'custom.calculateItemTotal': (value, sourceData, config, helpers) => {
+    const price = helpers.parseFloatSafe(sourceData.price, 0);
+    const qty = helpers.parseIntSafe(sourceData.quantity, 0);
+    const tax = helpers.parseFloatSafe(sourceData.tax, 0);
+    const shipping = helpers.parseFloatSafe(sourceData.shipping, 0);
+
+    return price * qty + tax + shipping;
+  },
+};
+```
+
+### 6. Use Logging for Debugging
+
+Use `helpers.logger` for debugging complex resolvers:
+
+```typescript
+'custom.mapOrderType': (value, sourceData, config, helpers) => {
+  helpers.logger?.debug('Mapping order type', {
+    inputValue: value,
+    sourceOrderType: sourceData.order_type
+  });
+
+  const mapped = orderTypeMapping[value] || 'HD';
+
+  helpers.logger?.debug('Mapped order type', {
+    input: value,
+    output: mapped
+  });
+
+  return mapped;
+}
+```
+
+---
+
+## Performance Optimization
+
+### 1. Memoize Expensive Operations
+
+```typescript
+const expensiveCalculation = helpers.memoize((value) => {
+  // Complex calculation here
+  return result;
+});
+
+'custom.calculate': (value) => expensiveCalculation(value)
+```
+
+### 2. Cache API Lookups
+
+```typescript
+const cache = new Map();
+
+'custom.lookup': async (value, sourceData, config, helpers) => {
+  if (cache.has(value)) {
+    return cache.get(value);
+  }
+
+  const result = await apiCall(value);
+  cache.set(value, result);
+  return result;
+}
+```
+
+### 3. Batch Process Arrays
+
+```typescript
+'custom.processItems': async (value, sourceData, config, helpers) => {
+  const items = helpers.ensureArray(value);
+
+  // Process 100 items at a time
+  const results = await helpers.batchProcess(
+    items,
+    async (item) => await processItem(item),
+    100
+  );
+
+  return results;
+}
+```
+
+### 4. Avoid Nested Loops
+
+```typescript
+// ❌ BAD: O(n²) complexity
+'custom.findMatch': (value, sourceData) => {
+  for (const item of sourceData.items) {
+    for (const match of sourceData.matches) {
+      if (item.id === match.id) return match;
+    }
+  }
+}
+
+// ✅ GOOD: O(n) complexity
+'custom.findMatch': (value, sourceData, config, helpers) => {
+  const matchMap = new Map(sourceData.matches.map(m => [m.id, m]));
+  return matchMap.get(value);
+}
+```
+
+---
+
+## Next Steps
+
+You've mastered all SDK resolvers and helper functions! Next:
+
+**Continue to:** [Module 7: API Reference →](../../auto-pagination/modules/auto-pagination-07-api-reference.md)
+
+Or explore:
+
+- [GraphQL Mutation Mapping Quick Reference](../graphql-mutation-mapping/graphql-mutation-mapping-quick-reference.md) - Comprehensive cheat sheet
+- [Examples](../examples/) - Complete working examples
+- [Module 5: Advanced Patterns](./mapping-05-advanced-patterns.md) - Review complex patterns
+
+---
+
+## Additional Resources
+
+- [SDK Resolvers Source Code](../../../../src/services/resolvers/sdk-resolvers.ts)
+- [Resolver Engine Source](../../../../src/services/resolvers/resolver-engine.ts)
+- [Helper Functions Reference](../../../../src/services/resolvers/resolver-helpers.ts)
+
+---
+
+[← Back to Index](../mapping-readme.md) | [Previous: Advanced Patterns](./mapping-05-advanced-patterns.md) | [Next: API Reference →](../../auto-pagination/modules/auto-pagination-07-api-reference.md)
+
+
+
+
+
+
+
+
+