@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

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

@@ -1,178 +1,178 @@
-# Mapping Documentation
-
-## 📖 Essential Reading (Start Here!)
-
-Before diving into specific mappers, **everyone should read these guides first**:
-
-⭐ **[Understanding Mapping: JavaScript Object Paths](./mapping-javascript-objects.md)** (30 min read)
-- Core concept: Mapping paths work on JavaScript objects, NOT source file formats
-- Real-world examples: CSV, JSON, XML with complex structures
-- Debugging guide and common mistakes
-- **MUST READ for all newcomers**
-
-📊 **[Mapper Comparison Guide](./mapping-mapper-comparison-guide.md)** (20 min read)
-- Real-world scenario: 100 locations from CSV
-- 4 different approaches with complete code
-- Decision matrix: Which approach to use when?
-- Performance comparison
-
-📋 **[Mapping Format Decision Tree](./mapping-format-decision-tree.md)** (15 min read)
-- External JSON vs Inline TypeScript configurations
-- When to use each pattern
-- Migration guide
-
----
-
-## 🔍 Which Guide Do I Need?
-
-This directory contains **3 specialized mapping guides**. Choose based on your use case:
-
-### 1. Universal Mapping (`modules/`)
-**Use when**: Transforming data **WITHOUT** GraphQL mutations
-
-**Common Use Cases**:
-- CSV/JSON → Fluent Batch API (Inventory, Location, Product ingestion)
-- GraphQL → Parquet extraction
-- JSON → Event API
-- Any non-GraphQL data transformation
-
-**Features**:
-- Simple field mapping configuration
-- Built-in SDK resolvers (trim, parseInt, parseFloat, etc.)
-- Custom resolver support
-- Schema validation
-
-**Start Here**: [Module 1: Foundations](./modules/02-CORE-GUIDES-mapping-01-foundations.md)
-
----
-
-### 2. GraphQL Mutation Mapping (`graphql-mutation-mapping/`)
-**Use when**: Transforming data **INTO** GraphQL mutations
-
-**Common Use Cases**:
-- XML orders → `createOrder` mutation
-- JSON products → `updateProduct` mutation
-- SFCC XML → Fluent GraphQL mutations
-- Any source → GraphQL API
-
-**Features**:
-- Automatic GraphQL mutation generation
-- Alias batching for performance
-- Path syntax for nested data
-- XML attribute support (`@` prefix)
-
-**Start Here**: [GraphQL Mapping Quick Start](./graphql-mutation-mapping/modules/graphql-mutation-mapping-02-quick-start.md)
-
----
-
-### 3. Custom Resolvers (`resolvers/`)
-**Use when**: Building **custom transformation functions**
-
-**Common Use Cases**:
-- Complex business logic transformations
-- API lookups during mapping
-- Async data enrichment
-- Multi-field conditional transformations
-- Custom data validation
-
-**Features**:
-- Full TypeScript/JavaScript functions
-- Access to context and helpers
-- Async/await support
-- Error handling
-
-**Start Here**: [Resolver Guide](./resolvers/mapping-resolvers-resolver-guide.md)
-
----
-
-## 🚀 Quick Decision Tree
-
-```
-Do you need to call GraphQL mutations?
-├─ YES → Use GraphQL Mutation Mapping
-└─ NO → Do you need complex custom logic?
-    ├─ YES → Use Universal Mapping + Custom Resolvers
-    └─ NO → Use Universal Mapping with SDK Resolvers
-```
-
----
-
-## 📚 Quick Reference & Advanced Topics
-
-- **[Quick Start Guide](./modules/02-CORE-GUIDES-mapping-02-quick-start.md)** - Get started with mapping quickly
-- **[Error Handling Guide](./modules/02-core-guides-mapping-08-error-handling.md)** - Comprehensive error handling for UniversalMapper **NEW!**
-- **[GraphQL Alias Batching Guide](./mapping-graphql-alias-batching-guide.md)** - Performance optimization
-- **[Understanding Mapping: JavaScript Object Paths](./mapping-javascript-objects.md)** - Complete ETL flow guide with examples
-
----
-
-## 🎯 Learning Paths
-
-### For Newcomers (Total: ~2 hours)
-1. Read: [mapping-javascript-objects.md](./mapping-javascript-objects.md) (30 min)
-2. Read: [Mapper Comparison Guide](./mapping-mapper-comparison-guide.md) (20 min)
-3. Choose your path: Universal Mapping OR GraphQL Mutation Mapping
-4. Complete Quick Start guide (30-45 min)
-5. Build first integration (30-45 min)
-
-### For Universal Mapping Users
-1. [Module 1: Foundations](./modules/02-CORE-GUIDES-mapping-01-foundations.md)
-2. [Module 2: Quick Start](./modules/02-CORE-GUIDES-mapping-02-quick-start.md)
-3. [Module 4: Use Cases](./modules/02-CORE-GUIDES-mapping-04-use-cases.md)
-4. [Module 5: Advanced Patterns](./modules/02-CORE-GUIDES-mapping-05-advanced-patterns.md)
-5. [Module 8: Error Handling](./modules/02-core-guides-mapping-08-error-handling.md) - **NEW!**
-
-### For GraphQL Mutation Mapping Users
-1. [Module 1: Introduction](./graphql-mutation-mapping/modules/graphql-mutation-mapping-01-introduction.md)
-2. [Module 2: Quick Start](./graphql-mutation-mapping/modules/graphql-mutation-mapping-02-quick-start.md)
-3. [Module 4: Mapping Patterns](./graphql-mutation-mapping/modules/graphql-mutation-mapping-04-mapping-patterns.md)
-4. [Module 9: Advanced Patterns](./graphql-mutation-mapping/modules/graphql-mutation-mapping-09-advanced-patterns.md)
-
-### For Advanced Users
-1. [Custom Resolvers](./resolvers/mapping-resolvers-resolver-guide.md)
-2. [GraphQL Alias Batching](./mapping-graphql-alias-batching-guide.md)
-3. [Advanced Patterns](./modules/02-CORE-GUIDES-mapping-05-advanced-patterns.md)
-4. [Error Handling: UniversalMapper](./modules/02-core-guides-mapping-08-error-handling.md) - **NEW!**
-5. [Error Handling: GraphQL Mutation Mapper](./graphql-mutation-mapping/modules/graphql-mutation-mapping-11-error-handling.md)
-
----
-
-## 🔗 Related Documentation
-
-- **[Versori Platform Integration](../../04-REFERENCE/platforms/versori/)** - Webhook and Schedule workflows
-- **[Batch API Guide](../ingestion/)** - Fluent Batch API integration
-- **[Data Sources](../data-sources/)** - SFTP, S3, CSV, XML, JSON, Parquet
-- **[Parser Documentation](../parsers/)** - XML, JSON, CSV parsing
-
----
-
-## Quick Start
-
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const mapper = new UniversalMapper({
-  fields: {
-    sku: { source: 'productRef', required: true },
-    quantity: { source: 'qty', resolver: 'sdk.parseInt' },
-    warehouse: { source: 'locationRef' }
-  }
-});
-
-const result = await mapper.map(data);
-```
-
-## Navigation
-
-- [Universal Mapping Modules](./modules/) - Progressive learning path
-- [GraphQL Mutation Mapping](./graphql-mutation-mapping/) - Generate GraphQL mutations
-- [Custom Resolvers](./resolvers/) - Build custom transformation logic
-- [Examples](./examples/) - Code examples
-
-## Which Guide Do I Need?
-
-| Use Case | Guide | When to Use |
-|----------|-------|-------------|
-| **Transform data (no GraphQL)** | [Universal Mapping](./modules/) | CSV → Batch API, data transformation |
-| **Generate GraphQL mutations** | [GraphQL Mutation Mapping](./graphql-mutation-mapping/) | XML → createOrder, JSON → updateProduct |
-| **Custom transformation logic** | [Custom Resolvers](./resolvers/) | Complex business logic, API lookups |
+# Mapping Documentation
+
+## 📖 Essential Reading (Start Here!)
+
+Before diving into specific mappers, **everyone should read these guides first**:
+
+⭐ **[Understanding Mapping: JavaScript Object Paths](./mapping-javascript-objects.md)** (30 min read)
+- Core concept: Mapping paths work on JavaScript objects, NOT source file formats
+- Real-world examples: CSV, JSON, XML with complex structures
+- Debugging guide and common mistakes
+- **MUST READ for all newcomers**
+
+📊 **[Mapper Comparison Guide](./mapping-mapper-comparison-guide.md)** (20 min read)
+- Real-world scenario: 100 locations from CSV
+- 4 different approaches with complete code
+- Decision matrix: Which approach to use when?
+- Performance comparison
+
+📋 **[Mapping Format Decision Tree](./mapping-format-decision-tree.md)** (15 min read)
+- External JSON vs Inline TypeScript configurations
+- When to use each pattern
+- Migration guide
+
+---
+
+## 🔍 Which Guide Do I Need?
+
+This directory contains **3 specialized mapping guides**. Choose based on your use case:
+
+### 1. Universal Mapping (`modules/`)
+**Use when**: Transforming data **WITHOUT** GraphQL mutations
+
+**Common Use Cases**:
+- CSV/JSON → Fluent Batch API (Inventory, Location, Product ingestion)
+- GraphQL → Parquet extraction
+- JSON → Event API
+- Any non-GraphQL data transformation
+
+**Features**:
+- Simple field mapping configuration
+- Built-in SDK resolvers (trim, parseInt, parseFloat, etc.)
+- Custom resolver support
+- Schema validation
+
+**Start Here**: [Module 1: Foundations](./modules/02-CORE-GUIDES-mapping-01-foundations.md)
+
+---
+
+### 2. GraphQL Mutation Mapping (`graphql-mutation-mapping/`)
+**Use when**: Transforming data **INTO** GraphQL mutations
+
+**Common Use Cases**:
+- XML orders → `createOrder` mutation
+- JSON products → `updateProduct` mutation
+- SFCC XML → Fluent GraphQL mutations
+- Any source → GraphQL API
+
+**Features**:
+- Automatic GraphQL mutation generation
+- Alias batching for performance
+- Path syntax for nested data
+- XML attribute support (`@` prefix)
+
+**Start Here**: [GraphQL Mapping Quick Start](./graphql-mutation-mapping/modules/graphql-mutation-mapping-02-quick-start.md)
+
+---
+
+### 3. Custom Resolvers (`resolvers/`)
+**Use when**: Building **custom transformation functions**
+
+**Common Use Cases**:
+- Complex business logic transformations
+- API lookups during mapping
+- Async data enrichment
+- Multi-field conditional transformations
+- Custom data validation
+
+**Features**:
+- Full TypeScript/JavaScript functions
+- Access to context and helpers
+- Async/await support
+- Error handling
+
+**Start Here**: [Resolver Guide](./resolvers/mapping-resolvers-resolver-guide.md)
+
+---
+
+## 🚀 Quick Decision Tree
+
+```
+Do you need to call GraphQL mutations?
+├─ YES → Use GraphQL Mutation Mapping
+└─ NO → Do you need complex custom logic?
+    ├─ YES → Use Universal Mapping + Custom Resolvers
+    └─ NO → Use Universal Mapping with SDK Resolvers
+```
+
+---
+
+## 📚 Quick Reference & Advanced Topics
+
+- **[Quick Start Guide](./modules/02-CORE-GUIDES-mapping-02-quick-start.md)** - Get started with mapping quickly
+- **[Error Handling Guide](./modules/02-core-guides-mapping-08-error-handling.md)** - Comprehensive error handling for UniversalMapper **NEW!**
+- **[GraphQL Alias Batching Guide](./mapping-graphql-alias-batching-guide.md)** - Performance optimization
+- **[Understanding Mapping: JavaScript Object Paths](./mapping-javascript-objects.md)** - Complete ETL flow guide with examples
+
+---
+
+## 🎯 Learning Paths
+
+### For Newcomers (Total: ~2 hours)
+1. Read: [mapping-javascript-objects.md](./mapping-javascript-objects.md) (30 min)
+2. Read: [Mapper Comparison Guide](./mapping-mapper-comparison-guide.md) (20 min)
+3. Choose your path: Universal Mapping OR GraphQL Mutation Mapping
+4. Complete Quick Start guide (30-45 min)
+5. Build first integration (30-45 min)
+
+### For Universal Mapping Users
+1. [Module 1: Foundations](./modules/02-CORE-GUIDES-mapping-01-foundations.md)
+2. [Module 2: Quick Start](./modules/02-CORE-GUIDES-mapping-02-quick-start.md)
+3. [Module 4: Use Cases](./modules/02-CORE-GUIDES-mapping-04-use-cases.md)
+4. [Module 5: Advanced Patterns](./modules/02-CORE-GUIDES-mapping-05-advanced-patterns.md)
+5. [Module 8: Error Handling](./modules/02-core-guides-mapping-08-error-handling.md) - **NEW!**
+
+### For GraphQL Mutation Mapping Users
+1. [Module 1: Introduction](./graphql-mutation-mapping/modules/graphql-mutation-mapping-01-introduction.md)
+2. [Module 2: Quick Start](./graphql-mutation-mapping/modules/graphql-mutation-mapping-02-quick-start.md)
+3. [Module 4: Mapping Patterns](./graphql-mutation-mapping/modules/graphql-mutation-mapping-04-mapping-patterns.md)
+4. [Module 9: Advanced Patterns](./graphql-mutation-mapping/modules/graphql-mutation-mapping-09-advanced-patterns.md)
+
+### For Advanced Users
+1. [Custom Resolvers](./resolvers/mapping-resolvers-resolver-guide.md)
+2. [GraphQL Alias Batching](./mapping-graphql-alias-batching-guide.md)
+3. [Advanced Patterns](./modules/02-CORE-GUIDES-mapping-05-advanced-patterns.md)
+4. [Error Handling: UniversalMapper](./modules/02-core-guides-mapping-08-error-handling.md) - **NEW!**
+5. [Error Handling: GraphQL Mutation Mapper](./graphql-mutation-mapping/modules/graphql-mutation-mapping-11-error-handling.md)
+
+---
+
+## 🔗 Related Documentation
+
+- **[Versori Platform Integration](../../04-REFERENCE/platforms/versori/)** - Webhook and Schedule workflows
+- **[Batch API Guide](../ingestion/)** - Fluent Batch API integration
+- **[Data Sources](../data-sources/)** - SFTP, S3, CSV, XML, JSON, Parquet
+- **[Parser Documentation](../parsers/)** - XML, JSON, CSV parsing
+
+---
+
+## Quick Start
+
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const mapper = new UniversalMapper({
+  fields: {
+    sku: { source: 'productRef', required: true },
+    quantity: { source: 'qty', resolver: 'sdk.parseInt' },
+    warehouse: { source: 'locationRef' }
+  }
+});
+
+const result = await mapper.map(data);
+```
+
+## Navigation
+
+- [Universal Mapping Modules](./modules/) - Progressive learning path
+- [GraphQL Mutation Mapping](./graphql-mutation-mapping/) - Generate GraphQL mutations
+- [Custom Resolvers](./resolvers/) - Build custom transformation logic
+- [Examples](./examples/) - Code examples
+
+## Which Guide Do I Need?
+
+| Use Case | Guide | When to Use |
+|----------|-------|-------------|
+| **Transform data (no GraphQL)** | [Universal Mapping](./modules/) | CSV → Batch API, data transformation |
+| **Generate GraphQL mutations** | [GraphQL Mutation Mapping](./graphql-mutation-mapping/) | XML → createOrder, JSON → updateProduct |
+| **Custom transformation logic** | [Custom Resolvers](./resolvers/) | Complex business logic, API lookups |