@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/04-REFERENCE/resolver-signature/modules/resolver-signature-07-api-reference.md

@@ -1,794 +1,794 @@
-# Module 7: API Reference
-
-**Level:** Reference
-**Estimated Time:** As needed
-
-## Overview
-
-This module provides complete TypeScript type definitions, interfaces, and testing utilities for the 4-parameter resolver signature. Use this as a reference when building production resolvers.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Know the exact TypeScript types for resolvers
-- ✅ Understand the ResolverHelpers interface
-- ✅ Use type-safe resolver development
-- ✅ Test resolvers with proper type checking
-- ✅ Access complete helper function reference
-
-## Type Definitions
-
-### ResolverFunction
-
-The standard resolver function type:
-
-```typescript
-/**
- * Standard resolver function signature
- *
- * @param value - The extracted field value to transform
- * @param sourceData - Complete source object for context-aware transformations
- * @param config - Resolver-specific configuration passed via mapper context
- * @param helpers - SDK utilities and user-provided context
- * @returns Transformed value or Promise of transformed value
- */
-type ResolverFunction = (
-  value: any,
-  sourceData: any,
-  config: any,
-  helpers: ResolverHelpers
-) => any | Promise<any>;
-```
-
-### FieldResolverFunction
-
-Alias for ResolverFunction used in field mapping contexts:
-
-```typescript
-type FieldResolverFunction = ResolverFunction;
-```
-
-### Resolver Collection Type
-
-For defining multiple resolvers:
-
-```typescript
-type ResolverCollection = Record<string, FieldResolverFunction>;
-
-// Example usage
-const myResolvers: ResolverCollection = {
-  'custom.formatSKU': (value, sourceData, config, helpers) => {
-    return String(value).toUpperCase();
-  },
-  'custom.parsePrice': (value, sourceData, config, helpers) => {
-    return helpers.parseFloatSafe(value, 0);
-  }
-};
-```
-
-## ResolverHelpers Interface
-
-Complete interface with all 54 helper functions:
-
-```typescript
-interface ResolverHelpers {
-  // ===== Core Utilities =====
-
-  /**
-   * Safely get nested property from object
-   * @param obj - Source object
-   * @param path - Dot-notation path (e.g., 'customer.address.city')
-   * @param defaultValue - Value to return if path doesn't exist
-   */
-  get(obj: any, path: string, defaultValue?: any): any;
-
-  /**
-   * Safely set nested property on object
-   * @param obj - Target object
-   * @param path - Dot-notation path
-   * @param value - Value to set
-   */
-  set(obj: any, path: string, value: any): any;
-
-  // Note: toString() is not a helper function
-  // Use native String(value) or sdk.toString resolver instead
-
-  /**
-   * Safely parse integer with fallback
-   * @param value - Value to parse
-   * @param defaultValue - Default if parsing fails (default: 0)
-   */
-  parseIntSafe(value: any, defaultValue?: number): number;
-
-  /**
-   * Safely parse float with fallback
-   * @param value - Value to parse
-   * @param defaultValue - Default if parsing fails (default: 0)
-   */
-  parseFloatSafe(value: any, defaultValue?: number): number;
-
-  // ===== Date Operations =====
-
-  /**
-   * Format date to ISO8601 string
-   * @param date - Date to format (string or Date object)
-   * @returns ISO8601 formatted date string
-   */
-  formatDate(date: string | Date): string;
-
-  // Note: formatDateShort() is not a helper function
-  // It's available as sdk.formatDateShort resolver instead
-
-  /**
-   * Parse date string to Date object
-   * @param dateStr - Date string to parse
-   */
-  parseDate(dateStr: string): Date | null;
-
-  /**
-   * Add days to a date
-   * @param date - Starting date
-   * @param days - Number of days to add
-   */
-  addDays(date: Date, days: number): Date;
-
-  /**
-   * Subtract days from a date
-   * @param date - Starting date
-   * @param days - Number of days to subtract
-   */
-  subtractDays(date: Date, days: number): Date;
-
-  /**
-   * Calculate difference between dates in days
-   * @param date1 - First date
-   * @param date2 - Second date
-   */
-  dateDiff(date1: Date, date2: Date): number;
-
-  // ===== String Operations =====
-
-  /**
-   * Normalize whitespace (collapse multiple spaces to one)
-   * @param str - String to normalize
-   */
-  normalizeWhitespace(str: string): string;
-
-  /**
-   * Convert string to camelCase
-   * @param str - String to convert
-   */
-  toCamelCase(str: string): string;
-
-  /**
-   * Convert string to snake_case
-   * @param str - String to convert
-   */
-  toSnakeCase(str: string): string;
-
-  /**
-   * Truncate string to max length
-   * @param str - String to truncate
-   * @param maxLength - Maximum length (includes '...' suffix)
-   * @returns Truncated string with '...' appended if needed
-   */
-  truncate(str: string, maxLength: number): string;
-
-  /**
-   * Create slug from string (lowercase, hyphenated)
-   * @param str - String to slugify
-   */
-  slugify(str: string): string;
-
-  /**
-   * Simple string template replacement
-   * @param template - Template string with {{placeholders}}
-   * @param values - Object with replacement values
-   */
-  template(template: string, values: Record<string, any>): string;
-
-  /**
-   * Hash string using simple algorithm
-   * @param str - String to hash
-   */
-  hashString(str: string): string;
-
-  // ===== Array Operations =====
-
-  /**
-   * Ensure value is an array (wraps non-arrays)
-   * @param value - Value to convert to array
-   */
-  ensureArray(value: any): any[];
-
-  /**
-   * Return first non-null/non-undefined value from array
-   * @param values - Array of values to check
-   */
-  coalesce(values: any[]): any;
-
-  /**
-   * Group array items by key
-   * @param array - Array to group
-   * @param key - Property to group by
-   */
-  groupBy<T>(array: T[], key: string | ((item: T) => string)): Record<string, T[]>;
-
-  /**
-   * Convert array to object keyed by property
-   * @param array - Array to convert
-   * @param key - Property to use as key
-   */
-  keyBy<T>(array: T[], key: string | ((item: T) => string)): Record<string, T>;
-
-  /**
-   * Split array into chunks
-   * @param array - Array to chunk
-   * @param size - Chunk size
-   */
-  chunk<T>(array: T[], size: number): T[][];
-
-  /**
-   * Flatten nested arrays
-   * @param array - Array to flatten
-   * @param depth - Depth to flatten (default: 1)
-   */
-  flatten<T>(array: any[], depth?: number): T[];
-
-  /**
-   * Get unique values from array
-   * @param array - Array to deduplicate
-   */
-  unique<T>(array: T[]): T[];
-
-  /**
-   * Sort array by property
-   * @param array - Array to sort
-   * @param key - Property to sort by
-   * @param order - Sort order ('asc' or 'desc')
-   */
-  sortBy<T>(array: T[], key: string | ((item: T) => any), order?: 'asc' | 'desc'): T[];
-
-  /**
-   * Remove null/undefined values from array
-   * @param array - Array to compact
-   */
-  compact<T>(array: (T | null | undefined)[]): T[];
-
-  /**
-   * Sum numeric array values
-   * @param array - Array of numbers
-   */
-  sum(array: number[]): number;
-
-  /**
-   * Calculate average of numeric array
-   * @param array - Array of numbers
-   */
-  avg(array: number[]): number;
-
-  /**
-   * Find minimum value in array
-   * @param array - Array of numbers
-   */
-  min(array: number[]): number;
-
-  /**
-   * Find maximum value in array
-   * @param array - Array of numbers
-   */
-  max(array: number[]): number;
-
-  // ===== Object Operations =====
-
-  /**
-   * Deep clone an object
-   * @param obj - Object to clone
-   */
-  deepClone<T>(obj: T): T;
-
-  /**
-   * Deep merge objects
-   * @param target - Target object
-   * @param sources - Source objects to merge
-   */
-  deepMerge(target: any, ...sources: any[]): any;
-
-  /**
-   * Merge multiple objects
-   * @param objects - Objects to merge
-   */
-  merge(...objects: any[]): any;
-
-  // ===== Validation =====
-
-  /**
-   * Validate email address format
-   * @param email - Email to validate
-   */
-  isValidEmail(email: string): boolean;
-
-  /**
-   * Require field to be non-null/non-undefined
-   * @param value - Value to check
-   * @param fieldName - Field name for error message
-   * @throws Error if value is null/undefined
-   */
-  requireField(value: any, fieldName: string): any;
-
-  // ===== Number Operations =====
-
-  /**
-   * Clamp number between min and max
-   * @param value - Value to clamp
-   * @param min - Minimum value
-   * @param max - Maximum value
-   */
-  clamp(value: number, min: number, max: number): number;
-
-  /**
-   * Format number as currency with fixed decimal places
-   * @param amount - Number to format
-   * @param scale - Number of decimal places (default: 2)
-   * @returns Formatted currency string
-   */
-  formatCurrency(amount: number, scale?: number): string;
-
-  // ===== Type Checks =====
-
-  /**
-   * Check if value is a string
-   */
-  isString(value: any): value is string;
-
-  /**
-   * Check if value is a number
-   */
-  isNumber(value: any): value is number;
-
-  /**
-   * Check if value is an array
-   */
-  isArray(value: any): value is any[];
-
-  /**
-   * Check if value is an object
-   */
-  isObject(value: any): value is object;
-
-  /**
-   * Check if value is a Date
-   */
-  isDate(value: any): value is Date;
-
-  // ===== JSON Operations =====
-
-  /**
-   * Safely parse JSON with fallback
-   * @param str - JSON string to parse
-   * @param defaultValue - Default if parsing fails
-   */
-  safeJsonParse(str: string, defaultValue?: any): any;
-
-  // ===== Performance =====
-
-  /**
-   * Memoize function results (caches based on JSON.stringify of arguments)
-   * @param fn - Function to memoize
-   * @returns Memoized version of function
-   */
-  memoize<T extends (...args: any[]) => any>(fn: T): T;
-
-  /**
-   * Process array in batches with async operations
-   * @param items - Array items to process
-   * @param processor - Async function to process each item (receives item and index)
-   * @param batchSize - Number of items per batch (default: 50)
-   * @returns Array of results in original order
-   */
-  batchProcess<T, R>(
-    items: T[],
-    processor: (item: T, index: number) => Promise<R>,
-    batchSize?: number
-  ): Promise<R[]>;
-
-  /**
-   * Retry async function with exponential backoff
-   * @param fn - Async function to retry
-   * @param maxRetries - Maximum retry attempts (default: 3)
-   * @param delayMs - Initial delay in milliseconds (default: 100)
-   * @returns Result of successful function call
-   * @throws Last error if all retries fail
-   */
-  retry<T>(
-    fn: () => Promise<T>,
-    maxRetries?: number,
-    delayMs?: number
-  ): Promise<T>;
-
-  /**
-   * Debounce function calls
-   * @param fn - Function to debounce
-   * @param delayMs - Delay in milliseconds
-   */
-  debounce<T extends (...args: any[]) => any>(fn: T, delayMs: number): T;
-
-  /**
-   * Throttle function calls
-   * @param fn - Function to throttle
-   * @param limitMs - Throttle limit in milliseconds
-   */
-  throttle<T extends (...args: any[]) => any>(fn: T, limitMs: number): T;
-
-  // ===== Utility Functions =====
-
-  /**
-   * Extract custom attribute from attributes array
-   * @param attributes - Array of {name, value} objects
-   * @param attrName - Attribute name to extract
-   * @param defaultValue - Default if not found
-   */
-  extractCustomAttribute(
-    attributes: Array<{ name: string; value: any }>,
-    attrName: string,
-    defaultValue?: any
-  ): any;
-
-  /**
-   * Map value using lookup table
-   * @param value - Value to map
-   * @param mapping - Lookup table
-   * @param defaultValue - Default if not in mapping
-   */
-  mapValue(value: any, mapping: Record<string, any>, defaultValue?: any): any;
-
-  /**
-   * Combine first and last name
-   * @param firstName - First name
-   * @param lastName - Last name
-   */
-  fullName(firstName: string, lastName: string): string;
-
-  /**
-   * Generate UUID v4
-   */
-  uuid(): string;
-
-  // ===== Context Objects =====
-
-  /**
-   * Logger instance for debugging
-   */
-  log: {
-    debug(message: string, ...args: any[]): void;
-    info(message: string, ...args: any[]): void;
-    warn(message: string, ...args: any[]): void;
-    error(message: string, ...args: any[]): void;
-  };
-
-  /**
-   * FluentClient instance for GraphQL queries (optional)
-   */
-  fluentClient?: {
-    graphql(params: { query: string; variables?: any }): Promise<any>;
-  };
-
-  /**
-   * User-provided shared configuration object
-   * Prefer using the config parameter for custom settings
-   */
-  context?: any;
-}
-```
-
-## Typed Resolver Examples
-
-### Basic Typed Resolver
-
-```typescript
-import type { FieldResolverFunction } from '@fluentcommerce/fc-connect-sdk';
-
-const formatSKU: FieldResolverFunction = (value, sourceData, config, helpers) => {
-  const prefix = config?.prefix || 'SKU';
-  return `${prefix}-${String(value).toUpperCase()}`;
-};
-```
-
-### Typed Resolver with Config Interface
-
-```typescript
-interface SKUConfig {
-  prefix?: string;
-  separator?: string;
-  includeTimestamp?: boolean;
-}
-
-const formatSKU = (
-  value: any,
-  sourceData: any,
-  config: SKUConfig,
-  helpers: ResolverHelpers
-): string => {
-  const prefix = config.prefix || 'SKU';
-  const separator = config.separator || '-';
-
-  let result = `${prefix}${separator}${String(value).toUpperCase()}`;
-
-  if (config.includeTimestamp) {
-    const timestamp = helpers.formatDate(new Date(), 'YYYYMMDD');
-    result += `${separator}${timestamp}`;
-  }
-
-  return result;
-};
-```
-
-### Async Typed Resolver
-
-```typescript
-interface EnrichmentConfig {
-  enableEnrichment?: boolean;
-  timeout?: number;
-}
-
-const enrichProduct = async (
-  sku: string,
-  sourceData: any,
-  config: EnrichmentConfig,
-  helpers: ResolverHelpers
-): Promise<any> => {
-  if (!helpers.fluentClient || !config.enableEnrichment) {
-    return { sku };
-  }
-
-  try {
-    const result = await helpers.fluentClient.graphql({
-      query: `query { product(ref: "${sku}") { id name } }`
-    });
-
-    return result.data.product || { sku, found: false };
-  } catch (error) {
-    helpers.log.error('Enrichment failed', error);
-    return { sku, error: (error as Error).message };
-  }
-};
-```
-
-## Testing Utilities
-
-### Mock ResolverHelpers
-
-```typescript
-import type { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
-
-function createMockHelpers(): ResolverHelpers {
-  return {
-    // Core utilities
-    get: (obj: any, path: string, defaultValue?: any) => {
-      // Simple implementation for testing
-      const keys = path.split('.');
-      let result = obj;
-      for (const key of keys) {
-        if (result === null || result === undefined) {
-          return defaultValue;
-        }
-        result = result[key];
-      }
-      return result ?? defaultValue;
-    },
-    set: (obj: any, path: string, value: any) => {
-      const keys = path.split('.');
-      let current = obj;
-      for (let i = 0; i < keys.length - 1; i++) {
-        current[keys[i]] = current[keys[i]] || {};
-        current = current[keys[i]];
-      }
-      current[keys[keys.length - 1]] = value;
-      return obj;
-    },
-    toString: (value: any) => String(value ?? ''),
-    parseIntSafe: (value: any, defaultValue: number = 0) => {
-      const parsed = parseInt(value, 10);
-      return isNaN(parsed) ? defaultValue : parsed;
-    },
-    parseFloatSafe: (value: any, defaultValue: number = 0) => {
-      const parsed = parseFloat(value);
-      return isNaN(parsed) ? defaultValue : parsed;
-    },
-    // ... implement other helpers as needed for testing
-    log: {
-      debug: jest.fn(),
-      info: jest.fn(),
-      warn: jest.fn(),
-      error: jest.fn()
-    }
-  } as any as ResolverHelpers;
-}
-```
-
-### Unit Test Template
-
-```typescript
-import type { FieldResolverFunction } from '@fluentcommerce/fc-connect-sdk';
-
-describe('Custom Resolver', () => {
-  let helpers: ResolverHelpers;
-
-  beforeEach(() => {
-    helpers = createMockHelpers();
-  });
-
-  it('should transform value correctly', () => {
-    const resolver: FieldResolverFunction = (value, sourceData, config, helpers) => {
-      return String(value).toUpperCase();
-    };
-
-    const result = resolver('test', {}, {}, helpers);
-
-    expect(result).toBe('TEST');
-  });
-
-  it('should use config parameter', () => {
-    const resolver: FieldResolverFunction = (value, sourceData, config, helpers) => {
-      const prefix = config.prefix || 'DEFAULT';
-      return `${prefix}-${value}`;
-    };
-
-    const result = resolver('test', {}, { prefix: 'CUSTOM' }, helpers);
-
-    expect(result).toBe('CUSTOM-test');
-  });
-
-  it('should access sourceData', () => {
-    const resolver: FieldResolverFunction = (value, sourceData, config, helpers) => {
-      const quantity = helpers.get(sourceData, 'quantity', 1);
-      return value * quantity;
-    };
-
-    const result = resolver(10, { quantity: 5 }, {}, helpers);
-
-    expect(result).toBe(50);
-  });
-});
-```
-
-### Integration Test Template
-
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-describe('Resolver Integration', () => {
-  it('should work with UniversalMapper', async () => {
-    const customResolvers = {
-      'custom.transform': (value, sourceData, config, helpers) => {
-        return `${config.prefix}-${value}`;
-      }
-    };
-
-    const mapper = new UniversalMapper(
-      {
-        fields: {
-          result: { source: 'input', resolver: 'custom.transform' }
-        }
-      },
-      {
-        customResolvers,
-        context: { prefix: 'TEST' }
-      }
-    );
-
-    const result = await mapper.map({ input: 'value' });
-
-    expect(result.success).toBe(true);
-    expect(result.data.result).toBe('TEST-value');
-  });
-});
-```
-
-## Production Best Practices
-
-### 1. Always Type Your Resolvers
-
-```typescript
-// ✅ GOOD: Fully typed
-const resolver: FieldResolverFunction = (value, sourceData, config, helpers) => {
-      return String(value).toUpperCase();
-};
-
-// ❌ BAD: No types
-const resolver = (value, sourceData, config, helpers) => {
-      return String(value).toUpperCase();
-};
-```
-
-### 2. Document Config Requirements
-
-```typescript
-/**
- * Format SKU with configurable prefix
- *
- * @param value - SKU to format
- * @param sourceData - Source data context
- * @param config - Configuration
- * @param config.prefix - SKU prefix (default: 'SKU')
- * @param config.separator - Separator (default: '-')
- * @param helpers - SDK helpers
- */
-const formatSKU: FieldResolverFunction = (value, sourceData, config, helpers) => {
-  // Implementation
-};
-```
-
-### 3. Handle Edge Cases
-
-```typescript
-const resolver: FieldResolverFunction = (value, sourceData, config, helpers) => {
-  // Handle null/undefined
-  if (value === null || value === undefined) {
-    return config.defaultValue || null;
-  }
-
-  // Handle empty string
-  if (String(value).trim() === '') {
-    return config.defaultValue || null;
-  }
-
-  // Proceed with transformation
-      return String(value).toUpperCase();
-};
-```
-
-### 4. Use Type Guards
-
-```typescript
-const resolver: FieldResolverFunction = (value, sourceData, config, helpers) => {
-  if (!helpers.isString(value) && !helpers.isNumber(value)) {
-    helpers.log.warn(`Unexpected value type: ${typeof value}`);
-    return null;
-  }
-
-      return String(value).toUpperCase();
-};
-```
-
-## Key Takeaways
-
-- 🎯 **Use TypeScript types** - `FieldResolverFunction` for type safety
-- 🎯 **Know ResolverHelpers** - 48+ utility functions available
-- 🎯 **Test thoroughly** - Unit and integration tests
-- 🎯 **Document config** - Clear JSDoc comments
-- 🎯 **Handle edge cases** - Null, undefined, empty values
-
-## Quick Reference
-
-```typescript
-// Standard signature
-(value: any, sourceData: any, config: any, helpers: ResolverHelpers) => any | Promise<any>
-
-// Typed version
-const resolver: FieldResolverFunction = (value, sourceData, config, helpers) => {
-  // Implementation
-};
-
-// With config interface
-interface MyConfig {
-  option?: string;
-}
-
-const resolver = (
-  value: any,
-  sourceData: any,
-  config: MyConfig,
-  helpers: ResolverHelpers
-): any => {
-  // Implementation
-};
-```
-
-## Conclusion
-
-You now have complete reference documentation for the 4-parameter resolver signature. Use this module as a reference when building production resolvers.
-
----
-
-**Next:** Return to the [Main Guide](../resolver-signature-readme.md) or explore the [Examples Directory](../examples/) for practical implementations.
+# Module 7: API Reference
+
+**Level:** Reference
+**Estimated Time:** As needed
+
+## Overview
+
+This module provides complete TypeScript type definitions, interfaces, and testing utilities for the 4-parameter resolver signature. Use this as a reference when building production resolvers.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Know the exact TypeScript types for resolvers
+- ✅ Understand the ResolverHelpers interface
+- ✅ Use type-safe resolver development
+- ✅ Test resolvers with proper type checking
+- ✅ Access complete helper function reference
+
+## Type Definitions
+
+### ResolverFunction
+
+The standard resolver function type:
+
+```typescript
+/**
+ * Standard resolver function signature
+ *
+ * @param value - The extracted field value to transform
+ * @param sourceData - Complete source object for context-aware transformations
+ * @param config - Resolver-specific configuration passed via mapper context
+ * @param helpers - SDK utilities and user-provided context
+ * @returns Transformed value or Promise of transformed value
+ */
+type ResolverFunction = (
+  value: any,
+  sourceData: any,
+  config: any,
+  helpers: ResolverHelpers
+) => any | Promise<any>;
+```
+
+### FieldResolverFunction
+
+Alias for ResolverFunction used in field mapping contexts:
+
+```typescript
+type FieldResolverFunction = ResolverFunction;
+```
+
+### Resolver Collection Type
+
+For defining multiple resolvers:
+
+```typescript
+type ResolverCollection = Record<string, FieldResolverFunction>;
+
+// Example usage
+const myResolvers: ResolverCollection = {
+  'custom.formatSKU': (value, sourceData, config, helpers) => {
+    return String(value).toUpperCase();
+  },
+  'custom.parsePrice': (value, sourceData, config, helpers) => {
+    return helpers.parseFloatSafe(value, 0);
+  }
+};
+```
+
+## ResolverHelpers Interface
+
+Complete interface with all 54 helper functions:
+
+```typescript
+interface ResolverHelpers {
+  // ===== Core Utilities =====
+
+  /**
+   * Safely get nested property from object
+   * @param obj - Source object
+   * @param path - Dot-notation path (e.g., 'customer.address.city')
+   * @param defaultValue - Value to return if path doesn't exist
+   */
+  get(obj: any, path: string, defaultValue?: any): any;
+
+  /**
+   * Safely set nested property on object
+   * @param obj - Target object
+   * @param path - Dot-notation path
+   * @param value - Value to set
+   */
+  set(obj: any, path: string, value: any): any;
+
+  // Note: toString() is not a helper function
+  // Use native String(value) or sdk.toString resolver instead
+
+  /**
+   * Safely parse integer with fallback
+   * @param value - Value to parse
+   * @param defaultValue - Default if parsing fails (default: 0)
+   */
+  parseIntSafe(value: any, defaultValue?: number): number;
+
+  /**
+   * Safely parse float with fallback
+   * @param value - Value to parse
+   * @param defaultValue - Default if parsing fails (default: 0)
+   */
+  parseFloatSafe(value: any, defaultValue?: number): number;
+
+  // ===== Date Operations =====
+
+  /**
+   * Format date to ISO8601 string
+   * @param date - Date to format (string or Date object)
+   * @returns ISO8601 formatted date string
+   */
+  formatDate(date: string | Date): string;
+
+  // Note: formatDateShort() is not a helper function
+  // It's available as sdk.formatDateShort resolver instead
+
+  /**
+   * Parse date string to Date object
+   * @param dateStr - Date string to parse
+   */
+  parseDate(dateStr: string): Date | null;
+
+  /**
+   * Add days to a date
+   * @param date - Starting date
+   * @param days - Number of days to add
+   */
+  addDays(date: Date, days: number): Date;
+
+  /**
+   * Subtract days from a date
+   * @param date - Starting date
+   * @param days - Number of days to subtract
+   */
+  subtractDays(date: Date, days: number): Date;
+
+  /**
+   * Calculate difference between dates in days
+   * @param date1 - First date
+   * @param date2 - Second date
+   */
+  dateDiff(date1: Date, date2: Date): number;
+
+  // ===== String Operations =====
+
+  /**
+   * Normalize whitespace (collapse multiple spaces to one)
+   * @param str - String to normalize
+   */
+  normalizeWhitespace(str: string): string;
+
+  /**
+   * Convert string to camelCase
+   * @param str - String to convert
+   */
+  toCamelCase(str: string): string;
+
+  /**
+   * Convert string to snake_case
+   * @param str - String to convert
+   */
+  toSnakeCase(str: string): string;
+
+  /**
+   * Truncate string to max length
+   * @param str - String to truncate
+   * @param maxLength - Maximum length (includes '...' suffix)
+   * @returns Truncated string with '...' appended if needed
+   */
+  truncate(str: string, maxLength: number): string;
+
+  /**
+   * Create slug from string (lowercase, hyphenated)
+   * @param str - String to slugify
+   */
+  slugify(str: string): string;
+
+  /**
+   * Simple string template replacement
+   * @param template - Template string with {{placeholders}}
+   * @param values - Object with replacement values
+   */
+  template(template: string, values: Record<string, any>): string;
+
+  /**
+   * Hash string using simple algorithm
+   * @param str - String to hash
+   */
+  hashString(str: string): string;
+
+  // ===== Array Operations =====
+
+  /**
+   * Ensure value is an array (wraps non-arrays)
+   * @param value - Value to convert to array
+   */
+  ensureArray(value: any): any[];
+
+  /**
+   * Return first non-null/non-undefined value from array
+   * @param values - Array of values to check
+   */
+  coalesce(values: any[]): any;
+
+  /**
+   * Group array items by key
+   * @param array - Array to group
+   * @param key - Property to group by
+   */
+  groupBy<T>(array: T[], key: string | ((item: T) => string)): Record<string, T[]>;
+
+  /**
+   * Convert array to object keyed by property
+   * @param array - Array to convert
+   * @param key - Property to use as key
+   */
+  keyBy<T>(array: T[], key: string | ((item: T) => string)): Record<string, T>;
+
+  /**
+   * Split array into chunks
+   * @param array - Array to chunk
+   * @param size - Chunk size
+   */
+  chunk<T>(array: T[], size: number): T[][];
+
+  /**
+   * Flatten nested arrays
+   * @param array - Array to flatten
+   * @param depth - Depth to flatten (default: 1)
+   */
+  flatten<T>(array: any[], depth?: number): T[];
+
+  /**
+   * Get unique values from array
+   * @param array - Array to deduplicate
+   */
+  unique<T>(array: T[]): T[];
+
+  /**
+   * Sort array by property
+   * @param array - Array to sort
+   * @param key - Property to sort by
+   * @param order - Sort order ('asc' or 'desc')
+   */
+  sortBy<T>(array: T[], key: string | ((item: T) => any), order?: 'asc' | 'desc'): T[];
+
+  /**
+   * Remove null/undefined values from array
+   * @param array - Array to compact
+   */
+  compact<T>(array: (T | null | undefined)[]): T[];
+
+  /**
+   * Sum numeric array values
+   * @param array - Array of numbers
+   */
+  sum(array: number[]): number;
+
+  /**
+   * Calculate average of numeric array
+   * @param array - Array of numbers
+   */
+  avg(array: number[]): number;
+
+  /**
+   * Find minimum value in array
+   * @param array - Array of numbers
+   */
+  min(array: number[]): number;
+
+  /**
+   * Find maximum value in array
+   * @param array - Array of numbers
+   */
+  max(array: number[]): number;
+
+  // ===== Object Operations =====
+
+  /**
+   * Deep clone an object
+   * @param obj - Object to clone
+   */
+  deepClone<T>(obj: T): T;
+
+  /**
+   * Deep merge objects
+   * @param target - Target object
+   * @param sources - Source objects to merge
+   */
+  deepMerge(target: any, ...sources: any[]): any;
+
+  /**
+   * Merge multiple objects
+   * @param objects - Objects to merge
+   */
+  merge(...objects: any[]): any;
+
+  // ===== Validation =====
+
+  /**
+   * Validate email address format
+   * @param email - Email to validate
+   */
+  isValidEmail(email: string): boolean;
+
+  /**
+   * Require field to be non-null/non-undefined
+   * @param value - Value to check
+   * @param fieldName - Field name for error message
+   * @throws Error if value is null/undefined
+   */
+  requireField(value: any, fieldName: string): any;
+
+  // ===== Number Operations =====
+
+  /**
+   * Clamp number between min and max
+   * @param value - Value to clamp
+   * @param min - Minimum value
+   * @param max - Maximum value
+   */
+  clamp(value: number, min: number, max: number): number;
+
+  /**
+   * Format number as currency with fixed decimal places
+   * @param amount - Number to format
+   * @param scale - Number of decimal places (default: 2)
+   * @returns Formatted currency string
+   */
+  formatCurrency(amount: number, scale?: number): string;
+
+  // ===== Type Checks =====
+
+  /**
+   * Check if value is a string
+   */
+  isString(value: any): value is string;
+
+  /**
+   * Check if value is a number
+   */
+  isNumber(value: any): value is number;
+
+  /**
+   * Check if value is an array
+   */
+  isArray(value: any): value is any[];
+
+  /**
+   * Check if value is an object
+   */
+  isObject(value: any): value is object;
+
+  /**
+   * Check if value is a Date
+   */
+  isDate(value: any): value is Date;
+
+  // ===== JSON Operations =====
+
+  /**
+   * Safely parse JSON with fallback
+   * @param str - JSON string to parse
+   * @param defaultValue - Default if parsing fails
+   */
+  safeJsonParse(str: string, defaultValue?: any): any;
+
+  // ===== Performance =====
+
+  /**
+   * Memoize function results (caches based on JSON.stringify of arguments)
+   * @param fn - Function to memoize
+   * @returns Memoized version of function
+   */
+  memoize<T extends (...args: any[]) => any>(fn: T): T;
+
+  /**
+   * Process array in batches with async operations
+   * @param items - Array items to process
+   * @param processor - Async function to process each item (receives item and index)
+   * @param batchSize - Number of items per batch (default: 50)
+   * @returns Array of results in original order
+   */
+  batchProcess<T, R>(
+    items: T[],
+    processor: (item: T, index: number) => Promise<R>,
+    batchSize?: number
+  ): Promise<R[]>;
+
+  /**
+   * Retry async function with exponential backoff
+   * @param fn - Async function to retry
+   * @param maxRetries - Maximum retry attempts (default: 3)
+   * @param delayMs - Initial delay in milliseconds (default: 100)
+   * @returns Result of successful function call
+   * @throws Last error if all retries fail
+   */
+  retry<T>(
+    fn: () => Promise<T>,
+    maxRetries?: number,
+    delayMs?: number
+  ): Promise<T>;
+
+  /**
+   * Debounce function calls
+   * @param fn - Function to debounce
+   * @param delayMs - Delay in milliseconds
+   */
+  debounce<T extends (...args: any[]) => any>(fn: T, delayMs: number): T;
+
+  /**
+   * Throttle function calls
+   * @param fn - Function to throttle
+   * @param limitMs - Throttle limit in milliseconds
+   */
+  throttle<T extends (...args: any[]) => any>(fn: T, limitMs: number): T;
+
+  // ===== Utility Functions =====
+
+  /**
+   * Extract custom attribute from attributes array
+   * @param attributes - Array of {name, value} objects
+   * @param attrName - Attribute name to extract
+   * @param defaultValue - Default if not found
+   */
+  extractCustomAttribute(
+    attributes: Array<{ name: string; value: any }>,
+    attrName: string,
+    defaultValue?: any
+  ): any;
+
+  /**
+   * Map value using lookup table
+   * @param value - Value to map
+   * @param mapping - Lookup table
+   * @param defaultValue - Default if not in mapping
+   */
+  mapValue(value: any, mapping: Record<string, any>, defaultValue?: any): any;
+
+  /**
+   * Combine first and last name
+   * @param firstName - First name
+   * @param lastName - Last name
+   */
+  fullName(firstName: string, lastName: string): string;
+
+  /**
+   * Generate UUID v4
+   */
+  uuid(): string;
+
+  // ===== Context Objects =====
+
+  /**
+   * Logger instance for debugging
+   */
+  log: {
+    debug(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+  };
+
+  /**
+   * FluentClient instance for GraphQL queries (optional)
+   */
+  fluentClient?: {
+    graphql(params: { query: string; variables?: any }): Promise<any>;
+  };
+
+  /**
+   * User-provided shared configuration object
+   * Prefer using the config parameter for custom settings
+   */
+  context?: any;
+}
+```
+
+## Typed Resolver Examples
+
+### Basic Typed Resolver
+
+```typescript
+import type { FieldResolverFunction } from '@fluentcommerce/fc-connect-sdk';
+
+const formatSKU: FieldResolverFunction = (value, sourceData, config, helpers) => {
+  const prefix = config?.prefix || 'SKU';
+  return `${prefix}-${String(value).toUpperCase()}`;
+};
+```
+
+### Typed Resolver with Config Interface
+
+```typescript
+interface SKUConfig {
+  prefix?: string;
+  separator?: string;
+  includeTimestamp?: boolean;
+}
+
+const formatSKU = (
+  value: any,
+  sourceData: any,
+  config: SKUConfig,
+  helpers: ResolverHelpers
+): string => {
+  const prefix = config.prefix || 'SKU';
+  const separator = config.separator || '-';
+
+  let result = `${prefix}${separator}${String(value).toUpperCase()}`;
+
+  if (config.includeTimestamp) {
+    const timestamp = helpers.formatDate(new Date(), 'YYYYMMDD');
+    result += `${separator}${timestamp}`;
+  }
+
+  return result;
+};
+```
+
+### Async Typed Resolver
+
+```typescript
+interface EnrichmentConfig {
+  enableEnrichment?: boolean;
+  timeout?: number;
+}
+
+const enrichProduct = async (
+  sku: string,
+  sourceData: any,
+  config: EnrichmentConfig,
+  helpers: ResolverHelpers
+): Promise<any> => {
+  if (!helpers.fluentClient || !config.enableEnrichment) {
+    return { sku };
+  }
+
+  try {
+    const result = await helpers.fluentClient.graphql({
+      query: `query { product(ref: "${sku}") { id name } }`
+    });
+
+    return result.data.product || { sku, found: false };
+  } catch (error) {
+    helpers.log.error('Enrichment failed', error);
+    return { sku, error: (error as Error).message };
+  }
+};
+```
+
+## Testing Utilities
+
+### Mock ResolverHelpers
+
+```typescript
+import type { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
+
+function createMockHelpers(): ResolverHelpers {
+  return {
+    // Core utilities
+    get: (obj: any, path: string, defaultValue?: any) => {
+      // Simple implementation for testing
+      const keys = path.split('.');
+      let result = obj;
+      for (const key of keys) {
+        if (result === null || result === undefined) {
+          return defaultValue;
+        }
+        result = result[key];
+      }
+      return result ?? defaultValue;
+    },
+    set: (obj: any, path: string, value: any) => {
+      const keys = path.split('.');
+      let current = obj;
+      for (let i = 0; i < keys.length - 1; i++) {
+        current[keys[i]] = current[keys[i]] || {};
+        current = current[keys[i]];
+      }
+      current[keys[keys.length - 1]] = value;
+      return obj;
+    },
+    toString: (value: any) => String(value ?? ''),
+    parseIntSafe: (value: any, defaultValue: number = 0) => {
+      const parsed = parseInt(value, 10);
+      return isNaN(parsed) ? defaultValue : parsed;
+    },
+    parseFloatSafe: (value: any, defaultValue: number = 0) => {
+      const parsed = parseFloat(value);
+      return isNaN(parsed) ? defaultValue : parsed;
+    },
+    // ... implement other helpers as needed for testing
+    log: {
+      debug: jest.fn(),
+      info: jest.fn(),
+      warn: jest.fn(),
+      error: jest.fn()
+    }
+  } as any as ResolverHelpers;
+}
+```
+
+### Unit Test Template
+
+```typescript
+import type { FieldResolverFunction } from '@fluentcommerce/fc-connect-sdk';
+
+describe('Custom Resolver', () => {
+  let helpers: ResolverHelpers;
+
+  beforeEach(() => {
+    helpers = createMockHelpers();
+  });
+
+  it('should transform value correctly', () => {
+    const resolver: FieldResolverFunction = (value, sourceData, config, helpers) => {
+      return String(value).toUpperCase();
+    };
+
+    const result = resolver('test', {}, {}, helpers);
+
+    expect(result).toBe('TEST');
+  });
+
+  it('should use config parameter', () => {
+    const resolver: FieldResolverFunction = (value, sourceData, config, helpers) => {
+      const prefix = config.prefix || 'DEFAULT';
+      return `${prefix}-${value}`;
+    };
+
+    const result = resolver('test', {}, { prefix: 'CUSTOM' }, helpers);
+
+    expect(result).toBe('CUSTOM-test');
+  });
+
+  it('should access sourceData', () => {
+    const resolver: FieldResolverFunction = (value, sourceData, config, helpers) => {
+      const quantity = helpers.get(sourceData, 'quantity', 1);
+      return value * quantity;
+    };
+
+    const result = resolver(10, { quantity: 5 }, {}, helpers);
+
+    expect(result).toBe(50);
+  });
+});
+```
+
+### Integration Test Template
+
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+describe('Resolver Integration', () => {
+  it('should work with UniversalMapper', async () => {
+    const customResolvers = {
+      'custom.transform': (value, sourceData, config, helpers) => {
+        return `${config.prefix}-${value}`;
+      }
+    };
+
+    const mapper = new UniversalMapper(
+      {
+        fields: {
+          result: { source: 'input', resolver: 'custom.transform' }
+        }
+      },
+      {
+        customResolvers,
+        context: { prefix: 'TEST' }
+      }
+    );
+
+    const result = await mapper.map({ input: 'value' });
+
+    expect(result.success).toBe(true);
+    expect(result.data.result).toBe('TEST-value');
+  });
+});
+```
+
+## Production Best Practices
+
+### 1. Always Type Your Resolvers
+
+```typescript
+// ✅ GOOD: Fully typed
+const resolver: FieldResolverFunction = (value, sourceData, config, helpers) => {
+      return String(value).toUpperCase();
+};
+
+// ❌ BAD: No types
+const resolver = (value, sourceData, config, helpers) => {
+      return String(value).toUpperCase();
+};
+```
+
+### 2. Document Config Requirements
+
+```typescript
+/**
+ * Format SKU with configurable prefix
+ *
+ * @param value - SKU to format
+ * @param sourceData - Source data context
+ * @param config - Configuration
+ * @param config.prefix - SKU prefix (default: 'SKU')
+ * @param config.separator - Separator (default: '-')
+ * @param helpers - SDK helpers
+ */
+const formatSKU: FieldResolverFunction = (value, sourceData, config, helpers) => {
+  // Implementation
+};
+```
+
+### 3. Handle Edge Cases
+
+```typescript
+const resolver: FieldResolverFunction = (value, sourceData, config, helpers) => {
+  // Handle null/undefined
+  if (value === null || value === undefined) {
+    return config.defaultValue || null;
+  }
+
+  // Handle empty string
+  if (String(value).trim() === '') {
+    return config.defaultValue || null;
+  }
+
+  // Proceed with transformation
+      return String(value).toUpperCase();
+};
+```
+
+### 4. Use Type Guards
+
+```typescript
+const resolver: FieldResolverFunction = (value, sourceData, config, helpers) => {
+  if (!helpers.isString(value) && !helpers.isNumber(value)) {
+    helpers.log.warn(`Unexpected value type: ${typeof value}`);
+    return null;
+  }
+
+      return String(value).toUpperCase();
+};
+```
+
+## Key Takeaways
+
+- 🎯 **Use TypeScript types** - `FieldResolverFunction` for type safety
+- 🎯 **Know ResolverHelpers** - 48+ utility functions available
+- 🎯 **Test thoroughly** - Unit and integration tests
+- 🎯 **Document config** - Clear JSDoc comments
+- 🎯 **Handle edge cases** - Null, undefined, empty values
+
+## Quick Reference
+
+```typescript
+// Standard signature
+(value: any, sourceData: any, config: any, helpers: ResolverHelpers) => any | Promise<any>
+
+// Typed version
+const resolver: FieldResolverFunction = (value, sourceData, config, helpers) => {
+  // Implementation
+};
+
+// With config interface
+interface MyConfig {
+  option?: string;
+}
+
+const resolver = (
+  value: any,
+  sourceData: any,
+  config: MyConfig,
+  helpers: ResolverHelpers
+): any => {
+  // Implementation
+};
+```
+
+## Conclusion
+
+You now have complete reference documentation for the 4-parameter resolver signature. Use this module as a reference when building production resolvers.
+
+---
+
+**Next:** Return to the [Main Guide](../resolver-signature-readme.md) or explore the [Examples Directory](../examples/) for practical implementations.