@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/03-PATTERN-GUIDES/multiple-connections/modules/multiple-connections-04-parallel-queries.md

@@ -1,656 +1,656 @@
-# Module 4: Parallel Queries
-
-**Level:** Advanced
-**Estimated Time:** 30 minutes
-
-**SDK Version:** Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
-## Overview
-
-This module teaches you how to paginate multiple connections **simultaneously** using parallel queries with `Promise.all()`. This is the recommended workaround when all connections need full pagination.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Understand why parallel queries are the recommended approach
-- ✅ Implement `Promise.all()` patterns for multi-connection pagination
-- ✅ Handle errors and monitoring for parallel operations
-- ✅ Know when to use parallel vs sequential approaches
-- ✅ Optimize performance for bulk exports
-
-## Why Parallel Queries?
-
-### The Challenge
-
-```typescript
-// ❌ This won't work - can only target ONE connection
-const result = await client.graphql({
-  query: multiConnectionQuery,
-  pagination: {
-    connectionPath: ['products', 'locations']  // ← NOT SUPPORTED
-  }
-});
-```
-
-### The Solution
-
-```typescript
-// ✅ Use separate queries in parallel
-const [products, locations] = await Promise.all([
-  client.graphql({
-    query: productsQuery,
-    pagination: { maxPages: 10 }
-  }),
-  client.graphql({
-    query: locationsQuery,
-    pagination: { maxPages: 5 }
-  })
-]);
-```
-
-## Benefits of Parallel Queries
-
-| Aspect | Single Query | Parallel Queries |
-|--------|-------------|------------------|
-| **All connections paginated** | ❌ No | ✅ Yes |
-| **Independent limits** | ❌ Same for all | ✅ Different per connection |
-| **Progress tracking** | ⚠️ One callback | ✅ Separate callbacks |
-| **Error isolation** | ⚠️ All-or-nothing | ✅ Can handle individually |
-| **Performance** | ⚠️ Sequential | ✅ Parallel execution |
-| **Flexibility** | ⚠️ Limited | ✅ Full control |
-
-## Basic Parallel Query Pattern
-
-### Step 1: Define Separate Queries
-
-```typescript
-const productsQuery = `
-  query GetProducts($first: Int!, $after: String) {
-    products(first: $first, after: $after) {
-      edges {
-        node { id ref type status }
-        cursor
-      }
-      pageInfo { hasNextPage }
-    }
-  }
-`;
-
-const locationsQuery = `
-  query GetLocations($first: Int!, $after: String) {
-    locations(first: $first, after: $after) {
-      edges {
-        node { id ref name type }
-        cursor
-      }
-      pageInfo { hasNextPage }
-    }
-  }
-`;
-```
-
-### Step 2: Execute in Parallel
-
-```typescript
-const [productsResult, locationsResult] = await Promise.all([
-  client.graphql({
-    query: productsQuery,
-    variables: { first: 100 },
-    pagination: {
-      maxPages: 10,
-      maxRecords: 1000,
-      onProgress: (page, records) => {
-        console.log(`[Products] Page ${page}: ${records} records`);
-      }
-    }
-  }),
-  client.graphql({
-    query: locationsQuery,
-    variables: { first: 50 },
-    pagination: {
-      maxPages: 5,
-      maxRecords: 250,
-      onProgress: (page, records) => {
-        console.log(`[Locations] Page ${page}: ${records} records`);
-      }
-    }
-  })
-]);
-```
-
-### Step 3: Process Results
-
-```typescript
-// Access data from each result
-const products = productsResult.data.products.edges.map(e => e.node);
-const locations = locationsResult.data.locations.edges.map(e => e.node);
-
-// Check metadata
-console.log(`Products: ${productsResult.extensions.autoPagination.totalRecords} records`);
-console.log(`Locations: ${locationsResult.extensions.autoPagination.totalRecords} records`);
-
-// Combine if needed
-const combinedData = {
-  products,
-  locations,
-  metadata: {
-    productsPages: productsResult.extensions.autoPagination.totalPages,
-    locationsPages: locationsResult.extensions.autoPagination.totalPages
-  }
-};
-```
-
-## Real-World Examples
-
-### Example 1: Simple Dual Export
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-async function exportProductsAndLocations() {
-  const client = await createClient({
-    config: {
-      baseUrl: process.env.FLUENT_BASE_URL!,
-      clientId: process.env.FLUENT_CLIENT_ID!,
-      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-      username: process.env.FLUENT_USERNAME!,
-      password: process.env.FLUENT_PASSWORD!,
-      retailerId: process.env.FLUENT_RETAILER_ID!
-    }
-  });
-
-  console.log('Starting parallel export...\n');
-
-  const [products, locations] = await Promise.all([
-    client.graphql({
-      query: `
-        query GetProducts($first: Int!, $after: String) {
-          products(first: $first, after: $after) {
-            edges {
-              node { id ref type status }
-              cursor
-            }
-            pageInfo { hasNextPage }
-          }
-        }
-      `,
-      variables: { first: 100 },
-      pagination: {
-        maxPages: 10,
-        maxRecords: 1000,
-        onProgress: (page, records) => {
-          console.log(`[Products] Page ${page}: ${records} records`);
-        }
-      }
-    }),
-    client.graphql({
-      query: `
-        query GetLocations($first: Int!, $after: String) {
-          locations(first: $first, after: $after) {
-            edges {
-              node { id ref name type }
-              cursor
-            }
-            pageInfo { hasNextPage }
-          }
-        }
-      `,
-      variables: { first: 50 },
-      pagination: {
-        maxPages: 5,
-        maxRecords: 250,
-        onProgress: (page, records) => {
-          console.log(`[Locations] Page ${page}: ${records} records`);
-        }
-      }
-    })
-  ]);
-
-  console.log('\n✅ Export complete!');
-  console.log(`Products: ${products.extensions.autoPagination.totalRecords}`);
-  console.log(`Locations: ${locations.extensions.autoPagination.totalRecords}`);
-
-  return {
-    products: products.data.products.edges.map(e => e.node),
-    locations: locations.data.locations.edges.map(e => e.node)
-  };
-}
-
-// Run
-exportProductsAndLocations().catch(console.error);
-```
-
-**Output:**
-```
-Starting parallel export...
-
-[Products] Page 1: 100 records
-[Locations] Page 1: 50 records
-[Products] Page 2: 200 records
-[Locations] Page 2: 100 records
-[Products] Page 3: 300 records
-[Locations] Page 3: 150 records
-...
-
-✅ Export complete!
-Products: 873
-Locations: 234
-```
-
-### Example 2: Bulk Export (3+ Connections)
-
-```typescript
-async function bulkExport() {
-  const client = await createClient({ /* config */ });
-
-  console.log('Starting bulk export...\n');
-
-  const [products, locations, virtualPositions, orders] = await Promise.all([
-    client.graphql({
-      query: productsQuery,
-      variables: { first: 100 },
-      pagination: {
-        maxRecords: 5000,
-        onProgress: (p, r) => process.stdout.write(`\r[Products] ${r}`)
-      }
-    }),
-    client.graphql({
-      query: locationsQuery,
-      variables: { first: 50 },
-      pagination: {
-        maxRecords: 500,
-        onProgress: (p, r) => process.stdout.write(`\r[Locations] ${r}`)
-      }
-    }),
-    client.graphql({
-      query: virtualPositionsQuery,
-      variables: { first: 200 },
-      pagination: {
-        maxRecords: 10000,
-        onProgress: (p, r) => process.stdout.write(`\r[VirtualPos] ${r}`)
-      }
-    }),
-    client.graphql({
-      query: ordersQuery,
-      variables: { first: 75 },
-      pagination: {
-        maxRecords: 2000,
-        onProgress: (p, r) => process.stdout.write(`\r[Orders] ${r}`)
-      }
-    })
-  ]);
-
-  console.log('\n\n✅ Bulk export complete!');
-  console.log(`Products: ${products.extensions.autoPagination.totalRecords}`);
-  console.log(`Locations: ${locations.extensions.autoPagination.totalRecords}`);
-  console.log(`Virtual Positions: ${virtualPositions.extensions.autoPagination.totalRecords}`);
-  console.log(`Orders: ${orders.extensions.autoPagination.totalRecords}`);
-}
-```
-
-### Example 3: Sequential Processing (When Needed)
-
-Sometimes you need sequential execution (one after another):
-
-```typescript
-async function sequentialExport() {
-  const client = await createClient({ /* config */ });
-
-  // Step 1: Get all products first
-  console.log('Fetching products...');
-  const products = await client.graphql({
-    query: productsQuery,
-    variables: { first: 100 },
-    pagination: { maxPages: 10 }
-  });
-
-  console.log(`✅ Products: ${products.extensions.autoPagination.totalRecords}\n`);
-
-  // Step 2: Get locations (after products complete)
-  console.log('Fetching locations...');
-  const locations = await client.graphql({
-    query: locationsQuery,
-    variables: { first: 50 },
-    pagination: { maxPages: 5 }
-  });
-
-  console.log(`✅ Locations: ${locations.extensions.autoPagination.totalRecords}\n`);
-
-  // Step 3: Get virtual positions (after locations complete)
-  console.log('Fetching virtual positions...');
-  const virtualPositions = await client.graphql({
-    query: virtualPositionsQuery,
-    variables: { first: 200 },
-    pagination: { maxPages: 20 }
-  });
-
-  console.log(`✅ Virtual Positions: ${virtualPositions.extensions.autoPagination.totalRecords}`);
-
-  return { products, locations, virtualPositions };
-}
-```
-
-**Use Sequential When:**
-- ⚠️ API has strict rate limits
-- ⚠️ Memory constraints (large datasets)
-- ⚠️ One query depends on results of previous
-
-**Use Parallel When:**
-- ✅ Queries are independent
-- ✅ Want faster execution
-- ✅ Have sufficient memory/resources
-
-## Error Handling
-
-### Basic Error Handling
-
-```typescript
-try {
-  const [products, locations] = await Promise.all([
-    client.graphql({ query: productsQuery, pagination: { maxPages: 10 } }),
-    client.graphql({ query: locationsQuery, pagination: { maxPages: 5 } })
-  ]);
-
-  console.log('✅ Both queries succeeded');
-} catch (error) {
-  console.error('❌ At least one query failed:', error);
-  // Both results lost if one fails
-}
-```
-
-### Individual Error Handling with Promise.allSettled
-
-```typescript
-const results = await Promise.allSettled([
-  client.graphql({
-    query: productsQuery,
-    pagination: { maxPages: 10 }
-  }),
-  client.graphql({
-    query: locationsQuery,
-    pagination: { maxPages: 5 }
-  })
-]);
-
-// Process results individually
-results.forEach((result, index) => {
-  const name = index === 0 ? 'Products' : 'Locations';
-
-  if (result.status === 'fulfilled') {
-    const { totalRecords } = result.value.extensions.autoPagination;
-    console.log(`✅ ${name}: ${totalRecords} records`);
-  } else {
-    console.error(`❌ ${name} failed:`, result.reason);
-  }
-});
-
-// Extract successful results
-const products = results[0].status === 'fulfilled' ? results[0].value : null;
-const locations = results[1].status === 'fulfilled' ? results[1].value : null;
-```
-
-### Retry Failed Queries
-
-```typescript
-async function fetchWithRetry(queryFn: () => Promise<any>, maxRetries = 3) {
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    try {
-      return await queryFn();
-    } catch (error) {
-      if (attempt === maxRetries) throw error;
-      console.log(`⚠️ Attempt ${attempt} failed, retrying...`);
-      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
-    }
-  }
-}
-
-const [products, locations] = await Promise.all([
-  fetchWithRetry(() =>
-    client.graphql({
-      query: productsQuery,
-      pagination: { maxPages: 10 }
-    })
-  ),
-  fetchWithRetry(() =>
-    client.graphql({
-      query: locationsQuery,
-      pagination: { maxPages: 5 }
-    })
-  )
-]);
-```
-
-## Progress Monitoring
-
-### Aggregate Progress Tracking
-
-```typescript
-class ProgressTracker {
-  private progress: Map<string, { page: number; records: number }> = new Map();
-
-  update(name: string, page: number, records: number) {
-    this.progress.set(name, { page, records });
-    this.display();
-  }
-
-  display() {
-    process.stdout.write('\r'); // Clear line
-    const status = Array.from(this.progress.entries())
-      .map(([name, { page, records }]) => `${name}: ${records} (p${page})`)
-      .join(' | ');
-    process.stdout.write(status);
-  }
-}
-
-const tracker = new ProgressTracker();
-
-const [products, locations, virtualPositions] = await Promise.all([
-  client.graphql({
-    query: productsQuery,
-    pagination: {
-      maxPages: 10,
-      onProgress: (page, records) => tracker.update('Products', page, records)
-    }
-  }),
-  client.graphql({
-    query: locationsQuery,
-    pagination: {
-      maxPages: 5,
-      onProgress: (page, records) => tracker.update('Locations', page, records)
-    }
-  }),
-  client.graphql({
-    query: virtualPositionsQuery,
-    pagination: {
-      maxPages: 20,
-      onProgress: (page, records) => tracker.update('VirtualPos', page, records)
-    }
-  })
-]);
-
-console.log('\n✅ Complete!');
-```
-
-**Output:**
-```
-Products: 873 (p9) | Locations: 234 (p5) | VirtualPos: 1847 (p10)
-✅ Complete!
-```
-
-## Performance Optimization
-
-### Optimize Page Sizes
-
-Different entities have different optimal page sizes:
-
-```typescript
-const [products, locations, virtualPositions] = await Promise.all([
-  client.graphql({
-    query: productsQuery,
-    variables: { first: 50 },  // ← Medium complexity
-    pagination: { maxRecords: 5000 }
-  }),
-  client.graphql({
-    query: locationsQuery,
-    variables: { first: 100 },  // ← Simple entity
-    pagination: { maxRecords: 500 }
-  }),
-  client.graphql({
-    query: virtualPositionsQuery,
-    variables: { first: 200 },  // ← Very simple
-    pagination: { maxRecords: 10000 }
-  })
-]);
-```
-
-**Guidelines:**
-- Simple entities (locations, virtual positions): 100-200/page
-- Medium entities (products): 50-100/page
-- Complex entities (orders with items): 20-50/page
-
-### Connection Pooling
-
-Reuse client instances:
-
-```typescript
-// ✅ Good - reuse client
-const client = await createClient({ /* config */ });
-
-const [batch1, batch2, batch3] = await Promise.all([
-  client.graphql({ query: query1, pagination: { maxPages: 10 } }),
-  client.graphql({ query: query2, pagination: { maxPages: 5 } }),
-  client.graphql({ query: query3, pagination: { maxPages: 8 } })
-]);
-
-// ❌ Bad - create new client each time
-const results = await Promise.all([
-  createClient({ ... }).then(c => c.graphql({ ... })),
-  createClient({ ... }).then(c => c.graphql({ ... })),
-  createClient({ ... }).then(c => c.graphql({ ... }))
-]);
-```
-
-### Batch Size Limits
-
-Don't query too many connections at once:
-
-```typescript
-// ⚠️ Risky - 10 parallel queries
-const results = await Promise.all([...Array(10)].map(/* query */));
-
-// ✅ Better - chunk into batches
-async function queryInBatches(queries: any[], batchSize = 3) {
-  const results = [];
-  for (let i = 0; i < queries.length; i += batchSize) {
-    const batch = queries.slice(i, i + batchSize);
-    const batchResults = await Promise.all(batch.map(q => client.graphql(q)));
-    results.push(...batchResults);
-  }
-  return results;
-}
-```
-
-## Trade-offs: Parallel vs Single Query
-
-### Parallel Queries
-
-**Pros:**
-- ✅ All connections fully paginated
-- ✅ Independent limits per connection
-- ✅ Better error isolation
-- ✅ Faster execution (parallel)
-- ✅ Separate progress tracking
-
-**Cons:**
-- ⚠️ Multiple network requests
-- ⚠️ More code to write
-- ⚠️ Manual result combining
-- ⚠️ Higher initial resource usage
-
-### Single Query with connectionPath
-
-**Pros:**
-- ✅ Single network request
-- ✅ Less code to write
-- ✅ Atomic operation
-
-**Cons:**
-- ⚠️ Only one connection paginated
-- ⚠️ Other connections limited to first page
-- ⚠️ Single point of failure
-
-## Key Takeaways
-
-- 🎯 **Use `Promise.all()`** - For paginating multiple connections
-- 🎯 **Separate queries** - One query per connection
-- 🎯 **Independent configs** - Different limits per connection
-- 🎯 **Error handling** - Use `Promise.allSettled()` for resilience
-- 🎯 **Monitor individually** - Separate `onProgress` callbacks
-- 🎯 **Optimize page sizes** - Match entity complexity
-
-## Practice Exercise
-
-Implement a parallel export that:
-1. Fetches products (100/page, max 1000 records)
-2. Fetches locations (50/page, max 500 records)
-3. Fetches virtual positions (200/page, max 5000 records)
-4. Tracks progress for each
-5. Handles errors gracefully with `Promise.allSettled()`
-
-<details>
-<summary>Solution</summary>
-
-```typescript
-async function parallelExport() {
-  const client = await createClient({ /* config */ });
-
-  console.log('Starting parallel export...\n');
-
-  const results = await Promise.allSettled([
-    client.graphql({
-      query: productsQuery,
-      variables: { first: 100 },
-      pagination: {
-        maxRecords: 1000,
-        onProgress: (p, r) => console.log(`[Products] Page ${p}: ${r} records`)
-      }
-    }),
-    client.graphql({
-      query: locationsQuery,
-      variables: { first: 50 },
-      pagination: {
-        maxRecords: 500,
-        onProgress: (p, r) => console.log(`[Locations] Page ${p}: ${r} records`)
-      }
-    }),
-    client.graphql({
-      query: virtualPositionsQuery,
-      variables: { first: 200 },
-      pagination: {
-        maxRecords: 5000,
-        onProgress: (p, r) => console.log(`[VirtualPos] Page ${p}: ${r} records`)
-      }
-    })
-  ]);
-
-  const names = ['Products', 'Locations', 'VirtualPositions'];
-  results.forEach((result, index) => {
-    if (result.status === 'fulfilled') {
-      console.log(`✅ ${names[index]}: ${result.value.extensions.autoPagination.totalRecords}`);
-    } else {
-      console.error(`❌ ${names[index]} failed:`, result.reason.message);
-    }
-  });
-
-  return {
-    products: results[0].status === 'fulfilled' ? results[0].value.data.products : null,
-    locations: results[1].status === 'fulfilled' ? results[1].value.data.locations : null,
-    virtualPositions: results[2].status === 'fulfilled' ? results[2].value.data.virtualPositions : null
-  };
-}
-```
-</details>
-
-## Next Steps
-
-Continue to [Module 5: Best Practices](./multiple-connections-05-best-practices.md) to learn production patterns and optimization techniques.
+# Module 4: Parallel Queries
+
+**Level:** Advanced
+**Estimated Time:** 30 minutes
+
+**SDK Version:** Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+## Overview
+
+This module teaches you how to paginate multiple connections **simultaneously** using parallel queries with `Promise.all()`. This is the recommended workaround when all connections need full pagination.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Understand why parallel queries are the recommended approach
+- ✅ Implement `Promise.all()` patterns for multi-connection pagination
+- ✅ Handle errors and monitoring for parallel operations
+- ✅ Know when to use parallel vs sequential approaches
+- ✅ Optimize performance for bulk exports
+
+## Why Parallel Queries?
+
+### The Challenge
+
+```typescript
+// ❌ This won't work - can only target ONE connection
+const result = await client.graphql({
+  query: multiConnectionQuery,
+  pagination: {
+    connectionPath: ['products', 'locations']  // ← NOT SUPPORTED
+  }
+});
+```
+
+### The Solution
+
+```typescript
+// ✅ Use separate queries in parallel
+const [products, locations] = await Promise.all([
+  client.graphql({
+    query: productsQuery,
+    pagination: { maxPages: 10 }
+  }),
+  client.graphql({
+    query: locationsQuery,
+    pagination: { maxPages: 5 }
+  })
+]);
+```
+
+## Benefits of Parallel Queries
+
+| Aspect | Single Query | Parallel Queries |
+|--------|-------------|------------------|
+| **All connections paginated** | ❌ No | ✅ Yes |
+| **Independent limits** | ❌ Same for all | ✅ Different per connection |
+| **Progress tracking** | ⚠️ One callback | ✅ Separate callbacks |
+| **Error isolation** | ⚠️ All-or-nothing | ✅ Can handle individually |
+| **Performance** | ⚠️ Sequential | ✅ Parallel execution |
+| **Flexibility** | ⚠️ Limited | ✅ Full control |
+
+## Basic Parallel Query Pattern
+
+### Step 1: Define Separate Queries
+
+```typescript
+const productsQuery = `
+  query GetProducts($first: Int!, $after: String) {
+    products(first: $first, after: $after) {
+      edges {
+        node { id ref type status }
+        cursor
+      }
+      pageInfo { hasNextPage }
+    }
+  }
+`;
+
+const locationsQuery = `
+  query GetLocations($first: Int!, $after: String) {
+    locations(first: $first, after: $after) {
+      edges {
+        node { id ref name type }
+        cursor
+      }
+      pageInfo { hasNextPage }
+    }
+  }
+`;
+```
+
+### Step 2: Execute in Parallel
+
+```typescript
+const [productsResult, locationsResult] = await Promise.all([
+  client.graphql({
+    query: productsQuery,
+    variables: { first: 100 },
+    pagination: {
+      maxPages: 10,
+      maxRecords: 1000,
+      onProgress: (page, records) => {
+        console.log(`[Products] Page ${page}: ${records} records`);
+      }
+    }
+  }),
+  client.graphql({
+    query: locationsQuery,
+    variables: { first: 50 },
+    pagination: {
+      maxPages: 5,
+      maxRecords: 250,
+      onProgress: (page, records) => {
+        console.log(`[Locations] Page ${page}: ${records} records`);
+      }
+    }
+  })
+]);
+```
+
+### Step 3: Process Results
+
+```typescript
+// Access data from each result
+const products = productsResult.data.products.edges.map(e => e.node);
+const locations = locationsResult.data.locations.edges.map(e => e.node);
+
+// Check metadata
+console.log(`Products: ${productsResult.extensions.autoPagination.totalRecords} records`);
+console.log(`Locations: ${locationsResult.extensions.autoPagination.totalRecords} records`);
+
+// Combine if needed
+const combinedData = {
+  products,
+  locations,
+  metadata: {
+    productsPages: productsResult.extensions.autoPagination.totalPages,
+    locationsPages: locationsResult.extensions.autoPagination.totalPages
+  }
+};
+```
+
+## Real-World Examples
+
+### Example 1: Simple Dual Export
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+async function exportProductsAndLocations() {
+  const client = await createClient({
+    config: {
+      baseUrl: process.env.FLUENT_BASE_URL!,
+      clientId: process.env.FLUENT_CLIENT_ID!,
+      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+      username: process.env.FLUENT_USERNAME!,
+      password: process.env.FLUENT_PASSWORD!,
+      retailerId: process.env.FLUENT_RETAILER_ID!
+    }
+  });
+
+  console.log('Starting parallel export...\n');
+
+  const [products, locations] = await Promise.all([
+    client.graphql({
+      query: `
+        query GetProducts($first: Int!, $after: String) {
+          products(first: $first, after: $after) {
+            edges {
+              node { id ref type status }
+              cursor
+            }
+            pageInfo { hasNextPage }
+          }
+        }
+      `,
+      variables: { first: 100 },
+      pagination: {
+        maxPages: 10,
+        maxRecords: 1000,
+        onProgress: (page, records) => {
+          console.log(`[Products] Page ${page}: ${records} records`);
+        }
+      }
+    }),
+    client.graphql({
+      query: `
+        query GetLocations($first: Int!, $after: String) {
+          locations(first: $first, after: $after) {
+            edges {
+              node { id ref name type }
+              cursor
+            }
+            pageInfo { hasNextPage }
+          }
+        }
+      `,
+      variables: { first: 50 },
+      pagination: {
+        maxPages: 5,
+        maxRecords: 250,
+        onProgress: (page, records) => {
+          console.log(`[Locations] Page ${page}: ${records} records`);
+        }
+      }
+    })
+  ]);
+
+  console.log('\n✅ Export complete!');
+  console.log(`Products: ${products.extensions.autoPagination.totalRecords}`);
+  console.log(`Locations: ${locations.extensions.autoPagination.totalRecords}`);
+
+  return {
+    products: products.data.products.edges.map(e => e.node),
+    locations: locations.data.locations.edges.map(e => e.node)
+  };
+}
+
+// Run
+exportProductsAndLocations().catch(console.error);
+```
+
+**Output:**
+```
+Starting parallel export...
+
+[Products] Page 1: 100 records
+[Locations] Page 1: 50 records
+[Products] Page 2: 200 records
+[Locations] Page 2: 100 records
+[Products] Page 3: 300 records
+[Locations] Page 3: 150 records
+...
+
+✅ Export complete!
+Products: 873
+Locations: 234
+```
+
+### Example 2: Bulk Export (3+ Connections)
+
+```typescript
+async function bulkExport() {
+  const client = await createClient({ /* config */ });
+
+  console.log('Starting bulk export...\n');
+
+  const [products, locations, virtualPositions, orders] = await Promise.all([
+    client.graphql({
+      query: productsQuery,
+      variables: { first: 100 },
+      pagination: {
+        maxRecords: 5000,
+        onProgress: (p, r) => process.stdout.write(`\r[Products] ${r}`)
+      }
+    }),
+    client.graphql({
+      query: locationsQuery,
+      variables: { first: 50 },
+      pagination: {
+        maxRecords: 500,
+        onProgress: (p, r) => process.stdout.write(`\r[Locations] ${r}`)
+      }
+    }),
+    client.graphql({
+      query: virtualPositionsQuery,
+      variables: { first: 200 },
+      pagination: {
+        maxRecords: 10000,
+        onProgress: (p, r) => process.stdout.write(`\r[VirtualPos] ${r}`)
+      }
+    }),
+    client.graphql({
+      query: ordersQuery,
+      variables: { first: 75 },
+      pagination: {
+        maxRecords: 2000,
+        onProgress: (p, r) => process.stdout.write(`\r[Orders] ${r}`)
+      }
+    })
+  ]);
+
+  console.log('\n\n✅ Bulk export complete!');
+  console.log(`Products: ${products.extensions.autoPagination.totalRecords}`);
+  console.log(`Locations: ${locations.extensions.autoPagination.totalRecords}`);
+  console.log(`Virtual Positions: ${virtualPositions.extensions.autoPagination.totalRecords}`);
+  console.log(`Orders: ${orders.extensions.autoPagination.totalRecords}`);
+}
+```
+
+### Example 3: Sequential Processing (When Needed)
+
+Sometimes you need sequential execution (one after another):
+
+```typescript
+async function sequentialExport() {
+  const client = await createClient({ /* config */ });
+
+  // Step 1: Get all products first
+  console.log('Fetching products...');
+  const products = await client.graphql({
+    query: productsQuery,
+    variables: { first: 100 },
+    pagination: { maxPages: 10 }
+  });
+
+  console.log(`✅ Products: ${products.extensions.autoPagination.totalRecords}\n`);
+
+  // Step 2: Get locations (after products complete)
+  console.log('Fetching locations...');
+  const locations = await client.graphql({
+    query: locationsQuery,
+    variables: { first: 50 },
+    pagination: { maxPages: 5 }
+  });
+
+  console.log(`✅ Locations: ${locations.extensions.autoPagination.totalRecords}\n`);
+
+  // Step 3: Get virtual positions (after locations complete)
+  console.log('Fetching virtual positions...');
+  const virtualPositions = await client.graphql({
+    query: virtualPositionsQuery,
+    variables: { first: 200 },
+    pagination: { maxPages: 20 }
+  });
+
+  console.log(`✅ Virtual Positions: ${virtualPositions.extensions.autoPagination.totalRecords}`);
+
+  return { products, locations, virtualPositions };
+}
+```
+
+**Use Sequential When:**
+- ⚠️ API has strict rate limits
+- ⚠️ Memory constraints (large datasets)
+- ⚠️ One query depends on results of previous
+
+**Use Parallel When:**
+- ✅ Queries are independent
+- ✅ Want faster execution
+- ✅ Have sufficient memory/resources
+
+## Error Handling
+
+### Basic Error Handling
+
+```typescript
+try {
+  const [products, locations] = await Promise.all([
+    client.graphql({ query: productsQuery, pagination: { maxPages: 10 } }),
+    client.graphql({ query: locationsQuery, pagination: { maxPages: 5 } })
+  ]);
+
+  console.log('✅ Both queries succeeded');
+} catch (error) {
+  console.error('❌ At least one query failed:', error);
+  // Both results lost if one fails
+}
+```
+
+### Individual Error Handling with Promise.allSettled
+
+```typescript
+const results = await Promise.allSettled([
+  client.graphql({
+    query: productsQuery,
+    pagination: { maxPages: 10 }
+  }),
+  client.graphql({
+    query: locationsQuery,
+    pagination: { maxPages: 5 }
+  })
+]);
+
+// Process results individually
+results.forEach((result, index) => {
+  const name = index === 0 ? 'Products' : 'Locations';
+
+  if (result.status === 'fulfilled') {
+    const { totalRecords } = result.value.extensions.autoPagination;
+    console.log(`✅ ${name}: ${totalRecords} records`);
+  } else {
+    console.error(`❌ ${name} failed:`, result.reason);
+  }
+});
+
+// Extract successful results
+const products = results[0].status === 'fulfilled' ? results[0].value : null;
+const locations = results[1].status === 'fulfilled' ? results[1].value : null;
+```
+
+### Retry Failed Queries
+
+```typescript
+async function fetchWithRetry(queryFn: () => Promise<any>, maxRetries = 3) {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await queryFn();
+    } catch (error) {
+      if (attempt === maxRetries) throw error;
+      console.log(`⚠️ Attempt ${attempt} failed, retrying...`);
+      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
+    }
+  }
+}
+
+const [products, locations] = await Promise.all([
+  fetchWithRetry(() =>
+    client.graphql({
+      query: productsQuery,
+      pagination: { maxPages: 10 }
+    })
+  ),
+  fetchWithRetry(() =>
+    client.graphql({
+      query: locationsQuery,
+      pagination: { maxPages: 5 }
+    })
+  )
+]);
+```
+
+## Progress Monitoring
+
+### Aggregate Progress Tracking
+
+```typescript
+class ProgressTracker {
+  private progress: Map<string, { page: number; records: number }> = new Map();
+
+  update(name: string, page: number, records: number) {
+    this.progress.set(name, { page, records });
+    this.display();
+  }
+
+  display() {
+    process.stdout.write('\r'); // Clear line
+    const status = Array.from(this.progress.entries())
+      .map(([name, { page, records }]) => `${name}: ${records} (p${page})`)
+      .join(' | ');
+    process.stdout.write(status);
+  }
+}
+
+const tracker = new ProgressTracker();
+
+const [products, locations, virtualPositions] = await Promise.all([
+  client.graphql({
+    query: productsQuery,
+    pagination: {
+      maxPages: 10,
+      onProgress: (page, records) => tracker.update('Products', page, records)
+    }
+  }),
+  client.graphql({
+    query: locationsQuery,
+    pagination: {
+      maxPages: 5,
+      onProgress: (page, records) => tracker.update('Locations', page, records)
+    }
+  }),
+  client.graphql({
+    query: virtualPositionsQuery,
+    pagination: {
+      maxPages: 20,
+      onProgress: (page, records) => tracker.update('VirtualPos', page, records)
+    }
+  })
+]);
+
+console.log('\n✅ Complete!');
+```
+
+**Output:**
+```
+Products: 873 (p9) | Locations: 234 (p5) | VirtualPos: 1847 (p10)
+✅ Complete!
+```
+
+## Performance Optimization
+
+### Optimize Page Sizes
+
+Different entities have different optimal page sizes:
+
+```typescript
+const [products, locations, virtualPositions] = await Promise.all([
+  client.graphql({
+    query: productsQuery,
+    variables: { first: 50 },  // ← Medium complexity
+    pagination: { maxRecords: 5000 }
+  }),
+  client.graphql({
+    query: locationsQuery,
+    variables: { first: 100 },  // ← Simple entity
+    pagination: { maxRecords: 500 }
+  }),
+  client.graphql({
+    query: virtualPositionsQuery,
+    variables: { first: 200 },  // ← Very simple
+    pagination: { maxRecords: 10000 }
+  })
+]);
+```
+
+**Guidelines:**
+- Simple entities (locations, virtual positions): 100-200/page
+- Medium entities (products): 50-100/page
+- Complex entities (orders with items): 20-50/page
+
+### Connection Pooling
+
+Reuse client instances:
+
+```typescript
+// ✅ Good - reuse client
+const client = await createClient({ /* config */ });
+
+const [batch1, batch2, batch3] = await Promise.all([
+  client.graphql({ query: query1, pagination: { maxPages: 10 } }),
+  client.graphql({ query: query2, pagination: { maxPages: 5 } }),
+  client.graphql({ query: query3, pagination: { maxPages: 8 } })
+]);
+
+// ❌ Bad - create new client each time
+const results = await Promise.all([
+  createClient({ ... }).then(c => c.graphql({ ... })),
+  createClient({ ... }).then(c => c.graphql({ ... })),
+  createClient({ ... }).then(c => c.graphql({ ... }))
+]);
+```
+
+### Batch Size Limits
+
+Don't query too many connections at once:
+
+```typescript
+// ⚠️ Risky - 10 parallel queries
+const results = await Promise.all([...Array(10)].map(/* query */));
+
+// ✅ Better - chunk into batches
+async function queryInBatches(queries: any[], batchSize = 3) {
+  const results = [];
+  for (let i = 0; i < queries.length; i += batchSize) {
+    const batch = queries.slice(i, i + batchSize);
+    const batchResults = await Promise.all(batch.map(q => client.graphql(q)));
+    results.push(...batchResults);
+  }
+  return results;
+}
+```
+
+## Trade-offs: Parallel vs Single Query
+
+### Parallel Queries
+
+**Pros:**
+- ✅ All connections fully paginated
+- ✅ Independent limits per connection
+- ✅ Better error isolation
+- ✅ Faster execution (parallel)
+- ✅ Separate progress tracking
+
+**Cons:**
+- ⚠️ Multiple network requests
+- ⚠️ More code to write
+- ⚠️ Manual result combining
+- ⚠️ Higher initial resource usage
+
+### Single Query with connectionPath
+
+**Pros:**
+- ✅ Single network request
+- ✅ Less code to write
+- ✅ Atomic operation
+
+**Cons:**
+- ⚠️ Only one connection paginated
+- ⚠️ Other connections limited to first page
+- ⚠️ Single point of failure
+
+## Key Takeaways
+
+- 🎯 **Use `Promise.all()`** - For paginating multiple connections
+- 🎯 **Separate queries** - One query per connection
+- 🎯 **Independent configs** - Different limits per connection
+- 🎯 **Error handling** - Use `Promise.allSettled()` for resilience
+- 🎯 **Monitor individually** - Separate `onProgress` callbacks
+- 🎯 **Optimize page sizes** - Match entity complexity
+
+## Practice Exercise
+
+Implement a parallel export that:
+1. Fetches products (100/page, max 1000 records)
+2. Fetches locations (50/page, max 500 records)
+3. Fetches virtual positions (200/page, max 5000 records)
+4. Tracks progress for each
+5. Handles errors gracefully with `Promise.allSettled()`
+
+<details>
+<summary>Solution</summary>
+
+```typescript
+async function parallelExport() {
+  const client = await createClient({ /* config */ });
+
+  console.log('Starting parallel export...\n');
+
+  const results = await Promise.allSettled([
+    client.graphql({
+      query: productsQuery,
+      variables: { first: 100 },
+      pagination: {
+        maxRecords: 1000,
+        onProgress: (p, r) => console.log(`[Products] Page ${p}: ${r} records`)
+      }
+    }),
+    client.graphql({
+      query: locationsQuery,
+      variables: { first: 50 },
+      pagination: {
+        maxRecords: 500,
+        onProgress: (p, r) => console.log(`[Locations] Page ${p}: ${r} records`)
+      }
+    }),
+    client.graphql({
+      query: virtualPositionsQuery,
+      variables: { first: 200 },
+      pagination: {
+        maxRecords: 5000,
+        onProgress: (p, r) => console.log(`[VirtualPos] Page ${p}: ${r} records`)
+      }
+    })
+  ]);
+
+  const names = ['Products', 'Locations', 'VirtualPositions'];
+  results.forEach((result, index) => {
+    if (result.status === 'fulfilled') {
+      console.log(`✅ ${names[index]}: ${result.value.extensions.autoPagination.totalRecords}`);
+    } else {
+      console.error(`❌ ${names[index]} failed:`, result.reason.message);
+    }
+  });
+
+  return {
+    products: results[0].status === 'fulfilled' ? results[0].value.data.products : null,
+    locations: results[1].status === 'fulfilled' ? results[1].value.data.locations : null,
+    virtualPositions: results[2].status === 'fulfilled' ? results[2].value.data.virtualPositions : null
+  };
+}
+```
+</details>
+
+## Next Steps
+
+Continue to [Module 5: Best Practices](./multiple-connections-05-best-practices.md) to learn production patterns and optimization techniques.