npm - @fluentcommerce/fc-connect-sdk - Versions diffs - 0.1.53 → 0.1.55 - Mend

@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (495) hide show

package/docs/02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-resolver-helpers-reference.md CHANGED Viewed

@@ -1,1437 +1,1437 @@
-# Resolver Helper Functions Reference
-**Complete reference for all 57 helper utilities**
----
-## Table of Contents
-1. [Overview](#overview)
-2. [Data Access](#data-access) (2 functions)
-3. [Parsing](#parsing) (3 functions)
-4. [Formatting](#formatting) (2 functions)
-5. [Validation](#validation) (3 functions)
-6. [String Utilities](#string-utilities) (8 functions)
-7. [Object Utilities](#object-utilities) (7 functions)
-8. [Array Transformation](#array-transformation) (8 functions)
-9. [Array Aggregation](#array-aggregation) (5 functions)
-10. [Date/Time](#datetime) (5 functions)
-11. [Function Utilities](#function-utilities) (2 functions)
-12. [Type Guards](#type-guards) (5 functions)
-13. [Utility Functions](#utility-functions) (3 functions)
-14. [Performance](#performance) (3 functions)
-15. [XML/JSON Specific](#xmljson-specific) (5 functions)
-**Total: 57 helper functions**
----
-## Overview
-Helper functions are available through the `helpers` parameter in every resolver:
-```typescript
-import { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
-// In resolvers
-builder.field('input.ref', (data, config, helpers) => {
-  // helpers.get(), helpers.parseFloatSafe(), etc.
-  return helpers.get(data, 'order.orderNo');
-});
-// Standalone usage
-const value = ResolverHelpers.get(data, 'order.orderNo');
-```
-### Import Options
-```typescript
-// Import all helpers
-import { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
-// Import specific helpers
-import {
-  get,
-  formatDate,
-  formatCurrency,
-  parseFloatSafe
-} from '@fluentcommerce/fc-connect-sdk';
-```
----
-## Data Access
-### `get(obj, path, defaultValue?)`
-Safe nested property getter with dot notation. Never throws errors.
-**Signature:**
-```typescript
-get(obj: any, path: string, defaultValue?: any): any
-```
-**Supported Path Syntax:**
-- Dot notation: `'order.customer.email'`
-- Array indexing: `'items[0].name'`
-- XML attributes: `'order@order-no'` (note: NO dot before @)
-- Filters: `'custom-attribute[attribute-id=value]'`
-**Examples:**
-```typescript
-// Simple path
-const email = helpers.get(data, 'orders.order.customer.customer-email');
-// With default
-const currency = helpers.get(data, 'orders.order.currency', 'USD');
-// Array access
-const firstItem = helpers.get(data, 'orders.order.product-lineitems.product-lineitem[0]');
-// XML attribute (NO dot before @)
-const orderNo = helpers.get(data, 'orders.order@order-no');
-// Nested with default
-const street = helpers.get(data, 'customer.address.street1', 'N/A');
-```
-**Returns:** Value at path or `defaultValue` (or `undefined`)
----
-### `ensureArray(value)`
-Convert single items to arrays. Returns empty array for null/undefined.
-**Signature:**
-```typescript
-ensureArray<T>(val: T | T[] | null | undefined): T[]
-```
-**Behavior:**
-- `undefined` or `null` → `[]`
-- Array → Returns array unchanged
-- Single object → `[object]`
-- Primitive → `[primitive]`
-**Examples:**
-```typescript
-helpers.ensureArray([1, 2, 3]);        // => [1, 2, 3]
-helpers.ensureArray('single');         // => ['single']
-helpers.ensureArray(null);             // => []
-helpers.ensureArray({ id: 1 });        // => [{ id: 1 }]
-// Real-world: Handle XML single vs multiple elements
-const items = helpers.get(data, 'orders.order.product-lineitems.product-lineitem');
-// items might be object (1 item) or array (multiple items)
-const itemsArray = helpers.ensureArray(items);
-itemsArray.forEach(item => { ... });  // Always works!
-```
-**Use Case:** XML parsing where single elements return object, multiple return array.
----
-## Parsing
-### `parseFloatSafe(value, defaultValue?)`
-Parse float with safe fallback. Never throws.
-**Signature:**
-```typescript
-parseFloatSafe(value: any, defaultValue?: number): number
-```
-**Examples:**
-```typescript
-helpers.parseFloatSafe('10.50', 0);       // => 10.5
-helpers.parseFloatSafe('invalid', 0);     // => 0
-helpers.parseFloatSafe(null, 99.99);      // => 99.99
-helpers.parseFloatSafe('123.456');        // => 123.456
-```
-**Returns:** Parsed number or `defaultValue` (or `0`)
----
-### `parseIntSafe(value, defaultValue?)`
-Parse integer with safe fallback. Never throws.
-**Signature:**
-```typescript
-parseIntSafe(value: any, defaultValue?: number): number
-```
-**Examples:**
-```typescript
-helpers.parseIntSafe('5', 1);             // => 5
-helpers.parseIntSafe('5.7', 1);           // => 5 (truncates)
-helpers.parseIntSafe('invalid', 1);       // => 1
-helpers.parseIntSafe(null, 100);          // => 100
-```
-**Returns:** Parsed integer or `defaultValue` (or `0`)
----
-### `safeJsonParse(jsonString, defaultValue?)`
-Parse JSON with safe fallback. Never throws.
-**Signature:**
-```typescript
-safeJsonParse<T = any>(jsonString: string, defaultValue?: T): T
-```
-**Examples:**
-```typescript
-helpers.safeJsonParse('{"key":"value"}', {});
-// => { key: 'value' }
-helpers.safeJsonParse('invalid json', {});
-// => {}
-helpers.safeJsonParse('["a","b"]', []);
-// => ['a', 'b']
-```
-**Returns:** Parsed object or `defaultValue` (or `{}`)
----
-## Formatting
-### `formatDate(date)`
-Format date to ISO8601 string.
-**Signature:**
-```typescript
-formatDate(date: Date | string): string
-```
-**Examples:**
-```typescript
-helpers.formatDate('2025-01-14');
-// => '2025-01-14T00:00:00.000Z'
-helpers.formatDate(new Date('2025-01-14T10:30:00Z'));
-// => '2025-01-14T10:30:00.000Z'
-helpers.formatDate(1705227000000);  // Timestamp
-// => '2025-01-14T06:30:00.000Z'
-```
-**Returns:** ISO8601 formatted string
----
-### `formatCurrency(amount, scale?)`
-Format currency with specified decimal places. Uses half-down rounding.
-**Signature:**
-```typescript
-formatCurrency(amount: number, scale?: number): string
-```
-**Parameters:**
-- `amount: number` - Amount to format
-- `scale?: number` - Decimal places (default: 2)
-**Rounding:** Half-down (0.5 rounds toward zero)
-- `10.555` → `'10.55'`
-- `10.556` → `'10.56'`
-**Examples:**
-```typescript
-helpers.formatCurrency(10.555, 2);        // => '10.55'
-helpers.formatCurrency(10.556, 2);        // => '10.56'
-helpers.formatCurrency(99.999, 2);        // => '100.00'
-helpers.formatCurrency(1234.5, 2);        // => '1234.50'
-helpers.formatCurrency(7.123456, 4);      // => '7.1235'
-```
-**Returns:** Formatted currency string
----
-## Validation
-### `isValidEmail(email)`
-Validate email format using regex.
-**Signature:**
-```typescript
-isValidEmail(email: string): boolean
-```
-**Examples:**
-```typescript
-helpers.isValidEmail('test@example.com');     // => true
-helpers.isValidEmail('user+tag@domain.co.uk'); // => true
-helpers.isValidEmail('invalid-email');        // => false
-helpers.isValidEmail('missing@domain');       // => false
-helpers.isValidEmail('');                     // => false
-```
-**Returns:** `true` if valid email, `false` otherwise
----
-### `requireField(value, fieldName)`
-Validate required field. Throws error if missing/empty.
-**Signature:**
-```typescript
-requireField(value: any, fieldName: string): void
-```
-**Throws:** Error if value is `null`, `undefined`, or empty string
-**Examples:**
-```typescript
-helpers.requireField(orderRef, 'Order Reference');
-// OK if orderRef has value
-helpers.requireField(null, 'Customer ID');
-// Throws: 'Required field missing: Customer ID'
-helpers.requireField('', 'Email');
-// Throws: 'Required field missing: Email'
-```
-**Use Case:** Enforce required fields in resolvers
----
-### `mapValue(value, mapping, defaultValue?)`
-Map value using mapping object.
-**Signature:**
-```typescript
-mapValue<T>(value: any, mapping: Record<string, T>, defaultValue?: T): T
-```
-**Examples:**
-```typescript
-const channelMapping = {
-  'Storefront': 'HD',
-  'CallCenter': 'CC',
-  'Mobile': 'MOBILE'
-};
-helpers.mapValue('Storefront', channelMapping, 'UNKNOWN');  // => 'HD'
-helpers.mapValue('POS', channelMapping, 'STORE');           // => 'STORE' (default)
-helpers.mapValue('CallCenter', channelMapping);             // => 'CC'
-```
-**Returns:** Mapped value or `defaultValue` (or `undefined`)
----
-## String Utilities
-### `fullName(firstName?, lastName?)`
-Combine first and last name with space.
-**Signature:**
-```typescript
-fullName(firstName?: string, lastName?: string): string
-```
-**Examples:**
-```typescript
-helpers.fullName('John', 'Doe');        // => 'John Doe'
-helpers.fullName('John', '');           // => 'John'
-helpers.fullName('', 'Doe');            // => 'Doe'
-helpers.fullName('', '');               // => ''
-```
----
-### `truncate(str, maxLength)`
-Truncate string to max length, preserving words when possible.
-**Signature:**
-```typescript
-truncate(str: string, maxLength: number): string
-```
-**Examples:**
-```typescript
-helpers.truncate('This is a very long text', 10);
-// => 'This is...'
-helpers.truncate('Short', 10);
-// => 'Short'
-helpers.truncate('OneVeryLongWord', 8);
-// => 'OneVery...'
-```
----
-### `normalizeWhitespace(str)`
-Collapse multiple spaces into single space, trim edges.
-**Signature:**
-```typescript
-normalizeWhitespace(str: string): string
-```
-**Examples:**
-```typescript
-helpers.normalizeWhitespace('Hello    World  \n  !');
-// => 'Hello World !'
-helpers.normalizeWhitespace('  Too   many   spaces  ');
-// => 'Too many spaces'
-```
----
-### `toCamelCase(str)`
-Convert string to camelCase.
-**Signature:**
-```typescript
-toCamelCase(str: string): string
-```
-**Examples:**
-```typescript
-helpers.toCamelCase('order-number');      // => 'orderNumber'
-helpers.toCamelCase('order_number');      // => 'orderNumber'
-helpers.toCamelCase('Order Number');      // => 'orderNumber'
-helpers.toCamelCase('ORDER-NUMBER');      // => 'orderNumber'
-```
----
-### `toSnakeCase(str)`
-Convert string to snake_case.
-**Signature:**
-```typescript
-toSnakeCase(str: string): string
-```
-**Examples:**
-```typescript
-helpers.toSnakeCase('orderNumber');       // => 'order_number'
-helpers.toSnakeCase('OrderNumber');       // => '_order_number'
-helpers.toSnakeCase('order-number');      // => 'order_number'
-```
----
-### `template(str, vars)`
-String interpolation with `{{variable}}` syntax.
-**Signature:**
-```typescript
-template(str: string, vars: Record<string, any>): string
-```
-**Examples:**
-```typescript
-helpers.template('Hello {{name}}!', { name: 'World' });
-// => 'Hello World!'
-helpers.template('Order {{id}} for {{customer}}', {
-  id: '123',
-  customer: 'John Doe'
-});
-// => 'Order 123 for John Doe'
-```
----
-### `slugify(str)`
-Convert string to URL-safe slug.
-**Signature:**
-```typescript
-slugify(str: string): string
-```
-**Examples:**
-```typescript
-helpers.slugify('Hello World!');           // => 'hello-world'
-helpers.slugify('Product Name (2024)');    // => 'product-name-2024'
-helpers.slugify('Café & Restaurant');      // => 'cafe-restaurant'
-```
----
-### `uuid()`
-Generate UUID v4.
-**Signature:**
-```typescript
-uuid(): string
-```
-**Examples:**
-```typescript
-helpers.uuid();
-// => '550e8400-e29b-41d4-a716-446655440000'
-// Use for unique IDs
-const uniqueRef = `ORDER-${helpers.uuid()}`;
-```
----
-## Object Utilities
-### `isEmpty(value)`
-Check if value is empty (null, undefined, '', [], {}).
-**Signature:**
-```typescript
-isEmpty(value: any): boolean
-```
-**Examples:**
-```typescript
-helpers.isEmpty(null);              // => true
-helpers.isEmpty(undefined);         // => true
-helpers.isEmpty('');                // => true
-helpers.isEmpty([]);                // => true
-helpers.isEmpty({});                // => true
-helpers.isEmpty('text');            // => false
-helpers.isEmpty([1, 2]);            // => false
-helpers.isEmpty({ key: 'value' });  // => false
-helpers.isEmpty(0);                 // => false (0 is not empty)
-```
----
-### `pick(obj, keys)`
-Pick specific fields from object.
-**Signature:**
-```typescript
-pick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>
-```
-**Examples:**
-```typescript
-const order = { id: '1', ref: 'ORD-1', status: 'OPEN', total: 100 };
-helpers.pick(order, ['id', 'ref']);
-// => { id: '1', ref: 'ORD-1' }
-```
----
-### `omit(obj, keys)`
-Omit specific fields from object.
-**Signature:**
-```typescript
-omit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>
-```
-**Examples:**
-```typescript
-const order = { id: '1', ref: 'ORD-1', status: 'OPEN', total: 100 };
-helpers.omit(order, ['status', 'total']);
-// => { id: '1', ref: 'ORD-1' }
-```
----
-### `deepClone(obj)`
-Deep clone object using JSON serialization.
-**Signature:**
-```typescript
-deepClone<T>(obj: T): T
-```
-**Examples:**
-```typescript
-const original = { a: { b: { c: 1 } } };
-const cloned = helpers.deepClone(original);
-cloned.a.b.c = 2;
-console.log(original.a.b.c);  // => 1 (unchanged)
-```
-**Warning:** Only works with JSON-serializable objects (no functions, undefined, etc.)
----
-### `deepMerge(target, source)`
-Merge objects deeply.
-**Signature:**
-```typescript
-deepMerge<T extends object>(target: T, source: Partial<T>): T
-```
-**Examples:**
-```typescript
-const target = { a: { b: 1, c: 2 } };
-const source = { a: { c: 3, d: 4 }, e: 5 };
-helpers.deepMerge(target, source);
-// => { a: { b: 1, c: 3, d: 4 }, e: 5 }
-```
----
-### `set(obj, path, value)`
-Set nested property value with dot notation. Creates intermediate objects as needed.
-**Signature:**
-```typescript
-set(obj: any, path: string, value: any): void
-```
-**Examples:**
-```typescript
-const data = {};
-helpers.set(data, 'order.customer.email', 'test@example.com');
-// => { order: { customer: { email: 'test@example.com' } } }
-helpers.set(data, 'order.total', 100);
-// => { order: { customer: {...}, total: 100 } }
-```
----
-### `merge(...objects)`
-Shallow merge multiple objects.
-**Signature:**
-```typescript
-merge<T extends object>(...objects: Partial<T>[]): T
-```
-**Examples:**
-```typescript
-const defaults = { currency: 'USD', tax: 0 };
-const order = { total: 100, tax: 10 };
-helpers.merge(defaults, order);
-// => { currency: 'USD', tax: 10, total: 100 }
-```
----
-## Array Transformation
-### `groupBy(array, key)`
-Group array items by key or function.
-**Signature:**
-```typescript
-groupBy<T>(array: T[], key: keyof T | ((item: T) => string)): Record<string, T[]>
-```
-**Examples:**
-```typescript
-const items = [
-  { sku: 'A', category: 'electronics' },
-  { sku: 'B', category: 'electronics' },
-  { sku: 'C', category: 'clothing' }
-];
-helpers.groupBy(items, 'category');
-// => {
-//   electronics: [{ sku: 'A', ... }, { sku: 'B', ... }],
-//   clothing: [{ sku: 'C', ... }]
-// }
-helpers.groupBy(items, item => item.sku[0]);
-// => { A: [...], B: [...], C: [...] }
-```
----
-### `keyBy(array, key)`
-Convert array to object keyed by property.
-**Signature:**
-```typescript
-keyBy<T>(array: T[], key: keyof T | ((item: T) => string)): Record<string, T>
-```
-**Examples:**
-```typescript
-const items = [
-  { sku: 'SKU-1', name: 'Product 1' },
-  { sku: 'SKU-2', name: 'Product 2' }
-];
-helpers.keyBy(items, 'sku');
-// => {
-//   'SKU-1': { sku: 'SKU-1', name: 'Product 1' },
-//   'SKU-2': { sku: 'SKU-2', name: 'Product 2' }
-// }
-```
----
-### `chunk(array, size)`
-Split array into chunks of specified size.
-**Signature:**
-```typescript
-chunk<T>(array: T[], size: number): T[][]
-```
-**Examples:**
-```typescript
-helpers.chunk([1, 2, 3, 4, 5], 2);
-// => [[1, 2], [3, 4], [5]]
-helpers.chunk(['a', 'b', 'c', 'd', 'e', 'f'], 3);
-// => [['a', 'b', 'c'], ['d', 'e', 'f']]
-```
----
-### `flatten(array, depth)`
-Flatten nested arrays to specified depth.
-**Signature:**
-```typescript
-flatten<T>(array: any[], depth?: number): T[]
-```
-**Examples:**
-```typescript
-helpers.flatten([[1, 2], [3, 4]], 1);
-// => [1, 2, 3, 4]
-helpers.flatten([[[1, 2]], [[3, 4]]], 2);
-// => [1, 2, 3, 4]
-```
----
-### `unique(array, key?)`
-Get unique values from array, optionally by key for objects.
-**Signature:**
-```typescript
-unique<T>(array: T[], key?: keyof T | ((item: T) => any)): T[]
-```
-**Examples:**
-```typescript
-helpers.unique([1, 2, 2, 3, 3, 3]);
-// => [1, 2, 3]
-const items = [
-  { sku: 'A', qty: 1 },
-  { sku: 'B', qty: 2 },
-  { sku: 'A', qty: 3 }
-];
-helpers.unique(items, 'sku');
-// => [{ sku: 'A', qty: 1 }, { sku: 'B', qty: 2 }]
-```
----
-### `sortBy(array, key, order)`
-Sort array by key or function.
-**Signature:**
-```typescript
-sortBy<T>(array: T[], key: keyof T | ((item: T) => any), order?: 'asc' | 'desc'): T[]
-```
-**Examples:**
-```typescript
-const items = [
-  { sku: 'C', price: 30 },
-  { sku: 'A', price: 10 },
-  { sku: 'B', price: 20 }
-];
-helpers.sortBy(items, 'price', 'asc');
-// => [{ sku: 'A', price: 10 }, { sku: 'B', price: 20 }, { sku: 'C', price: 30 }]
-helpers.sortBy(items, 'sku', 'desc');
-// => [{ sku: 'C', ... }, { sku: 'B', ... }, { sku: 'A', ... }]
-```
----
-### `compact(array)`
-Remove falsy values (null, undefined, false, 0, '') from array.
-**Signature:**
-```typescript
-compact<T>(array: (T | null | undefined | false | 0 | '')[]): T[]
-```
-**Examples:**
-```typescript
-helpers.compact([1, null, 2, undefined, 3, false, 0, '']);
-// => [1, 2, 3]
-helpers.compact(['a', '', 'b', null, 'c']);
-// => ['a', 'b', 'c']
-```
----
-### `coalesce(...values)`
-Return first non-null/undefined value (like SQL COALESCE).
-**Signature:**
-```typescript
-coalesce<T>(...values: (T | null | undefined)[]): T | undefined
-```
-**Examples:**
-```typescript
-helpers.coalesce(null, undefined, 'first', 'second');  // => 'first'
-helpers.coalesce(null, 0, 1);                          // => 0
-helpers.coalesce(null, '', 'value');                   // => ''
-```
----
-## Array Aggregation
-### `sum(array, key?)`
-Sum numeric values in array, optionally by key for objects.
-**Signature:**
-```typescript
-sum<T>(array: T[], key?: keyof T | ((item: T) => number)): number
-```
-**Examples:**
-```typescript
-helpers.sum([1, 2, 3, 4, 5]);  // => 15
-const items = [
-  { price: 10 },
-  { price: 20 },
-  { price: 30 }
-];
-helpers.sum(items, 'price');  // => 60
-helpers.sum(items, item => item.price * 1.1);  // => 66 (with markup)
-```
----
-### `avg(array, key?)`
-Calculate average of numeric values.
-**Signature:**
-```typescript
-avg<T>(array: T[], key?: keyof T | ((item: T) => number)): number
-```
-**Examples:**
-```typescript
-helpers.avg([10, 20, 30]);  // => 20
-const items = [{ score: 80 }, { score: 90 }, { score: 70 }];
-helpers.avg(items, 'score');  // => 80
-```
----
-### `min(array, key?)`
-Find minimum value in array.
-**Signature:**
-```typescript
-min<T>(array: T[], key?: keyof T | ((item: T) => number)): number | undefined
-```
-**Examples:**
-```typescript
-helpers.min([10, 5, 20, 3]);  // => 3
-const items = [{ price: 10 }, { price: 5 }, { price: 20 }];
-helpers.min(items, 'price');  // => 5
-```
----
-### `max(array, key?)`
-Find maximum value in array.
-**Signature:**
-```typescript
-max<T>(array: T[], key?: keyof T | ((item: T) => number)): number | undefined
-```
-**Examples:**
-```typescript
-helpers.max([10, 5, 20, 3]);  // => 20
-const items = [{ quantity: 10 }, { quantity: 5 }, { quantity: 20 }];
-helpers.max(items, 'quantity');  // => 20
-```
----
-### `clamp(num, min, max)`
-Clamp number to specified range.
-**Signature:**
-```typescript
-clamp(num: number, min: number, max: number): number
-```
-**Examples:**
-```typescript
-helpers.clamp(5, 0, 10);    // => 5
-helpers.clamp(-5, 0, 10);   // => 0
-helpers.clamp(15, 0, 10);   // => 10
-```
----
-## Date/Time
-### `addDays(date, days)`
-Add days to date.
-**Signature:**
-```typescript
-addDays(date: Date | string, days: number): Date
-```
-**Examples:**
-```typescript
-helpers.addDays(new Date('2025-01-14'), 7);
-// => Date('2025-01-21')
-helpers.addDays('2025-01-14', 30);
-// => Date('2025-02-13')
-```
----
-### `subtractDays(date, days)`
-Subtract days from date.
-**Signature:**
-```typescript
-subtractDays(date: Date | string, days: number): Date
-```
-**Examples:**
-```typescript
-helpers.subtractDays(new Date('2025-01-14'), 7);
-// => Date('2025-01-07')
-```
----
-### `dateDiff(date1, date2)`
-Get difference between dates in days.
-**Signature:**
-```typescript
-dateDiff(date1: Date | string, date2: Date | string): number
-```
-**Examples:**
-```typescript
-helpers.dateDiff('2025-01-14', '2025-01-21');  // => 7
-helpers.dateDiff('2025-01-21', '2025-01-14');  // => -7
-```
----
-### `parseDate(dateStr, format?)`
-Parse date with multiple format support.
-**Signature:**
-```typescript
-parseDate(dateStr: string, format?: string): Date | null
-```
-**Supported Formats:**
-- ISO: `'2025-01-14'`
-- US: `'01/14/2025'`
-- EU: `'14-01-2025'`
-- Compact: `'20250114'`
-**Examples:**
-```typescript
-helpers.parseDate('2025-01-14');       // ISO
-helpers.parseDate('01/14/2025');       // MM/DD/YYYY
-helpers.parseDate('14-01-2025');       // DD-MM-YYYY
-helpers.parseDate('20250114');         // YYYYMMDD
-```
-**Returns:** `Date` object or `null` if parsing fails
----
-## Function Utilities
-### `debounce(fn, delayMs)`
-Delay function execution until after delay period.
-**Signature:**
-```typescript
-debounce<T extends (...args: any[]) => any>(fn: T, delayMs: number): T
-```
-**Examples:**
-```typescript
-const logMessage = (msg: string) => console.log(msg);
-const debouncedLog = helpers.debounce(logMessage, 1000);
-debouncedLog('Message 1');  // Cancelled
-debouncedLog('Message 2');  // Cancelled
-debouncedLog('Message 3');  // Executed after 1000ms
-```
----
-### `throttle(fn, limitMs)`
-Limit function execution rate.
-**Signature:**
-```typescript
-throttle<T extends (...args: any[]) => any>(fn: T, limitMs: number): T
-```
-**Examples:**
-```typescript
-const logMessage = (msg: string) => console.log(msg);
-const throttledLog = helpers.throttle(logMessage, 1000);
-throttledLog('Message 1');  // Executed immediately
-throttledLog('Message 2');  // Ignored (within 1000ms)
-// Wait 1000ms
-throttledLog('Message 3');  // Executed
-```
----
-## Type Guards
-### `isString(value)`, `isNumber(value)`, `isArray(value)`, `isObject(value)`, `isDate(value)`
-Type checking utilities.
-**Signatures:**
-```typescript
-isString(value: any): boolean
-isNumber(value: any): boolean
-isArray(value: any): boolean
-isObject(value: any): boolean
-isDate(value: any): boolean
-```
-**Examples:**
-```typescript
-helpers.isString('hello');             // => true
-helpers.isNumber(123);                 // => true
-helpers.isNumber(NaN);                 // => false
-helpers.isArray([1, 2, 3]);            // => true
-helpers.isObject({ key: 'value' });    // => true
-helpers.isObject([1, 2, 3]);           // => false
-helpers.isDate(new Date());            // => true
-helpers.isDate('2025-01-14');          // => false
-```
----
-## Utility Functions
-### `defaultTo(value, defaultValue)`
-Return default if value is null/undefined.
-**Signature:**
-```typescript
-defaultTo<T>(value: T | null | undefined, defaultValue: T): T
-```
-**Examples:**
-```typescript
-helpers.defaultTo(null, 'default');       // => 'default'
-helpers.defaultTo(undefined, 'default');  // => 'default'
-helpers.defaultTo('value', 'default');    // => 'value'
-helpers.defaultTo(0, 10);                 // => 0 (0 is not null/undefined)
-```
----
-### `range(start, end?, step?)`
-Generate numeric ranges.
-**Signature:**
-```typescript
-range(start: number, end?: number, step?: number): number[]
-```
-**Examples:**
-```typescript
-helpers.range(5);              // => [0, 1, 2, 3, 4]
-helpers.range(1, 6);           // => [1, 2, 3, 4, 5]
-helpers.range(0, 10, 2);       // => [0, 2, 4, 6, 8]
-helpers.range(10, 0, -2);      // => [10, 8, 6, 4, 2]
-```
----
-### `hashString(str)`
-Generate deterministic hash from string (not cryptographically secure).
-**Signature:**
-```typescript
-hashString(str: string): string
-```
-**Examples:**
-```typescript
-helpers.hashString('hello');  // => '4x93m' (deterministic)
-helpers.hashString('hello');  // => '4x93m' (same input = same output)
-```
-**Use Case:** Stable keys, content-based IDs, deduplication keys
----
-## Performance
-### `memoize(fn)`
-Memoize expensive function.
-**Signature:**
-```typescript
-memoize<T extends (...args: any[]) => any>(fn: T): T
-```
-**Examples:**
-```typescript
-const expensiveCalculation = (a, b) => {
-  console.log('Calculating...');
-  return a + b;
-};
-const memoized = helpers.memoize(expensiveCalculation);
-memoized(1, 2);  // => Logs "Calculating...", returns 3
-memoized(1, 2);  // => Returns 3 (from cache, no log)
-memoized(2, 3);  // => Logs "Calculating...", returns 5
-```
----
-### `retry(fn, maxRetries?, delayMs?)`
-Retry function with exponential backoff.
-**Signature:**
-```typescript
-retry<T>(fn: () => Promise<T>, maxRetries?: number, delayMs?: number): Promise<T>
-```
-**Parameters:**
-- `fn` - Async function to retry
-- `maxRetries` - Max attempts (default: 3)
-- `delayMs` - Initial delay (default: 100ms)
-**Examples:**
-```typescript
-const result = await helpers.retry(
-  async () => {
-    const response = await fetch('https://api.example.com/data');
-    return response.json();
-  },
-  3,    // Max 3 retries
-  100   // Start with 100ms delay
-);
-```
----
-### `batchProcess(items, processor, batchSize?)`
-Process array in batches (async, default: 50 items/batch).
-**Signature:**
-```typescript
-batchProcess<T, R>(
-  items: T[],
-  processor: (item: T, index: number) => Promise<R>,
-  batchSize?: number
-): Promise<R[]>
-```
-**Examples:**
-```typescript
-const items = [1, 2, 3, 4, 5];
-const results = await helpers.batchProcess(
-  items,
-  async (item, index) => {
-    // Call external API
-    return await fetchData(item);
-  },
-  2  // Process 2 items at a time
-);
-```
----
-## XML/JSON Specific
-### `extractCustomAttribute(customAttributes, attributeId, defaultValue?)`
-Extract custom attribute by ID from XML/JSON custom attributes.
-**Signature:**
-```typescript
-extractCustomAttribute(customAttributes: any, attributeId: string, defaultValue?: any): any
-```
-**Handles Multiple Formats:**
-- Array of attributes: `[{ '@attribute-id': 'id', '#text': 'value' }, ...]`
-- Single attribute object: `{ '@attribute-id': 'id', '#text': 'value' }`
-- Object with keys: `{ 'key1': 'value1', 'key2': 'value2' }`
-**Examples:**
-```typescript
-// Array format (SFCC XML)
-const attrs = [
-  { '@attribute-id': 'retailerId', '#text': '123' },
-  { '@attribute-id': 'orderType', '#text': 'HD' }
-];
-helpers.extractCustomAttribute(attrs, 'retailerId');
-// => '123'
-// Object format
-const attrs2 = { 'retailerId': '123', 'orderType': 'HD' };
-helpers.extractCustomAttribute(attrs2, 'orderType');
-// => 'HD'
-// With default
-helpers.extractCustomAttribute(attrs, 'missing', 'DEFAULT');
-// => 'DEFAULT'
-```
----
-### `getXmlAttribute(obj, attrName, defaultValue?)`
-Extract XML attribute from object with multi-format support. Automatically handles different XML parser formats.
-**Signature:**
-```typescript
-getXmlAttribute(obj: any, attrName: string, defaultValue?: any): any
-```
-**Supported XML Attribute Formats:**
-The function tries multiple formats in priority order:
-1. `$attr-name` - Versori/xml2js with $ prefix as direct key
-2. `$['attr-name']` - Nested in $ object (Versori platform format)
-3. `@attr-name` - SDK XMLParserService default format
-4. `@['attr-name']` - Nested in @ object (alternative format)
-5. `attr-name` - Direct attribute (fallback)
-6. `_attributes['attr-name']` - xml2js _attributes format
-**Why This Exists:**
-Different XML parsers store attributes in different formats. This helper eliminates the need to manually check multiple formats in resolvers.
-**Examples:**
-```typescript
-// Versori format (nested $ object)
-const versoriData = { $: { 'shipment-id': '02408380' } };
-helpers.getXmlAttribute(versoriData, 'shipment-id');
-// => '02408380'
-// SDK format (@ prefix)
-const sdkData = { '@shipment-id': '02408380' };
-helpers.getXmlAttribute(sdkData, 'shipment-id');
-// => '02408380'
-// Direct format
-const directData = { 'shipment-id': '02408380' };
-helpers.getXmlAttribute(directData, 'shipment-id');
-// => '02408380'
-// With default value
-helpers.getXmlAttribute({}, 'shipment-id', 'DEFAULT');
-// => 'DEFAULT'
-// Real-world usage in resolver
-'custom.createFulfilmentChoiceRef': (value, data, config, helpers) => {
-  const shipmentData = value || data || {};
-  const shipmentId = helpers.getXmlAttribute(shipmentData, 'shipment-id');
-  return `fc_${shipmentId}`;
-}
-```
-**Use Cases:**
-- Extracting XML attributes in custom resolvers
-- Handling multiple XML parser formats (Versori, SDK, xml2js)
-- Simplifying resolver code (no need to check multiple formats manually)
-**Returns:** Attribute value or `defaultValue` (or `undefined`)
----
-### `getXmlTextContent(obj, defaultValue?)`
-Extract XML text content from object with multi-format support. Automatically handles different XML parser formats for text content.
-**Signature:**
-```typescript
-getXmlTextContent(obj: any, defaultValue?: any): any
-```
-**Supported XML Text Content Formats:**
-The function tries multiple formats in priority order:
-1. `_` - Versori platform format (text content)
-2. `#text` - SDK XMLParserService default format (text content)
-3. `value` - Fallback property
-4. Direct value - If already a string/primitive
-**Why This Exists:**
-Different XML parsers store text content in different properties. This helper eliminates the need to manually check multiple formats in resolvers.
-**Examples:**
-```typescript
-// Versori format (text in _ property)
-const versoriData = { $: { unit: '1' }, _: '1.0' };
-helpers.getXmlTextContent(versoriData);
-// => '1.0'
-// SDK format (text in #text property)
-const sdkData = { '@unit': '1', '#text': '1.0' };
-helpers.getXmlTextContent(sdkData);
-// => '1.0'
-// Direct string
-helpers.getXmlTextContent('1.0');
-// => '1.0'
-// With default value
-helpers.getXmlTextContent({}, 'DEFAULT');
-// => 'DEFAULT'
-// Real-world usage in resolver
-'custom.parseQuantity': (value, data, config, helpers) => {
-  const qty = helpers.getXmlTextContent(value) ?? value;
-  return parseFloat(String(qty));
-}
-```
-**Use Cases:**
-- Extracting XML text content in custom resolvers
-- Handling multiple XML parser formats (Versori, SDK, xml2js)
-- Simplifying resolver code (no need to check multiple formats manually)
-**Returns:** Text content value or `defaultValue` (or `undefined`)
----
-### `normalizeEmpty(value, defaultValue?, trimWhitespace?)`
-Normalize empty value handling null, undefined, empty string, and whitespace. Useful for CSV and JSON data where empty values may be represented differently.
-**Signature:**
-```typescript
-normalizeEmpty(value: any, defaultValue?: any, trimWhitespace?: boolean): any
-```
-**Normalization Rules:**
-- `null` → defaultValue
-- `undefined` → defaultValue
-- `''` (empty string) → defaultValue
-- `'   '` (whitespace-only) → defaultValue (if trimWhitespace: true, default)
-- Other values → returned as-is
-**Parameters:**
-- `value` - Value to normalize
-- `defaultValue` - Value to return if empty (default: undefined)
-- `trimWhitespace` - Whether to treat whitespace-only strings as empty (default: true)
-**Examples:**
-```typescript
-// CSV empty values
-helpers.normalizeEmpty(null, 'N/A');           // => 'N/A'
-helpers.normalizeEmpty(undefined, 'N/A');      // => 'N/A'
-helpers.normalizeEmpty('', 'N/A');             // => 'N/A'
-helpers.normalizeEmpty('   ', 'N/A');          // => 'N/A' (trimWhitespace: true)
-helpers.normalizeEmpty('value', 'N/A');        // => 'value'
-// JSON null handling
-helpers.normalizeEmpty(jsonData.field, 'DEFAULT'); // => 'DEFAULT' if null/undefined/empty
-// Preserve whitespace when needed
-helpers.normalizeEmpty('   ', 'N/A', false);   // => '   ' (preserves whitespace)
-```
-**Use Cases:**
-- Normalizing CSV empty values (null, '', whitespace)
-- Handling JSON null/undefined values
-- Consistent empty value handling across data sources
-- Simplifying resolver code (no need to check multiple empty formats)
-**Returns:** Normalized value or `defaultValue` (or `undefined`)
----
-## See Also
-- [Main Resolver Guide](./mapping-resolvers-resolver-guide.md) - Getting started
-- [API Reference](./mapping-resolvers-resolver-api-reference.md) - ResolverBuilder methods
-- [Parameters Reference](./mapping-resolvers-resolver-parameters-reference.md) - value, data, config, helpers
-- [Troubleshooting](./mapping-resolvers-resolver-troubleshooting.md) - Common issues
-- [Cookbook](./mapping-resolvers-resolver-cookbook.md) - Advanced patterns
----
-**License:** MIT
+# Resolver Helper Functions Reference
+**Complete reference for all 57 helper utilities**
+---
+## Table of Contents
+1. [Overview](#overview)
+2. [Data Access](#data-access) (2 functions)
+3. [Parsing](#parsing) (3 functions)
+4. [Formatting](#formatting) (2 functions)
+5. [Validation](#validation) (3 functions)
+6. [String Utilities](#string-utilities) (8 functions)
+7. [Object Utilities](#object-utilities) (7 functions)
+8. [Array Transformation](#array-transformation) (8 functions)
+9. [Array Aggregation](#array-aggregation) (5 functions)
+10. [Date/Time](#datetime) (5 functions)
+11. [Function Utilities](#function-utilities) (2 functions)
+12. [Type Guards](#type-guards) (5 functions)
+13. [Utility Functions](#utility-functions) (3 functions)
+14. [Performance](#performance) (3 functions)
+15. [XML/JSON Specific](#xmljson-specific) (5 functions)
+**Total: 57 helper functions**
+---
+## Overview
+Helper functions are available through the `helpers` parameter in every resolver:
+```typescript
+import { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
+// In resolvers
+builder.field('input.ref', (data, config, helpers) => {
+  // helpers.get(), helpers.parseFloatSafe(), etc.
+  return helpers.get(data, 'order.orderNo');
+});
+// Standalone usage
+const value = ResolverHelpers.get(data, 'order.orderNo');
+```
+### Import Options
+```typescript
+// Import all helpers
+import { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
+// Import specific helpers
+import {
+  get,
+  formatDate,
+  formatCurrency,
+  parseFloatSafe
+} from '@fluentcommerce/fc-connect-sdk';
+```
+---
+## Data Access
+### `get(obj, path, defaultValue?)`
+Safe nested property getter with dot notation. Never throws errors.
+**Signature:**
+```typescript
+get(obj: any, path: string, defaultValue?: any): any
+```
+**Supported Path Syntax:**
+- Dot notation: `'order.customer.email'`
+- Array indexing: `'items[0].name'`
+- XML attributes: `'order@order-no'` (note: NO dot before @)
+- Filters: `'custom-attribute[attribute-id=value]'`
+**Examples:**
+```typescript
+// Simple path
+const email = helpers.get(data, 'orders.order.customer.customer-email');
+// With default
+const currency = helpers.get(data, 'orders.order.currency', 'USD');
+// Array access
+const firstItem = helpers.get(data, 'orders.order.product-lineitems.product-lineitem[0]');
+// XML attribute (NO dot before @)
+const orderNo = helpers.get(data, 'orders.order@order-no');
+// Nested with default
+const street = helpers.get(data, 'customer.address.street1', 'N/A');
+```
+**Returns:** Value at path or `defaultValue` (or `undefined`)
+---
+### `ensureArray(value)`
+Convert single items to arrays. Returns empty array for null/undefined.
+**Signature:**
+```typescript
+ensureArray<T>(val: T | T[] | null | undefined): T[]
+```
+**Behavior:**
+- `undefined` or `null` → `[]`
+- Array → Returns array unchanged
+- Single object → `[object]`
+- Primitive → `[primitive]`
+**Examples:**
+```typescript
+helpers.ensureArray([1, 2, 3]);        // => [1, 2, 3]
+helpers.ensureArray('single');         // => ['single']
+helpers.ensureArray(null);             // => []
+helpers.ensureArray({ id: 1 });        // => [{ id: 1 }]
+// Real-world: Handle XML single vs multiple elements
+const items = helpers.get(data, 'orders.order.product-lineitems.product-lineitem');
+// items might be object (1 item) or array (multiple items)
+const itemsArray = helpers.ensureArray(items);
+itemsArray.forEach(item => { ... });  // Always works!
+```
+**Use Case:** XML parsing where single elements return object, multiple return array.
+---
+## Parsing
+### `parseFloatSafe(value, defaultValue?)`
+Parse float with safe fallback. Never throws.
+**Signature:**
+```typescript
+parseFloatSafe(value: any, defaultValue?: number): number
+```
+**Examples:**
+```typescript
+helpers.parseFloatSafe('10.50', 0);       // => 10.5
+helpers.parseFloatSafe('invalid', 0);     // => 0
+helpers.parseFloatSafe(null, 99.99);      // => 99.99
+helpers.parseFloatSafe('123.456');        // => 123.456
+```
+**Returns:** Parsed number or `defaultValue` (or `0`)
+---
+### `parseIntSafe(value, defaultValue?)`
+Parse integer with safe fallback. Never throws.
+**Signature:**
+```typescript
+parseIntSafe(value: any, defaultValue?: number): number
+```
+**Examples:**
+```typescript
+helpers.parseIntSafe('5', 1);             // => 5
+helpers.parseIntSafe('5.7', 1);           // => 5 (truncates)
+helpers.parseIntSafe('invalid', 1);       // => 1
+helpers.parseIntSafe(null, 100);          // => 100
+```
+**Returns:** Parsed integer or `defaultValue` (or `0`)
+---
+### `safeJsonParse(jsonString, defaultValue?)`
+Parse JSON with safe fallback. Never throws.
+**Signature:**
+```typescript
+safeJsonParse<T = any>(jsonString: string, defaultValue?: T): T
+```
+**Examples:**
+```typescript
+helpers.safeJsonParse('{"key":"value"}', {});
+// => { key: 'value' }
+helpers.safeJsonParse('invalid json', {});
+// => {}
+helpers.safeJsonParse('["a","b"]', []);
+// => ['a', 'b']
+```
+**Returns:** Parsed object or `defaultValue` (or `{}`)
+---
+## Formatting
+### `formatDate(date)`
+Format date to ISO8601 string.
+**Signature:**
+```typescript
+formatDate(date: Date | string): string
+```
+**Examples:**
+```typescript
+helpers.formatDate('2025-01-14');
+// => '2025-01-14T00:00:00.000Z'
+helpers.formatDate(new Date('2025-01-14T10:30:00Z'));
+// => '2025-01-14T10:30:00.000Z'
+helpers.formatDate(1705227000000);  // Timestamp
+// => '2025-01-14T06:30:00.000Z'
+```
+**Returns:** ISO8601 formatted string
+---
+### `formatCurrency(amount, scale?)`
+Format currency with specified decimal places. Uses half-down rounding.
+**Signature:**
+```typescript
+formatCurrency(amount: number, scale?: number): string
+```
+**Parameters:**
+- `amount: number` - Amount to format
+- `scale?: number` - Decimal places (default: 2)
+**Rounding:** Half-down (0.5 rounds toward zero)
+- `10.555` → `'10.55'`
+- `10.556` → `'10.56'`
+**Examples:**
+```typescript
+helpers.formatCurrency(10.555, 2);        // => '10.55'
+helpers.formatCurrency(10.556, 2);        // => '10.56'
+helpers.formatCurrency(99.999, 2);        // => '100.00'
+helpers.formatCurrency(1234.5, 2);        // => '1234.50'
+helpers.formatCurrency(7.123456, 4);      // => '7.1235'
+```
+**Returns:** Formatted currency string
+---
+## Validation
+### `isValidEmail(email)`
+Validate email format using regex.
+**Signature:**
+```typescript
+isValidEmail(email: string): boolean
+```
+**Examples:**
+```typescript
+helpers.isValidEmail('test@example.com');     // => true
+helpers.isValidEmail('user+tag@domain.co.uk'); // => true
+helpers.isValidEmail('invalid-email');        // => false
+helpers.isValidEmail('missing@domain');       // => false
+helpers.isValidEmail('');                     // => false
+```
+**Returns:** `true` if valid email, `false` otherwise
+---
+### `requireField(value, fieldName)`
+Validate required field. Throws error if missing/empty.
+**Signature:**
+```typescript
+requireField(value: any, fieldName: string): void
+```
+**Throws:** Error if value is `null`, `undefined`, or empty string
+**Examples:**
+```typescript
+helpers.requireField(orderRef, 'Order Reference');
+// OK if orderRef has value
+helpers.requireField(null, 'Customer ID');
+// Throws: 'Required field missing: Customer ID'
+helpers.requireField('', 'Email');
+// Throws: 'Required field missing: Email'
+```
+**Use Case:** Enforce required fields in resolvers
+---
+### `mapValue(value, mapping, defaultValue?)`
+Map value using mapping object.
+**Signature:**
+```typescript
+mapValue<T>(value: any, mapping: Record<string, T>, defaultValue?: T): T
+```
+**Examples:**
+```typescript
+const channelMapping = {
+  'Storefront': 'HD',
+  'CallCenter': 'CC',
+  'Mobile': 'MOBILE'
+};
+helpers.mapValue('Storefront', channelMapping, 'UNKNOWN');  // => 'HD'
+helpers.mapValue('POS', channelMapping, 'STORE');           // => 'STORE' (default)
+helpers.mapValue('CallCenter', channelMapping);             // => 'CC'
+```
+**Returns:** Mapped value or `defaultValue` (or `undefined`)
+---
+## String Utilities
+### `fullName(firstName?, lastName?)`
+Combine first and last name with space.
+**Signature:**
+```typescript
+fullName(firstName?: string, lastName?: string): string
+```
+**Examples:**
+```typescript
+helpers.fullName('John', 'Doe');        // => 'John Doe'
+helpers.fullName('John', '');           // => 'John'
+helpers.fullName('', 'Doe');            // => 'Doe'
+helpers.fullName('', '');               // => ''
+```
+---
+### `truncate(str, maxLength)`
+Truncate string to max length, preserving words when possible.
+**Signature:**
+```typescript
+truncate(str: string, maxLength: number): string
+```
+**Examples:**
+```typescript
+helpers.truncate('This is a very long text', 10);
+// => 'This is...'
+helpers.truncate('Short', 10);
+// => 'Short'
+helpers.truncate('OneVeryLongWord', 8);
+// => 'OneVery...'
+```
+---
+### `normalizeWhitespace(str)`
+Collapse multiple spaces into single space, trim edges.
+**Signature:**
+```typescript
+normalizeWhitespace(str: string): string
+```
+**Examples:**
+```typescript
+helpers.normalizeWhitespace('Hello    World  \n  !');
+// => 'Hello World !'
+helpers.normalizeWhitespace('  Too   many   spaces  ');
+// => 'Too many spaces'
+```
+---
+### `toCamelCase(str)`
+Convert string to camelCase.
+**Signature:**
+```typescript
+toCamelCase(str: string): string
+```
+**Examples:**
+```typescript
+helpers.toCamelCase('order-number');      // => 'orderNumber'
+helpers.toCamelCase('order_number');      // => 'orderNumber'
+helpers.toCamelCase('Order Number');      // => 'orderNumber'
+helpers.toCamelCase('ORDER-NUMBER');      // => 'orderNumber'
+```
+---
+### `toSnakeCase(str)`
+Convert string to snake_case.
+**Signature:**
+```typescript
+toSnakeCase(str: string): string
+```
+**Examples:**
+```typescript
+helpers.toSnakeCase('orderNumber');       // => 'order_number'
+helpers.toSnakeCase('OrderNumber');       // => '_order_number'
+helpers.toSnakeCase('order-number');      // => 'order_number'
+```
+---
+### `template(str, vars)`
+String interpolation with `{{variable}}` syntax.
+**Signature:**
+```typescript
+template(str: string, vars: Record<string, any>): string
+```
+**Examples:**
+```typescript
+helpers.template('Hello {{name}}!', { name: 'World' });
+// => 'Hello World!'
+helpers.template('Order {{id}} for {{customer}}', {
+  id: '123',
+  customer: 'John Doe'
+});
+// => 'Order 123 for John Doe'
+```
+---
+### `slugify(str)`
+Convert string to URL-safe slug.
+**Signature:**
+```typescript
+slugify(str: string): string
+```
+**Examples:**
+```typescript
+helpers.slugify('Hello World!');           // => 'hello-world'
+helpers.slugify('Product Name (2024)');    // => 'product-name-2024'
+helpers.slugify('Café & Restaurant');      // => 'cafe-restaurant'
+```
+---
+### `uuid()`
+Generate UUID v4.
+**Signature:**
+```typescript
+uuid(): string
+```
+**Examples:**
+```typescript
+helpers.uuid();
+// => '550e8400-e29b-41d4-a716-446655440000'
+// Use for unique IDs
+const uniqueRef = `ORDER-${helpers.uuid()}`;
+```
+---
+## Object Utilities
+### `isEmpty(value)`
+Check if value is empty (null, undefined, '', [], {}).
+**Signature:**
+```typescript
+isEmpty(value: any): boolean
+```
+**Examples:**
+```typescript
+helpers.isEmpty(null);              // => true
+helpers.isEmpty(undefined);         // => true
+helpers.isEmpty('');                // => true
+helpers.isEmpty([]);                // => true
+helpers.isEmpty({});                // => true
+helpers.isEmpty('text');            // => false
+helpers.isEmpty([1, 2]);            // => false
+helpers.isEmpty({ key: 'value' });  // => false
+helpers.isEmpty(0);                 // => false (0 is not empty)
+```
+---
+### `pick(obj, keys)`
+Pick specific fields from object.
+**Signature:**
+```typescript
+pick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>
+```
+**Examples:**
+```typescript
+const order = { id: '1', ref: 'ORD-1', status: 'OPEN', total: 100 };
+helpers.pick(order, ['id', 'ref']);
+// => { id: '1', ref: 'ORD-1' }
+```
+---
+### `omit(obj, keys)`
+Omit specific fields from object.
+**Signature:**
+```typescript
+omit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>
+```
+**Examples:**
+```typescript
+const order = { id: '1', ref: 'ORD-1', status: 'OPEN', total: 100 };
+helpers.omit(order, ['status', 'total']);
+// => { id: '1', ref: 'ORD-1' }
+```
+---
+### `deepClone(obj)`
+Deep clone object using JSON serialization.
+**Signature:**
+```typescript
+deepClone<T>(obj: T): T
+```
+**Examples:**
+```typescript
+const original = { a: { b: { c: 1 } } };
+const cloned = helpers.deepClone(original);
+cloned.a.b.c = 2;
+console.log(original.a.b.c);  // => 1 (unchanged)
+```
+**Warning:** Only works with JSON-serializable objects (no functions, undefined, etc.)
+---
+### `deepMerge(target, source)`
+Merge objects deeply.
+**Signature:**
+```typescript
+deepMerge<T extends object>(target: T, source: Partial<T>): T
+```
+**Examples:**
+```typescript
+const target = { a: { b: 1, c: 2 } };
+const source = { a: { c: 3, d: 4 }, e: 5 };
+helpers.deepMerge(target, source);
+// => { a: { b: 1, c: 3, d: 4 }, e: 5 }
+```
+---
+### `set(obj, path, value)`
+Set nested property value with dot notation. Creates intermediate objects as needed.
+**Signature:**
+```typescript
+set(obj: any, path: string, value: any): void
+```
+**Examples:**
+```typescript
+const data = {};
+helpers.set(data, 'order.customer.email', 'test@example.com');
+// => { order: { customer: { email: 'test@example.com' } } }
+helpers.set(data, 'order.total', 100);
+// => { order: { customer: {...}, total: 100 } }
+```
+---
+### `merge(...objects)`
+Shallow merge multiple objects.
+**Signature:**
+```typescript
+merge<T extends object>(...objects: Partial<T>[]): T
+```
+**Examples:**
+```typescript
+const defaults = { currency: 'USD', tax: 0 };
+const order = { total: 100, tax: 10 };
+helpers.merge(defaults, order);
+// => { currency: 'USD', tax: 10, total: 100 }
+```
+---
+## Array Transformation
+### `groupBy(array, key)`
+Group array items by key or function.
+**Signature:**
+```typescript
+groupBy<T>(array: T[], key: keyof T | ((item: T) => string)): Record<string, T[]>
+```
+**Examples:**
+```typescript
+const items = [
+  { sku: 'A', category: 'electronics' },
+  { sku: 'B', category: 'electronics' },
+  { sku: 'C', category: 'clothing' }
+];
+helpers.groupBy(items, 'category');
+// => {
+//   electronics: [{ sku: 'A', ... }, { sku: 'B', ... }],
+//   clothing: [{ sku: 'C', ... }]
+// }
+helpers.groupBy(items, item => item.sku[0]);
+// => { A: [...], B: [...], C: [...] }
+```
+---
+### `keyBy(array, key)`
+Convert array to object keyed by property.
+**Signature:**
+```typescript
+keyBy<T>(array: T[], key: keyof T | ((item: T) => string)): Record<string, T>
+```
+**Examples:**
+```typescript
+const items = [
+  { sku: 'SKU-1', name: 'Product 1' },
+  { sku: 'SKU-2', name: 'Product 2' }
+];
+helpers.keyBy(items, 'sku');
+// => {
+//   'SKU-1': { sku: 'SKU-1', name: 'Product 1' },
+//   'SKU-2': { sku: 'SKU-2', name: 'Product 2' }
+// }
+```
+---
+### `chunk(array, size)`
+Split array into chunks of specified size.
+**Signature:**
+```typescript
+chunk<T>(array: T[], size: number): T[][]
+```
+**Examples:**
+```typescript
+helpers.chunk([1, 2, 3, 4, 5], 2);
+// => [[1, 2], [3, 4], [5]]
+helpers.chunk(['a', 'b', 'c', 'd', 'e', 'f'], 3);
+// => [['a', 'b', 'c'], ['d', 'e', 'f']]
+```
+---
+### `flatten(array, depth)`
+Flatten nested arrays to specified depth.
+**Signature:**
+```typescript
+flatten<T>(array: any[], depth?: number): T[]
+```
+**Examples:**
+```typescript
+helpers.flatten([[1, 2], [3, 4]], 1);
+// => [1, 2, 3, 4]
+helpers.flatten([[[1, 2]], [[3, 4]]], 2);
+// => [1, 2, 3, 4]
+```
+---
+### `unique(array, key?)`
+Get unique values from array, optionally by key for objects.
+**Signature:**
+```typescript
+unique<T>(array: T[], key?: keyof T | ((item: T) => any)): T[]
+```
+**Examples:**
+```typescript
+helpers.unique([1, 2, 2, 3, 3, 3]);
+// => [1, 2, 3]
+const items = [
+  { sku: 'A', qty: 1 },
+  { sku: 'B', qty: 2 },
+  { sku: 'A', qty: 3 }
+];
+helpers.unique(items, 'sku');
+// => [{ sku: 'A', qty: 1 }, { sku: 'B', qty: 2 }]
+```
+---
+### `sortBy(array, key, order)`
+Sort array by key or function.
+**Signature:**
+```typescript
+sortBy<T>(array: T[], key: keyof T | ((item: T) => any), order?: 'asc' | 'desc'): T[]
+```
+**Examples:**
+```typescript
+const items = [
+  { sku: 'C', price: 30 },
+  { sku: 'A', price: 10 },
+  { sku: 'B', price: 20 }
+];
+helpers.sortBy(items, 'price', 'asc');
+// => [{ sku: 'A', price: 10 }, { sku: 'B', price: 20 }, { sku: 'C', price: 30 }]
+helpers.sortBy(items, 'sku', 'desc');
+// => [{ sku: 'C', ... }, { sku: 'B', ... }, { sku: 'A', ... }]
+```
+---
+### `compact(array)`
+Remove falsy values (null, undefined, false, 0, '') from array.
+**Signature:**
+```typescript
+compact<T>(array: (T | null | undefined | false | 0 | '')[]): T[]
+```
+**Examples:**
+```typescript
+helpers.compact([1, null, 2, undefined, 3, false, 0, '']);
+// => [1, 2, 3]
+helpers.compact(['a', '', 'b', null, 'c']);
+// => ['a', 'b', 'c']
+```
+---
+### `coalesce(...values)`
+Return first non-null/undefined value (like SQL COALESCE).
+**Signature:**
+```typescript
+coalesce<T>(...values: (T | null | undefined)[]): T | undefined
+```
+**Examples:**
+```typescript
+helpers.coalesce(null, undefined, 'first', 'second');  // => 'first'
+helpers.coalesce(null, 0, 1);                          // => 0
+helpers.coalesce(null, '', 'value');                   // => ''
+```
+---
+## Array Aggregation
+### `sum(array, key?)`
+Sum numeric values in array, optionally by key for objects.
+**Signature:**
+```typescript
+sum<T>(array: T[], key?: keyof T | ((item: T) => number)): number
+```
+**Examples:**
+```typescript
+helpers.sum([1, 2, 3, 4, 5]);  // => 15
+const items = [
+  { price: 10 },
+  { price: 20 },
+  { price: 30 }
+];
+helpers.sum(items, 'price');  // => 60
+helpers.sum(items, item => item.price * 1.1);  // => 66 (with markup)
+```
+---
+### `avg(array, key?)`
+Calculate average of numeric values.
+**Signature:**
+```typescript
+avg<T>(array: T[], key?: keyof T | ((item: T) => number)): number
+```
+**Examples:**
+```typescript
+helpers.avg([10, 20, 30]);  // => 20
+const items = [{ score: 80 }, { score: 90 }, { score: 70 }];
+helpers.avg(items, 'score');  // => 80
+```
+---
+### `min(array, key?)`
+Find minimum value in array.
+**Signature:**
+```typescript
+min<T>(array: T[], key?: keyof T | ((item: T) => number)): number | undefined
+```
+**Examples:**
+```typescript
+helpers.min([10, 5, 20, 3]);  // => 3
+const items = [{ price: 10 }, { price: 5 }, { price: 20 }];
+helpers.min(items, 'price');  // => 5
+```
+---
+### `max(array, key?)`
+Find maximum value in array.
+**Signature:**
+```typescript
+max<T>(array: T[], key?: keyof T | ((item: T) => number)): number | undefined
+```
+**Examples:**
+```typescript
+helpers.max([10, 5, 20, 3]);  // => 20
+const items = [{ quantity: 10 }, { quantity: 5 }, { quantity: 20 }];
+helpers.max(items, 'quantity');  // => 20
+```
+---
+### `clamp(num, min, max)`
+Clamp number to specified range.
+**Signature:**
+```typescript
+clamp(num: number, min: number, max: number): number
+```
+**Examples:**
+```typescript
+helpers.clamp(5, 0, 10);    // => 5
+helpers.clamp(-5, 0, 10);   // => 0
+helpers.clamp(15, 0, 10);   // => 10
+```
+---
+## Date/Time
+### `addDays(date, days)`
+Add days to date.
+**Signature:**
+```typescript
+addDays(date: Date | string, days: number): Date
+```
+**Examples:**
+```typescript
+helpers.addDays(new Date('2025-01-14'), 7);
+// => Date('2025-01-21')
+helpers.addDays('2025-01-14', 30);
+// => Date('2025-02-13')
+```
+---
+### `subtractDays(date, days)`
+Subtract days from date.
+**Signature:**
+```typescript
+subtractDays(date: Date | string, days: number): Date
+```
+**Examples:**
+```typescript
+helpers.subtractDays(new Date('2025-01-14'), 7);
+// => Date('2025-01-07')
+```
+---
+### `dateDiff(date1, date2)`
+Get difference between dates in days.
+**Signature:**
+```typescript
+dateDiff(date1: Date | string, date2: Date | string): number
+```
+**Examples:**
+```typescript
+helpers.dateDiff('2025-01-14', '2025-01-21');  // => 7
+helpers.dateDiff('2025-01-21', '2025-01-14');  // => -7
+```
+---
+### `parseDate(dateStr, format?)`
+Parse date with multiple format support.
+**Signature:**
+```typescript
+parseDate(dateStr: string, format?: string): Date | null
+```
+**Supported Formats:**
+- ISO: `'2025-01-14'`
+- US: `'01/14/2025'`
+- EU: `'14-01-2025'`
+- Compact: `'20250114'`
+**Examples:**
+```typescript
+helpers.parseDate('2025-01-14');       // ISO
+helpers.parseDate('01/14/2025');       // MM/DD/YYYY
+helpers.parseDate('14-01-2025');       // DD-MM-YYYY
+helpers.parseDate('20250114');         // YYYYMMDD
+```
+**Returns:** `Date` object or `null` if parsing fails
+---
+## Function Utilities
+### `debounce(fn, delayMs)`
+Delay function execution until after delay period.
+**Signature:**
+```typescript
+debounce<T extends (...args: any[]) => any>(fn: T, delayMs: number): T
+```
+**Examples:**
+```typescript
+const logMessage = (msg: string) => console.log(msg);
+const debouncedLog = helpers.debounce(logMessage, 1000);
+debouncedLog('Message 1');  // Cancelled
+debouncedLog('Message 2');  // Cancelled
+debouncedLog('Message 3');  // Executed after 1000ms
+```
+---
+### `throttle(fn, limitMs)`
+Limit function execution rate.
+**Signature:**
+```typescript
+throttle<T extends (...args: any[]) => any>(fn: T, limitMs: number): T
+```
+**Examples:**
+```typescript
+const logMessage = (msg: string) => console.log(msg);
+const throttledLog = helpers.throttle(logMessage, 1000);
+throttledLog('Message 1');  // Executed immediately
+throttledLog('Message 2');  // Ignored (within 1000ms)
+// Wait 1000ms
+throttledLog('Message 3');  // Executed
+```
+---
+## Type Guards
+### `isString(value)`, `isNumber(value)`, `isArray(value)`, `isObject(value)`, `isDate(value)`
+Type checking utilities.
+**Signatures:**
+```typescript
+isString(value: any): boolean
+isNumber(value: any): boolean
+isArray(value: any): boolean
+isObject(value: any): boolean
+isDate(value: any): boolean
+```
+**Examples:**
+```typescript
+helpers.isString('hello');             // => true
+helpers.isNumber(123);                 // => true
+helpers.isNumber(NaN);                 // => false
+helpers.isArray([1, 2, 3]);            // => true
+helpers.isObject({ key: 'value' });    // => true
+helpers.isObject([1, 2, 3]);           // => false
+helpers.isDate(new Date());            // => true
+helpers.isDate('2025-01-14');          // => false
+```
+---
+## Utility Functions
+### `defaultTo(value, defaultValue)`
+Return default if value is null/undefined.
+**Signature:**
+```typescript
+defaultTo<T>(value: T | null | undefined, defaultValue: T): T
+```
+**Examples:**
+```typescript
+helpers.defaultTo(null, 'default');       // => 'default'
+helpers.defaultTo(undefined, 'default');  // => 'default'
+helpers.defaultTo('value', 'default');    // => 'value'
+helpers.defaultTo(0, 10);                 // => 0 (0 is not null/undefined)
+```
+---
+### `range(start, end?, step?)`
+Generate numeric ranges.
+**Signature:**
+```typescript
+range(start: number, end?: number, step?: number): number[]
+```
+**Examples:**
+```typescript
+helpers.range(5);              // => [0, 1, 2, 3, 4]
+helpers.range(1, 6);           // => [1, 2, 3, 4, 5]
+helpers.range(0, 10, 2);       // => [0, 2, 4, 6, 8]
+helpers.range(10, 0, -2);      // => [10, 8, 6, 4, 2]
+```
+---
+### `hashString(str)`
+Generate deterministic hash from string (not cryptographically secure).
+**Signature:**
+```typescript
+hashString(str: string): string
+```
+**Examples:**
+```typescript
+helpers.hashString('hello');  // => '4x93m' (deterministic)
+helpers.hashString('hello');  // => '4x93m' (same input = same output)
+```
+**Use Case:** Stable keys, content-based IDs, deduplication keys
+---
+## Performance
+### `memoize(fn)`
+Memoize expensive function.
+**Signature:**
+```typescript
+memoize<T extends (...args: any[]) => any>(fn: T): T
+```
+**Examples:**
+```typescript
+const expensiveCalculation = (a, b) => {
+  console.log('Calculating...');
+  return a + b;
+};
+const memoized = helpers.memoize(expensiveCalculation);
+memoized(1, 2);  // => Logs "Calculating...", returns 3
+memoized(1, 2);  // => Returns 3 (from cache, no log)
+memoized(2, 3);  // => Logs "Calculating...", returns 5
+```
+---
+### `retry(fn, maxRetries?, delayMs?)`
+Retry function with exponential backoff.
+**Signature:**
+```typescript
+retry<T>(fn: () => Promise<T>, maxRetries?: number, delayMs?: number): Promise<T>
+```
+**Parameters:**
+- `fn` - Async function to retry
+- `maxRetries` - Max attempts (default: 3)
+- `delayMs` - Initial delay (default: 100ms)
+**Examples:**
+```typescript
+const result = await helpers.retry(
+  async () => {
+    const response = await fetch('https://api.example.com/data');
+    return response.json();
+  },
+  3,    // Max 3 retries
+  100   // Start with 100ms delay
+);
+```
+---
+### `batchProcess(items, processor, batchSize?)`
+Process array in batches (async, default: 50 items/batch).
+**Signature:**
+```typescript
+batchProcess<T, R>(
+  items: T[],
+  processor: (item: T, index: number) => Promise<R>,
+  batchSize?: number
+): Promise<R[]>
+```
+**Examples:**
+```typescript
+const items = [1, 2, 3, 4, 5];
+const results = await helpers.batchProcess(
+  items,
+  async (item, index) => {
+    // Call external API
+    return await fetchData(item);
+  },
+  2  // Process 2 items at a time
+);
+```
+---
+## XML/JSON Specific
+### `extractCustomAttribute(customAttributes, attributeId, defaultValue?)`
+Extract custom attribute by ID from XML/JSON custom attributes.
+**Signature:**
+```typescript
+extractCustomAttribute(customAttributes: any, attributeId: string, defaultValue?: any): any
+```
+**Handles Multiple Formats:**
+- Array of attributes: `[{ '@attribute-id': 'id', '#text': 'value' }, ...]`
+- Single attribute object: `{ '@attribute-id': 'id', '#text': 'value' }`
+- Object with keys: `{ 'key1': 'value1', 'key2': 'value2' }`
+**Examples:**
+```typescript
+// Array format (SFCC XML)
+const attrs = [
+  { '@attribute-id': 'retailerId', '#text': '123' },
+  { '@attribute-id': 'orderType', '#text': 'HD' }
+];
+helpers.extractCustomAttribute(attrs, 'retailerId');
+// => '123'
+// Object format
+const attrs2 = { 'retailerId': '123', 'orderType': 'HD' };
+helpers.extractCustomAttribute(attrs2, 'orderType');
+// => 'HD'
+// With default
+helpers.extractCustomAttribute(attrs, 'missing', 'DEFAULT');
+// => 'DEFAULT'
+```
+---
+### `getXmlAttribute(obj, attrName, defaultValue?)`
+Extract XML attribute from object with multi-format support. Automatically handles different XML parser formats.
+**Signature:**
+```typescript
+getXmlAttribute(obj: any, attrName: string, defaultValue?: any): any
+```
+**Supported XML Attribute Formats:**
+The function tries multiple formats in priority order:
+1. `$attr-name` - Versori/xml2js with $ prefix as direct key
+2. `$['attr-name']` - Nested in $ object (Versori platform format)
+3. `@attr-name` - SDK XMLParserService default format
+4. `@['attr-name']` - Nested in @ object (alternative format)
+5. `attr-name` - Direct attribute (fallback)
+6. `_attributes['attr-name']` - xml2js _attributes format
+**Why This Exists:**
+Different XML parsers store attributes in different formats. This helper eliminates the need to manually check multiple formats in resolvers.
+**Examples:**
+```typescript
+// Versori format (nested $ object)
+const versoriData = { $: { 'shipment-id': '02408380' } };
+helpers.getXmlAttribute(versoriData, 'shipment-id');
+// => '02408380'
+// SDK format (@ prefix)
+const sdkData = { '@shipment-id': '02408380' };
+helpers.getXmlAttribute(sdkData, 'shipment-id');
+// => '02408380'
+// Direct format
+const directData = { 'shipment-id': '02408380' };
+helpers.getXmlAttribute(directData, 'shipment-id');
+// => '02408380'
+// With default value
+helpers.getXmlAttribute({}, 'shipment-id', 'DEFAULT');
+// => 'DEFAULT'
+// Real-world usage in resolver
+'custom.createFulfilmentChoiceRef': (value, data, config, helpers) => {
+  const shipmentData = value || data || {};
+  const shipmentId = helpers.getXmlAttribute(shipmentData, 'shipment-id');
+  return `fc_${shipmentId}`;
+}
+```
+**Use Cases:**
+- Extracting XML attributes in custom resolvers
+- Handling multiple XML parser formats (Versori, SDK, xml2js)
+- Simplifying resolver code (no need to check multiple formats manually)
+**Returns:** Attribute value or `defaultValue` (or `undefined`)
+---
+### `getXmlTextContent(obj, defaultValue?)`
+Extract XML text content from object with multi-format support. Automatically handles different XML parser formats for text content.
+**Signature:**
+```typescript
+getXmlTextContent(obj: any, defaultValue?: any): any
+```
+**Supported XML Text Content Formats:**
+The function tries multiple formats in priority order:
+1. `_` - Versori platform format (text content)
+2. `#text` - SDK XMLParserService default format (text content)
+3. `value` - Fallback property
+4. Direct value - If already a string/primitive
+**Why This Exists:**
+Different XML parsers store text content in different properties. This helper eliminates the need to manually check multiple formats in resolvers.
+**Examples:**
+```typescript
+// Versori format (text in _ property)
+const versoriData = { $: { unit: '1' }, _: '1.0' };
+helpers.getXmlTextContent(versoriData);
+// => '1.0'
+// SDK format (text in #text property)
+const sdkData = { '@unit': '1', '#text': '1.0' };
+helpers.getXmlTextContent(sdkData);
+// => '1.0'
+// Direct string
+helpers.getXmlTextContent('1.0');
+// => '1.0'
+// With default value
+helpers.getXmlTextContent({}, 'DEFAULT');
+// => 'DEFAULT'
+// Real-world usage in resolver
+'custom.parseQuantity': (value, data, config, helpers) => {
+  const qty = helpers.getXmlTextContent(value) ?? value;
+  return parseFloat(String(qty));
+}
+```
+**Use Cases:**
+- Extracting XML text content in custom resolvers
+- Handling multiple XML parser formats (Versori, SDK, xml2js)
+- Simplifying resolver code (no need to check multiple formats manually)
+**Returns:** Text content value or `defaultValue` (or `undefined`)
+---
+### `normalizeEmpty(value, defaultValue?, trimWhitespace?)`
+Normalize empty value handling null, undefined, empty string, and whitespace. Useful for CSV and JSON data where empty values may be represented differently.
+**Signature:**
+```typescript
+normalizeEmpty(value: any, defaultValue?: any, trimWhitespace?: boolean): any
+```
+**Normalization Rules:**
+- `null` → defaultValue
+- `undefined` → defaultValue
+- `''` (empty string) → defaultValue
+- `'   '` (whitespace-only) → defaultValue (if trimWhitespace: true, default)
+- Other values → returned as-is
+**Parameters:**
+- `value` - Value to normalize
+- `defaultValue` - Value to return if empty (default: undefined)
+- `trimWhitespace` - Whether to treat whitespace-only strings as empty (default: true)
+**Examples:**
+```typescript
+// CSV empty values
+helpers.normalizeEmpty(null, 'N/A');           // => 'N/A'
+helpers.normalizeEmpty(undefined, 'N/A');      // => 'N/A'
+helpers.normalizeEmpty('', 'N/A');             // => 'N/A'
+helpers.normalizeEmpty('   ', 'N/A');          // => 'N/A' (trimWhitespace: true)
+helpers.normalizeEmpty('value', 'N/A');        // => 'value'
+// JSON null handling
+helpers.normalizeEmpty(jsonData.field, 'DEFAULT'); // => 'DEFAULT' if null/undefined/empty
+// Preserve whitespace when needed
+helpers.normalizeEmpty('   ', 'N/A', false);   // => '   ' (preserves whitespace)
+```
+**Use Cases:**
+- Normalizing CSV empty values (null, '', whitespace)
+- Handling JSON null/undefined values
+- Consistent empty value handling across data sources
+- Simplifying resolver code (no need to check multiple empty formats)
+**Returns:** Normalized value or `defaultValue` (or `undefined`)
+---
+## See Also
+- [Main Resolver Guide](./mapping-resolvers-resolver-guide.md) - Getting started
+- [API Reference](./mapping-resolvers-resolver-api-reference.md) - ResolverBuilder methods
+- [Parameters Reference](./mapping-resolvers-resolver-parameters-reference.md) - value, data, config, helpers
+- [Troubleshooting](./mapping-resolvers-resolver-troubleshooting.md) - Common issues
+- [Cookbook](./mapping-resolvers-resolver-cookbook.md) - Advanced patterns
+---
+**License:** MIT