@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/04-REFERENCE/resolver-signature/modules/resolver-signature-01-foundations.md

@@ -1,286 +1,286 @@
-# Module 1: Foundations
-
-**Level:** Beginner
-**Estimated Time:** 10 minutes
-
-## Overview
-
-This module introduces the standard 4-parameter resolver signature used consistently across ALL mappers in the Fluent Connect SDK. You'll understand why this signature exists and how it ensures predictability and ease of use.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Understand the standard 4-parameter resolver signature
-- ✅ Know why the SDK uses 4 parameters instead of 3
-- ✅ Recognize how consistency benefits your development workflow
-- ✅ Identify which mappers use this signature
-
-## The Standard Resolver Signature
-
-Every resolver function in the FC Connect SDK follows this exact signature:
-
-```typescript
-type ResolverFunction = (
-  value: any,              // Parameter 1: The field value being transformed
-  sourceData: any,         // Parameter 2: Full source object for context
-  config: any,             // Parameter 3: Resolver-specific configuration
-  helpers: ResolverHelpers // Parameter 4: SDK utilities and user context
-) => any | Promise<any>;
-```
-
-### Quick Example
-
-```typescript
-// This signature works everywhere in the SDK
-const customResolver = (value, sourceData, config, helpers) => {
-  // Transform the value
-  return String(value).toUpperCase();
-};
-```
-
-## Why 4 Parameters?
-
-The SDK evolved from a 3-parameter signature to the current 4-parameter design for critical architectural reasons:
-
-### 1. Separation of Concerns
-
-**Before (3 parameters):**
-```typescript
-// ❌ Configuration and helpers were mixed
-(value, sourceData, helpers) => {
-  const taxRate = helpers.context?.taxRate; // Unclear source
-  return value * (1 + taxRate);
-}
-```
-
-**After (4 parameters):**
-```typescript
-// ✅ Clear separation: config for business rules, helpers for utilities
-(value, sourceData, config, helpers) => {
-  const taxRate = config.taxRate;  // Business rule
-  const safe = helpers.parseFloatSafe(value, 0);  // Utility function
-  return safe * (1 + taxRate);
-}
-```
-
-### 2. Type Safety
-
-With dedicated parameters, TypeScript can provide better type inference:
-
-```typescript
-interface ResolverHelpers {
-  // 48+ utility functions
-  get(obj: any, path: string): any;
-  parseFloatSafe(value: any, defaultValue: number): number;
-  formatDate(date: any, format?: string): string;
-  // ... 45 more
-}
-
-// TypeScript knows exactly what's in helpers
-(value, sourceData, config, helpers) => {
-  helpers.parseFloatSafe(value, 0);  // ✅ Autocomplete works!
-}
-```
-
-### 3. Predictability Across Mappers
-
-The 4-parameter signature is used by BOTH major mappers:
-
-```typescript
-import { UniversalMapper, GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-
-// Define once
-const resolvers = {
-  'custom.transform': (value, sourceData, config, helpers) => {
-    return String(value).toUpperCase();
-  }
-};
-
-// Use everywhere
-const mapper1 = new UniversalMapper(mapping, { customResolvers: resolvers });
-const mapper2 = new GraphQLMutationMapper(mapping, { customResolvers: resolvers });
-
-// Same signature, same behavior, zero surprises
-```
-
-### 4. Future-Proof Design
-
-The 4-parameter design allows the SDK to grow without breaking changes:
-
-```typescript
-// Today: config contains business rules
-(value, sourceData, config, helpers) => {
-  const rate = config.taxRate;
-}
-
-// Tomorrow: SDK can add more to config without breaking your code
-(value, sourceData, config, helpers) => {
-  const rate = config.taxRate;
-  const region = config.region;  // New field added by SDK
-}
-```
-
-## Consistency Across the SDK
-
-### Used by ALL Mappers
-
-| Mapper | Purpose | Uses 4-Param Signature |
-|--------|---------|----------------------|
-| **UniversalMapper** | CSV/JSON/Parquet/XML transformations | ✅ Yes |
-| **GraphQLMutationMapper** | XML/JSON → GraphQL mutations | ✅ Yes |
-
-### Used by SDK Resolvers
-
-All built-in SDK resolvers follow the same signature:
-
-```typescript
-// SDK resolver: sdk.parseFloat
-'sdk.parseFloat': (value, sourceData, config, helpers) => {
-  return helpers.parseFloatSafe(value, 0);
-}
-
-// Your custom resolver: custom.parseFloat
-'custom.parseFloat': (value, sourceData, config, helpers) => {
-  return helpers.parseFloatSafe(value, 0);
-}
-
-// Identical signature = consistent behavior
-```
-
-## What This Means for You
-
-### As a Developer
-
-**You write resolvers once, use them everywhere:**
-```typescript
-const resolvers = {
-  'custom.formatSKU': (value, sourceData, config, helpers) => {
-    return `${config.prefix}-${value}`;
-  }
-};
-
-// Works in CSV ingestion
-const csvMapper = new UniversalMapper(csvMapping, {
-  customResolvers: resolvers,
-  context: { prefix: 'CSV' }
-});
-
-// Works in XML order processing
-const xmlMapper = new GraphQLMutationMapper(xmlMapping, {
-  customResolvers: resolvers,
-  context: { prefix: 'XML' }
-});
-
-// Works in Parquet extraction
-const parquetMapper = new UniversalMapper(parquetMapping, {
-  customResolvers: resolvers,
-  context: { prefix: 'PQT' }
-});
-```
-
-### As a Team
-
-**Everyone learns one pattern:**
-- New developers learn 4 parameters once
-- Code reviews check for 4 parameters
-- Testing frameworks expect 4 parameters
-- Documentation consistently shows 4 parameters
-
-### As a System
-
-**The SDK is predictable:**
-- Error messages reference the same parameters
-- Debugging tools understand the signature
-- Type systems enforce consistency
-- Performance optimizations work uniformly
-
-## Real-World Analogy
-
-Think of the 4-parameter signature like a standardized electrical outlet:
-
-**Without Standard (3-param, varies):**
-- Every resolver has different parameters
-- Need adapters to share resolvers between mappers
-- Hard to remember which parameter order is correct
-- Type safety is difficult to enforce
-
-**With Standard (4-param, consistent):**
-- Every resolver uses the same "plug shape"
-- Resolvers work in any mapper "socket"
-- Clear documentation applies universally
-- TypeScript enforces correct usage automatically
-
-## Quick Reference
-
-```typescript
-// ✅ ALWAYS use this signature
-(value, sourceData, config, helpers) => {
-  // Your transformation logic
-  return transformedValue;
-}
-
-// ❌ NEVER use these variations
-(value, helpers) => { ... }                    // Missing parameters
-(value, sourceData, helpers) => { ... }        // Old 3-param style
-(val, src, cfg, hlp) => { ... }                // Non-standard names
-(value, config, sourceData, helpers) => { ... } // Wrong parameter order
-```
-
-## Parameter Preview
-
-Here's a quick preview of each parameter (covered in detail in Module 2):
-
-1. **value** - The extracted field value to transform
-2. **sourceData** - Complete source object for accessing related fields
-3. **config** - Business rules and configuration passed to the mapper
-4. **helpers** - 48+ SDK utility functions plus fluentClient and logger
-
-## Key Takeaways
-
-- 🎯 **Standard Signature**: `(value, sourceData, config, helpers) => any`
-- 🎯 **Used Everywhere**: UniversalMapper AND GraphQLMutationMapper
-- 🎯 **Consistent Behavior**: Same signature = same mental model
-- 🎯 **Type Safe**: TypeScript enforces correct usage
-- 🎯 **Future Proof**: Design allows growth without breaking changes
-
-## Practice Exercise
-
-Convert this old 3-parameter resolver to the new 4-parameter signature:
-
-```typescript
-// OLD (3 parameters)
-const oldResolver = (value, sourceData, helpers) => {
-  const prefix = helpers.context?.prefix || 'SKU';
-  return `${prefix}-${value}`;
-};
-
-// YOUR TASK: Convert to 4 parameters
-// HINT: Move context access to config parameter
-```
-
-<details>
-<summary>Show Solution</summary>
-
-```typescript
-// NEW (4 parameters)
-const newResolver = (value, sourceData, config, helpers) => {
-  const prefix = config.prefix || 'SKU';
-  return `${prefix}-${value}`;
-};
-
-// Usage with mapper
-const mapper = new UniversalMapper(mapping, {
-  customResolvers: { 'custom.format': newResolver },
-  context: { prefix: 'PROD' }  // Becomes 'config' parameter
-});
-```
-
-**Key changes:**
-1. Added `config` parameter (3rd position)
-2. Changed `helpers.context?.prefix` to `config.prefix`
-3. Context passed via mapper options becomes the `config` parameter
-</details>
-
-## Next Steps
-
-Continue to [Module 2: Parameter Reference](./resolver-signature-02-parameter-reference.md) to learn what each parameter does and how to use them effectively.
+# Module 1: Foundations
+
+**Level:** Beginner
+**Estimated Time:** 10 minutes
+
+## Overview
+
+This module introduces the standard 4-parameter resolver signature used consistently across ALL mappers in the Fluent Connect SDK. You'll understand why this signature exists and how it ensures predictability and ease of use.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Understand the standard 4-parameter resolver signature
+- ✅ Know why the SDK uses 4 parameters instead of 3
+- ✅ Recognize how consistency benefits your development workflow
+- ✅ Identify which mappers use this signature
+
+## The Standard Resolver Signature
+
+Every resolver function in the FC Connect SDK follows this exact signature:
+
+```typescript
+type ResolverFunction = (
+  value: any,              // Parameter 1: The field value being transformed
+  sourceData: any,         // Parameter 2: Full source object for context
+  config: any,             // Parameter 3: Resolver-specific configuration
+  helpers: ResolverHelpers // Parameter 4: SDK utilities and user context
+) => any | Promise<any>;
+```
+
+### Quick Example
+
+```typescript
+// This signature works everywhere in the SDK
+const customResolver = (value, sourceData, config, helpers) => {
+  // Transform the value
+  return String(value).toUpperCase();
+};
+```
+
+## Why 4 Parameters?
+
+The SDK evolved from a 3-parameter signature to the current 4-parameter design for critical architectural reasons:
+
+### 1. Separation of Concerns
+
+**Before (3 parameters):**
+```typescript
+// ❌ Configuration and helpers were mixed
+(value, sourceData, helpers) => {
+  const taxRate = helpers.context?.taxRate; // Unclear source
+  return value * (1 + taxRate);
+}
+```
+
+**After (4 parameters):**
+```typescript
+// ✅ Clear separation: config for business rules, helpers for utilities
+(value, sourceData, config, helpers) => {
+  const taxRate = config.taxRate;  // Business rule
+  const safe = helpers.parseFloatSafe(value, 0);  // Utility function
+  return safe * (1 + taxRate);
+}
+```
+
+### 2. Type Safety
+
+With dedicated parameters, TypeScript can provide better type inference:
+
+```typescript
+interface ResolverHelpers {
+  // 48+ utility functions
+  get(obj: any, path: string): any;
+  parseFloatSafe(value: any, defaultValue: number): number;
+  formatDate(date: any, format?: string): string;
+  // ... 45 more
+}
+
+// TypeScript knows exactly what's in helpers
+(value, sourceData, config, helpers) => {
+  helpers.parseFloatSafe(value, 0);  // ✅ Autocomplete works!
+}
+```
+
+### 3. Predictability Across Mappers
+
+The 4-parameter signature is used by BOTH major mappers:
+
+```typescript
+import { UniversalMapper, GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+
+// Define once
+const resolvers = {
+  'custom.transform': (value, sourceData, config, helpers) => {
+    return String(value).toUpperCase();
+  }
+};
+
+// Use everywhere
+const mapper1 = new UniversalMapper(mapping, { customResolvers: resolvers });
+const mapper2 = new GraphQLMutationMapper(mapping, { customResolvers: resolvers });
+
+// Same signature, same behavior, zero surprises
+```
+
+### 4. Future-Proof Design
+
+The 4-parameter design allows the SDK to grow without breaking changes:
+
+```typescript
+// Today: config contains business rules
+(value, sourceData, config, helpers) => {
+  const rate = config.taxRate;
+}
+
+// Tomorrow: SDK can add more to config without breaking your code
+(value, sourceData, config, helpers) => {
+  const rate = config.taxRate;
+  const region = config.region;  // New field added by SDK
+}
+```
+
+## Consistency Across the SDK
+
+### Used by ALL Mappers
+
+| Mapper | Purpose | Uses 4-Param Signature |
+|--------|---------|----------------------|
+| **UniversalMapper** | CSV/JSON/Parquet/XML transformations | ✅ Yes |
+| **GraphQLMutationMapper** | XML/JSON → GraphQL mutations | ✅ Yes |
+
+### Used by SDK Resolvers
+
+All built-in SDK resolvers follow the same signature:
+
+```typescript
+// SDK resolver: sdk.parseFloat
+'sdk.parseFloat': (value, sourceData, config, helpers) => {
+  return helpers.parseFloatSafe(value, 0);
+}
+
+// Your custom resolver: custom.parseFloat
+'custom.parseFloat': (value, sourceData, config, helpers) => {
+  return helpers.parseFloatSafe(value, 0);
+}
+
+// Identical signature = consistent behavior
+```
+
+## What This Means for You
+
+### As a Developer
+
+**You write resolvers once, use them everywhere:**
+```typescript
+const resolvers = {
+  'custom.formatSKU': (value, sourceData, config, helpers) => {
+    return `${config.prefix}-${value}`;
+  }
+};
+
+// Works in CSV ingestion
+const csvMapper = new UniversalMapper(csvMapping, {
+  customResolvers: resolvers,
+  context: { prefix: 'CSV' }
+});
+
+// Works in XML order processing
+const xmlMapper = new GraphQLMutationMapper(xmlMapping, {
+  customResolvers: resolvers,
+  context: { prefix: 'XML' }
+});
+
+// Works in Parquet extraction
+const parquetMapper = new UniversalMapper(parquetMapping, {
+  customResolvers: resolvers,
+  context: { prefix: 'PQT' }
+});
+```
+
+### As a Team
+
+**Everyone learns one pattern:**
+- New developers learn 4 parameters once
+- Code reviews check for 4 parameters
+- Testing frameworks expect 4 parameters
+- Documentation consistently shows 4 parameters
+
+### As a System
+
+**The SDK is predictable:**
+- Error messages reference the same parameters
+- Debugging tools understand the signature
+- Type systems enforce consistency
+- Performance optimizations work uniformly
+
+## Real-World Analogy
+
+Think of the 4-parameter signature like a standardized electrical outlet:
+
+**Without Standard (3-param, varies):**
+- Every resolver has different parameters
+- Need adapters to share resolvers between mappers
+- Hard to remember which parameter order is correct
+- Type safety is difficult to enforce
+
+**With Standard (4-param, consistent):**
+- Every resolver uses the same "plug shape"
+- Resolvers work in any mapper "socket"
+- Clear documentation applies universally
+- TypeScript enforces correct usage automatically
+
+## Quick Reference
+
+```typescript
+// ✅ ALWAYS use this signature
+(value, sourceData, config, helpers) => {
+  // Your transformation logic
+  return transformedValue;
+}
+
+// ❌ NEVER use these variations
+(value, helpers) => { ... }                    // Missing parameters
+(value, sourceData, helpers) => { ... }        // Old 3-param style
+(val, src, cfg, hlp) => { ... }                // Non-standard names
+(value, config, sourceData, helpers) => { ... } // Wrong parameter order
+```
+
+## Parameter Preview
+
+Here's a quick preview of each parameter (covered in detail in Module 2):
+
+1. **value** - The extracted field value to transform
+2. **sourceData** - Complete source object for accessing related fields
+3. **config** - Business rules and configuration passed to the mapper
+4. **helpers** - 48+ SDK utility functions plus fluentClient and logger
+
+## Key Takeaways
+
+- 🎯 **Standard Signature**: `(value, sourceData, config, helpers) => any`
+- 🎯 **Used Everywhere**: UniversalMapper AND GraphQLMutationMapper
+- 🎯 **Consistent Behavior**: Same signature = same mental model
+- 🎯 **Type Safe**: TypeScript enforces correct usage
+- 🎯 **Future Proof**: Design allows growth without breaking changes
+
+## Practice Exercise
+
+Convert this old 3-parameter resolver to the new 4-parameter signature:
+
+```typescript
+// OLD (3 parameters)
+const oldResolver = (value, sourceData, helpers) => {
+  const prefix = helpers.context?.prefix || 'SKU';
+  return `${prefix}-${value}`;
+};
+
+// YOUR TASK: Convert to 4 parameters
+// HINT: Move context access to config parameter
+```
+
+<details>
+<summary>Show Solution</summary>
+
+```typescript
+// NEW (4 parameters)
+const newResolver = (value, sourceData, config, helpers) => {
+  const prefix = config.prefix || 'SKU';
+  return `${prefix}-${value}`;
+};
+
+// Usage with mapper
+const mapper = new UniversalMapper(mapping, {
+  customResolvers: { 'custom.format': newResolver },
+  context: { prefix: 'PROD' }  // Becomes 'config' parameter
+});
+```
+
+**Key changes:**
+1. Added `config` parameter (3rd position)
+2. Changed `helpers.context?.prefix` to `config.prefix`
+3. Context passed via mapper options becomes the `config` parameter
+</details>
+
+## Next Steps
+
+Continue to [Module 2: Parameter Reference](./resolver-signature-02-parameter-reference.md) to learn what each parameter does and how to use them effectively.