@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-08-custom-resolvers.md

@@ -1,544 +1,544 @@
-# Custom Resolvers
-
-[← Back to GraphQL Mutation Mapping Guide](../graphql-mutation-mapping-readme.md)
-
-**Module 8 of 13** | **Level**: Advanced | **Time**: 20 minutes
-
----
-
-## Custom Resolvers
-
-**For GraphQL mutation mapping, use custom resolver functions.** Resolvers provide full access to source data, helper functions, and async operations.
-
-**⚠️ CRITICAL:** Custom resolvers **ONLY work with `mapWithNodes()`**. The `map()` method does **NOT** accept a resolvers parameter. If you need custom resolvers, you must use `mapWithNodes()`.
-
-### Why Resolvers?
-
-- ✅ Access full source data context via `helpers.get(data, 'any.path')`
-- ✅ 57 helper functions (parseIntSafe, formatDate, groupBy, getXmlAttribute, getXmlTextContent, normalizeEmpty, etc.)
-- ✅ Async operations (API calls, database lookups)
-- ✅ Complex business logic and conditional transformations
-- ✅ Better testability and maintainability
-
-### Resolver Example
-
-**Mapping configuration:**
-
-```json
-{
-  "quantity": {
-    "source": "qty",
-    "resolver": "custom.parseQuantity"
-  },
-  "customer.id": {
-    "resolver": "custom.lookupOrCreateCustomer"
-  }
-}
-```
-
-**Resolver implementation:**
-
-```typescript
-import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-
-// Define custom resolvers (Record<string, Function>)
-const customResolvers = {
-  // Simple transformation
-  'custom.parseQuantity': (value, data, config, helpers) => {
-    void data; void config; // Unused parameters
-    return helpers.parseIntSafe(value, 0);
-  },
-
-  // Complex logic with data access
-  'custom.calculateTotal': (value, data, config, helpers) => {
-    void value; void config; // Unused parameters
-    const items = helpers.ensureArray(helpers.get(data, 'order.items.item'));
-    return items.reduce(
-      (sum, item) =>
-        sum + helpers.parseFloatSafe(item.price, 0) * helpers.parseIntSafe(item.quantity, 0),
-      0
-    );
-  },
-
-  // Async operations
-  'custom.lookupOrCreateCustomer': async (value, data, config, helpers) => {
-    void value; void config; // Unused parameters
-    const customerId = helpers.get(data, 'order.customer.id');
-
-    // Query Fluent API
-    const existing = await helpers.fluentClient.graphql({
-      query: `query { customers(id: "${customerId}") { id } }`,
-    });
-
-    if (existing.data?.customers?.length > 0) {
-      return existing.data.customers[0].id;
-    }
-
-    // Create new customer
-    const created = await helpers.fluentClient.graphql({
-      query: `mutation { createCustomer(input: { id: "${customerId}" }) { id } }`,
-    });
-
-    return created.data?.createCustomer?.id;
-  },
-};
-
-// ✅ CORRECT: Resolvers in constructor (primary pattern - consistent with UniversalMapper)
-const mapper = new GraphQLMutationMapper(
-  mappingConfig, 
-  logger,
-  { 
-    customResolvers, // Resolvers registered in constructor
-    fluentClient: fluentClient 
-  }
-);
-
-// Pass resolverContext with config - resolvers access via helpers.context.config
-const resolverContext = {
-  fluentClient,
-  config: {
-    retailerId: '1',
-    defaultOrderType: 'HD'
-  }
-};
-const result = await mapper.mapWithNodes(xmlData, undefined, resolverContext);
-// Constructor resolvers are automatically used
-// Resolvers can access config via helpers.context.config or config parameter
-
-// ✅ CORRECT: Method call resolvers override constructor resolvers (for per-call customization)
-const mapper = new GraphQLMutationMapper(
-  mappingConfig, 
-  logger,
-  { 
-    customResolvers: baseResolvers, // Base resolvers in constructor
-    fluentClient: fluentClient 
-  }
-);
-const result = await mapper.mapWithNodes(xmlData, overrideResolvers, { fluentClient });
-// overrideResolvers take precedence over baseResolvers
-
-// ❌ WRONG: map() does NOT accept custom resolvers parameter
-// const payload = await mapper.map(xmlData, customResolvers); // ❌ This will fail!
-// const exec = await fluentClient.graphql(payload);
-```
-
-## Available Helper Functions
-
-Resolvers have access to 57 helper functions:
-
-### Data Access
-
-**`get(obj, path)`** - Safe path resolution
-
-```typescript
-const email = helpers.get(data, 'order.customer.email');
-const firstItemSku = helpers.get(data, 'order.items[0].sku');
-```
-
-**`set(obj, path, value)`** - Set nested values
-
-```typescript
-helpers.set(data, 'order.calculatedTotal', 199.99);
-```
-
-**`ensureArray(value)`** - Normalize to array
-
-```typescript
-const items = helpers.ensureArray(helpers.get(data, 'order.items.item'));
-// Single object → [object]
-// Array → array (unchanged)
-// null/undefined → []
-```
-
-### Parsing
-
-**`parseIntSafe(value, default)`** - Safe integer parsing
-
-```typescript
-const quantity = helpers.parseIntSafe(value, 0);
-// "123" → 123
-// "abc" → 0 (default)
-// null → 0 (default)
-```
-
-**`parseFloatSafe(value, default)`** - Safe float parsing
-
-```typescript
-const price = helpers.parseFloatSafe(value, 0.0);
-// "19.99" → 19.99
-// "abc" → 0.0 (default)
-```
-
-**`safeJsonParse(str, default)`** - Safe JSON parsing
-
-```typescript
-const metadata = helpers.safeJsonParse(value, {});
-// Valid JSON → parsed object
-// Invalid JSON → {} (default)
-```
-
-### String Operations
-
-**`trim(str)`** - Remove whitespace
-
-```typescript
-const clean = helpers.trim(value);
-```
-
-**`truncate(str, len)`** - Truncate to length
-
-```typescript
-const short = helpers.truncate(value, 100);
-```
-
-**`normalizeWhitespace(str)`** - Normalize multiple spaces
-
-```typescript
-const normalized = helpers.normalizeWhitespace('Hello    World');
-// → "Hello World"
-```
-
-**`toCamelCase(str)`**, **`toSnakeCase(str)`**, **`slugify(str)`** - Case conversion
-
-```typescript
-helpers.toCamelCase('first-name'); // → "firstName"
-helpers.toSnakeCase('firstName'); // → "first_name"
-helpers.slugify('Product Name!'); // → "product-name"
-```
-
-**`template(str, vars)`** - String interpolation
-
-```typescript
-const message = helpers.template('Order {orderNo} for {customer}', {
-  orderNo: 'ORD-123',
-  customer: 'John Doe',
-});
-// → "Order ORD-123 for John Doe"
-```
-
-### Array Operations
-
-**`groupBy(arr, key)`** - Group array by key
-
-```typescript
-const byStatus = helpers.groupBy(orders, 'status');
-// → { OPEN: [...], CLOSED: [...] }
-```
-
-**`keyBy(arr, key)`** - Index array by key
-
-```typescript
-const byId = helpers.keyBy(items, 'id');
-// → { "123": {...}, "456": {...} }
-```
-
-**`chunk(arr, size)`** - Split into chunks
-
-```typescript
-const batches = helpers.chunk(items, 10);
-// → [[1..10], [11..20], ...]
-```
-
-**`unique(arr, key)`** - Remove duplicates
-
-```typescript
-const uniqueSkus = helpers.unique(items, 'sku');
-```
-
-**`sortBy(arr, key)`** - Sort by key
-
-```typescript
-const sorted = helpers.sortBy(items, 'price');
-```
-
-**`compact(arr)`** - Remove falsy values
-
-```typescript
-const clean = helpers.compact([1, null, 2, undefined, 3]);
-// → [1, 2, 3]
-```
-
-**`sum(arr, key)`**, **`avg(arr, key)`**, **`min(arr)`**, **`max(arr)`** - Array math
-
-```typescript
-const total = helpers.sum(items, 'price');
-const average = helpers.avg(items, 'quantity');
-const lowest = helpers.min(prices);
-const highest = helpers.max(prices);
-```
-
-### Date Operations
-
-**`formatDate(date)`** - Format to ISO 8601
-
-```typescript
-const formatted = helpers.formatDate(new Date());
-// → "2025-10-19T12:00:00Z"
-```
-
-**`parseDate(str)`** - Parse date string
-
-```typescript
-const date = helpers.parseDate('2025-10-19');
-```
-
-**`addDays(date, n)`**, **`subtractDays(date, n)`** - Date arithmetic
-
-```typescript
-const future = helpers.addDays(new Date(), 7);
-const past = helpers.subtractDays(new Date(), 30);
-```
-
-**`dateDiff(d1, d2)`** - Difference in days
-
-```typescript
-const days = helpers.dateDiff(endDate, startDate);
-```
-
-### Validation
-
-**`isValidEmail(str)`** - Email validation
-
-```typescript
-if (helpers.isValidEmail(email)) {
-  // Valid email
-}
-```
-
-**`requireField(value, name)`** - Throw if missing
-
-```typescript
-helpers.requireField(value, 'customerId');
-// Throws if value is null/undefined/empty
-```
-
-**`isString(val)`**, **`isNumber(val)`**, **`isArray(val)`**, **`isObject(val)`** - Type checking
-
-```typescript
-if (helpers.isArray(value)) {
-  // Handle array
-}
-```
-
-### Utilities
-
-**`deepClone(obj)`** - Deep copy
-
-```typescript
-const copy = helpers.deepClone(original);
-```
-
-**`deepMerge(obj1, obj2)`** - Deep merge
-
-```typescript
-const merged = helpers.deepMerge(defaults, overrides);
-```
-
-**`pick(obj, keys)`**, **`omit(obj, keys)`** - Select/exclude keys
-
-```typescript
-const subset = helpers.pick(order, ['id', 'ref', 'status']);
-const cleaned = helpers.omit(order, ['internalField']);
-```
-
-**`merge(...objs)`** - Shallow merge
-
-```typescript
-const combined = helpers.merge(obj1, obj2, obj3);
-```
-
-**`coalesce(...values)`** - First non-null value
-
-```typescript
-const value = helpers.coalesce(null, undefined, 'default');
-// → "default"
-```
-
-**`defaultTo(value, default)`** - Default value
-
-```typescript
-const quantity = helpers.defaultTo(value, 1);
-```
-
-**`retry(fn, maxRetries)`** - Retry async function
-
-```typescript
-const result = await helpers.retry(async () => {
-  return await api.call();
-}, 3);
-```
-
-**`batchProcess(items, fn)`** - Process in batches
-
-```typescript
-await helpers.batchProcess(items, async batch => {
-  await processBatch(batch);
-});
-```
-
-## Accessing Runtime Configuration
-
-**Important:** When you pass `resolverContext` to `mapWithNodes()`, resolvers can access it via `helpers.context`.
-
-**Example: Accessing retailerId from resolverContext**
-
-```typescript
-// Pass config in resolverContext
-const resolverContext = {
-  fluentClient,
-  config: {
-    retailerId: '1',
-    defaultOrderType: 'HD',
-    defaultCountry: 'US'
-  }
-};
-
-const result = await mapper.mapWithNodes(xmlData, undefined, resolverContext);
-```
-
-**In your custom resolver:**
-
-```typescript
-const customResolvers = {
-  'custom.getRetailerId': (value, sourceData, config, helpers) => {
-    // Access resolverContext.config via helpers.context.config
-    return helpers.context?.config?.retailerId || config?.retailerId;
-  },
-  
-  'custom.getOrderType': (value, sourceData, config, helpers) => {
-    // Access nested config values
-    return helpers.context?.config?.defaultOrderType || 'STANDARD';
-  }
-};
-```
-
-**In your mapping config JSON:**
-
-```json
-{
-  "fields": {
-    "retailer": {
-      "fields": {
-        "id": {
-          "resolver": "custom.getRetailerId",
-          "required": true
-        }
-      }
-    },
-    "type": {
-      "resolver": "custom.getOrderType"
-    }
-  }
-}
-```
-
-**Note:** The `config` parameter (3rd param) and `helpers.context.config` both reference the same `resolverContext.config` object. Use whichever is more convenient.
-
----
-
-## Resolver Patterns
-
-### Pattern 1: Data Enrichment
-
-```typescript
-'custom.enrichProduct': async (value, data, config, helpers) => {
-  const sku = helpers.get(data, 'item.sku');
-
-  // Lookup product details from API
-  const product = await helpers.fluentClient.graphql({
-    query: `query { products(sku: "${sku}") { id name category } }`
-  });
-
-  return {
-    sku,
-    productId: product.data.products[0].id,
-    name: product.data.products[0].name
-  };
-}
-```
-
-### Pattern 2: Conditional Logic
-
-```typescript
-'custom.determineOrderType': (value, data, config, helpers) => {
-  const totalPrice = helpers.parseFloatSafe(
-    helpers.get(data, 'order.total'),
-    0
-  );
-
-  const isExpress = helpers.get(data, 'order.shipping.express') === 'true';
-
-  if (isExpress) {
-    return 'EXPRESS';
-  } else if (totalPrice > 1000) {
-    return 'PREMIUM';
-  } else {
-    return 'STANDARD';
-  }
-}
-```
-
-### Pattern 3: Complex Calculations
-
-```typescript
-'custom.calculateOrderTotal': (value, data, config, helpers) => {
-  const items = helpers.ensureArray(helpers.get(data, 'order.items.item'));
-
-  const subtotal = helpers.sum(items.map(item => ({
-    total: helpers.parseFloatSafe(item.price, 0) *
-           helpers.parseIntSafe(item.quantity, 0)
-  })), 'total');
-
-  const taxRate = helpers.parseFloatSafe(
-    helpers.get(data, 'order.taxRate'),
-    0.1
-  );
-
-  const shippingCost = helpers.parseFloatSafe(
-    helpers.get(data, 'order.shipping.cost'),
-    0
-  );
-
-  return subtotal * (1 + taxRate) + shippingCost;
-}
-```
-
-### Pattern 4: Error Handling
-
-```typescript
-'custom.safeParseCustomer': (value, data, config, helpers) => {
-  try {
-    const customerId = helpers.requireField(
-      helpers.get(data, 'order.customer.id'),
-      'customerId'
-    );
-
-    const email = helpers.get(data, 'order.customer.email');
-    if (!helpers.isValidEmail(email)) {
-      throw new Error('Invalid customer email');
-    }
-
-    return {
-      id: customerId,
-      email: email.toLowerCase()
-    };
-
-  } catch (error) {
-    helpers.logger.error('Failed to parse customer:', error);
-    throw error;
-  }
-}
-```
-
----
-
-## Navigation
-
-[← Previous: Array Handling](./graphql-mutation-mapping-07-array-handling.md) | [Back to Guide](../graphql-mutation-mapping-readme.md) | [Next: Advanced Patterns →](./graphql-mutation-mapping-09-advanced-patterns.md)
-
-## Related Documentation
-
-- [Resolver Helpers Reference](../../../mapping/resolvers/mapping-resolvers-resolver-helpers-reference.md) - Complete helper function documentation
-- [Module 09: Advanced Patterns](./graphql-mutation-mapping-09-advanced-patterns.md) - Advanced resolver use cases
-- [Module 10: Hooks and Variables](./graphql-mutation-mapping-10-hooks-and-variables.md) - Pre/post-processing hooks
-- [API Reference](../../../api-reference/api-reference-readme.md) - Complete API documentation
+# Custom Resolvers
+
+[← Back to GraphQL Mutation Mapping Guide](../graphql-mutation-mapping-readme.md)
+
+**Module 8 of 13** | **Level**: Advanced | **Time**: 20 minutes
+
+---
+
+## Custom Resolvers
+
+**For GraphQL mutation mapping, use custom resolver functions.** Resolvers provide full access to source data, helper functions, and async operations.
+
+**⚠️ CRITICAL:** Custom resolvers **ONLY work with `mapWithNodes()`**. The `map()` method does **NOT** accept a resolvers parameter. If you need custom resolvers, you must use `mapWithNodes()`.
+
+### Why Resolvers?
+
+- ✅ Access full source data context via `helpers.get(data, 'any.path')`
+- ✅ 57 helper functions (parseIntSafe, formatDate, groupBy, getXmlAttribute, getXmlTextContent, normalizeEmpty, etc.)
+- ✅ Async operations (API calls, database lookups)
+- ✅ Complex business logic and conditional transformations
+- ✅ Better testability and maintainability
+
+### Resolver Example
+
+**Mapping configuration:**
+
+```json
+{
+  "quantity": {
+    "source": "qty",
+    "resolver": "custom.parseQuantity"
+  },
+  "customer.id": {
+    "resolver": "custom.lookupOrCreateCustomer"
+  }
+}
+```
+
+**Resolver implementation:**
+
+```typescript
+import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+
+// Define custom resolvers (Record<string, Function>)
+const customResolvers = {
+  // Simple transformation
+  'custom.parseQuantity': (value, data, config, helpers) => {
+    void data; void config; // Unused parameters
+    return helpers.parseIntSafe(value, 0);
+  },
+
+  // Complex logic with data access
+  'custom.calculateTotal': (value, data, config, helpers) => {
+    void value; void config; // Unused parameters
+    const items = helpers.ensureArray(helpers.get(data, 'order.items.item'));
+    return items.reduce(
+      (sum, item) =>
+        sum + helpers.parseFloatSafe(item.price, 0) * helpers.parseIntSafe(item.quantity, 0),
+      0
+    );
+  },
+
+  // Async operations
+  'custom.lookupOrCreateCustomer': async (value, data, config, helpers) => {
+    void value; void config; // Unused parameters
+    const customerId = helpers.get(data, 'order.customer.id');
+
+    // Query Fluent API
+    const existing = await helpers.fluentClient.graphql({
+      query: `query { customers(id: "${customerId}") { id } }`,
+    });
+
+    if (existing.data?.customers?.length > 0) {
+      return existing.data.customers[0].id;
+    }
+
+    // Create new customer
+    const created = await helpers.fluentClient.graphql({
+      query: `mutation { createCustomer(input: { id: "${customerId}" }) { id } }`,
+    });
+
+    return created.data?.createCustomer?.id;
+  },
+};
+
+// ✅ CORRECT: Resolvers in constructor (primary pattern - consistent with UniversalMapper)
+const mapper = new GraphQLMutationMapper(
+  mappingConfig, 
+  logger,
+  { 
+    customResolvers, // Resolvers registered in constructor
+    fluentClient: fluentClient 
+  }
+);
+
+// Pass resolverContext with config - resolvers access via helpers.context.config
+const resolverContext = {
+  fluentClient,
+  config: {
+    retailerId: '1',
+    defaultOrderType: 'HD'
+  }
+};
+const result = await mapper.mapWithNodes(xmlData, undefined, resolverContext);
+// Constructor resolvers are automatically used
+// Resolvers can access config via helpers.context.config or config parameter
+
+// ✅ CORRECT: Method call resolvers override constructor resolvers (for per-call customization)
+const mapper = new GraphQLMutationMapper(
+  mappingConfig, 
+  logger,
+  { 
+    customResolvers: baseResolvers, // Base resolvers in constructor
+    fluentClient: fluentClient 
+  }
+);
+const result = await mapper.mapWithNodes(xmlData, overrideResolvers, { fluentClient });
+// overrideResolvers take precedence over baseResolvers
+
+// ❌ WRONG: map() does NOT accept custom resolvers parameter
+// const payload = await mapper.map(xmlData, customResolvers); // ❌ This will fail!
+// const exec = await fluentClient.graphql(payload);
+```
+
+## Available Helper Functions
+
+Resolvers have access to 57 helper functions:
+
+### Data Access
+
+**`get(obj, path)`** - Safe path resolution
+
+```typescript
+const email = helpers.get(data, 'order.customer.email');
+const firstItemSku = helpers.get(data, 'order.items[0].sku');
+```
+
+**`set(obj, path, value)`** - Set nested values
+
+```typescript
+helpers.set(data, 'order.calculatedTotal', 199.99);
+```
+
+**`ensureArray(value)`** - Normalize to array
+
+```typescript
+const items = helpers.ensureArray(helpers.get(data, 'order.items.item'));
+// Single object → [object]
+// Array → array (unchanged)
+// null/undefined → []
+```
+
+### Parsing
+
+**`parseIntSafe(value, default)`** - Safe integer parsing
+
+```typescript
+const quantity = helpers.parseIntSafe(value, 0);
+// "123" → 123
+// "abc" → 0 (default)
+// null → 0 (default)
+```
+
+**`parseFloatSafe(value, default)`** - Safe float parsing
+
+```typescript
+const price = helpers.parseFloatSafe(value, 0.0);
+// "19.99" → 19.99
+// "abc" → 0.0 (default)
+```
+
+**`safeJsonParse(str, default)`** - Safe JSON parsing
+
+```typescript
+const metadata = helpers.safeJsonParse(value, {});
+// Valid JSON → parsed object
+// Invalid JSON → {} (default)
+```
+
+### String Operations
+
+**`trim(str)`** - Remove whitespace
+
+```typescript
+const clean = helpers.trim(value);
+```
+
+**`truncate(str, len)`** - Truncate to length
+
+```typescript
+const short = helpers.truncate(value, 100);
+```
+
+**`normalizeWhitespace(str)`** - Normalize multiple spaces
+
+```typescript
+const normalized = helpers.normalizeWhitespace('Hello    World');
+// → "Hello World"
+```
+
+**`toCamelCase(str)`**, **`toSnakeCase(str)`**, **`slugify(str)`** - Case conversion
+
+```typescript
+helpers.toCamelCase('first-name'); // → "firstName"
+helpers.toSnakeCase('firstName'); // → "first_name"
+helpers.slugify('Product Name!'); // → "product-name"
+```
+
+**`template(str, vars)`** - String interpolation
+
+```typescript
+const message = helpers.template('Order {orderNo} for {customer}', {
+  orderNo: 'ORD-123',
+  customer: 'John Doe',
+});
+// → "Order ORD-123 for John Doe"
+```
+
+### Array Operations
+
+**`groupBy(arr, key)`** - Group array by key
+
+```typescript
+const byStatus = helpers.groupBy(orders, 'status');
+// → { OPEN: [...], CLOSED: [...] }
+```
+
+**`keyBy(arr, key)`** - Index array by key
+
+```typescript
+const byId = helpers.keyBy(items, 'id');
+// → { "123": {...}, "456": {...} }
+```
+
+**`chunk(arr, size)`** - Split into chunks
+
+```typescript
+const batches = helpers.chunk(items, 10);
+// → [[1..10], [11..20], ...]
+```
+
+**`unique(arr, key)`** - Remove duplicates
+
+```typescript
+const uniqueSkus = helpers.unique(items, 'sku');
+```
+
+**`sortBy(arr, key)`** - Sort by key
+
+```typescript
+const sorted = helpers.sortBy(items, 'price');
+```
+
+**`compact(arr)`** - Remove falsy values
+
+```typescript
+const clean = helpers.compact([1, null, 2, undefined, 3]);
+// → [1, 2, 3]
+```
+
+**`sum(arr, key)`**, **`avg(arr, key)`**, **`min(arr)`**, **`max(arr)`** - Array math
+
+```typescript
+const total = helpers.sum(items, 'price');
+const average = helpers.avg(items, 'quantity');
+const lowest = helpers.min(prices);
+const highest = helpers.max(prices);
+```
+
+### Date Operations
+
+**`formatDate(date)`** - Format to ISO 8601
+
+```typescript
+const formatted = helpers.formatDate(new Date());
+// → "2025-10-19T12:00:00Z"
+```
+
+**`parseDate(str)`** - Parse date string
+
+```typescript
+const date = helpers.parseDate('2025-10-19');
+```
+
+**`addDays(date, n)`**, **`subtractDays(date, n)`** - Date arithmetic
+
+```typescript
+const future = helpers.addDays(new Date(), 7);
+const past = helpers.subtractDays(new Date(), 30);
+```
+
+**`dateDiff(d1, d2)`** - Difference in days
+
+```typescript
+const days = helpers.dateDiff(endDate, startDate);
+```
+
+### Validation
+
+**`isValidEmail(str)`** - Email validation
+
+```typescript
+if (helpers.isValidEmail(email)) {
+  // Valid email
+}
+```
+
+**`requireField(value, name)`** - Throw if missing
+
+```typescript
+helpers.requireField(value, 'customerId');
+// Throws if value is null/undefined/empty
+```
+
+**`isString(val)`**, **`isNumber(val)`**, **`isArray(val)`**, **`isObject(val)`** - Type checking
+
+```typescript
+if (helpers.isArray(value)) {
+  // Handle array
+}
+```
+
+### Utilities
+
+**`deepClone(obj)`** - Deep copy
+
+```typescript
+const copy = helpers.deepClone(original);
+```
+
+**`deepMerge(obj1, obj2)`** - Deep merge
+
+```typescript
+const merged = helpers.deepMerge(defaults, overrides);
+```
+
+**`pick(obj, keys)`**, **`omit(obj, keys)`** - Select/exclude keys
+
+```typescript
+const subset = helpers.pick(order, ['id', 'ref', 'status']);
+const cleaned = helpers.omit(order, ['internalField']);
+```
+
+**`merge(...objs)`** - Shallow merge
+
+```typescript
+const combined = helpers.merge(obj1, obj2, obj3);
+```
+
+**`coalesce(...values)`** - First non-null value
+
+```typescript
+const value = helpers.coalesce(null, undefined, 'default');
+// → "default"
+```
+
+**`defaultTo(value, default)`** - Default value
+
+```typescript
+const quantity = helpers.defaultTo(value, 1);
+```
+
+**`retry(fn, maxRetries)`** - Retry async function
+
+```typescript
+const result = await helpers.retry(async () => {
+  return await api.call();
+}, 3);
+```
+
+**`batchProcess(items, fn)`** - Process in batches
+
+```typescript
+await helpers.batchProcess(items, async batch => {
+  await processBatch(batch);
+});
+```
+
+## Accessing Runtime Configuration
+
+**Important:** When you pass `resolverContext` to `mapWithNodes()`, resolvers can access it via `helpers.context`.
+
+**Example: Accessing retailerId from resolverContext**
+
+```typescript
+// Pass config in resolverContext
+const resolverContext = {
+  fluentClient,
+  config: {
+    retailerId: '1',
+    defaultOrderType: 'HD',
+    defaultCountry: 'US'
+  }
+};
+
+const result = await mapper.mapWithNodes(xmlData, undefined, resolverContext);
+```
+
+**In your custom resolver:**
+
+```typescript
+const customResolvers = {
+  'custom.getRetailerId': (value, sourceData, config, helpers) => {
+    // Access resolverContext.config via helpers.context.config
+    return helpers.context?.config?.retailerId || config?.retailerId;
+  },
+  
+  'custom.getOrderType': (value, sourceData, config, helpers) => {
+    // Access nested config values
+    return helpers.context?.config?.defaultOrderType || 'STANDARD';
+  }
+};
+```
+
+**In your mapping config JSON:**
+
+```json
+{
+  "fields": {
+    "retailer": {
+      "fields": {
+        "id": {
+          "resolver": "custom.getRetailerId",
+          "required": true
+        }
+      }
+    },
+    "type": {
+      "resolver": "custom.getOrderType"
+    }
+  }
+}
+```
+
+**Note:** The `config` parameter (3rd param) and `helpers.context.config` both reference the same `resolverContext.config` object. Use whichever is more convenient.
+
+---
+
+## Resolver Patterns
+
+### Pattern 1: Data Enrichment
+
+```typescript
+'custom.enrichProduct': async (value, data, config, helpers) => {
+  const sku = helpers.get(data, 'item.sku');
+
+  // Lookup product details from API
+  const product = await helpers.fluentClient.graphql({
+    query: `query { products(sku: "${sku}") { id name category } }`
+  });
+
+  return {
+    sku,
+    productId: product.data.products[0].id,
+    name: product.data.products[0].name
+  };
+}
+```
+
+### Pattern 2: Conditional Logic
+
+```typescript
+'custom.determineOrderType': (value, data, config, helpers) => {
+  const totalPrice = helpers.parseFloatSafe(
+    helpers.get(data, 'order.total'),
+    0
+  );
+
+  const isExpress = helpers.get(data, 'order.shipping.express') === 'true';
+
+  if (isExpress) {
+    return 'EXPRESS';
+  } else if (totalPrice > 1000) {
+    return 'PREMIUM';
+  } else {
+    return 'STANDARD';
+  }
+}
+```
+
+### Pattern 3: Complex Calculations
+
+```typescript
+'custom.calculateOrderTotal': (value, data, config, helpers) => {
+  const items = helpers.ensureArray(helpers.get(data, 'order.items.item'));
+
+  const subtotal = helpers.sum(items.map(item => ({
+    total: helpers.parseFloatSafe(item.price, 0) *
+           helpers.parseIntSafe(item.quantity, 0)
+  })), 'total');
+
+  const taxRate = helpers.parseFloatSafe(
+    helpers.get(data, 'order.taxRate'),
+    0.1
+  );
+
+  const shippingCost = helpers.parseFloatSafe(
+    helpers.get(data, 'order.shipping.cost'),
+    0
+  );
+
+  return subtotal * (1 + taxRate) + shippingCost;
+}
+```
+
+### Pattern 4: Error Handling
+
+```typescript
+'custom.safeParseCustomer': (value, data, config, helpers) => {
+  try {
+    const customerId = helpers.requireField(
+      helpers.get(data, 'order.customer.id'),
+      'customerId'
+    );
+
+    const email = helpers.get(data, 'order.customer.email');
+    if (!helpers.isValidEmail(email)) {
+      throw new Error('Invalid customer email');
+    }
+
+    return {
+      id: customerId,
+      email: email.toLowerCase()
+    };
+
+  } catch (error) {
+    helpers.logger.error('Failed to parse customer:', error);
+    throw error;
+  }
+}
+```
+
+---
+
+## Navigation
+
+[← Previous: Array Handling](./graphql-mutation-mapping-07-array-handling.md) | [Back to Guide](../graphql-mutation-mapping-readme.md) | [Next: Advanced Patterns →](./graphql-mutation-mapping-09-advanced-patterns.md)
+
+## Related Documentation
+
+- [Resolver Helpers Reference](../../../mapping/resolvers/mapping-resolvers-resolver-helpers-reference.md) - Complete helper function documentation
+- [Module 09: Advanced Patterns](./graphql-mutation-mapping-09-advanced-patterns.md) - Advanced resolver use cases
+- [Module 10: Hooks and Variables](./graphql-mutation-mapping-10-hooks-and-variables.md) - Pre/post-processing hooks
+- [API Reference](../../../api-reference/api-reference-readme.md) - Complete API documentation