@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/03-PATTERN-GUIDES/multiple-connections/modules/multiple-connections-03-targeting-connections.md

@@ -1,659 +1,659 @@
-# Module 3: Targeting Connections
-
-**Level:** Intermediate
-**Estimated Time:** 25 minutes
-
-**SDK Version:** Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
-## Overview
-
-This module dives deep into the `connectionPath` configuration option, teaching you how to precisely target connections in simple and complex query structures.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Master `connectionPath` syntax for all scenarios
-- ✅ Understand dot notation for nested connections
-- ✅ Know when auto-detection works vs when it fails
-- ✅ Handle edge cases with complex query structures
-- ✅ Debug connection path issues effectively
-
-## The connectionPath Option
-
-### Basic Syntax
-
-```typescript
-pagination: {
-  connectionPath: string,  // Path to target connection
-  // ... other options
-}
-```
-
-### Value Types
-
-| Type | Example | Use Case |
-|------|---------|----------|
-| Simple string | `'products'` | Root-level connection |
-| Dot notation | `'order.items'` | Nested connection |
-| Deep nesting | `'order.fulfilments.items'` | Multiple levels deep |
-
-## Root-Level Connections
-
-### Single Root Connection
-
-When query has one root connection, `connectionPath` is optional:
-
-```typescript
-const query = `
-  query GetProducts($first: Int!, $after: String) {
-    products(first: $first, after: $after) {
-      edges { node { id } cursor }
-      pageInfo { hasNextPage }
-    }
-  }
-`;
-
-// ✅ Auto-detection works
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  // No connectionPath needed - only one connection
-});
-
-// ✅ Explicit also works
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: { connectionPath: 'products' }
-});
-```
-
-### Multiple Root Connections
-
-When query has multiple root connections, **always use `connectionPath`**:
-
-```typescript
-const query = `
-  query GetMultiple($first: Int!, $after: String) {
-    products(first: $first, after: $after) {
-      edges { node { id } cursor }
-      pageInfo { hasNextPage }
-    }
-    locations(first: $first, after: $after) {
-      edges { node { id } cursor }
-      pageInfo { hasNextPage }
-    }
-    virtualPositions(first: $first, after: $after) {
-      edges { node { id } cursor }
-      pageInfo { hasNextPage }
-    }
-  }
-`;
-
-// ✅ Explicit - paginate products
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: { connectionPath: 'products', maxPages: 10 }
-});
-
-// ✅ Explicit - paginate locations
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: { connectionPath: 'locations', maxPages: 5 }
-});
-
-// ⚠️ Risky - auto-detection picks first connection
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  // Which connection? Unpredictable!
-});
-```
-
-## Nested Connections
-
-### One Level Deep
-
-```typescript
-const query = `
-  query GetOrderItems($orderId: ID!, $first: Int!, $after: String) {
-    order(id: $orderId) {
-      id
-      ref
-      items(first: $first, after: $after) {
-        edges {
-          node { id sku quantity }
-          cursor
-        }
-        pageInfo { hasNextPage }
-      }
-    }
-  }
-`;
-
-const result = await client.graphql({
-  query,
-  variables: { orderId: '123', first: 25 },
-  pagination: {
-    connectionPath: 'order.items',  // ← Dot notation
-    maxPages: 10
-  }
-});
-
-console.log(`Order has ${result.data.order.items.edges.length} items`);
-```
-
-### Multiple Levels Deep
-
-```typescript
-const query = `
-  query GetFulfilmentItems(
-    $orderId: ID!,
-    $fulfilmentId: ID!,
-    $first: Int!,
-    $after: String
-  ) {
-    order(id: $orderId) {
-      id
-      ref
-      fulfilments(first: 10) {
-        edges {
-          node {
-            id
-            ref
-            items(first: $first, after: $after) {
-              edges {
-                node { id sku quantity }
-                cursor
-              }
-              pageInfo { hasNextPage }
-            }
-          }
-        }
-      }
-    }
-  }
-`;
-
-const result = await client.graphql({
-  query,
-  variables: { orderId: '123', fulfilmentId: '456', first: 20 },
-  pagination: {
-    connectionPath: 'order.fulfilments.edges.node.items',  // ← Deep path
-    maxPages: 5
-  }
-});
-```
-
-**Note:** You may need to include `edges.node` in the path depending on the query structure.
-
-### Simplified Deep Path
-
-The SDK is smart about traversing edges and nodes:
-
-```typescript
-// These are equivalent:
-connectionPath: 'order.fulfilments.edges.node.items'
-connectionPath: 'order.fulfilments.items'  // SDK infers edges/node
-```
-
-**Best Practice:** Use the **simplified form** unless you encounter issues.
-
-## Auto-Detection Behavior
-
-### How Auto-Detection Works
-
-When `connectionPath` is **not specified**, the SDK:
-
-1. Receives GraphQL response
-2. Recursively searches for connection structure
-3. Looks for objects with: `edges`, `pageInfo.hasNextPage`
-4. Uses **first match found**
-
-### Auto-Detection Search Order
-
-```typescript
-const query = `
-  query MultiLevel {
-    products { ... }      # ← Checked first
-    locations { ... }     # ← Checked second
-    nested {
-      items { ... }       # ← Checked third
-    }
-  }
-`;
-```
-
-**Order:** Depth-first search, typically matches query field order.
-
-### When Auto-Detection Fails
-
-#### Case 1: No Connection Structure
-
-```typescript
-const query = `
-  query GetProduct($id: ID!) {
-    product(id: $id) {
-      id
-      ref
-      name
-    }
-  }
-`;
-
-// ❌ No edges/pageInfo - auto-detection finds nothing
-```
-
-#### Case 2: Non-Standard Structure
-
-```typescript
-const query = `
-  query CustomStructure {
-    products {
-      items {          # ← Not 'edges'
-        data { id }    # ← Not 'node'
-      }
-      pagination {     # ← Not 'pageInfo'
-        hasMore
-      }
-    }
-  }
-`;
-
-// ❌ Doesn't match Relay spec - auto-detection fails
-```
-
-#### Case 3: Multiple Connections (Ambiguous)
-
-```typescript
-const query = `
-  query GetMultiple {
-    products { edges { ... } pageInfo { ... } }
-    locations { edges { ... } pageInfo { ... } }
-  }
-`;
-
-// ⚠️ Auto-detection picks 'products' (first found)
-// But which did you intend? Ambiguous!
-```
-
-## Advanced Targeting Scenarios
-
-### Scenario 1: Pagination Variables Don't Match Connection
-
-```typescript
-const query = `
-  query GetProductsAndLocations(
-    $pFirst: Int!,      # ← Different variable names
-    $pAfter: String,
-    $lFirst: Int!,
-    $lAfter: String
-  ) {
-    products(first: $pFirst, after: $pAfter) {
-      edges { node { id } cursor }
-      pageInfo { hasNextPage }
-    }
-    locations(first: $lFirst, after: $lAfter) {
-      edges { node { id } cursor }
-      pageInfo { hasNextPage }
-    }
-  }
-`;
-
-// ✅ connectionPath still works - it targets response structure
-const result = await client.graphql({
-  query,
-  variables: { pFirst: 50, lFirst: 20 },
-  pagination: {
-    connectionPath: 'products',  // Works regardless of variable names
-    maxPages: 5
-  }
-});
-```
-
-### Scenario 2: Aliased Fields
-
-```typescript
-const query = `
-  query GetAliased($first: Int!, $after: String) {
-    allProducts: products(first: $first, after: $after) {
-      edges { node { id } cursor }
-      pageInfo { hasNextPage }
-    }
-    allLocations: locations(first: $first) {
-      edges { node { id } cursor }
-      pageInfo { hasNextPage }
-    }
-  }
-`;
-
-// ✅ Use the ALIAS name in connectionPath
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: {
-    connectionPath: 'allProducts',  // ← Use alias, not 'products'
-    maxPages: 10
-  }
-});
-
-console.log(result.data.allProducts.edges.length);  // Access via alias
-```
-
-### Scenario 3: Mixed Paginated and Non-Paginated
-
-```typescript
-const query = `
-  query GetMixed($first: Int!, $after: String) {
-    # Paginated connection
-    products(first: $first, after: $after) {
-      edges { node { id } cursor }
-      pageInfo { hasNextPage }
-    }
-
-    # Non-paginated scalar
-    totalProductCount
-
-    # Non-paginated object
-    retailer {
-      id
-      name
-    }
-
-    # Another paginated connection
-    locations(first: $first, after: $after) {
-      edges { node { id } cursor }
-      pageInfo { hasNextPage }
-    }
-  }
-`;
-
-// ✅ SDK only looks at connections, ignores scalars/objects
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: {
-    connectionPath: 'products',  // Targets products, ignores non-connections
-    maxPages: 5
-  }
-});
-```
-
-### Scenario 4: Fragments
-
-```typescript
-const query = `
-  fragment ProductFields on Product {
-    id
-    ref
-    type
-  }
-
-  query GetProducts($first: Int!, $after: String) {
-    products(first: $first, after: $after) {
-      edges {
-        node {
-          ...ProductFields
-        }
-        cursor
-      }
-      pageInfo { hasNextPage }
-    }
-  }
-`;
-
-// ✅ Fragments don't affect connectionPath
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: {
-    connectionPath: 'products',  // Works normally
-    maxPages: 10
-  }
-});
-```
-
-## Debugging Connection Paths
-
-### Technique 1: Enable Debug Logging
-
-```typescript
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: {
-    connectionPath: 'products',
-    maxPages: 2,
-    onProgress: (page, records) => {
-      console.log(`[DEBUG] Page ${page}: ${records} records`);
-      // If this fires, connectionPath is working
-    }
-  }
-});
-```
-
-### Technique 2: Inspect Response Structure
-
-```typescript
-const result = await client.graphql({
-  query,
-  variables: { first: 100 }
-  // No pagination first - see structure
-});
-
-console.log('Response keys:', Object.keys(result.data));
-// Output: ['products', 'locations']
-
-console.log('Products structure:', {
-  hasEdges: !!result.data.products.edges,
-  hasPageInfo: !!result.data.products.pageInfo,
-  edgesCount: result.data.products.edges?.length
-});
-```
-
-### Technique 3: Test with Small Limits
-
-```typescript
-// Start with maxPages: 2 to verify behavior
-const result = await client.graphql({
-  query,
-  variables: { first: 10 },
-  pagination: {
-    connectionPath: 'products',
-    maxPages: 2  // ← Small limit for testing
-  }
-});
-
-// Expected: 20 records (2 pages × 10 per page)
-console.assert(
-  result.data.products.edges.length === 20,
-  'Expected 20 records'
-);
-```
-
-### Technique 4: Try Auto-Detection First
-
-```typescript
-// Remove connectionPath to see what SDK finds
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: { maxPages: 2 }
-  // Let SDK auto-detect
-});
-
-// Check which connection has 200 records
-console.log('Products:', result.data.products?.edges?.length);
-console.log('Locations:', result.data.locations?.edges?.length);
-// Whichever has 200 was auto-detected
-```
-
-## Common Mistakes and Fixes
-
-### Mistake 1: Wrong Path Depth
-
-```typescript
-// ❌ Wrong - too shallow
-connectionPath: 'order'
-
-// ✅ Correct - include full path to connection
-connectionPath: 'order.items'
-```
-
-### Mistake 2: Using Field Name Instead of Alias
-
-```typescript
-const query = `
-  query {
-    myProducts: products(...) { ... }
-  }
-`;
-
-// ❌ Wrong
-connectionPath: 'products'
-
-// ✅ Correct
-connectionPath: 'myProducts'
-```
-
-### Mistake 3: Including edges/node When Not Needed
-
-```typescript
-// ❌ Overly verbose
-connectionPath: 'products.edges.node'
-
-// ✅ Simplified (SDK handles it)
-connectionPath: 'products'
-```
-
-### Mistake 4: Array Syntax (Not Supported)
-
-```typescript
-// ❌ Wrong - arrays not supported
-connectionPath: ['products', 'locations']
-
-// ✅ Correct - target one
-connectionPath: 'products'
-```
-
-## Best Practices
-
-### ✅ DO: Always Be Explicit
-
-```typescript
-// ✅ Good
-pagination: {
-  connectionPath: 'products',
-  maxPages: 10
-}
-```
-
-### ✅ DO: Use Simplified Paths
-
-```typescript
-// ✅ Good
-connectionPath: 'order.items'
-
-// ❌ Overly complex
-connectionPath: 'order.edges.node.items.edges.node'
-```
-
-### ✅ DO: Match Aliases Exactly
-
-```typescript
-const query = `myProducts: products(...) { ... }`;
-
-// ✅ Good
-connectionPath: 'myProducts'
-```
-
-### ❌ DON'T: Rely on Auto-Detection for Multiple Connections
-
-```typescript
-// ❌ Bad - which connection?
-const result = await client.graphql({
-  query: multiConnectionQuery,
-  pagination: { maxPages: 5 }
-});
-
-// ✅ Good - explicit
-const result = await client.graphql({
-  query: multiConnectionQuery,
-  pagination: {
-    connectionPath: 'products',
-    maxPages: 5
-  }
-});
-```
-
-## Key Takeaways
-
-- 🎯 **Use `connectionPath`** - Always for multiple connections
-- 🎯 **Dot notation for nesting** - `'order.items'` works
-- 🎯 **Simplified paths** - SDK infers `edges` and `node`
-- 🎯 **Match aliases** - Use alias names, not original field names
-- 🎯 **Test small first** - Verify with `maxPages: 2` before production
-
-## Practice Exercise
-
-Given this query, write the correct `connectionPath` for each scenario:
-
-```graphql
-query ComplexQuery {
-  retailer {
-    id
-    name
-  }
-  allProducts: products(first: 50, after: $cursor) {
-    edges {
-      node { id ref }
-      cursor
-    }
-    pageInfo { hasNextPage }
-  }
-  order(id: "123") {
-    id
-    ref
-    fulfilments {
-      edges {
-        node {
-          id
-          items(first: 20) {
-            edges {
-              node { id sku }
-              cursor
-            }
-            pageInfo { hasNextPage }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-**Questions:**
-1. Paginate the products connection
-2. Paginate the fulfilment items
-
-<details>
-<summary>Answers</summary>
-
-1. **Paginate products:**
-```typescript
-connectionPath: 'allProducts'  // Use alias name
-```
-
-2. **Paginate fulfilment items:**
-```typescript
-connectionPath: 'order.fulfilments.items'  // Simplified path
-// OR
-connectionPath: 'order.fulfilments.edges.node.items'  // Explicit path
-```
-</details>
-
-## Next Steps
-
-Continue to [Module 4: Parallel Queries](./multiple-connections-04-parallel-queries.md) to learn how to paginate multiple connections simultaneously using `Promise.all()`.
+# Module 3: Targeting Connections
+
+**Level:** Intermediate
+**Estimated Time:** 25 minutes
+
+**SDK Version:** Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+## Overview
+
+This module dives deep into the `connectionPath` configuration option, teaching you how to precisely target connections in simple and complex query structures.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Master `connectionPath` syntax for all scenarios
+- ✅ Understand dot notation for nested connections
+- ✅ Know when auto-detection works vs when it fails
+- ✅ Handle edge cases with complex query structures
+- ✅ Debug connection path issues effectively
+
+## The connectionPath Option
+
+### Basic Syntax
+
+```typescript
+pagination: {
+  connectionPath: string,  // Path to target connection
+  // ... other options
+}
+```
+
+### Value Types
+
+| Type | Example | Use Case |
+|------|---------|----------|
+| Simple string | `'products'` | Root-level connection |
+| Dot notation | `'order.items'` | Nested connection |
+| Deep nesting | `'order.fulfilments.items'` | Multiple levels deep |
+
+## Root-Level Connections
+
+### Single Root Connection
+
+When query has one root connection, `connectionPath` is optional:
+
+```typescript
+const query = `
+  query GetProducts($first: Int!, $after: String) {
+    products(first: $first, after: $after) {
+      edges { node { id } cursor }
+      pageInfo { hasNextPage }
+    }
+  }
+`;
+
+// ✅ Auto-detection works
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  // No connectionPath needed - only one connection
+});
+
+// ✅ Explicit also works
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: { connectionPath: 'products' }
+});
+```
+
+### Multiple Root Connections
+
+When query has multiple root connections, **always use `connectionPath`**:
+
+```typescript
+const query = `
+  query GetMultiple($first: Int!, $after: String) {
+    products(first: $first, after: $after) {
+      edges { node { id } cursor }
+      pageInfo { hasNextPage }
+    }
+    locations(first: $first, after: $after) {
+      edges { node { id } cursor }
+      pageInfo { hasNextPage }
+    }
+    virtualPositions(first: $first, after: $after) {
+      edges { node { id } cursor }
+      pageInfo { hasNextPage }
+    }
+  }
+`;
+
+// ✅ Explicit - paginate products
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: { connectionPath: 'products', maxPages: 10 }
+});
+
+// ✅ Explicit - paginate locations
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: { connectionPath: 'locations', maxPages: 5 }
+});
+
+// ⚠️ Risky - auto-detection picks first connection
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  // Which connection? Unpredictable!
+});
+```
+
+## Nested Connections
+
+### One Level Deep
+
+```typescript
+const query = `
+  query GetOrderItems($orderId: ID!, $first: Int!, $after: String) {
+    order(id: $orderId) {
+      id
+      ref
+      items(first: $first, after: $after) {
+        edges {
+          node { id sku quantity }
+          cursor
+        }
+        pageInfo { hasNextPage }
+      }
+    }
+  }
+`;
+
+const result = await client.graphql({
+  query,
+  variables: { orderId: '123', first: 25 },
+  pagination: {
+    connectionPath: 'order.items',  // ← Dot notation
+    maxPages: 10
+  }
+});
+
+console.log(`Order has ${result.data.order.items.edges.length} items`);
+```
+
+### Multiple Levels Deep
+
+```typescript
+const query = `
+  query GetFulfilmentItems(
+    $orderId: ID!,
+    $fulfilmentId: ID!,
+    $first: Int!,
+    $after: String
+  ) {
+    order(id: $orderId) {
+      id
+      ref
+      fulfilments(first: 10) {
+        edges {
+          node {
+            id
+            ref
+            items(first: $first, after: $after) {
+              edges {
+                node { id sku quantity }
+                cursor
+              }
+              pageInfo { hasNextPage }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+
+const result = await client.graphql({
+  query,
+  variables: { orderId: '123', fulfilmentId: '456', first: 20 },
+  pagination: {
+    connectionPath: 'order.fulfilments.edges.node.items',  // ← Deep path
+    maxPages: 5
+  }
+});
+```
+
+**Note:** You may need to include `edges.node` in the path depending on the query structure.
+
+### Simplified Deep Path
+
+The SDK is smart about traversing edges and nodes:
+
+```typescript
+// These are equivalent:
+connectionPath: 'order.fulfilments.edges.node.items'
+connectionPath: 'order.fulfilments.items'  // SDK infers edges/node
+```
+
+**Best Practice:** Use the **simplified form** unless you encounter issues.
+
+## Auto-Detection Behavior
+
+### How Auto-Detection Works
+
+When `connectionPath` is **not specified**, the SDK:
+
+1. Receives GraphQL response
+2. Recursively searches for connection structure
+3. Looks for objects with: `edges`, `pageInfo.hasNextPage`
+4. Uses **first match found**
+
+### Auto-Detection Search Order
+
+```typescript
+const query = `
+  query MultiLevel {
+    products { ... }      # ← Checked first
+    locations { ... }     # ← Checked second
+    nested {
+      items { ... }       # ← Checked third
+    }
+  }
+`;
+```
+
+**Order:** Depth-first search, typically matches query field order.
+
+### When Auto-Detection Fails
+
+#### Case 1: No Connection Structure
+
+```typescript
+const query = `
+  query GetProduct($id: ID!) {
+    product(id: $id) {
+      id
+      ref
+      name
+    }
+  }
+`;
+
+// ❌ No edges/pageInfo - auto-detection finds nothing
+```
+
+#### Case 2: Non-Standard Structure
+
+```typescript
+const query = `
+  query CustomStructure {
+    products {
+      items {          # ← Not 'edges'
+        data { id }    # ← Not 'node'
+      }
+      pagination {     # ← Not 'pageInfo'
+        hasMore
+      }
+    }
+  }
+`;
+
+// ❌ Doesn't match Relay spec - auto-detection fails
+```
+
+#### Case 3: Multiple Connections (Ambiguous)
+
+```typescript
+const query = `
+  query GetMultiple {
+    products { edges { ... } pageInfo { ... } }
+    locations { edges { ... } pageInfo { ... } }
+  }
+`;
+
+// ⚠️ Auto-detection picks 'products' (first found)
+// But which did you intend? Ambiguous!
+```
+
+## Advanced Targeting Scenarios
+
+### Scenario 1: Pagination Variables Don't Match Connection
+
+```typescript
+const query = `
+  query GetProductsAndLocations(
+    $pFirst: Int!,      # ← Different variable names
+    $pAfter: String,
+    $lFirst: Int!,
+    $lAfter: String
+  ) {
+    products(first: $pFirst, after: $pAfter) {
+      edges { node { id } cursor }
+      pageInfo { hasNextPage }
+    }
+    locations(first: $lFirst, after: $lAfter) {
+      edges { node { id } cursor }
+      pageInfo { hasNextPage }
+    }
+  }
+`;
+
+// ✅ connectionPath still works - it targets response structure
+const result = await client.graphql({
+  query,
+  variables: { pFirst: 50, lFirst: 20 },
+  pagination: {
+    connectionPath: 'products',  // Works regardless of variable names
+    maxPages: 5
+  }
+});
+```
+
+### Scenario 2: Aliased Fields
+
+```typescript
+const query = `
+  query GetAliased($first: Int!, $after: String) {
+    allProducts: products(first: $first, after: $after) {
+      edges { node { id } cursor }
+      pageInfo { hasNextPage }
+    }
+    allLocations: locations(first: $first) {
+      edges { node { id } cursor }
+      pageInfo { hasNextPage }
+    }
+  }
+`;
+
+// ✅ Use the ALIAS name in connectionPath
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: {
+    connectionPath: 'allProducts',  // ← Use alias, not 'products'
+    maxPages: 10
+  }
+});
+
+console.log(result.data.allProducts.edges.length);  // Access via alias
+```
+
+### Scenario 3: Mixed Paginated and Non-Paginated
+
+```typescript
+const query = `
+  query GetMixed($first: Int!, $after: String) {
+    # Paginated connection
+    products(first: $first, after: $after) {
+      edges { node { id } cursor }
+      pageInfo { hasNextPage }
+    }
+
+    # Non-paginated scalar
+    totalProductCount
+
+    # Non-paginated object
+    retailer {
+      id
+      name
+    }
+
+    # Another paginated connection
+    locations(first: $first, after: $after) {
+      edges { node { id } cursor }
+      pageInfo { hasNextPage }
+    }
+  }
+`;
+
+// ✅ SDK only looks at connections, ignores scalars/objects
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: {
+    connectionPath: 'products',  // Targets products, ignores non-connections
+    maxPages: 5
+  }
+});
+```
+
+### Scenario 4: Fragments
+
+```typescript
+const query = `
+  fragment ProductFields on Product {
+    id
+    ref
+    type
+  }
+
+  query GetProducts($first: Int!, $after: String) {
+    products(first: $first, after: $after) {
+      edges {
+        node {
+          ...ProductFields
+        }
+        cursor
+      }
+      pageInfo { hasNextPage }
+    }
+  }
+`;
+
+// ✅ Fragments don't affect connectionPath
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: {
+    connectionPath: 'products',  // Works normally
+    maxPages: 10
+  }
+});
+```
+
+## Debugging Connection Paths
+
+### Technique 1: Enable Debug Logging
+
+```typescript
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: {
+    connectionPath: 'products',
+    maxPages: 2,
+    onProgress: (page, records) => {
+      console.log(`[DEBUG] Page ${page}: ${records} records`);
+      // If this fires, connectionPath is working
+    }
+  }
+});
+```
+
+### Technique 2: Inspect Response Structure
+
+```typescript
+const result = await client.graphql({
+  query,
+  variables: { first: 100 }
+  // No pagination first - see structure
+});
+
+console.log('Response keys:', Object.keys(result.data));
+// Output: ['products', 'locations']
+
+console.log('Products structure:', {
+  hasEdges: !!result.data.products.edges,
+  hasPageInfo: !!result.data.products.pageInfo,
+  edgesCount: result.data.products.edges?.length
+});
+```
+
+### Technique 3: Test with Small Limits
+
+```typescript
+// Start with maxPages: 2 to verify behavior
+const result = await client.graphql({
+  query,
+  variables: { first: 10 },
+  pagination: {
+    connectionPath: 'products',
+    maxPages: 2  // ← Small limit for testing
+  }
+});
+
+// Expected: 20 records (2 pages × 10 per page)
+console.assert(
+  result.data.products.edges.length === 20,
+  'Expected 20 records'
+);
+```
+
+### Technique 4: Try Auto-Detection First
+
+```typescript
+// Remove connectionPath to see what SDK finds
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: { maxPages: 2 }
+  // Let SDK auto-detect
+});
+
+// Check which connection has 200 records
+console.log('Products:', result.data.products?.edges?.length);
+console.log('Locations:', result.data.locations?.edges?.length);
+// Whichever has 200 was auto-detected
+```
+
+## Common Mistakes and Fixes
+
+### Mistake 1: Wrong Path Depth
+
+```typescript
+// ❌ Wrong - too shallow
+connectionPath: 'order'
+
+// ✅ Correct - include full path to connection
+connectionPath: 'order.items'
+```
+
+### Mistake 2: Using Field Name Instead of Alias
+
+```typescript
+const query = `
+  query {
+    myProducts: products(...) { ... }
+  }
+`;
+
+// ❌ Wrong
+connectionPath: 'products'
+
+// ✅ Correct
+connectionPath: 'myProducts'
+```
+
+### Mistake 3: Including edges/node When Not Needed
+
+```typescript
+// ❌ Overly verbose
+connectionPath: 'products.edges.node'
+
+// ✅ Simplified (SDK handles it)
+connectionPath: 'products'
+```
+
+### Mistake 4: Array Syntax (Not Supported)
+
+```typescript
+// ❌ Wrong - arrays not supported
+connectionPath: ['products', 'locations']
+
+// ✅ Correct - target one
+connectionPath: 'products'
+```
+
+## Best Practices
+
+### ✅ DO: Always Be Explicit
+
+```typescript
+// ✅ Good
+pagination: {
+  connectionPath: 'products',
+  maxPages: 10
+}
+```
+
+### ✅ DO: Use Simplified Paths
+
+```typescript
+// ✅ Good
+connectionPath: 'order.items'
+
+// ❌ Overly complex
+connectionPath: 'order.edges.node.items.edges.node'
+```
+
+### ✅ DO: Match Aliases Exactly
+
+```typescript
+const query = `myProducts: products(...) { ... }`;
+
+// ✅ Good
+connectionPath: 'myProducts'
+```
+
+### ❌ DON'T: Rely on Auto-Detection for Multiple Connections
+
+```typescript
+// ❌ Bad - which connection?
+const result = await client.graphql({
+  query: multiConnectionQuery,
+  pagination: { maxPages: 5 }
+});
+
+// ✅ Good - explicit
+const result = await client.graphql({
+  query: multiConnectionQuery,
+  pagination: {
+    connectionPath: 'products',
+    maxPages: 5
+  }
+});
+```
+
+## Key Takeaways
+
+- 🎯 **Use `connectionPath`** - Always for multiple connections
+- 🎯 **Dot notation for nesting** - `'order.items'` works
+- 🎯 **Simplified paths** - SDK infers `edges` and `node`
+- 🎯 **Match aliases** - Use alias names, not original field names
+- 🎯 **Test small first** - Verify with `maxPages: 2` before production
+
+## Practice Exercise
+
+Given this query, write the correct `connectionPath` for each scenario:
+
+```graphql
+query ComplexQuery {
+  retailer {
+    id
+    name
+  }
+  allProducts: products(first: 50, after: $cursor) {
+    edges {
+      node { id ref }
+      cursor
+    }
+    pageInfo { hasNextPage }
+  }
+  order(id: "123") {
+    id
+    ref
+    fulfilments {
+      edges {
+        node {
+          id
+          items(first: 20) {
+            edges {
+              node { id sku }
+              cursor
+            }
+            pageInfo { hasNextPage }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Questions:**
+1. Paginate the products connection
+2. Paginate the fulfilment items
+
+<details>
+<summary>Answers</summary>
+
+1. **Paginate products:**
+```typescript
+connectionPath: 'allProducts'  // Use alias name
+```
+
+2. **Paginate fulfilment items:**
+```typescript
+connectionPath: 'order.fulfilments.items'  // Simplified path
+// OR
+connectionPath: 'order.fulfilments.edges.node.items'  // Explicit path
+```
+</details>
+
+## Next Steps
+
+Continue to [Module 4: Parallel Queries](./multiple-connections-04-parallel-queries.md) to learn how to paginate multiple connections simultaneously using `Promise.all()`.