@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-readme.md

@@ -1,274 +1,274 @@
-# Resolver Documentation
-
-**Complete guide to building and using custom resolvers with the FC Connect SDK**
-
----
-
-## 📖 Overview
-
-This directory contains comprehensive documentation for working with resolvers in the FC Connect SDK. Resolvers are functions that transform data during field mapping.
-
-**There are two aspects to resolvers**:
-
-1. **Using Resolvers** - Understanding the 4-parameter signature pattern
-2. **Building Resolvers** - Creating custom resolver functions with the ResolverBuilder API
-
----
-
-## 🎯 Which Guide Do I Need?
-
-### New to Resolvers? Start Here:
-
-**[→ Resolver Signature Guide](../../../04-REFERENCE/resolver-signature/resolver-signature-readme.md)**
-
-Learn the standard 4-parameter resolver signature used across ALL mappers:
-
-- ✅ What each parameter does (value, sourceData, config, helpers)
-- ✅ How to write basic transformations
-- ✅ Context-aware pattern with sourceData
-- ✅ Using the 48+ ResolverHelper functions
-
-**Time**: 1-2 hours | **Level**: Beginner to Intermediate
-
----
-
-### Need to Build Complex Custom Resolvers?
-
-**➡️ [Resolver Pattern Guide](./mapping-resolvers-resolver-guide.md)**
-
-Deep dive into building production-ready resolvers with the ResolverBuilder API:
-
-- ✅ ResolverBuilder API for clean, maintainable code
-- ✅ 54 helper functions reference
-- ✅ Real-world order management examples
-- ✅ Async operations (API calls, database lookups)
-- ✅ Advanced patterns and troubleshooting
-
-**Time**: 2-4 hours | **Level**: Intermediate to Advanced
-
----
-
-## 📚 Documentation Structure
-
-### 1. Understanding Resolvers (Start Here)
-
-**[→ Resolver Signature Guide](../../../04-REFERENCE/resolver-signature/resolver-signature-readme.md)** - _Progressive learning path_
-
-Learn the foundation - the standard 4-parameter signature:
-
-```typescript
-(value: any, sourceData: any, config: any, helpers: ResolverHelpers) => any;
-```
-
-**7 modules** covering:
-
-1. Foundations - Why 4 parameters
-2. Parameter Reference - What each does
-3. Basic Examples - Simple transformations
-4. Advanced Patterns - Context-aware logic
-5. SDK Resolvers - Built-in resolvers
-6. Migration Guide - From 3-arg to 4-arg
-7. API Reference - Complete TypeScript types
-
----
-
-### 2. Building Custom Resolvers (Advanced)
-
-**[RESOLVER_GUIDE.md](./mapping-resolvers-resolver-guide.md)** - _Main guide for building resolvers_
-
-Complete guide to the ResolverBuilder API and advanced patterns.
-
-**Key topics**:
-
-- Quick Start (5 minutes)
-- Core concepts explained
-- Real-world examples (orders, inventory)
-- Progressive learning path
-
-**Time**: 30 minutes to 2 hours
-
----
-
-### 3. Reference Documentation
-
-| Document                                                                   | Purpose                      | Use When                      |
-| -------------------------------------------------------------------------- | ---------------------------- | ----------------------------- |
-| **[RESOLVER_API_REFERENCE.md](./mapping-resolvers-resolver-api-reference.md)**               | ResolverBuilder API methods  | Building custom resolvers     |
-| **[RESOLVER_HELPERS_REFERENCE.md](./mapping-resolvers-resolver-helpers-reference.md)**       | All 54 helper functions      | Looking up helper functions   |
-| **[RESOLVER_PARAMETERS_REFERENCE.md](./mapping-resolvers-resolver-parameters-reference.md)** | Deep dive into 4 parameters  | Understanding parameter usage |
-| **[RESOLVER_COOKBOOK.md](./mapping-resolvers-resolver-cookbook.md)**                         | Practical recipes & patterns | Copy-paste solutions          |
-| **[RESOLVER_TROUBLESHOOTING.md](./mapping-resolvers-resolver-troubleshooting.md)**           | Common issues & solutions    | Debugging resolver problems   |
-| **[Implementation Summary](./mapping-resolvers-resolver-guide.md#core-concepts)**               | Implementation overview      | Architecture understanding    |
-
----
-
-## 🚀 Quick Start Paths
-
-### Path 1: "I Just Need Basic Transformations"
-
-**Duration**: 1 hour
-
-1. [Resolver Signature - Quick Start](../../../04-REFERENCE/resolver-signature/modules/resolver-signature-02-parameter-reference.md)
-2. [Resolver Signature - Basic Examples](../../../04-REFERENCE/resolver-signature/modules/resolver-signature-03-basic-examples.md)
-3. [Resolver Helpers Reference](./mapping-resolvers-resolver-helpers-reference.md) (for lookups)
-
----
-
-### Path 2: "I Need Production-Ready Resolvers"
-
-**Duration**: 3-4 hours
-
-1. [Resolver Signature Guide](../../../04-REFERENCE/resolver-signature/resolver-signature-readme.md) (complete - 7 modules)
-2. [Resolver Pattern Guide](./mapping-resolvers-resolver-guide.md) (ResolverBuilder API)
-3. [Resolver Cookbook](./mapping-resolvers-resolver-cookbook.md) (practical patterns)
-4. [Resolver Troubleshooting](./mapping-resolvers-resolver-troubleshooting.md) (debugging)
-
----
-
-### Path 3: "I'm Building Complex Integrations"
-
-**Duration**: Full day
-
-1. Complete Path 2 above
-2. [Resolver Parameters Reference](./mapping-resolvers-resolver-parameters-reference.md) (deep dive)
-3. [Resolver API Reference](./mapping-resolvers-resolver-api-reference.md) (complete API)
-4. [Implementation Summary](./mapping-resolvers-resolver-guide.md#core-concepts) (architecture)
-
----
-
-## 🎓 Learning Objectives
-
-### After Resolver Signature Guide:
-
-- ✅ Understand the 4-parameter signature
-- ✅ Write basic resolvers for UniversalMapper
-- ✅ Use SDK helpers (parseFloat, formatDate, etc.)
-- ✅ Create context-aware transformations
-
-### After Resolver Pattern Guide:
-
-- ✅ Use ResolverBuilder API
-- ✅ Build async resolvers with API calls
-- ✅ Implement complex business logic
-- ✅ Apply production best practices
-- ✅ Debug and troubleshoot resolver issues
-
----
-
-## 🔗 Related Documentation
-
-### Core Mapping Guides
-
-- **[Universal Mapping](../mapping-readme.md)** - Field mapping with resolvers
-- **[GraphQL Mutation Mapping](../graphql-mutation-mapping/)** - XML/JSON → GraphQL with resolvers
-
-### Integration Guides
-
-- **[Ingestion](../../ingestion/)** - Using resolvers in data ingestion
-- **[Extraction](../../extraction/)** - Using resolvers in data extraction
-- **[Connector Scenarios](../../../03-PATTERN-GUIDES/connector-scenarios/)** - Real-world resolver examples
-
----
-
-## 📝 Quick Examples
-
-### Basic Resolver (4-parameter signature)
-
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const customResolvers = {
-  'custom.formatSKU': (value, sourceData, config, helpers) => {
-    const prefix = config.skuPrefix || 'SKU';
-    return `${prefix}-${helpers.toString(value).toUpperCase()}`;
-  },
-};
-
-const mapper = new UniversalMapper(mappingConfig, {
-  customResolvers,
-  context: { skuPrefix: 'PROD' },
-});
-```
-
-### Using ResolverBuilder API
-
-```typescript
-import { ResolverBuilder } from '@fluentcommerce/fc-connect-sdk';
-
-const resolver = new ResolverBuilder()
-  .name('custom.formatSKU')
-  .description('Format SKU with prefix')
-  .transform((value, data, config, helpers) => {
-    const prefix = config.skuPrefix || 'SKU';
-    return `${prefix}-${helpers.toString(value).toUpperCase()}`;
-  })
-  .validate(result => {
-    if (!result || result.length === 0) {
-      throw new Error('SKU cannot be empty');
-    }
-    return result;
-  })
-  .build();
-```
-
----
-
-## 🆘 Need Help?
-
-### Common Issues
-
-- **"Which guide do I need?"** → Start with [Resolver Signature Guide](../../../04-REFERENCE/resolver-signature/resolver-signature-readme.md)
-- **"How do I debug resolvers?"** → See [RESOLVER_TROUBLESHOOTING.md](./mapping-resolvers-resolver-troubleshooting.md)
-- **"What helpers are available?"** → See [RESOLVER_HELPERS_REFERENCE.md](./mapping-resolvers-resolver-helpers-reference.md)
-- **"How do I write async resolvers?"** → See [RESOLVER_GUIDE.md - Async Operations](./mapping-resolvers-resolver-guide.md#async-operations-api-calls)
-
-### Quick References
-
-- [Resolver Signature Quick Reference](../../advanced-services/advanced-services-quick-reference.md)
-- [Resolver Cookbook](./mapping-resolvers-resolver-cookbook.md)
-- [Resolver Parameters Reference](./mapping-resolvers-resolver-parameters-reference.md)
-
----
-
-## 📊 Resolver Documentation Map
-
-```
-resolvers/ (This directory)
-├── readme.md (You are here - Navigation guide)
-│
-├── Core Documentation
-│   ├── RESOLVER_GUIDE.md (Main ResolverBuilder guide)
-│   ├── RESOLVER_API_REFERENCE.md (Complete API)
-│   └── mapping-resolvers-resolver-guide.md (Architecture)
-│
-├── Reference Materials
-│   ├── RESOLVER_HELPERS_REFERENCE.md (54 helper functions)
-│   ├── RESOLVER_PARAMETERS_REFERENCE.md (4 parameters deep dive)
-│   └── RESOLVER_COOKBOOK.md (Practical recipes)
-│
-├── Troubleshooting
-│   └── RESOLVER_TROUBLESHOOTING.md (Common issues)
-│
-└── Related Guide
-    └── ../resolver-signature/ (4-parameter signature learning path)
-```
-
----
-
-## 🎯 Key Takeaways
-
-1. **Two Complementary Guides**:
-   - `resolver-signature/` - Understanding the signature pattern
-   - `resolvers/` - Building complex resolvers with ResolverBuilder
-
-2. **Start with Signature**: Learn the 4-parameter pattern first
-
-3. **Progress to Builder**: Use ResolverBuilder for production code
-
-4. **Use References**: Keep helper and API references handy
-
-5. **Practice**: Use Cookbook recipes and real examples
-
----
-
-_For the complete SDK documentation, see the [main guides index](../../../00-START-HERE/readme.md)_
+# Resolver Documentation
+
+**Complete guide to building and using custom resolvers with the FC Connect SDK**
+
+---
+
+## 📖 Overview
+
+This directory contains comprehensive documentation for working with resolvers in the FC Connect SDK. Resolvers are functions that transform data during field mapping.
+
+**There are two aspects to resolvers**:
+
+1. **Using Resolvers** - Understanding the 4-parameter signature pattern
+2. **Building Resolvers** - Creating custom resolver functions with the ResolverBuilder API
+
+---
+
+## 🎯 Which Guide Do I Need?
+
+### New to Resolvers? Start Here:
+
+**[→ Resolver Signature Guide](../../../04-REFERENCE/resolver-signature/resolver-signature-readme.md)**
+
+Learn the standard 4-parameter resolver signature used across ALL mappers:
+
+- ✅ What each parameter does (value, sourceData, config, helpers)
+- ✅ How to write basic transformations
+- ✅ Context-aware pattern with sourceData
+- ✅ Using the 48+ ResolverHelper functions
+
+**Time**: 1-2 hours | **Level**: Beginner to Intermediate
+
+---
+
+### Need to Build Complex Custom Resolvers?
+
+**➡️ [Resolver Pattern Guide](./mapping-resolvers-resolver-guide.md)**
+
+Deep dive into building production-ready resolvers with the ResolverBuilder API:
+
+- ✅ ResolverBuilder API for clean, maintainable code
+- ✅ 54 helper functions reference
+- ✅ Real-world order management examples
+- ✅ Async operations (API calls, database lookups)
+- ✅ Advanced patterns and troubleshooting
+
+**Time**: 2-4 hours | **Level**: Intermediate to Advanced
+
+---
+
+## 📚 Documentation Structure
+
+### 1. Understanding Resolvers (Start Here)
+
+**[→ Resolver Signature Guide](../../../04-REFERENCE/resolver-signature/resolver-signature-readme.md)** - _Progressive learning path_
+
+Learn the foundation - the standard 4-parameter signature:
+
+```typescript
+(value: any, sourceData: any, config: any, helpers: ResolverHelpers) => any;
+```
+
+**7 modules** covering:
+
+1. Foundations - Why 4 parameters
+2. Parameter Reference - What each does
+3. Basic Examples - Simple transformations
+4. Advanced Patterns - Context-aware logic
+5. SDK Resolvers - Built-in resolvers
+6. Migration Guide - From 3-arg to 4-arg
+7. API Reference - Complete TypeScript types
+
+---
+
+### 2. Building Custom Resolvers (Advanced)
+
+**[RESOLVER_GUIDE.md](./mapping-resolvers-resolver-guide.md)** - _Main guide for building resolvers_
+
+Complete guide to the ResolverBuilder API and advanced patterns.
+
+**Key topics**:
+
+- Quick Start (5 minutes)
+- Core concepts explained
+- Real-world examples (orders, inventory)
+- Progressive learning path
+
+**Time**: 30 minutes to 2 hours
+
+---
+
+### 3. Reference Documentation
+
+| Document                                                                   | Purpose                      | Use When                      |
+| -------------------------------------------------------------------------- | ---------------------------- | ----------------------------- |
+| **[RESOLVER_API_REFERENCE.md](./mapping-resolvers-resolver-api-reference.md)**               | ResolverBuilder API methods  | Building custom resolvers     |
+| **[RESOLVER_HELPERS_REFERENCE.md](./mapping-resolvers-resolver-helpers-reference.md)**       | All 54 helper functions      | Looking up helper functions   |
+| **[RESOLVER_PARAMETERS_REFERENCE.md](./mapping-resolvers-resolver-parameters-reference.md)** | Deep dive into 4 parameters  | Understanding parameter usage |
+| **[RESOLVER_COOKBOOK.md](./mapping-resolvers-resolver-cookbook.md)**                         | Practical recipes & patterns | Copy-paste solutions          |
+| **[RESOLVER_TROUBLESHOOTING.md](./mapping-resolvers-resolver-troubleshooting.md)**           | Common issues & solutions    | Debugging resolver problems   |
+| **[Implementation Summary](./mapping-resolvers-resolver-guide.md#core-concepts)**               | Implementation overview      | Architecture understanding    |
+
+---
+
+## 🚀 Quick Start Paths
+
+### Path 1: "I Just Need Basic Transformations"
+
+**Duration**: 1 hour
+
+1. [Resolver Signature - Quick Start](../../../04-REFERENCE/resolver-signature/modules/resolver-signature-02-parameter-reference.md)
+2. [Resolver Signature - Basic Examples](../../../04-REFERENCE/resolver-signature/modules/resolver-signature-03-basic-examples.md)
+3. [Resolver Helpers Reference](./mapping-resolvers-resolver-helpers-reference.md) (for lookups)
+
+---
+
+### Path 2: "I Need Production-Ready Resolvers"
+
+**Duration**: 3-4 hours
+
+1. [Resolver Signature Guide](../../../04-REFERENCE/resolver-signature/resolver-signature-readme.md) (complete - 7 modules)
+2. [Resolver Pattern Guide](./mapping-resolvers-resolver-guide.md) (ResolverBuilder API)
+3. [Resolver Cookbook](./mapping-resolvers-resolver-cookbook.md) (practical patterns)
+4. [Resolver Troubleshooting](./mapping-resolvers-resolver-troubleshooting.md) (debugging)
+
+---
+
+### Path 3: "I'm Building Complex Integrations"
+
+**Duration**: Full day
+
+1. Complete Path 2 above
+2. [Resolver Parameters Reference](./mapping-resolvers-resolver-parameters-reference.md) (deep dive)
+3. [Resolver API Reference](./mapping-resolvers-resolver-api-reference.md) (complete API)
+4. [Implementation Summary](./mapping-resolvers-resolver-guide.md#core-concepts) (architecture)
+
+---
+
+## 🎓 Learning Objectives
+
+### After Resolver Signature Guide:
+
+- ✅ Understand the 4-parameter signature
+- ✅ Write basic resolvers for UniversalMapper
+- ✅ Use SDK helpers (parseFloat, formatDate, etc.)
+- ✅ Create context-aware transformations
+
+### After Resolver Pattern Guide:
+
+- ✅ Use ResolverBuilder API
+- ✅ Build async resolvers with API calls
+- ✅ Implement complex business logic
+- ✅ Apply production best practices
+- ✅ Debug and troubleshoot resolver issues
+
+---
+
+## 🔗 Related Documentation
+
+### Core Mapping Guides
+
+- **[Universal Mapping](../mapping-readme.md)** - Field mapping with resolvers
+- **[GraphQL Mutation Mapping](../graphql-mutation-mapping/)** - XML/JSON → GraphQL with resolvers
+
+### Integration Guides
+
+- **[Ingestion](../../ingestion/)** - Using resolvers in data ingestion
+- **[Extraction](../../extraction/)** - Using resolvers in data extraction
+- **[Connector Scenarios](../../../03-PATTERN-GUIDES/connector-scenarios/)** - Real-world resolver examples
+
+---
+
+## 📝 Quick Examples
+
+### Basic Resolver (4-parameter signature)
+
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const customResolvers = {
+  'custom.formatSKU': (value, sourceData, config, helpers) => {
+    const prefix = config.skuPrefix || 'SKU';
+    return `${prefix}-${helpers.toString(value).toUpperCase()}`;
+  },
+};
+
+const mapper = new UniversalMapper(mappingConfig, {
+  customResolvers,
+  context: { skuPrefix: 'PROD' },
+});
+```
+
+### Using ResolverBuilder API
+
+```typescript
+import { ResolverBuilder } from '@fluentcommerce/fc-connect-sdk';
+
+const resolver = new ResolverBuilder()
+  .name('custom.formatSKU')
+  .description('Format SKU with prefix')
+  .transform((value, data, config, helpers) => {
+    const prefix = config.skuPrefix || 'SKU';
+    return `${prefix}-${helpers.toString(value).toUpperCase()}`;
+  })
+  .validate(result => {
+    if (!result || result.length === 0) {
+      throw new Error('SKU cannot be empty');
+    }
+    return result;
+  })
+  .build();
+```
+
+---
+
+## 🆘 Need Help?
+
+### Common Issues
+
+- **"Which guide do I need?"** → Start with [Resolver Signature Guide](../../../04-REFERENCE/resolver-signature/resolver-signature-readme.md)
+- **"How do I debug resolvers?"** → See [RESOLVER_TROUBLESHOOTING.md](./mapping-resolvers-resolver-troubleshooting.md)
+- **"What helpers are available?"** → See [RESOLVER_HELPERS_REFERENCE.md](./mapping-resolvers-resolver-helpers-reference.md)
+- **"How do I write async resolvers?"** → See [RESOLVER_GUIDE.md - Async Operations](./mapping-resolvers-resolver-guide.md#async-operations-api-calls)
+
+### Quick References
+
+- [Resolver Signature Quick Reference](../../advanced-services/advanced-services-quick-reference.md)
+- [Resolver Cookbook](./mapping-resolvers-resolver-cookbook.md)
+- [Resolver Parameters Reference](./mapping-resolvers-resolver-parameters-reference.md)
+
+---
+
+## 📊 Resolver Documentation Map
+
+```
+resolvers/ (This directory)
+├── readme.md (You are here - Navigation guide)
+│
+├── Core Documentation
+│   ├── RESOLVER_GUIDE.md (Main ResolverBuilder guide)
+│   ├── RESOLVER_API_REFERENCE.md (Complete API)
+│   └── mapping-resolvers-resolver-guide.md (Architecture)
+│
+├── Reference Materials
+│   ├── RESOLVER_HELPERS_REFERENCE.md (54 helper functions)
+│   ├── RESOLVER_PARAMETERS_REFERENCE.md (4 parameters deep dive)
+│   └── RESOLVER_COOKBOOK.md (Practical recipes)
+│
+├── Troubleshooting
+│   └── RESOLVER_TROUBLESHOOTING.md (Common issues)
+│
+└── Related Guide
+    └── ../resolver-signature/ (4-parameter signature learning path)
+```
+
+---
+
+## 🎯 Key Takeaways
+
+1. **Two Complementary Guides**:
+   - `resolver-signature/` - Understanding the signature pattern
+   - `resolvers/` - Building complex resolvers with ResolverBuilder
+
+2. **Start with Signature**: Learn the 4-parameter pattern first
+
+3. **Progress to Builder**: Use ResolverBuilder for production code
+
+4. **Use References**: Keep helper and API references handy
+
+5. **Practice**: Use Cookbook recipes and real examples
+
+---
+
+_For the complete SDK documentation, see the [main guides index](../../../00-START-HERE/readme.md)_