@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/mapping/modules/mapping-07-api-reference.md

@@ -1,1319 +1,1319 @@
-# Module 7: API Reference
-
-**Complete Technical Reference**
-
-**Level:** Reference
-**Time:** As needed
-**Prerequisites:** Modules 1-6
-
----
-
-## Table of Contents
-
-1. [TypeScript Type Definitions](#typescript-type-definitions)
-2. [Configuration Migration](#configuration-migration)
-3. [Performance Tips](#performance-tips)
-4. [FAQ](#faq)
-5. [Troubleshooting](#troubleshooting)
-6. [Best Practices](#best-practices)
-7. [Cheat Sheet](#cheat-sheet)
-
----
-
-## TypeScript Type Definitions
-
-### MappingConfig
-
-Complete mapping configuration structure:
-
-```typescript
-interface MappingConfig {
-  /** Direction of mapping */
-  direction: 'ingest' | 'extract';
-
-  /** Source data format (for context) */
-  sourceFormat?: 'csv' | 'xml' | 'json' | 'parquet';
-
-  /** GraphQL mutation name (for ingest direction) */
-  mutation?: string;
-
-  /** GraphQL query name (for extract direction) */
-  query?: string;
-
-  /** Nodes configuration for nested/escaped data */
-  nodes?: Record<string, NodeConfig>;
-
-  /** Field mappings */
-  fields: Record<string, FieldConfig>;
-
-  /** Return fields for GraphQL mutation (defaults to ['id', 'ref']) */
-  returnFields?: string[];
-}
-```
-
-### FieldConfig
-
-Individual field configuration:
-
-```typescript
-interface FieldConfig {
-  /** Source field path (supports dot notation, array indices, XML attributes) */
-  source?: string;
-
-  /** Static value (alternative to source) */
-  value?: any;
-
-  /** Default value if source is null/undefined */
-  defaultValue?: any;
-
-  /** Resolver function name (sdk.* or custom.*) */
-  resolver?: string;
-
-  /** Whether field is required (throws if missing). 
-   * 
-   * **Validation Timing:**
-   * - Fields with `source`: Validated BEFORE resolver execution
-   * - Resolver-only fields (no source): Validated AFTER resolver execution
-   * 
-   * **Behavior:**
-   * - `required: true`: Mapping stops immediately if field is missing/empty, returns `success: false`
-   * - `required: false` or omitted: Mapping continues with warning, field omitted from output
-   * 
-   * **Important:** Resolvers can return `null`, `undefined`, or empty strings. 
-   * `required: true` validates AFTER resolver execution to catch these cases.
-   * 
-   * **Examples:**
-   * ```json
-   * // Source field - validates before resolver
-   * { "source": "sku", "resolver": "sdk.trim", "required": true }
-   * 
-   * // Resolver-only - validates after resolver
-   * { "resolver": "custom.generateUUID", "required": true }
-   * ```
-   */
-  required?: boolean;
-
-  /** Nested object fields */
-  fields?: Record<string, FieldConfig>;
-
-  /** Array configuration */
-  isArray?: boolean;
-
-  /** Comment for documentation */
-  comment?: string;
-}
-```
-
-### NodeConfig
-
-Configuration for extracting nested/escaped data:
-
-```typescript
-interface NodeConfig {
-  /** Path to extract data from source */
-  extract: string;
-
-  /** How to parse extracted data */
-  parse: 'xml' | 'json';
-
-  /** Optional schema validation */
-  schema?: string;
-}
-```
-
-### ResolverFunction
-
-Custom resolver function signature:
-
-```typescript
-type ResolverFunction = (
-  value: any, // Extracted field value
-  sourceData: any, // Complete source object
-  config: any, // Resolver configuration
-  helpers: ResolverHelpers // 54 helper functions
-) => any | Promise<any>; // Transformed value (can be async)
-```
-
-### ResolverHelpers
-
-Helper functions available in custom resolvers:
-
-```typescript
-interface ResolverHelpers {
-  /** Fluent client instance (if available) */
-  fluentClient?: any;
-
-  /** Logger instance */
-  logger?: any;
-
-  /** Path resolution helper */
-  get: (obj: any, path: string, defaultValue?: any) => any;
-
-  /** Set value at path */
-  set: (obj: any, path: string, value: any) => void;
-
-  /** Array normalization helper */
-  ensureArray: <T>(val: T | T[] | null | undefined) => T[];
-
-  /** Safe number parsing */
-  parseIntSafe: (value: any, defaultValue?: number) => number;
-  parseFloatSafe: (value: any, defaultValue?: number) => number;
-
-  /** Safe JSON parsing */
-  safeJsonParse: (json: string, defaultValue?: any) => any;
-
-  /** Date formatting */
-  formatDate: (date: string | Date) => string;
-  parseDate: (value: any) => Date | null;
-
-  /** String utilities */
-  toCamelCase: (str: string) => string;
-  toSnakeCase: (str: string) => string;
-  truncate: (str: string, maxLength: number) => string;
-  normalizeWhitespace: (str: string) => string;
-  fullName: (firstName?: string, lastName?: string) => string;
-
-  /** Validation */
-  isValidEmail: (email: string) => boolean;
-  requireField: (value: any, fieldName: string) => void;
-  isEmpty: (value: any) => boolean;
-  isUrl: (url: string) => boolean;
-
-  /** Object utilities */
-  deepClone: <T>(obj: T) => T;
-  deepMerge: (target: any, source: any) => any;
-  pick: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Pick<T, K>;
-  omit: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Omit<T, K>;
-  flatten: (obj: any, prefix?: string) => Record<string, any>;
-
-  /** Array utilities */
-  unique: <T>(arr: T[]) => T[];
-  groupBy: <T>(arr: T[], key: string) => Record<string, T[]>;
-  sortBy: <T>(arr: T[], key: string) => T[];
-  chunk: <T>(arr: T[], size: number) => T[][];
-  findBy: <T>(arr: T[], key: string, value: any) => T | undefined;
-
-  /** Async utilities */
-  retry: <T>(fn: () => Promise<T>, maxRetries?: number, delayMs?: number) => Promise<T>;
-  batchProcess: <T, R>(
-    items: T[],
-    processor: (item: T) => Promise<R>,
-    batchSize?: number
-  ) => Promise<R[]>;
-  sleep: (ms: number) => Promise<void>;
-  timeout: <T>(promise: Promise<T>, ms: number) => Promise<T>;
-
-  /** Performance */
-  memoize: <T extends (...args: any[]) => any>(fn: T) => T;
-  hash: (data: string) => string;
-  uuid: () => string;
-
-  /** Context */
-  context: Record<string, any>;
-
-  /** Additional custom helpers */
-  [key: string]: any;
-}
-```
-
-### MapResult
-
-Result from UniversalMapper.map():
-
-```typescript
-interface MapResult {
-  /** Whether mapping succeeded */
-  success: boolean;
-
-  /** Mapped data */
-  data: Record<string, any>;
-
-  /** Error messages (if any) */
-  errors?: string[];
-
-  /** Warning messages (non-blocking) */
-  warnings?: string[];
-}
-```
-
----
-
-## Configuration Format
-
-**Field mapping format:**
-
-```json
-{
-  "fields": {
-    "productRef": {
-      "source": "sku",
-      "resolver": "sdk.uppercase"
-    },
-    "quantity": {
-      "source": "qty",
-      "resolver": "sdk.parseInt"
-    }
-  }
-}
-```
-
----
-
-## Field Configuration Edge Cases & Best Practices
-
-### ⚠️ Important Field Property Combinations
-
-Understanding how field properties interact is critical for correct mapping behavior.
-
----
-
-#### ✅ Resolver-Only Fields with `required: true`
-
-**New in SDK v0.1.37:** Resolver-only fields can now be required.
-
-**Pattern:**
-```json
-{
-  "id": {
-    "resolver": "custom.generateUUID",
-    "required": true
-  }
-}
-```
-
-**When to use:**
-- Generate unique IDs (UUID, composite keys)
-- Look up values from external APIs
-- Derive values from multiple source fields
-- Apply complex business logic
-
-**Validation behavior:**
-- Required validation runs AFTER resolver execution
-- Resolver must return a non-empty value
-- If resolver returns null/undefined/'', mapping fails
-
-**Example:**
-```typescript
-const mapper = new UniversalMapper(
-  {
-    fields: {
-      transactionId: {
-        resolver: 'custom.generateTransactionId',
-        required: true,
-      },
-    },
-  },
-  {
-    customResolvers: {
-      'custom.generateTransactionId': (value, sourceData, config, helpers) => {
-        return `TXN-${Date.now()}-${helpers.uuid()}`;
-      },
-    },
-  }
-);
-```
-
-📖 **Learn more:** [Resolver-Only Fields Guide](../resolvers/mapping-resolvers-resolver-guide.md#resolver-only-fields--required-validation)
-
----
-
-#### ⚠️ `required: true` + `defaultValue` (Contradictory)
-
-**Status:** ⚠️ This combination is semantically contradictory for source fields.
-
-**Problem:**
-```json
-{
-  "status": {
-    "source": "orderStatus",
-    "required": true,
-    "defaultValue": "PENDING"  // ❌ Never used!
-  }
-}
-```
-
-**Behavior:**
-1. Extract from source → `undefined` (missing)
-2. Validate required → ❌ Throws error immediately
-3. Apply defaultValue → ❌ Never reached
-
-**Why this doesn't work:**
-- Required validation happens BEFORE defaultValue application for source fields
-- DefaultValue is never applied because required fails first
-
-**Important:** The order for `source + resolver + defaultValue + required` is:
-1. Extract from source → `undefined`
-2. Validate required → ❌ Fails immediately (defaultValue never applied)
-3. Apply defaultValue → ❌ Never reached
-4. Run resolver → ❌ Never reached
-
-The code includes a warning when this combination is detected (see console output).
-
-**Solution:**
-```json
-// ✅ CORRECT - Optional field with default
-{
-  "status": {
-    "source": "orderStatus",
-    "required": false,  // or omit required
-    "defaultValue": "PENDING"
-  }
-}
-
-// ✅ CORRECT - Required field without default
-{
-  "status": {
-    "source": "orderStatus",
-    "required": true
-  }
-}
-```
-
----
-
-#### ✅ `defaultValue` + `resolver` (Works, but order matters)
-
-**Pattern:**
-```json
-{
-  "status": {
-    "source": "orderStatus",
-    "defaultValue": "pending",
-    "resolver": "sdk.uppercase"
-  }
-}
-```
-
-**Behavior:**
-1. Extract from source → `undefined` (missing)
-2. Apply defaultValue → `"pending"`
-3. Apply resolver → `"PENDING"`
-
-**Key insight:** Resolver receives the defaultValue, not the missing source value.
-
-**Real-world example:**
-```json
-{
-  "attributes.condition": {
-    "source": "condition",
-    "defaultValue": "NEW",
-    "resolver": "sdk.uppercase",
-    "required": false
-  }
-}
-// Missing source → "NEW" → "NEW" (already uppercase)
-// Empty source → "NEW" → "NEW"
-// Source "used" → "USED" → "USED"
-```
-
----
-
-#### ✅ `required: true` + `value` (Redundant but harmless)
-
-**Pattern:**
-```json
-{
-  "type": {
-    "value": "STANDARD",
-    "required": true  // ⚠️ Redundant
-  }
-}
-```
-
-**Behavior:**
-- Static values are always present
-- Required validation always passes
-- `required: true` has no effect but doesn't hurt
-
-**Recommendation:**
-```json
-// ✅ BETTER - Omit redundant required
-{
-  "type": {
-    "value": "STANDARD"
-  }
-}
-```
-
----
-
-#### ✅ Empty String Handling
-
-**Behavior:** Empty string (`''`) is treated as "missing" for:
-- Required validation
-- DefaultValue application
-
-**Example:**
-```json
-{
-  "status": {
-    "source": "orderStatus",  // = ""
-    "defaultValue": "PENDING",
-    "required": false
-  }
-}
-// Result: "PENDING" (empty string triggers default)
-```
-
-**Validation:**
-```typescript
-// Empty string fails required validation
-if (value === null || value === undefined || value === '')
-
-// Empty string triggers defaultValue
-if ((value === null || value === undefined || value === '') && config.defaultValue !== undefined)
-```
-
----
-
-### 📋 Field Property Combinations Summary
-
-| Combination | Status | Behavior |
-|-------------|--------|----------|
-| `source` + `required: true` | ✅ Correct | Validates before resolver, fails if missing |
-| `resolver` + `required: true` (no source) | ✅ Correct | Validates after resolver, fails if empty |
-| `source` + `resolver` + `required: true` | ✅ Correct | Validates source, then applies resolver |
-| `required: true` + `defaultValue` (source only) | ❌ Contradictory | Required fails before default applied |
-| `source` + `resolver` + `defaultValue` + `required: true` | ❌ Contradictory | Required fails before default applied (same as above) |
-| `defaultValue` + `resolver` | ✅ Works | Resolver receives default if source missing |
-| `value` + `required: true` | ⚠️ Redundant | Works but required is unnecessary |
-| `value` + `source` | ❌ Invalid | value takes precedence, source ignored |
-| `value` + `resolver` | ✅ Works | Resolver transforms static value |
-
----
-
-### 🎯 Best Practices
-
-**1. ✅ DO: Use `required: true` for mandatory source fields**
-```json
-{ "source": "sku", "required": true }
-```
-
-**2. ✅ DO: Use `defaultValue` for optional fields**
-```json
-{ "source": "status", "defaultValue": "ACTIVE", "required": false }
-```
-
-**3. ✅ DO: Use resolver-only for generated values**
-```json
-{ "resolver": "custom.generateId", "required": true }
-```
-
-**4. ❌ DON'T: Combine `required: true` with `defaultValue`**
-```json
-// ❌ Contradictory - default will never be used
-{ "source": "field", "required": true, "defaultValue": "FALLBACK" }
-```
-
-**5. ⚠️ CAUTION: `defaultValue` + `resolver` - default is passed to resolver**
-```json
-// Resolver receives "NEW" if source missing
-{ "source": "condition", "defaultValue": "NEW", "resolver": "sdk.uppercase" }
-```
-
----
-
-### From Old Transformer System
-
-**Old transformers → New resolvers:**
-
-| Old Transformer | New Resolver     |
-| --------------- | ---------------- |
-| `uppercase`     | `sdk.uppercase`  |
-| `lowercase`     | `sdk.lowercase`  |
-| `parseInt`      | `sdk.parseInt`   |
-| `parseFloat`    | `sdk.parseFloat` |
-| `formatDate`    | `sdk.formatDate` |
-| `boolean`       | `sdk.boolean`    |
-| `toJson`        | `sdk.toJson`     |
-| `parseJson`     | `sdk.parseJson`  |
-
-### Migration Steps
-
-1. **Identify mapping format**:
-   - Check for `fieldMappings` array
-   - Check for `transformer` property
-   - Check for field names
-
-2. **Convert to universal mapping format**:
-   - Replace `fieldMappings` with `fields` object
-   - Replace `sourceField` + `targetField` with nested structure
-   - Replace `transformer` with `resolver`
-   - Add `sdk.` prefix to resolver names
-
-3. **Validate against schema**:
-
-   ```bash
-   fc-connect-validate-schema --mapping config/new-mapping.json --schema schema.json
-   ```
-
-4. **Test with sample data**:
-   ```typescript
-   const mapper = new UniversalMapper(newConfig);
-   const result = await mapper.map(sampleData);
-   console.log('Migration result:', result);
-   ```
-
-### Example Migration
-
-**Before** (old format):
-
-```json
-{
-  "fieldMappings": [
-    {
-      "sourceField": "customer_email",
-      "targetField": "customer.email",
-      "transformer": "lowercase",
-      "required": true
-    },
-    {
-      "sourceField": "order_total",
-      "targetField": "totalPrice",
-      "transformer": "parseFloat"
-    },
-    {
-      "sourceField": "status",
-      "targetField": "status",
-      "transformer": "uppercase",
-      "defaultValue": "PENDING"
-    }
-  ]
-}
-```
-
-**After** (new format):
-
-```json
-{
-  "direction": "ingest",
-  "fields": {
-    "customer.email": {
-      "source": "customer_email",
-      "resolver": "sdk.lowercase",
-      "required": true
-    },
-    "totalPrice": {
-      "source": "order_total",
-      "resolver": "sdk.parseFloat"
-    },
-    "status": {
-      "source": "status",
-      "resolver": "sdk.uppercase",
-      "defaultValue": "PENDING"
-    }
-  }
-}
-```
-
----
-
-## Performance Tips
-
-### 1. Minimize Resolver Calls
-
-```typescript
-// ❌ BAD: Multiple resolvers for same transformation
-{
-  "fields": {
-    "email": {
-      "source": "customer_email",
-      "resolver": "sdk.lowercase"
-    },
-    "emailNormalized": {
-      "source": "customer_email",
-      "resolver": "sdk.trim" // Processes same field again
-    }
-  }
-}
-
-// ✅ GOOD: Single custom resolver
-{
-  "fields": {
-    "email": {
-      "source": "customer_email",
-      "resolver": "custom.normalizeEmail" // Does lowercase + trim in one pass
-    }
-  }
-}
-```
-
-### 2. Cache Expensive Lookups
-
-```typescript
-const customerCache = new Map();
-
-const customResolvers = {
-  'custom.lookupCustomer': async (value, data, config, helpers) => {
-    if (customerCache.has(value)) {
-      return customerCache.get(value); // Cache hit - no API call
-    }
-
-    const result = await helpers.fluentClient.graphql({
-      /* query */
-    });
-    customerCache.set(value, result.id);
-    return result.id;
-  },
-};
-```
-
-### 3. Use Memoization
-
-```typescript
-const expensiveCalculation = helpers.memoize((value) => {
-  // Complex calculation here
-  return result;
-});
-
-'custom.calculate': (value) => expensiveCalculation(value)
-```
-
-### 4. Batch Process Arrays
-
-```typescript
-// ❌ BAD: Sequential processing (slow for large arrays)
-for (const item of items) {
-  await processItem(item);
-}
-
-// ✅ GOOD: Batch processing (parallel chunks)
-await helpers.batchProcess(items, processItem, 100);
-```
-
-### 5. Avoid Deep Nesting
-
-```typescript
-// ❌ BAD: Deep nesting causes performance overhead
-{
-  "fields": {
-    "customer": {
-      "fields": {
-        "address": {
-          "fields": {
-            "location": {
-              "fields": {
-                "city": { "source": "city" }
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}
-
-// ✅ GOOD: Flat dot notation (faster)
-{
-  "fields": {
-    "customer.address.location.city": {
-      "source": "city"
-    }
-  }
-}
-```
-
----
-
-## FAQ
-
-### Q: What's the difference between UniversalMapper and GraphQLMutationMapper?
-
-**A**: Direction determines which to use:
-
-| Mapper                  | Direction | Purpose                                 | GraphQL Execution |
-| ----------------------- | --------- | --------------------------------------- | ----------------- |
-| `UniversalMapper`       | `extract` | Fluent → External (CSV, Parquet, JSON)  | ❌ No             |
-| `GraphQLMutationMapper` | `ingest`  | External → Fluent (XML, JSON → GraphQL) | ✅ Yes            |
-
-Both use the **same mapping configuration format**.
-
----
-
-### Q: Can I use the same mapping config for both ingestion and extraction?
-
-**A**: No, because:
-
-- **Ingestion**: Source = External data, Target = Fluent schema
-- **Extraction**: Source = Fluent data, Target = External format
-
-Field names and structures are different.
-
----
-
-### Q: How do I map arrays?
-
-**A**: Use `isArray: true` property:
-
-```json
-{
-  "fields": {
-    "items": {
-      "source": "line_items",
-      "isArray": true,
-      "fields": {
-        "ref": { "source": "$.id" },
-        "quantity": { "source": "$.qty" }
-      }
-    }
-  }
-}
-```
-
-See [Module 5: Arrays](./mapping-05-advanced-patterns.md#arrays) for complete guide.
-
----
-
-### Q: How do I handle nested/escaped XML?
-
-**A**: Use `nodes` configuration:
-
-```json
-{
-  "nodes": {
-    "radial": {
-      "extract": "orders.order.custom-attribute[attribute-id=CreateOrderServiceRequest]",
-      "parse": "xml"
-    }
-  },
-  "fields": {
-    "ref": {
-      "source": "$radial.Order@customerOrderId"
-    }
-  }
-}
-```
-
-See [Module 4: XML to GraphQL](./mapping-04-use-cases.md#use-case-2-xml-graphql-mutation) for complete example.
-
----
-
-### Q: Can resolvers be async?
-
-**A**: Yes! Custom resolvers can be async for API lookups:
-
-```typescript
-'custom.lookupCustomer': async (value, data, config, helpers) => {
-  const result = await helpers.fluentClient.graphql({ /* query */ });
-  return result.id;
-}
-```
-
-You must `await` the mapping when using async resolvers:
-
-```typescript
-const result = await mapper.map(data);
-```
-
----
-
-### Q: How do I validate my mapping config?
-
-**A**: Use the CLI validation tool:
-
-```bash
-fc-connect-validate-schema \
-  --mapping config/field-mappings.json \
-  --schema schema.json
-```
-
-See [Module 3: Schema Validation](../graphql-mutation-mapping/modules/graphql-mutation-mapping-03-schema-validation.md) for complete guide.
-
----
-
-### Q: What's the performance of UniversalMapper?
-
-**A**: Very fast for typical use cases:
-
-- **Small records** (< 100 fields): < 1ms per record
-- **Large records** (100-1000 fields): 1-5ms per record
-- **Batch processing** (10K records): 10-50 seconds
-
-Bottlenecks are usually:
-
-- Async resolvers making API calls
-- Complex nested transformations
-- JSON.parse/stringify operations
-
----
-
-### Q: Can I chain multiple resolvers?
-
-**A**: Not directly, but you can:
-
-1. **Use custom resolver** that calls SDK resolvers:
-
-   ```typescript
-   'custom.normalize': (value, data, config, helpers) => {
-     let result = value;
-     if (typeof result === 'string') {
-       result = result.toLowerCase().trim();
-     }
-     return result;
-   }
-   ```
-
-2. **Use multiple field configs** (less efficient):
-   ```json
-   {
-     "fields": {
-       "temp": { "source": "email", "resolver": "sdk.lowercase" },
-       "email": { "source": "temp", "resolver": "sdk.trim" }
-     }
-   }
-   ```
-
----
-
-### Q: How do I debug mapping issues?
-
-**A**: Enable debug logging:
-
-```typescript
-const mapper = new UniversalMapper(config);
-
-const result = await mapper.map(data);
-
-console.log('Mapping result:', JSON.stringify(result, null, 2));
-
-if (!result.success) {
-  console.error('Errors:', result.errors);
-}
-```
-
-See [Troubleshooting](#troubleshooting) section below.
-
----
-
-## Troubleshooting
-
-### Issue: "Missing required field"
-
-**Cause**: Required field is null/undefined in source data or resolver returned empty value.
-
-**Solution 1: Provide defaultValue**
-
-```json
-{
-  "fields": {
-    "productRef": {
-      "source": "sku",
-      "required": true,
-      "defaultValue": "UNKNOWN" // Provide fallback
-    }
-  }
-}
-```
-
-**Solution 2: Make field optional**
-
-```json
-{
-  "fields": {
-    "productRef": {
-      "source": "sku"
-      // Remove "required: true"
-    }
-  }
-}
-```
-
-**Solution 3: Fix resolver that returns empty value**
-
-If you have a resolver-only field that's required but returning empty:
-
-```json
-{
-  "fields": {
-    "customerId": {
-      "resolver": "custom.lookupCustomer",
-      "required": true
-    }
-  }
-}
-```
-
-**Problem:** Resolver returns `undefined` when customer not found:
-
-```typescript
-'custom.lookupCustomer': async (value, data, config, helpers) => {
-  const email = helpers.get(data, 'customer.email');
-  const customer = await lookupCustomerByEmail(email);
-  return customer?.id; // ❌ Returns undefined if customer not found
-}
-```
-
-**Fix:** Ensure resolver always returns a value or throw error:
-
-```typescript
-'custom.lookupCustomer': async (value, data, config, helpers) => {
-  const email = helpers.get(data, 'customer.email');
-  if (!email) {
-    throw new Error('Email required for customer lookup');
-  }
-  const customer = await lookupCustomerByEmail(email);
-  if (!customer) {
-    throw new Error(`Customer not found for email: ${email}`);
-  }
-  return customer.id; // ✅ Always returns a value or throws
-}
-```
-
-**Solution 4: Use defaultValue with resolver (but ensure resolver always returns value)**
-
-```json
-{
-  "fields": {
-    "discount": {
-      "source": "order.subtotal",
-      "resolver": "custom.calculateDiscount",
-      "required": true,
-      "defaultValue": 0  // Applied before resolver, but resolver must return non-empty
-    }
-  }
-}
-```
-
-**Important:** If `custom.calculateDiscount` returns `null`, `undefined`, or `''`, the mapping will still fail because required validation happens after resolver execution. The defaultValue only helps if the source is missing (it's applied before the resolver runs).
-
----
-
-### Issue: "Resolver not found"
-
-**Cause**: Resolver name is misspelled or not registered.
-
-**Solution**:
-
-- Check resolver name: `sdk.uppercase` (NOT `uppercase`)
-- Register custom resolver:
-  ```typescript
-  const mapper = new UniversalMapper(config, {
-    customResolvers: {
-      'custom.myResolver': value => transformValue(value),
-    },
-  });
-  ```
-
----
-
-### Issue: "Cannot read property of undefined"
-
-**Cause**: Path doesn't exist in source data.
-
-**Solution**: Use `defaultValue` or make path optional:
-
-```json
-{
-  "fields": {
-    "city": {
-      "source": "customer.address.city",
-      "defaultValue": "Unknown"
-    }
-  }
-}
-```
-
-Or use `helpers.get` in custom resolver:
-
-```typescript
-'custom.getCity': (value, data, config, helpers) => {
-  return helpers.get(data, 'customer.address.city', 'Unknown');
-}
-```
-
----
-
-### Issue: "Invalid JSON"
-
-**Cause**: Using `sdk.parseJson` on non-JSON string.
-
-**Solution**: `sdk.parseJson` is null-safe and returns original value if parse fails:
-
-```typescript
-// This won't throw - it returns "not json" unchanged
-{ "resolver": "sdk.parseJson" }
-```
-
-If you need strict validation, use custom resolver:
-
-```typescript
-'custom.strictParseJson': (value, data, config, helpers) => {
-  const result = helpers.safeJsonParse(value, null);
-  if (result === null) {
-    throw new Error(`Invalid JSON: ${value}`);
-  }
-  return result;
-}
-```
-
----
-
-### Issue: "Array expected but got object"
-
-**Cause**: XML parser doesn't create arrays for single items.
-
-**Solution**: Use `helpers.ensureArray`:
-
-```typescript
-'custom.processItems': (value, data, config, helpers) => {
-  const items = helpers.ensureArray(data.items);
-  // Now always an array, even if single item
-}
-```
-
----
-
-### Issue: "NaN in Fluent API response"
-
-**Cause**: Number resolver returned `NaN` instead of valid number.
-
-**Solution**: SDK resolvers (`sdk.parseInt`, `sdk.parseFloat`) return `0` by default (NOT `NaN`):
-
-```json
-{
-  "fields": {
-    "quantity": {
-      "source": "qty",
-      "resolver": "sdk.parseInt" // Returns 0 for invalid, NOT NaN
-    }
-  }
-}
-```
-
-If using custom resolver, ensure safe parsing:
-
-```typescript
-'custom.parseQty': (value, data, config, helpers) => {
-  return helpers.parseIntSafe(value, 0); // Safe default
-}
-```
-
----
-
-### Issue: "Circular reference in JSON"
-
-**Cause**: `sdk.toJson` on object with circular references.
-
-**Solution**: `sdk.toJson` is null-safe and returns original value if stringify fails:
-
-```typescript
-// Won't throw on circular references
-{ "resolver": "sdk.toJson" }
-```
-
-If you need custom handling:
-
-```typescript
-'custom.safeStringify': (value) => {
-  try {
-    return JSON.stringify(value, (key, val) => {
-      // Custom replacer logic
-      return val;
-    });
-  } catch {
-    return String(value);
-  }
-}
-```
-
----
-
-## Best Practices
-
-### 1. Always Validate Against Schema
-
-Before deployment:
-
-```bash
-fc-connect-validate-schema --mapping config/mappings.json --schema schema.json
-```
-
----
-
-### 2. Use SDK Resolvers First
-
-Don't write custom resolvers for common transformations:
-
-```typescript
-// ❌ NOT NEEDED
-'custom.uppercase': (value) => value?.toUpperCase()
-
-// ✅ USE SDK
-{ "resolver": "sdk.uppercase" }
-```
-
----
-
-### 3. Provide Default Values for Required Fields
-
-```json
-{
-  "fields": {
-    "status": {
-      "source": "order_status",
-      "required": true,
-      "defaultValue": "PENDING"
-    }
-  }
-}
-```
-
----
-
-### 4. Use Comments for Complex Mappings
-
-```json
-{
-  "fields": {
-    "totalPrice": {
-      "resolver": "custom.calculateTotal",
-      "comment": "Sum of (price * qty) + tax + shipping for all items"
-    }
-  }
-}
-```
-
----
-
-### 5. Keep Resolvers Pure and Testable
-
-```typescript
-// ✅ GOOD: Pure function, easy to test
-const customResolvers = {
-  'custom.buildRef': (value, data) => `${data.sku}-${data.location}`,
-};
-
-// Test
-const result = customResolvers`'custom.buildRef'`;
-console.assert(result === 'SKU001-WH01');
-```
-
----
-
-### 6. Log Errors and Warnings
-
-```typescript
-'custom.lookup': async (value, data, config, helpers) => {
-  try {
-    return await apiCall(value);
-  } catch (error) {
-    helpers.logger?.error('Lookup failed', { value, error });
-    return null; // Graceful degradation
-  }
-}
-```
-
----
-
-### 7. Use Nested Objects for Clarity
-
-```json
-{
-  "fields": {
-    "customer": {
-      "fields": {
-        "id": { "source": "customer_id" },
-        "email": { "source": "customer_email" }
-      }
-    }
-  }
-}
-```
-
-More readable than:
-
-```json
-{
-  "fields": {
-    "customer.id": { "source": "customer_id" },
-    "customer.email": { "source": "customer_email" }
-  }
-}
-```
-
----
-
-## Cheat Sheet
-
-### Quick Mapping Patterns
-
-```json
-// Static value
-{ "value": "ACTIVE" }
-
-// Simple mapping
-{ "source": "sku" }
-
-// With transformation
-{ "source": "email", "resolver": "sdk.lowercase" }
-
-// With default
-{ "source": "status", "defaultValue": "PENDING" }
-
-// Required field
-{ "source": "productRef", "required": true }
-
-// Custom resolver
-{ "source": "data", "resolver": "custom.transform" }
-
-// Nested object (dot notation)
-{ "customer.email": { "source": "email" } }
-
-// Nested object (fields)
-{
-  "customer": {
-    "fields": {
-      "email": { "source": "email" }
-    }
-  }
-}
-
-// Array
-{
-  "items": {
-    "source": "line_items",
-    "isArray": true,
-    "fields": {
-      "ref": { "source": "$.id" }
-    }
-  }
-}
-```
-
-### Common SDK Resolvers
-
-```json
-"sdk.uppercase"       // String to UPPER
-"sdk.lowercase"       // String to lower
-"sdk.trim"            // Remove whitespace
-"sdk.parseInt"        // String → int
-"sdk.parseFloat"      // String → float
-"sdk.formatDate"      // Date → ISO8601
-"sdk.boolean"         // "true"/"1"/"yes" → true
-"sdk.parseJson"       // JSON string → object
-"sdk.toJson"          // Object → JSON string
-```
-
----
-
-## Next Steps
-
-You've completed the Universal Mapping Guide! Next steps:
-
-- **[GraphQL Mutation Mapping Quick Reference](../graphql-mutation-mapping/graphql-mutation-mapping-quick-reference.md)** - Comprehensive cheat sheet
-- **[Examples](../examples/)** - Complete working examples
-- **[Use Cases](../../../01-TEMPLATES/readme.md)** - Real-world implementations
-
----
-
-## Additional Resources
-
-- [UniversalMapper Source Code](../../../../src/services/mapping/universal-mapper.ts)
-- [GraphQLMutationMapper Source](../../../../src/services/mapping/graphql-mutation-mapper.ts)
-- [SDK Resolvers Source](../../../../src/services/resolvers/sdk-resolvers.ts)
-- [Fluent Commerce API Documentation](https://docs.fluentcommerce.com/)
-
----
-
-[← Back to Index](../mapping-readme.md) | [Previous: Helpers & Resolvers](./mapping-06-helpers-resolvers.md)
-
+# Module 7: API Reference
+
+**Complete Technical Reference**
+
+**Level:** Reference
+**Time:** As needed
+**Prerequisites:** Modules 1-6
+
+---
+
+## Table of Contents
+
+1. [TypeScript Type Definitions](#typescript-type-definitions)
+2. [Configuration Migration](#configuration-migration)
+3. [Performance Tips](#performance-tips)
+4. [FAQ](#faq)
+5. [Troubleshooting](#troubleshooting)
+6. [Best Practices](#best-practices)
+7. [Cheat Sheet](#cheat-sheet)
+
+---
+
+## TypeScript Type Definitions
+
+### MappingConfig
+
+Complete mapping configuration structure:
+
+```typescript
+interface MappingConfig {
+  /** Direction of mapping */
+  direction: 'ingest' | 'extract';
+
+  /** Source data format (for context) */
+  sourceFormat?: 'csv' | 'xml' | 'json' | 'parquet';
+
+  /** GraphQL mutation name (for ingest direction) */
+  mutation?: string;
+
+  /** GraphQL query name (for extract direction) */
+  query?: string;
+
+  /** Nodes configuration for nested/escaped data */
+  nodes?: Record<string, NodeConfig>;
+
+  /** Field mappings */
+  fields: Record<string, FieldConfig>;
+
+  /** Return fields for GraphQL mutation (defaults to ['id', 'ref']) */
+  returnFields?: string[];
+}
+```
+
+### FieldConfig
+
+Individual field configuration:
+
+```typescript
+interface FieldConfig {
+  /** Source field path (supports dot notation, array indices, XML attributes) */
+  source?: string;
+
+  /** Static value (alternative to source) */
+  value?: any;
+
+  /** Default value if source is null/undefined */
+  defaultValue?: any;
+
+  /** Resolver function name (sdk.* or custom.*) */
+  resolver?: string;
+
+  /** Whether field is required (throws if missing). 
+   * 
+   * **Validation Timing:**
+   * - Fields with `source`: Validated BEFORE resolver execution
+   * - Resolver-only fields (no source): Validated AFTER resolver execution
+   * 
+   * **Behavior:**
+   * - `required: true`: Mapping stops immediately if field is missing/empty, returns `success: false`
+   * - `required: false` or omitted: Mapping continues with warning, field omitted from output
+   * 
+   * **Important:** Resolvers can return `null`, `undefined`, or empty strings. 
+   * `required: true` validates AFTER resolver execution to catch these cases.
+   * 
+   * **Examples:**
+   * ```json
+   * // Source field - validates before resolver
+   * { "source": "sku", "resolver": "sdk.trim", "required": true }
+   * 
+   * // Resolver-only - validates after resolver
+   * { "resolver": "custom.generateUUID", "required": true }
+   * ```
+   */
+  required?: boolean;
+
+  /** Nested object fields */
+  fields?: Record<string, FieldConfig>;
+
+  /** Array configuration */
+  isArray?: boolean;
+
+  /** Comment for documentation */
+  comment?: string;
+}
+```
+
+### NodeConfig
+
+Configuration for extracting nested/escaped data:
+
+```typescript
+interface NodeConfig {
+  /** Path to extract data from source */
+  extract: string;
+
+  /** How to parse extracted data */
+  parse: 'xml' | 'json';
+
+  /** Optional schema validation */
+  schema?: string;
+}
+```
+
+### ResolverFunction
+
+Custom resolver function signature:
+
+```typescript
+type ResolverFunction = (
+  value: any, // Extracted field value
+  sourceData: any, // Complete source object
+  config: any, // Resolver configuration
+  helpers: ResolverHelpers // 54 helper functions
+) => any | Promise<any>; // Transformed value (can be async)
+```
+
+### ResolverHelpers
+
+Helper functions available in custom resolvers:
+
+```typescript
+interface ResolverHelpers {
+  /** Fluent client instance (if available) */
+  fluentClient?: any;
+
+  /** Logger instance */
+  logger?: any;
+
+  /** Path resolution helper */
+  get: (obj: any, path: string, defaultValue?: any) => any;
+
+  /** Set value at path */
+  set: (obj: any, path: string, value: any) => void;
+
+  /** Array normalization helper */
+  ensureArray: <T>(val: T | T[] | null | undefined) => T[];
+
+  /** Safe number parsing */
+  parseIntSafe: (value: any, defaultValue?: number) => number;
+  parseFloatSafe: (value: any, defaultValue?: number) => number;
+
+  /** Safe JSON parsing */
+  safeJsonParse: (json: string, defaultValue?: any) => any;
+
+  /** Date formatting */
+  formatDate: (date: string | Date) => string;
+  parseDate: (value: any) => Date | null;
+
+  /** String utilities */
+  toCamelCase: (str: string) => string;
+  toSnakeCase: (str: string) => string;
+  truncate: (str: string, maxLength: number) => string;
+  normalizeWhitespace: (str: string) => string;
+  fullName: (firstName?: string, lastName?: string) => string;
+
+  /** Validation */
+  isValidEmail: (email: string) => boolean;
+  requireField: (value: any, fieldName: string) => void;
+  isEmpty: (value: any) => boolean;
+  isUrl: (url: string) => boolean;
+
+  /** Object utilities */
+  deepClone: <T>(obj: T) => T;
+  deepMerge: (target: any, source: any) => any;
+  pick: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Pick<T, K>;
+  omit: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Omit<T, K>;
+  flatten: (obj: any, prefix?: string) => Record<string, any>;
+
+  /** Array utilities */
+  unique: <T>(arr: T[]) => T[];
+  groupBy: <T>(arr: T[], key: string) => Record<string, T[]>;
+  sortBy: <T>(arr: T[], key: string) => T[];
+  chunk: <T>(arr: T[], size: number) => T[][];
+  findBy: <T>(arr: T[], key: string, value: any) => T | undefined;
+
+  /** Async utilities */
+  retry: <T>(fn: () => Promise<T>, maxRetries?: number, delayMs?: number) => Promise<T>;
+  batchProcess: <T, R>(
+    items: T[],
+    processor: (item: T) => Promise<R>,
+    batchSize?: number
+  ) => Promise<R[]>;
+  sleep: (ms: number) => Promise<void>;
+  timeout: <T>(promise: Promise<T>, ms: number) => Promise<T>;
+
+  /** Performance */
+  memoize: <T extends (...args: any[]) => any>(fn: T) => T;
+  hash: (data: string) => string;
+  uuid: () => string;
+
+  /** Context */
+  context: Record<string, any>;
+
+  /** Additional custom helpers */
+  [key: string]: any;
+}
+```
+
+### MapResult
+
+Result from UniversalMapper.map():
+
+```typescript
+interface MapResult {
+  /** Whether mapping succeeded */
+  success: boolean;
+
+  /** Mapped data */
+  data: Record<string, any>;
+
+  /** Error messages (if any) */
+  errors?: string[];
+
+  /** Warning messages (non-blocking) */
+  warnings?: string[];
+}
+```
+
+---
+
+## Configuration Format
+
+**Field mapping format:**
+
+```json
+{
+  "fields": {
+    "productRef": {
+      "source": "sku",
+      "resolver": "sdk.uppercase"
+    },
+    "quantity": {
+      "source": "qty",
+      "resolver": "sdk.parseInt"
+    }
+  }
+}
+```
+
+---
+
+## Field Configuration Edge Cases & Best Practices
+
+### ⚠️ Important Field Property Combinations
+
+Understanding how field properties interact is critical for correct mapping behavior.
+
+---
+
+#### ✅ Resolver-Only Fields with `required: true`
+
+**New in SDK v0.1.37:** Resolver-only fields can now be required.
+
+**Pattern:**
+```json
+{
+  "id": {
+    "resolver": "custom.generateUUID",
+    "required": true
+  }
+}
+```
+
+**When to use:**
+- Generate unique IDs (UUID, composite keys)
+- Look up values from external APIs
+- Derive values from multiple source fields
+- Apply complex business logic
+
+**Validation behavior:**
+- Required validation runs AFTER resolver execution
+- Resolver must return a non-empty value
+- If resolver returns null/undefined/'', mapping fails
+
+**Example:**
+```typescript
+const mapper = new UniversalMapper(
+  {
+    fields: {
+      transactionId: {
+        resolver: 'custom.generateTransactionId',
+        required: true,
+      },
+    },
+  },
+  {
+    customResolvers: {
+      'custom.generateTransactionId': (value, sourceData, config, helpers) => {
+        return `TXN-${Date.now()}-${helpers.uuid()}`;
+      },
+    },
+  }
+);
+```
+
+📖 **Learn more:** [Resolver-Only Fields Guide](../resolvers/mapping-resolvers-resolver-guide.md#resolver-only-fields--required-validation)
+
+---
+
+#### ⚠️ `required: true` + `defaultValue` (Contradictory)
+
+**Status:** ⚠️ This combination is semantically contradictory for source fields.
+
+**Problem:**
+```json
+{
+  "status": {
+    "source": "orderStatus",
+    "required": true,
+    "defaultValue": "PENDING"  // ❌ Never used!
+  }
+}
+```
+
+**Behavior:**
+1. Extract from source → `undefined` (missing)
+2. Validate required → ❌ Throws error immediately
+3. Apply defaultValue → ❌ Never reached
+
+**Why this doesn't work:**
+- Required validation happens BEFORE defaultValue application for source fields
+- DefaultValue is never applied because required fails first
+
+**Important:** The order for `source + resolver + defaultValue + required` is:
+1. Extract from source → `undefined`
+2. Validate required → ❌ Fails immediately (defaultValue never applied)
+3. Apply defaultValue → ❌ Never reached
+4. Run resolver → ❌ Never reached
+
+The code includes a warning when this combination is detected (see console output).
+
+**Solution:**
+```json
+// ✅ CORRECT - Optional field with default
+{
+  "status": {
+    "source": "orderStatus",
+    "required": false,  // or omit required
+    "defaultValue": "PENDING"
+  }
+}
+
+// ✅ CORRECT - Required field without default
+{
+  "status": {
+    "source": "orderStatus",
+    "required": true
+  }
+}
+```
+
+---
+
+#### ✅ `defaultValue` + `resolver` (Works, but order matters)
+
+**Pattern:**
+```json
+{
+  "status": {
+    "source": "orderStatus",
+    "defaultValue": "pending",
+    "resolver": "sdk.uppercase"
+  }
+}
+```
+
+**Behavior:**
+1. Extract from source → `undefined` (missing)
+2. Apply defaultValue → `"pending"`
+3. Apply resolver → `"PENDING"`
+
+**Key insight:** Resolver receives the defaultValue, not the missing source value.
+
+**Real-world example:**
+```json
+{
+  "attributes.condition": {
+    "source": "condition",
+    "defaultValue": "NEW",
+    "resolver": "sdk.uppercase",
+    "required": false
+  }
+}
+// Missing source → "NEW" → "NEW" (already uppercase)
+// Empty source → "NEW" → "NEW"
+// Source "used" → "USED" → "USED"
+```
+
+---
+
+#### ✅ `required: true` + `value` (Redundant but harmless)
+
+**Pattern:**
+```json
+{
+  "type": {
+    "value": "STANDARD",
+    "required": true  // ⚠️ Redundant
+  }
+}
+```
+
+**Behavior:**
+- Static values are always present
+- Required validation always passes
+- `required: true` has no effect but doesn't hurt
+
+**Recommendation:**
+```json
+// ✅ BETTER - Omit redundant required
+{
+  "type": {
+    "value": "STANDARD"
+  }
+}
+```
+
+---
+
+#### ✅ Empty String Handling
+
+**Behavior:** Empty string (`''`) is treated as "missing" for:
+- Required validation
+- DefaultValue application
+
+**Example:**
+```json
+{
+  "status": {
+    "source": "orderStatus",  // = ""
+    "defaultValue": "PENDING",
+    "required": false
+  }
+}
+// Result: "PENDING" (empty string triggers default)
+```
+
+**Validation:**
+```typescript
+// Empty string fails required validation
+if (value === null || value === undefined || value === '')
+
+// Empty string triggers defaultValue
+if ((value === null || value === undefined || value === '') && config.defaultValue !== undefined)
+```
+
+---
+
+### 📋 Field Property Combinations Summary
+
+| Combination | Status | Behavior |
+|-------------|--------|----------|
+| `source` + `required: true` | ✅ Correct | Validates before resolver, fails if missing |
+| `resolver` + `required: true` (no source) | ✅ Correct | Validates after resolver, fails if empty |
+| `source` + `resolver` + `required: true` | ✅ Correct | Validates source, then applies resolver |
+| `required: true` + `defaultValue` (source only) | ❌ Contradictory | Required fails before default applied |
+| `source` + `resolver` + `defaultValue` + `required: true` | ❌ Contradictory | Required fails before default applied (same as above) |
+| `defaultValue` + `resolver` | ✅ Works | Resolver receives default if source missing |
+| `value` + `required: true` | ⚠️ Redundant | Works but required is unnecessary |
+| `value` + `source` | ❌ Invalid | value takes precedence, source ignored |
+| `value` + `resolver` | ✅ Works | Resolver transforms static value |
+
+---
+
+### 🎯 Best Practices
+
+**1. ✅ DO: Use `required: true` for mandatory source fields**
+```json
+{ "source": "sku", "required": true }
+```
+
+**2. ✅ DO: Use `defaultValue` for optional fields**
+```json
+{ "source": "status", "defaultValue": "ACTIVE", "required": false }
+```
+
+**3. ✅ DO: Use resolver-only for generated values**
+```json
+{ "resolver": "custom.generateId", "required": true }
+```
+
+**4. ❌ DON'T: Combine `required: true` with `defaultValue`**
+```json
+// ❌ Contradictory - default will never be used
+{ "source": "field", "required": true, "defaultValue": "FALLBACK" }
+```
+
+**5. ⚠️ CAUTION: `defaultValue` + `resolver` - default is passed to resolver**
+```json
+// Resolver receives "NEW" if source missing
+{ "source": "condition", "defaultValue": "NEW", "resolver": "sdk.uppercase" }
+```
+
+---
+
+### From Old Transformer System
+
+**Old transformers → New resolvers:**
+
+| Old Transformer | New Resolver     |
+| --------------- | ---------------- |
+| `uppercase`     | `sdk.uppercase`  |
+| `lowercase`     | `sdk.lowercase`  |
+| `parseInt`      | `sdk.parseInt`   |
+| `parseFloat`    | `sdk.parseFloat` |
+| `formatDate`    | `sdk.formatDate` |
+| `boolean`       | `sdk.boolean`    |
+| `toJson`        | `sdk.toJson`     |
+| `parseJson`     | `sdk.parseJson`  |
+
+### Migration Steps
+
+1. **Identify mapping format**:
+   - Check for `fieldMappings` array
+   - Check for `transformer` property
+   - Check for field names
+
+2. **Convert to universal mapping format**:
+   - Replace `fieldMappings` with `fields` object
+   - Replace `sourceField` + `targetField` with nested structure
+   - Replace `transformer` with `resolver`
+   - Add `sdk.` prefix to resolver names
+
+3. **Validate against schema**:
+
+   ```bash
+   fc-connect-validate-schema --mapping config/new-mapping.json --schema schema.json
+   ```
+
+4. **Test with sample data**:
+   ```typescript
+   const mapper = new UniversalMapper(newConfig);
+   const result = await mapper.map(sampleData);
+   console.log('Migration result:', result);
+   ```
+
+### Example Migration
+
+**Before** (old format):
+
+```json
+{
+  "fieldMappings": [
+    {
+      "sourceField": "customer_email",
+      "targetField": "customer.email",
+      "transformer": "lowercase",
+      "required": true
+    },
+    {
+      "sourceField": "order_total",
+      "targetField": "totalPrice",
+      "transformer": "parseFloat"
+    },
+    {
+      "sourceField": "status",
+      "targetField": "status",
+      "transformer": "uppercase",
+      "defaultValue": "PENDING"
+    }
+  ]
+}
+```
+
+**After** (new format):
+
+```json
+{
+  "direction": "ingest",
+  "fields": {
+    "customer.email": {
+      "source": "customer_email",
+      "resolver": "sdk.lowercase",
+      "required": true
+    },
+    "totalPrice": {
+      "source": "order_total",
+      "resolver": "sdk.parseFloat"
+    },
+    "status": {
+      "source": "status",
+      "resolver": "sdk.uppercase",
+      "defaultValue": "PENDING"
+    }
+  }
+}
+```
+
+---
+
+## Performance Tips
+
+### 1. Minimize Resolver Calls
+
+```typescript
+// ❌ BAD: Multiple resolvers for same transformation
+{
+  "fields": {
+    "email": {
+      "source": "customer_email",
+      "resolver": "sdk.lowercase"
+    },
+    "emailNormalized": {
+      "source": "customer_email",
+      "resolver": "sdk.trim" // Processes same field again
+    }
+  }
+}
+
+// ✅ GOOD: Single custom resolver
+{
+  "fields": {
+    "email": {
+      "source": "customer_email",
+      "resolver": "custom.normalizeEmail" // Does lowercase + trim in one pass
+    }
+  }
+}
+```
+
+### 2. Cache Expensive Lookups
+
+```typescript
+const customerCache = new Map();
+
+const customResolvers = {
+  'custom.lookupCustomer': async (value, data, config, helpers) => {
+    if (customerCache.has(value)) {
+      return customerCache.get(value); // Cache hit - no API call
+    }
+
+    const result = await helpers.fluentClient.graphql({
+      /* query */
+    });
+    customerCache.set(value, result.id);
+    return result.id;
+  },
+};
+```
+
+### 3. Use Memoization
+
+```typescript
+const expensiveCalculation = helpers.memoize((value) => {
+  // Complex calculation here
+  return result;
+});
+
+'custom.calculate': (value) => expensiveCalculation(value)
+```
+
+### 4. Batch Process Arrays
+
+```typescript
+// ❌ BAD: Sequential processing (slow for large arrays)
+for (const item of items) {
+  await processItem(item);
+}
+
+// ✅ GOOD: Batch processing (parallel chunks)
+await helpers.batchProcess(items, processItem, 100);
+```
+
+### 5. Avoid Deep Nesting
+
+```typescript
+// ❌ BAD: Deep nesting causes performance overhead
+{
+  "fields": {
+    "customer": {
+      "fields": {
+        "address": {
+          "fields": {
+            "location": {
+              "fields": {
+                "city": { "source": "city" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+// ✅ GOOD: Flat dot notation (faster)
+{
+  "fields": {
+    "customer.address.location.city": {
+      "source": "city"
+    }
+  }
+}
+```
+
+---
+
+## FAQ
+
+### Q: What's the difference between UniversalMapper and GraphQLMutationMapper?
+
+**A**: Direction determines which to use:
+
+| Mapper                  | Direction | Purpose                                 | GraphQL Execution |
+| ----------------------- | --------- | --------------------------------------- | ----------------- |
+| `UniversalMapper`       | `extract` | Fluent → External (CSV, Parquet, JSON)  | ❌ No             |
+| `GraphQLMutationMapper` | `ingest`  | External → Fluent (XML, JSON → GraphQL) | ✅ Yes            |
+
+Both use the **same mapping configuration format**.
+
+---
+
+### Q: Can I use the same mapping config for both ingestion and extraction?
+
+**A**: No, because:
+
+- **Ingestion**: Source = External data, Target = Fluent schema
+- **Extraction**: Source = Fluent data, Target = External format
+
+Field names and structures are different.
+
+---
+
+### Q: How do I map arrays?
+
+**A**: Use `isArray: true` property:
+
+```json
+{
+  "fields": {
+    "items": {
+      "source": "line_items",
+      "isArray": true,
+      "fields": {
+        "ref": { "source": "$.id" },
+        "quantity": { "source": "$.qty" }
+      }
+    }
+  }
+}
+```
+
+See [Module 5: Arrays](./mapping-05-advanced-patterns.md#arrays) for complete guide.
+
+---
+
+### Q: How do I handle nested/escaped XML?
+
+**A**: Use `nodes` configuration:
+
+```json
+{
+  "nodes": {
+    "radial": {
+      "extract": "orders.order.custom-attribute[attribute-id=CreateOrderServiceRequest]",
+      "parse": "xml"
+    }
+  },
+  "fields": {
+    "ref": {
+      "source": "$radial.Order@customerOrderId"
+    }
+  }
+}
+```
+
+See [Module 4: XML to GraphQL](./mapping-04-use-cases.md#use-case-2-xml-graphql-mutation) for complete example.
+
+---
+
+### Q: Can resolvers be async?
+
+**A**: Yes! Custom resolvers can be async for API lookups:
+
+```typescript
+'custom.lookupCustomer': async (value, data, config, helpers) => {
+  const result = await helpers.fluentClient.graphql({ /* query */ });
+  return result.id;
+}
+```
+
+You must `await` the mapping when using async resolvers:
+
+```typescript
+const result = await mapper.map(data);
+```
+
+---
+
+### Q: How do I validate my mapping config?
+
+**A**: Use the CLI validation tool:
+
+```bash
+fc-connect-validate-schema \
+  --mapping config/field-mappings.json \
+  --schema schema.json
+```
+
+See [Module 3: Schema Validation](../graphql-mutation-mapping/modules/graphql-mutation-mapping-03-schema-validation.md) for complete guide.
+
+---
+
+### Q: What's the performance of UniversalMapper?
+
+**A**: Very fast for typical use cases:
+
+- **Small records** (< 100 fields): < 1ms per record
+- **Large records** (100-1000 fields): 1-5ms per record
+- **Batch processing** (10K records): 10-50 seconds
+
+Bottlenecks are usually:
+
+- Async resolvers making API calls
+- Complex nested transformations
+- JSON.parse/stringify operations
+
+---
+
+### Q: Can I chain multiple resolvers?
+
+**A**: Not directly, but you can:
+
+1. **Use custom resolver** that calls SDK resolvers:
+
+   ```typescript
+   'custom.normalize': (value, data, config, helpers) => {
+     let result = value;
+     if (typeof result === 'string') {
+       result = result.toLowerCase().trim();
+     }
+     return result;
+   }
+   ```
+
+2. **Use multiple field configs** (less efficient):
+   ```json
+   {
+     "fields": {
+       "temp": { "source": "email", "resolver": "sdk.lowercase" },
+       "email": { "source": "temp", "resolver": "sdk.trim" }
+     }
+   }
+   ```
+
+---
+
+### Q: How do I debug mapping issues?
+
+**A**: Enable debug logging:
+
+```typescript
+const mapper = new UniversalMapper(config);
+
+const result = await mapper.map(data);
+
+console.log('Mapping result:', JSON.stringify(result, null, 2));
+
+if (!result.success) {
+  console.error('Errors:', result.errors);
+}
+```
+
+See [Troubleshooting](#troubleshooting) section below.
+
+---
+
+## Troubleshooting
+
+### Issue: "Missing required field"
+
+**Cause**: Required field is null/undefined in source data or resolver returned empty value.
+
+**Solution 1: Provide defaultValue**
+
+```json
+{
+  "fields": {
+    "productRef": {
+      "source": "sku",
+      "required": true,
+      "defaultValue": "UNKNOWN" // Provide fallback
+    }
+  }
+}
+```
+
+**Solution 2: Make field optional**
+
+```json
+{
+  "fields": {
+    "productRef": {
+      "source": "sku"
+      // Remove "required: true"
+    }
+  }
+}
+```
+
+**Solution 3: Fix resolver that returns empty value**
+
+If you have a resolver-only field that's required but returning empty:
+
+```json
+{
+  "fields": {
+    "customerId": {
+      "resolver": "custom.lookupCustomer",
+      "required": true
+    }
+  }
+}
+```
+
+**Problem:** Resolver returns `undefined` when customer not found:
+
+```typescript
+'custom.lookupCustomer': async (value, data, config, helpers) => {
+  const email = helpers.get(data, 'customer.email');
+  const customer = await lookupCustomerByEmail(email);
+  return customer?.id; // ❌ Returns undefined if customer not found
+}
+```
+
+**Fix:** Ensure resolver always returns a value or throw error:
+
+```typescript
+'custom.lookupCustomer': async (value, data, config, helpers) => {
+  const email = helpers.get(data, 'customer.email');
+  if (!email) {
+    throw new Error('Email required for customer lookup');
+  }
+  const customer = await lookupCustomerByEmail(email);
+  if (!customer) {
+    throw new Error(`Customer not found for email: ${email}`);
+  }
+  return customer.id; // ✅ Always returns a value or throws
+}
+```
+
+**Solution 4: Use defaultValue with resolver (but ensure resolver always returns value)**
+
+```json
+{
+  "fields": {
+    "discount": {
+      "source": "order.subtotal",
+      "resolver": "custom.calculateDiscount",
+      "required": true,
+      "defaultValue": 0  // Applied before resolver, but resolver must return non-empty
+    }
+  }
+}
+```
+
+**Important:** If `custom.calculateDiscount` returns `null`, `undefined`, or `''`, the mapping will still fail because required validation happens after resolver execution. The defaultValue only helps if the source is missing (it's applied before the resolver runs).
+
+---
+
+### Issue: "Resolver not found"
+
+**Cause**: Resolver name is misspelled or not registered.
+
+**Solution**:
+
+- Check resolver name: `sdk.uppercase` (NOT `uppercase`)
+- Register custom resolver:
+  ```typescript
+  const mapper = new UniversalMapper(config, {
+    customResolvers: {
+      'custom.myResolver': value => transformValue(value),
+    },
+  });
+  ```
+
+---
+
+### Issue: "Cannot read property of undefined"
+
+**Cause**: Path doesn't exist in source data.
+
+**Solution**: Use `defaultValue` or make path optional:
+
+```json
+{
+  "fields": {
+    "city": {
+      "source": "customer.address.city",
+      "defaultValue": "Unknown"
+    }
+  }
+}
+```
+
+Or use `helpers.get` in custom resolver:
+
+```typescript
+'custom.getCity': (value, data, config, helpers) => {
+  return helpers.get(data, 'customer.address.city', 'Unknown');
+}
+```
+
+---
+
+### Issue: "Invalid JSON"
+
+**Cause**: Using `sdk.parseJson` on non-JSON string.
+
+**Solution**: `sdk.parseJson` is null-safe and returns original value if parse fails:
+
+```typescript
+// This won't throw - it returns "not json" unchanged
+{ "resolver": "sdk.parseJson" }
+```
+
+If you need strict validation, use custom resolver:
+
+```typescript
+'custom.strictParseJson': (value, data, config, helpers) => {
+  const result = helpers.safeJsonParse(value, null);
+  if (result === null) {
+    throw new Error(`Invalid JSON: ${value}`);
+  }
+  return result;
+}
+```
+
+---
+
+### Issue: "Array expected but got object"
+
+**Cause**: XML parser doesn't create arrays for single items.
+
+**Solution**: Use `helpers.ensureArray`:
+
+```typescript
+'custom.processItems': (value, data, config, helpers) => {
+  const items = helpers.ensureArray(data.items);
+  // Now always an array, even if single item
+}
+```
+
+---
+
+### Issue: "NaN in Fluent API response"
+
+**Cause**: Number resolver returned `NaN` instead of valid number.
+
+**Solution**: SDK resolvers (`sdk.parseInt`, `sdk.parseFloat`) return `0` by default (NOT `NaN`):
+
+```json
+{
+  "fields": {
+    "quantity": {
+      "source": "qty",
+      "resolver": "sdk.parseInt" // Returns 0 for invalid, NOT NaN
+    }
+  }
+}
+```
+
+If using custom resolver, ensure safe parsing:
+
+```typescript
+'custom.parseQty': (value, data, config, helpers) => {
+  return helpers.parseIntSafe(value, 0); // Safe default
+}
+```
+
+---
+
+### Issue: "Circular reference in JSON"
+
+**Cause**: `sdk.toJson` on object with circular references.
+
+**Solution**: `sdk.toJson` is null-safe and returns original value if stringify fails:
+
+```typescript
+// Won't throw on circular references
+{ "resolver": "sdk.toJson" }
+```
+
+If you need custom handling:
+
+```typescript
+'custom.safeStringify': (value) => {
+  try {
+    return JSON.stringify(value, (key, val) => {
+      // Custom replacer logic
+      return val;
+    });
+  } catch {
+    return String(value);
+  }
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Always Validate Against Schema
+
+Before deployment:
+
+```bash
+fc-connect-validate-schema --mapping config/mappings.json --schema schema.json
+```
+
+---
+
+### 2. Use SDK Resolvers First
+
+Don't write custom resolvers for common transformations:
+
+```typescript
+// ❌ NOT NEEDED
+'custom.uppercase': (value) => value?.toUpperCase()
+
+// ✅ USE SDK
+{ "resolver": "sdk.uppercase" }
+```
+
+---
+
+### 3. Provide Default Values for Required Fields
+
+```json
+{
+  "fields": {
+    "status": {
+      "source": "order_status",
+      "required": true,
+      "defaultValue": "PENDING"
+    }
+  }
+}
+```
+
+---
+
+### 4. Use Comments for Complex Mappings
+
+```json
+{
+  "fields": {
+    "totalPrice": {
+      "resolver": "custom.calculateTotal",
+      "comment": "Sum of (price * qty) + tax + shipping for all items"
+    }
+  }
+}
+```
+
+---
+
+### 5. Keep Resolvers Pure and Testable
+
+```typescript
+// ✅ GOOD: Pure function, easy to test
+const customResolvers = {
+  'custom.buildRef': (value, data) => `${data.sku}-${data.location}`,
+};
+
+// Test
+const result = customResolvers`'custom.buildRef'`;
+console.assert(result === 'SKU001-WH01');
+```
+
+---
+
+### 6. Log Errors and Warnings
+
+```typescript
+'custom.lookup': async (value, data, config, helpers) => {
+  try {
+    return await apiCall(value);
+  } catch (error) {
+    helpers.logger?.error('Lookup failed', { value, error });
+    return null; // Graceful degradation
+  }
+}
+```
+
+---
+
+### 7. Use Nested Objects for Clarity
+
+```json
+{
+  "fields": {
+    "customer": {
+      "fields": {
+        "id": { "source": "customer_id" },
+        "email": { "source": "customer_email" }
+      }
+    }
+  }
+}
+```
+
+More readable than:
+
+```json
+{
+  "fields": {
+    "customer.id": { "source": "customer_id" },
+    "customer.email": { "source": "customer_email" }
+  }
+}
+```
+
+---
+
+## Cheat Sheet
+
+### Quick Mapping Patterns
+
+```json
+// Static value
+{ "value": "ACTIVE" }
+
+// Simple mapping
+{ "source": "sku" }
+
+// With transformation
+{ "source": "email", "resolver": "sdk.lowercase" }
+
+// With default
+{ "source": "status", "defaultValue": "PENDING" }
+
+// Required field
+{ "source": "productRef", "required": true }
+
+// Custom resolver
+{ "source": "data", "resolver": "custom.transform" }
+
+// Nested object (dot notation)
+{ "customer.email": { "source": "email" } }
+
+// Nested object (fields)
+{
+  "customer": {
+    "fields": {
+      "email": { "source": "email" }
+    }
+  }
+}
+
+// Array
+{
+  "items": {
+    "source": "line_items",
+    "isArray": true,
+    "fields": {
+      "ref": { "source": "$.id" }
+    }
+  }
+}
+```
+
+### Common SDK Resolvers
+
+```json
+"sdk.uppercase"       // String to UPPER
+"sdk.lowercase"       // String to lower
+"sdk.trim"            // Remove whitespace
+"sdk.parseInt"        // String → int
+"sdk.parseFloat"      // String → float
+"sdk.formatDate"      // Date → ISO8601
+"sdk.boolean"         // "true"/"1"/"yes" → true
+"sdk.parseJson"       // JSON string → object
+"sdk.toJson"          // Object → JSON string
+```
+
+---
+
+## Next Steps
+
+You've completed the Universal Mapping Guide! Next steps:
+
+- **[GraphQL Mutation Mapping Quick Reference](../graphql-mutation-mapping/graphql-mutation-mapping-quick-reference.md)** - Comprehensive cheat sheet
+- **[Examples](../examples/)** - Complete working examples
+- **[Use Cases](../../../01-TEMPLATES/readme.md)** - Real-world implementations
+
+---
+
+## Additional Resources
+
+- [UniversalMapper Source Code](../../../../src/services/mapping/universal-mapper.ts)
+- [GraphQLMutationMapper Source](../../../../src/services/mapping/graphql-mutation-mapper.ts)
+- [SDK Resolvers Source](../../../../src/services/resolvers/sdk-resolvers.ts)
+- [Fluent Commerce API Documentation](https://docs.fluentcommerce.com/)
+
+---
+
+[← Back to Index](../mapping-readme.md) | [Previous: Helpers & Resolvers](./mapping-06-helpers-resolvers.md)
+