@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-resolver-troubleshooting.md

@@ -1,854 +1,854 @@
-# Resolver Troubleshooting Guide
-
-**Common issues, solutions, and debugging tips**
-
-Version: 2.0.0
-Last Updated: 2025-01-14
-
----
-
-## Table of Contents
-
-1. [Quick Diagnostics](#quick-diagnostics)
-2. [Common Issues](#common-issues)
-3. [Debugging Techniques](#debugging-techniques)
-4. [Error Patterns](#error-patterns)
-5. [Performance Problems](#performance-problems)
-6. [Testing Issues](#testing-issues)
-
----
-
-## Quick Diagnostics
-
-### Checklist Before Debugging
-
-✅ **Check these first:**
-
-1. **Resolver registered?**
-   ```typescript
-   console.log(Object.keys(resolvers));
-   // Should include your resolver path
-   ```
-
-2. **Path correct?**
-   ```typescript
-   // If you want: { input: { ref: 'value' } }
-   // Use path: 'input.ref'
-   ```
-
-3. **Data structure matches?**
-   ```typescript
-   console.log(JSON.stringify(data, null, 2));
-   // Verify paths exist
-   ```
-
-4. **Helpers imported?**
-   ```typescript
-   import { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
-   const result = resolver(data, config, ResolverHelpers);
-   ```
-
-5. **Async resolved?**
-   ```typescript
-   const result = await resolver(...);  // Don't forget await!
-   ```
-
----
-
-## Common Issues
-
-### Issue #1: Resolver Not Executing
-
-**Symptom:** Field is missing in output, no errors.
-
-**Possible Causes:**
-
-#### Cause A: Path Mismatch
-
-```typescript
-// ❌ Wrong path
-builder.from('ref', 'order.orderNo');
-// Creates: { ref: '...' }
-
-// ✅ Correct path for nested structure
-builder.from('input.ref', 'order.orderNo');
-// Creates: { input: { ref: '...' } }
-```
-
-**Solution:** Verify target path matches desired output structure.
-
----
-
-#### Cause B: Resolver Not in Registry
-
-```typescript
-// ❌ Forgot to add to builder
-const resolvers = builder
-  .from('input.ref', 'order.orderNo')
-  .build();
-
-// Missing: .from('input.totalPrice', ...)
-```
-
-**Solution:** Check all resolvers are added before `.build()`.
-
-```typescript
-console.log(Object.keys(resolvers));
-// Should print: ['input.ref', 'input.totalPrice', ...]
-```
-
----
-
-#### Cause C: Execution Order
-
-**Problem:** Resolver executes but value not set in output.
-
-```typescript
-// ❌ Not awaiting async resolver
-const result = resolver(data, config, helpers);  // Returns Promise
-console.log(result);  // Promise { <pending> }
-
-// ✅ Await async resolver
-const result = await resolver(data, config, helpers);
-console.log(result);  // Actual value
-```
-
-**Solution:** Always await async resolvers.
-
----
-
-### Issue #2: `helpers.xxx is not a function`
-
-**Symptom:** `TypeError: helpers.parseFloatSafe is not a function`
-
-**Cause:** Helpers not passed correctly.
-
-```typescript
-// ❌ Wrong - empty object
-const result = resolver(data, config, {});
-
-// ❌ Wrong - undefined
-const result = resolver(data, config);
-
-// ✅ Correct - pass ResolverHelpers
-import { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
-const result = resolver(data, config, ResolverHelpers);
-```
-
-**Solution:** Always pass `ResolverHelpers` as the fourth parameter.
-
----
-
-### Issue #3: Array Not Mapping Correctly
-
-**Symptom:** Getting single object instead of array, or empty array.
-
-#### Cause A: XML Single vs Multiple Elements
-
-XML parsers return:
-- **Single element** → Object
-- **Multiple elements** → Array
-
-```typescript
-// ❌ Breaks with single item
-const items = data.order.items.item;
-items.map(item => { ... });  // ERROR if items is object
-
-// ✅ Always works
-const items = helpers.ensureArray(data.order.items.item);
-items.map(item => { ... });
-```
-
-**Solution:** Always use `helpers.ensureArray()` when processing XML arrays.
-
----
-
-#### Cause B: Wrong Source Path
-
-```typescript
-// ❌ Wrong path
-builder.mapArray('input.items', 'order.items', ...)
-// But actual path is: 'orders.order.product-lineitems.product-lineitem'
-
-// ✅ Correct path
-builder.mapArray(
-  'input.items',
-  'orders.order.product-lineitems.product-lineitem',
-  (item) => ({ ... })
-);
-```
-
-**Solution:** Verify source path with:
-```typescript
-console.log(helpers.get(data, 'orders.order.product-lineitems.product-lineitem'));
-```
-
----
-
-### Issue #4: Validation Failing
-
-**Symptom:** `Error: Validation failed for input.email`
-
-**Debug Steps:**
-
-1. **Check the value:**
-```typescript
-builder.validate(
-  'input.email',
-  (data, config, helpers) => {
-    const email = helpers.get(data, 'customer.email');
-    console.log('Email value:', email);  // Debug
-    return email;
-  },
-  (value) => helpers.isValidEmail(value)
-);
-```
-
-2. **Make validation more lenient:**
-```typescript
-// Add default value
-builder.validate(
-  'input.email',
-  (data, config, helpers) => {
-    return helpers.get(data, 'customer.email', 'no-reply@example.com');
-  },
-  (value) => helpers.isValidEmail(value) || 'Email format invalid'
-);
-```
-
-3. **Check validation logic:**
-```typescript
-// Test validator separately
-const testEmail = 'test@example.com';
-console.log(helpers.isValidEmail(testEmail));  // Should be true
-```
-
----
-
-### Issue #5: Config Not Available
-
-**Symptom:** `TypeError: Cannot read property 'defaultRetailerId' of undefined`
-
-**Cause:** Config not passed when executing resolvers.
-
-```typescript
-// ❌ Wrong - no config
-const result = resolvers\['input.ref'](data);
-
-// ✅ Correct - pass config
-const config = {
-  defaultRetailerId: '1',
-  defaultCurrency: 'USD'
-};
-const result = resolvers\['input.ref'](data, config, helpers);
-```
-
-**Solution:** Always pass config as second parameter.
-
----
-
-### Issue #6: Async Resolver Not Awaiting
-
-**Symptom:** Promise returned instead of value.
-
-```typescript
-// ❌ Wrong - not awaiting
-const customerId = resolvers\['input.customer.id'](data, config, helpers);
-console.log(customerId);  // Promise { <pending> }
-
-// ✅ Correct - await async resolver
-const customerId = await resolvers\['input.customer.id'](data, config, helpers);
-console.log(customerId);  // Actual customer ID
-```
-
-**Solution:**
-- Mark your function `async`
-- Always `await` async resolvers
-- Check if resolver returns `Promise` in definition
-
----
-
-### Issue #7: Path Not Resolving (XML Attributes)
-
-**Symptom:** XML attribute returns `undefined`.
-
-**Cause:** Incorrect attribute syntax.
-
-```typescript
-// ❌ Wrong - dot before @
-const orderNo = helpers.get(data, 'orders.order.@order-no');
-
-// ✅ Correct - NO dot before @
-const orderNo = helpers.get(data, 'orders.order@order-no');
-```
-
-**XML Attribute Syntax:**
-```xml
-<order order-no="123">
-```
-
-```typescript
-// Access attribute
-helpers.get(data, 'orders.order@order-no')  // => "123"
-
-// Access nested attribute
-helpers.get(data, 'orders.order.customer@id')  // => customer id
-```
-
----
-
-### Issue #8: Nested Object Not Created
-
-**Symptom:** `TypeError: Cannot set property 'ref' of undefined`
-
-**Cause:** Parent object not initialized.
-
-```typescript
-// ❌ Wrong - obj.input doesn't exist
-const obj = {};
-obj.input.ref = 'ORD-001';  // ERROR!
-
-// ✅ Correct - initialize parent
-const obj = {};
-obj.input = {};
-obj.input.ref = 'ORD-001';
-
-// ✅ Better - use helper
-helpers.set(obj, 'input.ref', 'ORD-001');
-// Creates: { input: { ref: 'ORD-001' } }
-```
-
-**Solution:** Use `helpers.set()` for nested paths or ensure parent objects exist.
-
----
-
-### Issue #9: Data Structure Mismatch
-
-**Symptom:** `undefined` when accessing expected field.
-
-**Debug Steps:**
-
-1. **Inspect actual structure:**
-```typescript
-console.log(JSON.stringify(data, null, 2));
-```
-
-2. **Check for common XML quirks:**
-- Attributes use `@` prefix: `order@order-no`
-- Text content uses `#text`: `customAttribute['#text']`
-- Single vs array: Use `ensureArray()`
-- Hyphenated keys: `'order-date'` not `'orderDate'`
-
-3. **Test path incrementally:**
-```typescript
-console.log(helpers.get(data, 'orders'));           // Does this exist?
-console.log(helpers.get(data, 'orders.order'));     // How about this?
-console.log(helpers.get(data, 'orders.order@order-no'));  // Final path
-```
-
----
-
-### Issue #10: "Cannot Read Property of Null"
-
-**Symptom:** `TypeError: Cannot read property 'X' of null`
-
-**Cause:** Not using safe accessors.
-
-```typescript
-// ❌ Unsafe - crashes if null
-const email = data.order.customer.email;
-
-// ✅ Safe - returns undefined
-const email = helpers.get(data, 'order.customer.email');
-
-// ✅ Safe with default
-const email = helpers.get(data, 'order.customer.email', 'unknown@example.com');
-```
-
-**Solution:** Always use `helpers.get()` for nested access.
-
----
-
-## Debugging Techniques
-
-### Technique #1: Enable Verbose Logging
-
-```typescript
-builder.field('input.totalPrice', (data, config, helpers) => {
-  helpers.log?.debug('Calculating total price', {
-    data: helpers.get(data, 'orders.order.totals'),
-    config
-  });
-
-  const grossPrice = helpers.get(data, 'orders.order.totals.order-total.gross-price');
-  helpers.log?.debug('Extracted gross price', { grossPrice });
-
-  const result = helpers.parseFloatSafe(grossPrice, 0);
-  helpers.log?.debug('Parsed result', { result });
-
-  return result;
-});
-```
-
-**Run with logging:**
-```typescript
-import { log } from '@versori/run';
-
-const logger = {
-  debug: (msg, meta) => log.debug(msg, meta),
-  info: (msg, meta) => log.info(msg, meta),
-  warn: (msg, meta) => log.warn(msg, meta),
-  error: (msg, meta) => log.error(msg, meta)
-};
-
-// Pass logger in helpers
-const helpers = { ...ResolverHelpers, log: logger };
-```
-
----
-
-### Technique #2: Test Resolvers in Isolation
-
-```typescript
-import { canonicalOrder } from '../../../03-PATTERN-GUIDES/examples/test-data/canonical-order.json';
-import { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
-import { orderResolvers } from './order-resolvers';
-
-// Test single resolver
-const config = { defaultRetailerId: '1' };
-const result = orderResolvers\['input.ref'](canonicalOrder, config, ResolverHelpers);
-
-console.log('Result:', result);
-console.log('Expected:', 'ORD-2025-001');
-console.log('Match:', result === 'ORD-2025-001');
-```
-
----
-
-### Technique #3: Add Debug Breakpoints
-
-```typescript
-builder.field('input.items', (data, config, helpers) => {
-  const items = helpers.get(data, 'orders.order.product-lineitems.product-lineitem');
-
-  debugger;  // Pause here in debugger
-
-  const itemsArray = helpers.ensureArray(items);
-
-  return itemsArray.map((item, index) => {
-    debugger;  // Pause for each item
-
-    return {
-      ref: item['@lineitem-id'],
-      quantity: helpers.parseIntSafe(item.quantity, 1)
-    };
-  });
-});
-```
-
-**Run with:**
-```bash
-node --inspect-brk your-script.js
-```
-
----
-
-### Technique #4: Compare Expected vs Actual
-
-```typescript
-const expected = {
-  ref: 'ORD-2025-001',
-  totalPrice: 151.17,
-  customer: { email: 'john.doe@example.com' }
-};
-
-const actual = {
-  ref: resolvers\['input.ref'](data, config, helpers),
-  totalPrice: resolvers\['input.totalPrice'](data, config, helpers),
-  customer: {
-    email: resolvers\['input.customer.email'](data, config, helpers)
-  }
-};
-
-console.log('Expected:', JSON.stringify(expected, null, 2));
-console.log('Actual:', JSON.stringify(actual, null, 2));
-
-// Find differences
-Object.keys(expected).forEach(key => {
-  if (JSON.stringify(expected[key]) !== JSON.stringify(actual[key])) {
-    console.log(`❌ Mismatch in ${key}:`, {
-      expected: expected[key],
-      actual: actual[key]
-    });
-  }
-});
-```
-
----
-
-### Technique #5: Use TypeScript for Type Safety
-
-```typescript
-import type { ResolverFunction } from '@fluentcommerce/fc-connect-sdk';
-
-interface OrderData {
-  orders: {
-    order: {
-      '@order-no': string;
-      'totals': {
-        'order-total': {
-          'gross-price': string;
-        };
-      };
-    };
-  };
-}
-
-const orderRefResolver: ResolverFunction = (data: OrderData, config, helpers) => {
-  // TypeScript will catch typos
-  return helpers.get(data, 'orders.order@order-no');
-};
-```
-
----
-
-## Error Patterns
-
-### Pattern #1: "Cannot Find Module"
-
-```
-Error: Cannot find module '@fluentcommerce/fc-connect-sdk'
-```
-
-**Solutions:**
-
-1. **Install SDK:**
-```bash
-npm install @fluentcommerce/fc-connect-sdk
-```
-
-2. **Link local SDK (development):**
-```bash
-cd fc-connect-sdk && npm link
-cd ../your-project && npm link @fluentcommerce/fc-connect-sdk
-```
-
-3. **Check package.json:**
-```json
-{
-  "dependencies": {
-    "@fluentcommerce/fc-connect-sdk": "^1.5.0"
-  }
-}
-```
-
----
-
-### Pattern #2: "Unexpected Token" in Resolver
-
-```
-SyntaxError: Unexpected token '.'
-```
-
-**Cause:** Trying to use optional chaining in older Node versions.
-
-```typescript
-// ❌ Optional chaining (requires Node 14+)
-const email = data.order?.customer?.email;
-
-// ✅ Use helpers.get() (works everywhere)
-const email = helpers.get(data, 'order.customer.email');
-```
-
----
-
-### Pattern #3: "Maximum Call Stack Size Exceeded"
-
-```
-RangeError: Maximum call stack size exceeded
-```
-
-**Cause:** Circular reference or infinite recursion.
-
-```typescript
-// ❌ Circular reference
-const obj = { a: {} };
-obj.a = obj;  // Circular!
-helpers.deepClone(obj);  // ERROR
-
-// ❌ Infinite recursion
-builder.field('input.ref', (data, config, helpers) => {
-  return resolvers\['input.ref'](data, config, helpers);  // Calls itself!
-});
-```
-
-**Solution:** Check for circular references and recursive calls.
-
----
-
-### Pattern #4: "Headers Already Sent"
-
-```
-Error: Cannot set headers after they are sent to the client
-```
-
-**Cause:** Multiple response attempts in Versori workflow.
-
-```typescript
-// ❌ Wrong - multiple returns
-export default async function process(activation) {
-  try {
-    const result = await processOrder(data);
-    return http.respond({ status: 200, body: result });
-  } catch (error) {
-    return http.respond({ status: 500, body: { error } });  // Second return!
-  }
-  return http.respond({ status: 200, body: 'done' });  // Third return!
-}
-
-// ✅ Correct - single return path
-export default async function process(activation) {
-  try {
-    const result = await processOrder(data);
-    return http.respond({ status: 200, body: result });
-  } catch (error) {
-    return http.respond({ status: 500, body: { error } });
-  }
-  // No additional return
-}
-```
-
----
-
-## Performance Problems
-
-### Problem #1: Slow Resolver Execution
-
-**Symptoms:**
-- Timeout errors
-- High latency
-- Memory issues
-
-**Common Causes:**
-
-#### Cause A: Not Using Memoization
-
-```typescript
-// ❌ Slow - recalculates every time
-builder.field('input.discount', (data, config, helpers) => {
-  const items = helpers.get(data, 'order.items', []);
-  return calculateComplexDiscount(items, config.rules);  // Expensive!
-});
-
-// ✅ Fast - caches result
-const memoizedCalculate = helpers.memoize(calculateComplexDiscount);
-
-builder.field('input.discount', (data, config, helpers) => {
-  const items = helpers.get(data, 'order.items', []);
-  return memoizedCalculate(items, config.rules);  // Cached!
-});
-```
-
----
-
-#### Cause B: Sequential Async Operations
-
-```typescript
-// ❌ Slow - sequential (waits for each)
-const customer = await lookupCustomer(id);
-const inventory = await checkInventory(sku);
-const pricing = await getPricing(sku);
-
-// ✅ Fast - parallel
-const [customer, inventory, pricing] = await Promise.all([
-  lookupCustomer(id),
-  checkInventory(sku),
-  getPricing(sku)
-]);
-```
-
----
-
-#### Cause C: Large Data Processing
-
-```typescript
-// ❌ Slow - processes all at once
-const results = await Promise.all(
-  items.map(item => enrichItem(item))  // 1000 items!
-);
-
-// ✅ Fast - batch processing
-const results = await helpers.batchProcess(
-  items,
-  async (item) => await enrichItem(item),
-  10  // Process 10 at a time
-);
-```
-
----
-
-### Problem #2: Memory Leaks
-
-**Cause:** Not cleaning up resources.
-
-```typescript
-// ❌ Memory leak - cache grows forever
-const cache = new Map();
-
-builder.field('input.enrichedData', async (data, config, helpers) => {
-  const key = data.id;
-  if (cache.has(key)) {
-    return cache.get(key);
-  }
-
-  const result = await fetchData(key);
-  cache.set(key, result);  // Never removed!
-  return result;
-});
-
-// ✅ Better - use LRU cache with max size
-import LRU from 'lru-cache';
-
-const cache = new LRU({ max: 100 });  // Max 100 entries
-
-builder.field('input.enrichedData', async (data, config, helpers) => {
-  const key = data.id;
-  if (cache.has(key)) {
-    return cache.get(key);
-  }
-
-  const result = await fetchData(key);
-  cache.set(key, result);  // Automatically evicts old entries
-  return result;
-});
-```
-
----
-
-## Testing Issues
-
-### Issue: Tests Failing with "undefined"
-
-**Cause:** Test data doesn't match expected structure.
-
-```typescript
-// ❌ Wrong - minimal test data
-const testData = {
-  order: {
-    orderNo: '123'
-  }
-};
-
-// ✅ Correct - use canonical data
-import { canonicalOrder } from '../../../03-PATTERN-GUIDES/examples/test-data/canonical-order.json';
-
-it('should extract order reference', () => {
-  const result = resolvers\['input.ref'](canonicalOrder, config, helpers);
-  expect(result).toBe('ORD-2025-001');
-});
-```
-
-**Solution:** Use canonical test data for consistency.
-
----
-
-### Issue: Mock Helpers Not Working
-
-**Cause:** Mock doesn't implement all required methods.
-
-```typescript
-// ❌ Incomplete mock
-const mockHelpers = {
-  get: jest.fn()
-};
-
-// ✅ Complete mock (or use real ResolverHelpers)
-import { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
-
-const mockHelpers = {
-  ...ResolverHelpers,
-  log: {
-    debug: jest.fn(),
-    info: jest.fn(),
-    warn: jest.fn(),
-    error: jest.fn()
-  }
-};
-```
-
----
-
-## Getting Help
-
-### Steps Before Asking for Help
-
-1. ✅ Check this troubleshooting guide
-2. ✅ Read the [Main Guide](./mapping-resolvers-resolver-guide.md)
-3. ✅ Review [API Reference](./mapping-resolvers-resolver-api-reference.md)
-4. ✅ Test with canonical data
-5. ✅ Enable debug logging
-6. ✅ Isolate the failing resolver
-
-### Provide This Information
-
-When asking for help, include:
-
-```markdown
-## Issue Description
-[Brief description of the problem]
-
-## Expected Behavior
-[What should happen]
-
-## Actual Behavior
-[What actually happens]
-
-## Minimal Reproducible Example
-\`\`\`typescript
-// Resolver code
-const resolver = (data, config, helpers) => {
-  // ...
-};
-
-// Test data
-const testData = { ... };
-
-// Config
-const config = { ... };
-
-// Error
-// [Error message and stack trace]
-\`\`\`
-
-## Environment
-- SDK Version: 1.5.0
-- Node Version: 18.0.0
-- Platform: Versori / Standalone
-```
-
-### Support Channels
-
-- **GitHub Issues:** https://github.com/fluentcommerce/fc-connect-sdk/issues
-- **Documentation:** https://docs.fluentcommerce.com
-- **Email:** support@fluentcommerce.com
-
----
-
-## See Also
-
-- [Main Resolver Guide](./mapping-resolvers-resolver-guide.md)
-- [API Reference](./mapping-resolvers-resolver-api-reference.md)
-- [Helper Functions Reference](./mapping-resolvers-resolver-helpers-reference.md)
-- [Parameters Reference](./mapping-resolvers-resolver-parameters-reference.md)
-- [Cookbook](./mapping-resolvers-resolver-cookbook.md)
-
----
-
-**Document Version:** 2.0.0
-**SDK Version:** 1.5.0+
-**Last Updated:** 2025-01-14
-
----
-
-**License:** MIT
-**Copyright:** © 2025 Fluent Commerce
+# Resolver Troubleshooting Guide
+
+**Common issues, solutions, and debugging tips**
+
+Version: 2.0.0
+Last Updated: 2025-01-14
+
+---
+
+## Table of Contents
+
+1. [Quick Diagnostics](#quick-diagnostics)
+2. [Common Issues](#common-issues)
+3. [Debugging Techniques](#debugging-techniques)
+4. [Error Patterns](#error-patterns)
+5. [Performance Problems](#performance-problems)
+6. [Testing Issues](#testing-issues)
+
+---
+
+## Quick Diagnostics
+
+### Checklist Before Debugging
+
+✅ **Check these first:**
+
+1. **Resolver registered?**
+   ```typescript
+   console.log(Object.keys(resolvers));
+   // Should include your resolver path
+   ```
+
+2. **Path correct?**
+   ```typescript
+   // If you want: { input: { ref: 'value' } }
+   // Use path: 'input.ref'
+   ```
+
+3. **Data structure matches?**
+   ```typescript
+   console.log(JSON.stringify(data, null, 2));
+   // Verify paths exist
+   ```
+
+4. **Helpers imported?**
+   ```typescript
+   import { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
+   const result = resolver(data, config, ResolverHelpers);
+   ```
+
+5. **Async resolved?**
+   ```typescript
+   const result = await resolver(...);  // Don't forget await!
+   ```
+
+---
+
+## Common Issues
+
+### Issue #1: Resolver Not Executing
+
+**Symptom:** Field is missing in output, no errors.
+
+**Possible Causes:**
+
+#### Cause A: Path Mismatch
+
+```typescript
+// ❌ Wrong path
+builder.from('ref', 'order.orderNo');
+// Creates: { ref: '...' }
+
+// ✅ Correct path for nested structure
+builder.from('input.ref', 'order.orderNo');
+// Creates: { input: { ref: '...' } }
+```
+
+**Solution:** Verify target path matches desired output structure.
+
+---
+
+#### Cause B: Resolver Not in Registry
+
+```typescript
+// ❌ Forgot to add to builder
+const resolvers = builder
+  .from('input.ref', 'order.orderNo')
+  .build();
+
+// Missing: .from('input.totalPrice', ...)
+```
+
+**Solution:** Check all resolvers are added before `.build()`.
+
+```typescript
+console.log(Object.keys(resolvers));
+// Should print: ['input.ref', 'input.totalPrice', ...]
+```
+
+---
+
+#### Cause C: Execution Order
+
+**Problem:** Resolver executes but value not set in output.
+
+```typescript
+// ❌ Not awaiting async resolver
+const result = resolver(data, config, helpers);  // Returns Promise
+console.log(result);  // Promise { <pending> }
+
+// ✅ Await async resolver
+const result = await resolver(data, config, helpers);
+console.log(result);  // Actual value
+```
+
+**Solution:** Always await async resolvers.
+
+---
+
+### Issue #2: `helpers.xxx is not a function`
+
+**Symptom:** `TypeError: helpers.parseFloatSafe is not a function`
+
+**Cause:** Helpers not passed correctly.
+
+```typescript
+// ❌ Wrong - empty object
+const result = resolver(data, config, {});
+
+// ❌ Wrong - undefined
+const result = resolver(data, config);
+
+// ✅ Correct - pass ResolverHelpers
+import { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
+const result = resolver(data, config, ResolverHelpers);
+```
+
+**Solution:** Always pass `ResolverHelpers` as the fourth parameter.
+
+---
+
+### Issue #3: Array Not Mapping Correctly
+
+**Symptom:** Getting single object instead of array, or empty array.
+
+#### Cause A: XML Single vs Multiple Elements
+
+XML parsers return:
+- **Single element** → Object
+- **Multiple elements** → Array
+
+```typescript
+// ❌ Breaks with single item
+const items = data.order.items.item;
+items.map(item => { ... });  // ERROR if items is object
+
+// ✅ Always works
+const items = helpers.ensureArray(data.order.items.item);
+items.map(item => { ... });
+```
+
+**Solution:** Always use `helpers.ensureArray()` when processing XML arrays.
+
+---
+
+#### Cause B: Wrong Source Path
+
+```typescript
+// ❌ Wrong path
+builder.mapArray('input.items', 'order.items', ...)
+// But actual path is: 'orders.order.product-lineitems.product-lineitem'
+
+// ✅ Correct path
+builder.mapArray(
+  'input.items',
+  'orders.order.product-lineitems.product-lineitem',
+  (item) => ({ ... })
+);
+```
+
+**Solution:** Verify source path with:
+```typescript
+console.log(helpers.get(data, 'orders.order.product-lineitems.product-lineitem'));
+```
+
+---
+
+### Issue #4: Validation Failing
+
+**Symptom:** `Error: Validation failed for input.email`
+
+**Debug Steps:**
+
+1. **Check the value:**
+```typescript
+builder.validate(
+  'input.email',
+  (data, config, helpers) => {
+    const email = helpers.get(data, 'customer.email');
+    console.log('Email value:', email);  // Debug
+    return email;
+  },
+  (value) => helpers.isValidEmail(value)
+);
+```
+
+2. **Make validation more lenient:**
+```typescript
+// Add default value
+builder.validate(
+  'input.email',
+  (data, config, helpers) => {
+    return helpers.get(data, 'customer.email', 'no-reply@example.com');
+  },
+  (value) => helpers.isValidEmail(value) || 'Email format invalid'
+);
+```
+
+3. **Check validation logic:**
+```typescript
+// Test validator separately
+const testEmail = 'test@example.com';
+console.log(helpers.isValidEmail(testEmail));  // Should be true
+```
+
+---
+
+### Issue #5: Config Not Available
+
+**Symptom:** `TypeError: Cannot read property 'defaultRetailerId' of undefined`
+
+**Cause:** Config not passed when executing resolvers.
+
+```typescript
+// ❌ Wrong - no config
+const result = resolvers\['input.ref'](data);
+
+// ✅ Correct - pass config
+const config = {
+  defaultRetailerId: '1',
+  defaultCurrency: 'USD'
+};
+const result = resolvers\['input.ref'](data, config, helpers);
+```
+
+**Solution:** Always pass config as second parameter.
+
+---
+
+### Issue #6: Async Resolver Not Awaiting
+
+**Symptom:** Promise returned instead of value.
+
+```typescript
+// ❌ Wrong - not awaiting
+const customerId = resolvers\['input.customer.id'](data, config, helpers);
+console.log(customerId);  // Promise { <pending> }
+
+// ✅ Correct - await async resolver
+const customerId = await resolvers\['input.customer.id'](data, config, helpers);
+console.log(customerId);  // Actual customer ID
+```
+
+**Solution:**
+- Mark your function `async`
+- Always `await` async resolvers
+- Check if resolver returns `Promise` in definition
+
+---
+
+### Issue #7: Path Not Resolving (XML Attributes)
+
+**Symptom:** XML attribute returns `undefined`.
+
+**Cause:** Incorrect attribute syntax.
+
+```typescript
+// ❌ Wrong - dot before @
+const orderNo = helpers.get(data, 'orders.order.@order-no');
+
+// ✅ Correct - NO dot before @
+const orderNo = helpers.get(data, 'orders.order@order-no');
+```
+
+**XML Attribute Syntax:**
+```xml
+<order order-no="123">
+```
+
+```typescript
+// Access attribute
+helpers.get(data, 'orders.order@order-no')  // => "123"
+
+// Access nested attribute
+helpers.get(data, 'orders.order.customer@id')  // => customer id
+```
+
+---
+
+### Issue #8: Nested Object Not Created
+
+**Symptom:** `TypeError: Cannot set property 'ref' of undefined`
+
+**Cause:** Parent object not initialized.
+
+```typescript
+// ❌ Wrong - obj.input doesn't exist
+const obj = {};
+obj.input.ref = 'ORD-001';  // ERROR!
+
+// ✅ Correct - initialize parent
+const obj = {};
+obj.input = {};
+obj.input.ref = 'ORD-001';
+
+// ✅ Better - use helper
+helpers.set(obj, 'input.ref', 'ORD-001');
+// Creates: { input: { ref: 'ORD-001' } }
+```
+
+**Solution:** Use `helpers.set()` for nested paths or ensure parent objects exist.
+
+---
+
+### Issue #9: Data Structure Mismatch
+
+**Symptom:** `undefined` when accessing expected field.
+
+**Debug Steps:**
+
+1. **Inspect actual structure:**
+```typescript
+console.log(JSON.stringify(data, null, 2));
+```
+
+2. **Check for common XML quirks:**
+- Attributes use `@` prefix: `order@order-no`
+- Text content uses `#text`: `customAttribute['#text']`
+- Single vs array: Use `ensureArray()`
+- Hyphenated keys: `'order-date'` not `'orderDate'`
+
+3. **Test path incrementally:**
+```typescript
+console.log(helpers.get(data, 'orders'));           // Does this exist?
+console.log(helpers.get(data, 'orders.order'));     // How about this?
+console.log(helpers.get(data, 'orders.order@order-no'));  // Final path
+```
+
+---
+
+### Issue #10: "Cannot Read Property of Null"
+
+**Symptom:** `TypeError: Cannot read property 'X' of null`
+
+**Cause:** Not using safe accessors.
+
+```typescript
+// ❌ Unsafe - crashes if null
+const email = data.order.customer.email;
+
+// ✅ Safe - returns undefined
+const email = helpers.get(data, 'order.customer.email');
+
+// ✅ Safe with default
+const email = helpers.get(data, 'order.customer.email', 'unknown@example.com');
+```
+
+**Solution:** Always use `helpers.get()` for nested access.
+
+---
+
+## Debugging Techniques
+
+### Technique #1: Enable Verbose Logging
+
+```typescript
+builder.field('input.totalPrice', (data, config, helpers) => {
+  helpers.log?.debug('Calculating total price', {
+    data: helpers.get(data, 'orders.order.totals'),
+    config
+  });
+
+  const grossPrice = helpers.get(data, 'orders.order.totals.order-total.gross-price');
+  helpers.log?.debug('Extracted gross price', { grossPrice });
+
+  const result = helpers.parseFloatSafe(grossPrice, 0);
+  helpers.log?.debug('Parsed result', { result });
+
+  return result;
+});
+```
+
+**Run with logging:**
+```typescript
+import { log } from '@versori/run';
+
+const logger = {
+  debug: (msg, meta) => log.debug(msg, meta),
+  info: (msg, meta) => log.info(msg, meta),
+  warn: (msg, meta) => log.warn(msg, meta),
+  error: (msg, meta) => log.error(msg, meta)
+};
+
+// Pass logger in helpers
+const helpers = { ...ResolverHelpers, log: logger };
+```
+
+---
+
+### Technique #2: Test Resolvers in Isolation
+
+```typescript
+import { canonicalOrder } from '../../../03-PATTERN-GUIDES/examples/test-data/canonical-order.json';
+import { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
+import { orderResolvers } from './order-resolvers';
+
+// Test single resolver
+const config = { defaultRetailerId: '1' };
+const result = orderResolvers\['input.ref'](canonicalOrder, config, ResolverHelpers);
+
+console.log('Result:', result);
+console.log('Expected:', 'ORD-2025-001');
+console.log('Match:', result === 'ORD-2025-001');
+```
+
+---
+
+### Technique #3: Add Debug Breakpoints
+
+```typescript
+builder.field('input.items', (data, config, helpers) => {
+  const items = helpers.get(data, 'orders.order.product-lineitems.product-lineitem');
+
+  debugger;  // Pause here in debugger
+
+  const itemsArray = helpers.ensureArray(items);
+
+  return itemsArray.map((item, index) => {
+    debugger;  // Pause for each item
+
+    return {
+      ref: item['@lineitem-id'],
+      quantity: helpers.parseIntSafe(item.quantity, 1)
+    };
+  });
+});
+```
+
+**Run with:**
+```bash
+node --inspect-brk your-script.js
+```
+
+---
+
+### Technique #4: Compare Expected vs Actual
+
+```typescript
+const expected = {
+  ref: 'ORD-2025-001',
+  totalPrice: 151.17,
+  customer: { email: 'john.doe@example.com' }
+};
+
+const actual = {
+  ref: resolvers\['input.ref'](data, config, helpers),
+  totalPrice: resolvers\['input.totalPrice'](data, config, helpers),
+  customer: {
+    email: resolvers\['input.customer.email'](data, config, helpers)
+  }
+};
+
+console.log('Expected:', JSON.stringify(expected, null, 2));
+console.log('Actual:', JSON.stringify(actual, null, 2));
+
+// Find differences
+Object.keys(expected).forEach(key => {
+  if (JSON.stringify(expected[key]) !== JSON.stringify(actual[key])) {
+    console.log(`❌ Mismatch in ${key}:`, {
+      expected: expected[key],
+      actual: actual[key]
+    });
+  }
+});
+```
+
+---
+
+### Technique #5: Use TypeScript for Type Safety
+
+```typescript
+import type { ResolverFunction } from '@fluentcommerce/fc-connect-sdk';
+
+interface OrderData {
+  orders: {
+    order: {
+      '@order-no': string;
+      'totals': {
+        'order-total': {
+          'gross-price': string;
+        };
+      };
+    };
+  };
+}
+
+const orderRefResolver: ResolverFunction = (data: OrderData, config, helpers) => {
+  // TypeScript will catch typos
+  return helpers.get(data, 'orders.order@order-no');
+};
+```
+
+---
+
+## Error Patterns
+
+### Pattern #1: "Cannot Find Module"
+
+```
+Error: Cannot find module '@fluentcommerce/fc-connect-sdk'
+```
+
+**Solutions:**
+
+1. **Install SDK:**
+```bash
+npm install @fluentcommerce/fc-connect-sdk
+```
+
+2. **Link local SDK (development):**
+```bash
+cd fc-connect-sdk && npm link
+cd ../your-project && npm link @fluentcommerce/fc-connect-sdk
+```
+
+3. **Check package.json:**
+```json
+{
+  "dependencies": {
+    "@fluentcommerce/fc-connect-sdk": "^1.5.0"
+  }
+}
+```
+
+---
+
+### Pattern #2: "Unexpected Token" in Resolver
+
+```
+SyntaxError: Unexpected token '.'
+```
+
+**Cause:** Trying to use optional chaining in older Node versions.
+
+```typescript
+// ❌ Optional chaining (requires Node 14+)
+const email = data.order?.customer?.email;
+
+// ✅ Use helpers.get() (works everywhere)
+const email = helpers.get(data, 'order.customer.email');
+```
+
+---
+
+### Pattern #3: "Maximum Call Stack Size Exceeded"
+
+```
+RangeError: Maximum call stack size exceeded
+```
+
+**Cause:** Circular reference or infinite recursion.
+
+```typescript
+// ❌ Circular reference
+const obj = { a: {} };
+obj.a = obj;  // Circular!
+helpers.deepClone(obj);  // ERROR
+
+// ❌ Infinite recursion
+builder.field('input.ref', (data, config, helpers) => {
+  return resolvers\['input.ref'](data, config, helpers);  // Calls itself!
+});
+```
+
+**Solution:** Check for circular references and recursive calls.
+
+---
+
+### Pattern #4: "Headers Already Sent"
+
+```
+Error: Cannot set headers after they are sent to the client
+```
+
+**Cause:** Multiple response attempts in Versori workflow.
+
+```typescript
+// ❌ Wrong - multiple returns
+export default async function process(activation) {
+  try {
+    const result = await processOrder(data);
+    return http.respond({ status: 200, body: result });
+  } catch (error) {
+    return http.respond({ status: 500, body: { error } });  // Second return!
+  }
+  return http.respond({ status: 200, body: 'done' });  // Third return!
+}
+
+// ✅ Correct - single return path
+export default async function process(activation) {
+  try {
+    const result = await processOrder(data);
+    return http.respond({ status: 200, body: result });
+  } catch (error) {
+    return http.respond({ status: 500, body: { error } });
+  }
+  // No additional return
+}
+```
+
+---
+
+## Performance Problems
+
+### Problem #1: Slow Resolver Execution
+
+**Symptoms:**
+- Timeout errors
+- High latency
+- Memory issues
+
+**Common Causes:**
+
+#### Cause A: Not Using Memoization
+
+```typescript
+// ❌ Slow - recalculates every time
+builder.field('input.discount', (data, config, helpers) => {
+  const items = helpers.get(data, 'order.items', []);
+  return calculateComplexDiscount(items, config.rules);  // Expensive!
+});
+
+// ✅ Fast - caches result
+const memoizedCalculate = helpers.memoize(calculateComplexDiscount);
+
+builder.field('input.discount', (data, config, helpers) => {
+  const items = helpers.get(data, 'order.items', []);
+  return memoizedCalculate(items, config.rules);  // Cached!
+});
+```
+
+---
+
+#### Cause B: Sequential Async Operations
+
+```typescript
+// ❌ Slow - sequential (waits for each)
+const customer = await lookupCustomer(id);
+const inventory = await checkInventory(sku);
+const pricing = await getPricing(sku);
+
+// ✅ Fast - parallel
+const [customer, inventory, pricing] = await Promise.all([
+  lookupCustomer(id),
+  checkInventory(sku),
+  getPricing(sku)
+]);
+```
+
+---
+
+#### Cause C: Large Data Processing
+
+```typescript
+// ❌ Slow - processes all at once
+const results = await Promise.all(
+  items.map(item => enrichItem(item))  // 1000 items!
+);
+
+// ✅ Fast - batch processing
+const results = await helpers.batchProcess(
+  items,
+  async (item) => await enrichItem(item),
+  10  // Process 10 at a time
+);
+```
+
+---
+
+### Problem #2: Memory Leaks
+
+**Cause:** Not cleaning up resources.
+
+```typescript
+// ❌ Memory leak - cache grows forever
+const cache = new Map();
+
+builder.field('input.enrichedData', async (data, config, helpers) => {
+  const key = data.id;
+  if (cache.has(key)) {
+    return cache.get(key);
+  }
+
+  const result = await fetchData(key);
+  cache.set(key, result);  // Never removed!
+  return result;
+});
+
+// ✅ Better - use LRU cache with max size
+import LRU from 'lru-cache';
+
+const cache = new LRU({ max: 100 });  // Max 100 entries
+
+builder.field('input.enrichedData', async (data, config, helpers) => {
+  const key = data.id;
+  if (cache.has(key)) {
+    return cache.get(key);
+  }
+
+  const result = await fetchData(key);
+  cache.set(key, result);  // Automatically evicts old entries
+  return result;
+});
+```
+
+---
+
+## Testing Issues
+
+### Issue: Tests Failing with "undefined"
+
+**Cause:** Test data doesn't match expected structure.
+
+```typescript
+// ❌ Wrong - minimal test data
+const testData = {
+  order: {
+    orderNo: '123'
+  }
+};
+
+// ✅ Correct - use canonical data
+import { canonicalOrder } from '../../../03-PATTERN-GUIDES/examples/test-data/canonical-order.json';
+
+it('should extract order reference', () => {
+  const result = resolvers\['input.ref'](canonicalOrder, config, helpers);
+  expect(result).toBe('ORD-2025-001');
+});
+```
+
+**Solution:** Use canonical test data for consistency.
+
+---
+
+### Issue: Mock Helpers Not Working
+
+**Cause:** Mock doesn't implement all required methods.
+
+```typescript
+// ❌ Incomplete mock
+const mockHelpers = {
+  get: jest.fn()
+};
+
+// ✅ Complete mock (or use real ResolverHelpers)
+import { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
+
+const mockHelpers = {
+  ...ResolverHelpers,
+  log: {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn()
+  }
+};
+```
+
+---
+
+## Getting Help
+
+### Steps Before Asking for Help
+
+1. ✅ Check this troubleshooting guide
+2. ✅ Read the [Main Guide](./mapping-resolvers-resolver-guide.md)
+3. ✅ Review [API Reference](./mapping-resolvers-resolver-api-reference.md)
+4. ✅ Test with canonical data
+5. ✅ Enable debug logging
+6. ✅ Isolate the failing resolver
+
+### Provide This Information
+
+When asking for help, include:
+
+```markdown
+## Issue Description
+[Brief description of the problem]
+
+## Expected Behavior
+[What should happen]
+
+## Actual Behavior
+[What actually happens]
+
+## Minimal Reproducible Example
+\`\`\`typescript
+// Resolver code
+const resolver = (data, config, helpers) => {
+  // ...
+};
+
+// Test data
+const testData = { ... };
+
+// Config
+const config = { ... };
+
+// Error
+// [Error message and stack trace]
+\`\`\`
+
+## Environment
+- SDK Version: 1.5.0
+- Node Version: 18.0.0
+- Platform: Versori / Standalone
+```
+
+### Support Channels
+
+- **GitHub Issues:** https://github.com/fluentcommerce/fc-connect-sdk/issues
+- **Documentation:** https://docs.fluentcommerce.com
+- **Email:** support@fluentcommerce.com
+
+---
+
+## See Also
+
+- [Main Resolver Guide](./mapping-resolvers-resolver-guide.md)
+- [API Reference](./mapping-resolvers-resolver-api-reference.md)
+- [Helper Functions Reference](./mapping-resolvers-resolver-helpers-reference.md)
+- [Parameters Reference](./mapping-resolvers-resolver-parameters-reference.md)
+- [Cookbook](./mapping-resolvers-resolver-cookbook.md)
+
+---
+
+**Document Version:** 2.0.0
+**SDK Version:** 1.5.0+
+**Last Updated:** 2025-01-14
+
+---
+
+**License:** MIT
+**Copyright:** © 2025 Fluent Commerce