@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/mapping/resolver-registration.md

@@ -1,410 +1,410 @@
-# Resolver Registration Guide
-
-**⏱️ Read Time:** 5 minutes | **When:** Adding custom business logic to your mappings
-
----
-
-## Overview
-
-Both `GraphQLMutationMapper` and `UniversalMapper` support **custom resolvers** - functions that transform data during mapping. Resolvers can be registered in two ways:
-
-1. **Constructor registration** - Pass resolvers when creating the mapper
-2. **Runtime registration** - Register resolvers dynamically using `registerResolver()`
-
----
-
-## GraphQLMutationMapper Resolver Registration
-
-### Method 1: Constructor Registration
-
-```typescript
-import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const customResolvers = {
-  'custom.calculateTax': (value: any, sourceData: any, config: any, helpers: any) => {
-    const taxRate = helpers.get(sourceData, 'taxRate') || 0.1;
-    return value * (1 + taxRate);
-  },
-  'custom.formatPhone': (value: any) => {
-    return value.replace(/[^0-9]/g, '');
-  },
-};
-
-const mapper = new GraphQLMutationMapper(config, logger, {
-  customResolvers,
-  fluentClient: client,  // Available as helpers.fluentClient
-  context: { retailerId: '1' },  // Available as helpers.context
-});
-```
-
-**When to use:**
-- Resolvers are known at mapper creation time
-- Resolvers don't change during runtime
-- You want to pass context (FluentClient, config) to resolvers
-
----
-
-### Method 2: Runtime Registration (Dynamic)
-
-```typescript
-import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const mapper = new GraphQLMutationMapper(config, logger);
-
-// Register resolvers dynamically
-mapper.registerResolver('custom.calculateTax', (value: any) => {
-  return value * 1.1;
-});
-
-mapper.registerResolver('custom.formatPhone', (value: any) => {
-  return value.replace(/[^0-9]/g, '');
-});
-
-// Register multiple at once
-mapper.registerResolvers({
-  'custom.double': (value: any) => value * 2,
-  'custom.triple': (value: any) => value * 3,
-});
-```
-
-**When to use:**
-- Resolvers depend on runtime conditions
-- Resolvers need to be registered conditionally
-- You want to overwrite existing resolvers
-- Resolvers are loaded from external configuration
-
----
-
-### Resolver Overwriting
-
-You can overwrite existing resolvers by registering a new one with the same name:
-
-```typescript
-// Register first resolver
-mapper.registerResolver('custom.transform', (value: any) => value + 10);
-
-// Overwrite with new resolver
-mapper.registerResolver('custom.transform', (value: any) => value + 20);
-
-// Now uses the second resolver (value + 20)
-```
-
----
-
-## UniversalMapper Resolver Registration
-
-### Method 1: Constructor Registration
-
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const mapper = new UniversalMapper(config, logger);
-
-// Register resolvers via resolver engine
-mapper.registerResolver('custom.calculateTax', (value, source, config, helpers) => {
-  return value * 1.1;
-});
-```
-
----
-
-### Method 2: Runtime Registration (Dynamic)
-
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const mapper = new UniversalMapper(config, logger);
-
-// Register single resolver
-mapper.registerResolver('custom.calculateTax', (value, source, config, helpers) => {
-  return value * 1.1;
-});
-
-// Register multiple resolvers
-mapper.registerResolvers({
-  'custom.double': (value, source, config, helpers) => value * 2,
-  'custom.triple': (value, source, config, helpers) => value * 3,
-});
-```
-
----
-
-## Resolver Function Signature
-
-### GraphQLMutationMapper Resolvers
-
-**For `map()` pattern (used as transforms):**
-```typescript
-(value: any) => any | Promise<any>
-```
-
-**For `mapWithNodes()` pattern (full signature):**
-```typescript
-(value: any, sourceData: any, config: any, helpers: any) => any | Promise<any>
-```
-
-### UniversalMapper Resolvers
-
-```typescript
-(value: any, source: any, config: any, helpers: any) => any | Promise<any>
-```
-
-**Parameters:**
-- `value` - The current field value (after source extraction)
-- `source` / `sourceData` - The complete source data object
-- `config` - The field configuration
-- `helpers` - Helper functions (get, ensureArray, logger, fluentClient, etc.)
-
----
-
-## Async Resolver Support
-
-Both mappers support **async resolvers**:
-
-```typescript
-// Async resolver example
-mapper.registerResolver('custom.fetchPrice', async (value: any, sourceData: any, config: any, helpers: any) => {
-  // Make API call
-  const price = await helpers.fluentClient.graphql({
-    query: `query { product(ref: "${value}") { price } }`,
-  });
-  return price.data.product.price;
-});
-```
-
-**Note:** Async resolvers work automatically - the mapper handles promises correctly.
-
----
-
-## Using Resolvers in Mapping Config
-
-### GraphQLMutationMapper
-
-**Pattern 1: `map()` - Use as transform**
-```typescript
-const config = {
-  mutation: 'createOrder',
-  sourceFormat: 'json',
-  arguments: {
-    input: {
-      total: { 
-        source: 'order.total',
-        transform: 'custom.calculateTax'  // ← Uses registered resolver
-      },
-    },
-  },
-};
-```
-
-**Pattern 2: `mapWithNodes()` - Use as resolver**
-```typescript
-const config = {
-  mutation: 'createOrder',
-  sourceFormat: 'json',
-  fields: {
-    total: {
-      source: 'order.total',
-      resolver: 'custom.calculateTax'  // ← Uses registered resolver
-    },
-  },
-};
-```
-
-### UniversalMapper
-
-```typescript
-const config = {
-  fields: {
-    total: {
-      source: 'order.total',
-      resolver: 'custom.calculateTax'  // ← Uses registered resolver
-    },
-  },
-};
-```
-
----
-
-## Helper Functions Available in Resolvers
-
-Resolvers receive a `helpers` object with useful utilities:
-
-```typescript
-mapper.registerResolver('custom.example', (value, sourceData, config, helpers) => {
-  // Access nested values
-  const taxRate = helpers.get(sourceData, 'order.taxRate');
-  
-  // Ensure array
-  const items = helpers.ensureArray(sourceData.items);
-  
-  // Logger
-  helpers.logger?.info('Processing value:', value);
-  
-  // FluentClient (if provided)
-  const product = await helpers.fluentClient?.graphql({ /* ... */ });
-  
-  // Context (if provided)
-  const retailerId = helpers.context?.retailerId;
-  
-  // 50+ SDK helpers available
-  const uuid = helpers.uuid();
-  const formatted = helpers.formatCurrency(value);
-  const date = helpers.formatDate(new Date());
-  
-  return value;
-});
-```
-
-**Available Helpers:**
-- `get(obj, path)` - Get nested value by path
-- `ensureArray(val)` - Convert to array if needed
-- `logger` - Logger instance
-- `fluentClient` - FluentClient instance (if provided)
-- `context` - Custom context object (if provided)
-- `uuid()`, `formatCurrency()`, `formatDate()`, `parseIntSafe()`, etc. - 50+ SDK helpers
-
----
-
-## Real-World Examples
-
-### Example 1: Tax Calculation Resolver
-
-```typescript
-mapper.registerResolver('custom.calculateTax', (value, sourceData, config, helpers) => {
-  const taxRate = helpers.get(sourceData, 'order.taxRate') || 0.1;
-  const subtotal = helpers.get(sourceData, 'order.subtotal') || value;
-  return subtotal * (1 + taxRate);
-});
-```
-
-### Example 2: Phone Number Formatting
-
-```typescript
-mapper.registerResolver('custom.formatPhone', (value) => {
-  if (!value) return '';
-  // Remove all non-digits
-  const digits = value.replace(/[^0-9]/g, '');
-  // Format as (XXX) XXX-XXXX
-  if (digits.length === 10) {
-    return `(${digits.slice(0, 3)}) ${digits.slice(3, 6)}-${digits.slice(6)}`;
-  }
-  return value;
-});
-```
-
-### Example 3: Async Product Lookup
-
-```typescript
-mapper.registerResolver('custom.lookupProduct', async (value, sourceData, config, helpers) => {
-  if (!helpers.fluentClient) {
-    throw new Error('FluentClient not available');
-  }
-  
-  const result = await helpers.fluentClient.graphql({
-    query: `query { product(ref: "${value}") { id, name, price } }`,
-  });
-  
-  return result.data.product;
-});
-```
-
-### Example 4: Conditional Resolver Registration
-
-```typescript
-const mapper = new GraphQLMutationMapper(config, logger);
-
-// Register resolvers based on environment
-if (process.env.ENVIRONMENT === 'production') {
-  mapper.registerResolver('custom.calculateTax', (value) => value * 1.1);
-} else {
-  mapper.registerResolver('custom.calculateTax', (value) => value * 1.05); // Lower tax in dev
-}
-```
-
----
-
-## Best Practices
-
-### ✅ DO
-
-1. **Use descriptive resolver names**
-   ```typescript
-   // ✅ GOOD
-   mapper.registerResolver('custom.calculateTax', ...);
-   mapper.registerResolver('custom.formatPhoneNumber', ...);
-   
-   // ❌ BAD
-   mapper.registerResolver('custom.func1', ...);
-   mapper.registerResolver('custom.tax', ...);
-   ```
-
-2. **Use `custom.*` prefix for custom resolvers**
-   - Avoids conflicts with SDK built-in resolvers
-   - Makes it clear these are custom functions
-
-3. **Register resolvers before mapping**
-   ```typescript
-   const mapper = new GraphQLMutationMapper(config, logger);
-   mapper.registerResolver('custom.transform', ...);  // ← Register first
-   const result = await mapper.map(data);  // ← Then use
-   ```
-
-4. **Handle errors in resolvers**
-   ```typescript
-   mapper.registerResolver('custom.safeParse', (value) => {
-     try {
-       return JSON.parse(value);
-     } catch {
-       return null;
-     }
-   });
-   ```
-
-### ❌ DON'T
-
-1. **Don't register resolvers with SDK names**
-   ```typescript
-   // ❌ BAD - conflicts with SDK resolver
-   mapper.registerResolver('sdk.parseInt', ...);
-   
-   // ✅ GOOD - use custom prefix
-   mapper.registerResolver('custom.parseInt', ...);
-   ```
-
-2. **Don't mutate source data in resolvers**
-   ```typescript
-   // ❌ BAD - mutates source
-   mapper.registerResolver('custom.transform', (value, sourceData) => {
-     sourceData.modified = true;  // Don't do this!
-     return value;
-   });
-   ```
-
-3. **Don't register resolvers after mapping**
-   ```typescript
-   // ❌ BAD - resolver not available
-   const result = await mapper.map(data);
-   mapper.registerResolver('custom.transform', ...);  // Too late!
-   ```
-
----
-
-## Comparison: Constructor vs Runtime Registration
-
-| Feature | Constructor Registration | Runtime Registration |
-|---------|------------------------|---------------------|
-| **When to use** | Resolvers known at creation | Resolvers depend on runtime |
-| **Context access** | ✅ Yes (via options) | ⚠️ Limited (no context in `map()` pattern) |
-| **Overwriting** | ❌ No (set once) | ✅ Yes (can overwrite) |
-| **Conditional** | ⚠️ Possible but awkward | ✅ Easy |
-| **Best for** | Production code | Dynamic/configurable resolvers |
-
----
-
-## Related Documentation
-
-- [Error Handling Patterns](./error-handling-patterns.md) - How to handle resolver errors
-- [Mapper Comparison Guide](./mapping-mapper-comparison-guide.md) - Complete mapper comparison
-- [GraphQL Mutation Mapping](../graphql-mutation-mapping/) - GraphQLMutationMapper details
-- [Universal Mapping](./) - UniversalMapper details
-
+# Resolver Registration Guide
+
+**⏱️ Read Time:** 5 minutes | **When:** Adding custom business logic to your mappings
+
+---
+
+## Overview
+
+Both `GraphQLMutationMapper` and `UniversalMapper` support **custom resolvers** - functions that transform data during mapping. Resolvers can be registered in two ways:
+
+1. **Constructor registration** - Pass resolvers when creating the mapper
+2. **Runtime registration** - Register resolvers dynamically using `registerResolver()`
+
+---
+
+## GraphQLMutationMapper Resolver Registration
+
+### Method 1: Constructor Registration
+
+```typescript
+import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const customResolvers = {
+  'custom.calculateTax': (value: any, sourceData: any, config: any, helpers: any) => {
+    const taxRate = helpers.get(sourceData, 'taxRate') || 0.1;
+    return value * (1 + taxRate);
+  },
+  'custom.formatPhone': (value: any) => {
+    return value.replace(/[^0-9]/g, '');
+  },
+};
+
+const mapper = new GraphQLMutationMapper(config, logger, {
+  customResolvers,
+  fluentClient: client,  // Available as helpers.fluentClient
+  context: { retailerId: '1' },  // Available as helpers.context
+});
+```
+
+**When to use:**
+- Resolvers are known at mapper creation time
+- Resolvers don't change during runtime
+- You want to pass context (FluentClient, config) to resolvers
+
+---
+
+### Method 2: Runtime Registration (Dynamic)
+
+```typescript
+import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const mapper = new GraphQLMutationMapper(config, logger);
+
+// Register resolvers dynamically
+mapper.registerResolver('custom.calculateTax', (value: any) => {
+  return value * 1.1;
+});
+
+mapper.registerResolver('custom.formatPhone', (value: any) => {
+  return value.replace(/[^0-9]/g, '');
+});
+
+// Register multiple at once
+mapper.registerResolvers({
+  'custom.double': (value: any) => value * 2,
+  'custom.triple': (value: any) => value * 3,
+});
+```
+
+**When to use:**
+- Resolvers depend on runtime conditions
+- Resolvers need to be registered conditionally
+- You want to overwrite existing resolvers
+- Resolvers are loaded from external configuration
+
+---
+
+### Resolver Overwriting
+
+You can overwrite existing resolvers by registering a new one with the same name:
+
+```typescript
+// Register first resolver
+mapper.registerResolver('custom.transform', (value: any) => value + 10);
+
+// Overwrite with new resolver
+mapper.registerResolver('custom.transform', (value: any) => value + 20);
+
+// Now uses the second resolver (value + 20)
+```
+
+---
+
+## UniversalMapper Resolver Registration
+
+### Method 1: Constructor Registration
+
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const mapper = new UniversalMapper(config, logger);
+
+// Register resolvers via resolver engine
+mapper.registerResolver('custom.calculateTax', (value, source, config, helpers) => {
+  return value * 1.1;
+});
+```
+
+---
+
+### Method 2: Runtime Registration (Dynamic)
+
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const mapper = new UniversalMapper(config, logger);
+
+// Register single resolver
+mapper.registerResolver('custom.calculateTax', (value, source, config, helpers) => {
+  return value * 1.1;
+});
+
+// Register multiple resolvers
+mapper.registerResolvers({
+  'custom.double': (value, source, config, helpers) => value * 2,
+  'custom.triple': (value, source, config, helpers) => value * 3,
+});
+```
+
+---
+
+## Resolver Function Signature
+
+### GraphQLMutationMapper Resolvers
+
+**For `map()` pattern (used as transforms):**
+```typescript
+(value: any) => any | Promise<any>
+```
+
+**For `mapWithNodes()` pattern (full signature):**
+```typescript
+(value: any, sourceData: any, config: any, helpers: any) => any | Promise<any>
+```
+
+### UniversalMapper Resolvers
+
+```typescript
+(value: any, source: any, config: any, helpers: any) => any | Promise<any>
+```
+
+**Parameters:**
+- `value` - The current field value (after source extraction)
+- `source` / `sourceData` - The complete source data object
+- `config` - The field configuration
+- `helpers` - Helper functions (get, ensureArray, logger, fluentClient, etc.)
+
+---
+
+## Async Resolver Support
+
+Both mappers support **async resolvers**:
+
+```typescript
+// Async resolver example
+mapper.registerResolver('custom.fetchPrice', async (value: any, sourceData: any, config: any, helpers: any) => {
+  // Make API call
+  const price = await helpers.fluentClient.graphql({
+    query: `query { product(ref: "${value}") { price } }`,
+  });
+  return price.data.product.price;
+});
+```
+
+**Note:** Async resolvers work automatically - the mapper handles promises correctly.
+
+---
+
+## Using Resolvers in Mapping Config
+
+### GraphQLMutationMapper
+
+**Pattern 1: `map()` - Use as transform**
+```typescript
+const config = {
+  mutation: 'createOrder',
+  sourceFormat: 'json',
+  arguments: {
+    input: {
+      total: { 
+        source: 'order.total',
+        transform: 'custom.calculateTax'  // ← Uses registered resolver
+      },
+    },
+  },
+};
+```
+
+**Pattern 2: `mapWithNodes()` - Use as resolver**
+```typescript
+const config = {
+  mutation: 'createOrder',
+  sourceFormat: 'json',
+  fields: {
+    total: {
+      source: 'order.total',
+      resolver: 'custom.calculateTax'  // ← Uses registered resolver
+    },
+  },
+};
+```
+
+### UniversalMapper
+
+```typescript
+const config = {
+  fields: {
+    total: {
+      source: 'order.total',
+      resolver: 'custom.calculateTax'  // ← Uses registered resolver
+    },
+  },
+};
+```
+
+---
+
+## Helper Functions Available in Resolvers
+
+Resolvers receive a `helpers` object with useful utilities:
+
+```typescript
+mapper.registerResolver('custom.example', (value, sourceData, config, helpers) => {
+  // Access nested values
+  const taxRate = helpers.get(sourceData, 'order.taxRate');
+  
+  // Ensure array
+  const items = helpers.ensureArray(sourceData.items);
+  
+  // Logger
+  helpers.logger?.info('Processing value:', value);
+  
+  // FluentClient (if provided)
+  const product = await helpers.fluentClient?.graphql({ /* ... */ });
+  
+  // Context (if provided)
+  const retailerId = helpers.context?.retailerId;
+  
+  // 50+ SDK helpers available
+  const uuid = helpers.uuid();
+  const formatted = helpers.formatCurrency(value);
+  const date = helpers.formatDate(new Date());
+  
+  return value;
+});
+```
+
+**Available Helpers:**
+- `get(obj, path)` - Get nested value by path
+- `ensureArray(val)` - Convert to array if needed
+- `logger` - Logger instance
+- `fluentClient` - FluentClient instance (if provided)
+- `context` - Custom context object (if provided)
+- `uuid()`, `formatCurrency()`, `formatDate()`, `parseIntSafe()`, etc. - 50+ SDK helpers
+
+---
+
+## Real-World Examples
+
+### Example 1: Tax Calculation Resolver
+
+```typescript
+mapper.registerResolver('custom.calculateTax', (value, sourceData, config, helpers) => {
+  const taxRate = helpers.get(sourceData, 'order.taxRate') || 0.1;
+  const subtotal = helpers.get(sourceData, 'order.subtotal') || value;
+  return subtotal * (1 + taxRate);
+});
+```
+
+### Example 2: Phone Number Formatting
+
+```typescript
+mapper.registerResolver('custom.formatPhone', (value) => {
+  if (!value) return '';
+  // Remove all non-digits
+  const digits = value.replace(/[^0-9]/g, '');
+  // Format as (XXX) XXX-XXXX
+  if (digits.length === 10) {
+    return `(${digits.slice(0, 3)}) ${digits.slice(3, 6)}-${digits.slice(6)}`;
+  }
+  return value;
+});
+```
+
+### Example 3: Async Product Lookup
+
+```typescript
+mapper.registerResolver('custom.lookupProduct', async (value, sourceData, config, helpers) => {
+  if (!helpers.fluentClient) {
+    throw new Error('FluentClient not available');
+  }
+  
+  const result = await helpers.fluentClient.graphql({
+    query: `query { product(ref: "${value}") { id, name, price } }`,
+  });
+  
+  return result.data.product;
+});
+```
+
+### Example 4: Conditional Resolver Registration
+
+```typescript
+const mapper = new GraphQLMutationMapper(config, logger);
+
+// Register resolvers based on environment
+if (process.env.ENVIRONMENT === 'production') {
+  mapper.registerResolver('custom.calculateTax', (value) => value * 1.1);
+} else {
+  mapper.registerResolver('custom.calculateTax', (value) => value * 1.05); // Lower tax in dev
+}
+```
+
+---
+
+## Best Practices
+
+### ✅ DO
+
+1. **Use descriptive resolver names**
+   ```typescript
+   // ✅ GOOD
+   mapper.registerResolver('custom.calculateTax', ...);
+   mapper.registerResolver('custom.formatPhoneNumber', ...);
+   
+   // ❌ BAD
+   mapper.registerResolver('custom.func1', ...);
+   mapper.registerResolver('custom.tax', ...);
+   ```
+
+2. **Use `custom.*` prefix for custom resolvers**
+   - Avoids conflicts with SDK built-in resolvers
+   - Makes it clear these are custom functions
+
+3. **Register resolvers before mapping**
+   ```typescript
+   const mapper = new GraphQLMutationMapper(config, logger);
+   mapper.registerResolver('custom.transform', ...);  // ← Register first
+   const result = await mapper.map(data);  // ← Then use
+   ```
+
+4. **Handle errors in resolvers**
+   ```typescript
+   mapper.registerResolver('custom.safeParse', (value) => {
+     try {
+       return JSON.parse(value);
+     } catch {
+       return null;
+     }
+   });
+   ```
+
+### ❌ DON'T
+
+1. **Don't register resolvers with SDK names**
+   ```typescript
+   // ❌ BAD - conflicts with SDK resolver
+   mapper.registerResolver('sdk.parseInt', ...);
+   
+   // ✅ GOOD - use custom prefix
+   mapper.registerResolver('custom.parseInt', ...);
+   ```
+
+2. **Don't mutate source data in resolvers**
+   ```typescript
+   // ❌ BAD - mutates source
+   mapper.registerResolver('custom.transform', (value, sourceData) => {
+     sourceData.modified = true;  // Don't do this!
+     return value;
+   });
+   ```
+
+3. **Don't register resolvers after mapping**
+   ```typescript
+   // ❌ BAD - resolver not available
+   const result = await mapper.map(data);
+   mapper.registerResolver('custom.transform', ...);  // Too late!
+   ```
+
+---
+
+## Comparison: Constructor vs Runtime Registration
+
+| Feature | Constructor Registration | Runtime Registration |
+|---------|------------------------|---------------------|
+| **When to use** | Resolvers known at creation | Resolvers depend on runtime |
+| **Context access** | ✅ Yes (via options) | ⚠️ Limited (no context in `map()` pattern) |
+| **Overwriting** | ❌ No (set once) | ✅ Yes (can overwrite) |
+| **Conditional** | ⚠️ Possible but awkward | ✅ Easy |
+| **Best for** | Production code | Dynamic/configurable resolvers |
+
+---
+
+## Related Documentation
+
+- [Error Handling Patterns](./error-handling-patterns.md) - How to handle resolver errors
+- [Mapper Comparison Guide](./mapping-mapper-comparison-guide.md) - Complete mapper comparison
+- [GraphQL Mutation Mapping](../graphql-mutation-mapping/) - GraphQLMutationMapper details
+- [Universal Mapping](./) - UniversalMapper details
+