@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/extraction/extraction-quick-reference.md

@@ -1,596 +1,596 @@
-# Extraction Quick Reference
-
-> **One-page cheat sheet for data extraction patterns**
-
-## ExtractionOrchestrator Pattern (Recommended)
-
-```typescript
-import { createClient, ExtractionOrchestrator } from '@fluentcommerce/fc-connect-sdk';
-
-const client = await createClient({ config });
-const orchestrator = new ExtractionOrchestrator(client, console);
-
-const result = await orchestrator.extract({
-  query: `
-    query ExtractData($first: Int!, $after: String) {
-      inventoryPositions(first: $first, after: $after) {
-        edges {
-          node { id ref qty }
-          cursor
-        }
-        pageInfo { hasNextPage }
-      }
-    }
-  `,
-  resultPath: 'inventoryPositions.edges.node',
-  pageSize: 100,
-  maxRecords: 10000
-});
-
-// Access extracted data directly
-console.log(`Extracted ${result.data.length} records`);
-console.log(`Stats:`, result.stats);
-```
-
-## Manual Extraction Pattern (For Advanced Control)
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-const client = await createClient({ config });
-
-const result = await client.graphql({
-  query: `
-    query ExtractData($first: Int!, $after: String) {
-      inventoryPositions(first: $first, after: $after) {
-        edges {
-          node { id ref qty }
-          cursor
-        }
-        pageInfo { hasNextPage }
-      }
-    }
-  `,
-  variables: { first: 100 },
-  pagination: { maxRecords: 10000 },
-});
-
-// Manual extraction from edges
-const records = result.data.inventoryPositions.edges.map(e => e.node);
-```
-
-## Common Entity Queries
-
-### Inventory Positions
-
-```typescript
-query ExtractInventory($first: Int!, $after: String) {
-  inventoryPositions(first: $first, after: $after) {
-    edges {
-      node {
-        id ref productRef locationRef qty status
-        createdOn updatedOn
-      }
-      cursor
-    }
-    pageInfo { hasNextPage }
-  }
-}
-```
-
-### Virtual Positions
-
-```typescript
-query ExtractVirtualPositions($first: Int!, $after: String) {
-  virtualPositions(first: $first, after: $after) {
-    edges {
-      node {
-        id ref productRef groupRef quantity status
-        createdOn updatedOn
-      }
-      cursor
-    }
-    pageInfo { hasNextPage }
-  }
-}
-```
-
-### Products with Relations
-
-```typescript
-query ExtractProducts($first: Int!, $after: String) {
-  products(first: $first, after: $after) {
-    edges {
-      node {
-        id ref name gtin description
-        catalogue { ref name }
-        attributes { name value type }
-      }
-      cursor
-    }
-    pageInfo { hasNextPage }
-  }
-}
-```
-
-### Orders with Items
-
-```typescript
-query ExtractOrders($first: Int!, $after: String) {
-  orders(first: $first, after: $after) {
-    edges {
-      node {
-        id ref type status totalPrice currency
-        customer { ref email firstName lastName }
-        items {
-          edges {
-            node { ref productRef quantity price }
-          }
-        }
-      }
-      cursor
-    }
-    pageInfo { hasNextPage }
-  }
-}
-```
-
-## Parquet Processing
-
-### Read Parquet from S3
-
-```typescript
-import { S3DataSource, ParquetParserService } from '@fluentcommerce/fc-connect-sdk';
-
-const s3 = new S3DataSource(s3Config);
-const parser = new ParquetParserService(logger);
-
-const buffer = await s3.downloadFile('file.parquet', { encoding: 'binary' });
-const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
-
-const { records, stats } = await parser.parse(arrayBuffer, 'file.parquet', {
-  validation: {
-    enabled: true,
-    requiredColumns: ['id', 'ref', 'qty'],
-  },
-});
-```
-
-### Stream Large Parquet Files
-
-```typescript
-const streamResult = await parser.parseStreaming(arrayBuffer, 'large.parquet', {
-  batchSize: 5000,
-});
-
-for await (const batch of streamResult.records) {
-  for (const record of batch) {
-    // Process each record
-    await processRecord(record);
-  }
-}
-```
-
-## Data Enrichment
-
-### Batch Enrichment
-
-```typescript
-async function enrichBatch(records: any[], batchSize = 50) {
-  const enriched = [];
-
-  for (let i = 0; i < records.length; i += batchSize) {
-    const batch = records.slice(i, i + batchSize);
-    const refs = batch.map(r => r.ref);
-
-    const result = await client.graphql({
-      query: `
-        query BatchEnrichment($refs: [String!]!) {
-          products(filter: { ref: { in: $refs } }, first: ${batchSize}) {
-            edges {
-              node {
-                ref name catalogue { ref name }
-              }
-            }
-          }
-        }
-      `,
-      variables: { refs },
-    });
-
-    const productMap = new Map(result.data.products.edges.map(e => [e.node.ref, e.node]));
-
-    enriched.push(
-      ...batch.map(record => ({
-        ...record,
-        ...(productMap.get(record.ref) || {}),
-      }))
-    );
-  }
-
-  return enriched;
-}
-```
-
-### Single Record Enrichment
-
-```typescript
-async function enrichRecord(record: any) {
-  const result = await client.graphql({
-    query: `
-      query GetProduct($ref: String!) {
-        product(ref: $ref) {
-          ref name gtin
-          catalogue { ref name }
-          attributes { name value }
-        }
-      }
-    `,
-    variables: { ref: record.productRef },
-  });
-
-  return {
-    ...record,
-    product: result.data.product,
-  };
-}
-```
-
-## Data Transformation
-
-### UniversalMapper
-
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const mapper = new UniversalMapper({
-  fields: {
-    sku: { source: 'productRef', required: true },
-    warehouse: { source: 'locationRef', required: true },
-    quantity: { source: 'qty', resolver: 'sdk.parseInt' },
-    status: { source: 'status', resolver: 'sdk.lowercase' },
-    productName: { source: 'product.name' },
-    lastUpdated: { source: 'updatedOn', resolver: 'sdk.formatDate' },
-  },
-});
-
-const result = await mapper.map(records);
-
-if (!result.success) {
-  console.error('Errors:', result.errors);
-}
-```
-
-### Custom Transformer
-
-```typescript
-class CustomTransformer {
-  transform(records: any[]): any[] {
-    return records.map(record => ({
-      sku: record.productRef,
-      warehouse: record.locationRef,
-      available_quantity: parseInt(record.qty) || 0,
-      status: this.mapStatus(record.status),
-      last_updated: record.updatedOn || new Date().toISOString(),
-    }));
-  }
-
-  private mapStatus(status: string): string {
-    const statusMap = {
-      AVAILABLE: 'in_stock',
-      OUT_OF_STOCK: 'out_of_stock',
-    };
-    return statusMap[status] || status.toLowerCase();
-  }
-}
-```
-
-## Export Formats
-
-### JSON Export
-
-```typescript
-import { S3DataSource } from '@fluentcommerce/fc-connect-sdk';
-
-const s3 = new S3DataSource(s3Config);
-
-await s3.uploadFile('output.json', JSON.stringify(data, null, 2), { contentType: 'application/json' });
-```
-
-### JSONL Streaming Export
-
-```typescript
-const jsonl = data.map(record => JSON.stringify(record)).join('\n');
-
-await s3.uploadFile('output.jsonl', jsonl, { contentType: 'application/x-ndjson' });
-```
-
-### CSV Export
-
-```typescript
-import { stringify } from 'csv-stringify/sync';
-
-const csv = stringify(data, {
-  header: true,
-  columns: ['sku', 'warehouse', 'quantity', 'status'],
-});
-
-await s3.uploadFile('output.csv', csv, { contentType: 'text/csv' });
-```
-
-### Parquet Export
-
-```typescript
-import { ParquetWriter } from 'parquetjs';
-
-const schema = new ParquetSchema({
-  sku: { type: 'UTF8' },
-  warehouse: { type: 'UTF8' },
-  quantity: { type: 'INT32' },
-  status: { type: 'UTF8' },
-});
-
-const writer = await ParquetWriter.openFile(schema, 'output.parquet');
-
-for (const record of data) {
-  await writer.appendRow(record);
-}
-
-await writer.close();
-```
-
-## Delta Extraction
-
-```typescript
-import { StateService } from '@fluentcommerce/fc-connect-sdk';
-
-async function extractDelta(entityType: string) {
-  const state = new StateService(kvAdapter);
-
-  // Get last extraction time
-  const lastExtraction = await state.get(`lastExtraction_${entityType}`);
-  const fromDate = lastExtraction || new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
-
-  // Query only changed records
-  const result = await client.graphql({
-    query: `
-      query DeltaExtraction($fromDate: DateTime!, $toDate: DateTime!) {
-        inventoryPositions(
-          updatedOn: { from: $fromDate, to: $toDate }
-          first: 100
-        ) {
-          edges {
-            node { id ref qty status updatedOn }
-            cursor
-          }
-          pageInfo { hasNextPage }
-        }
-      }
-    `,
-    variables: {
-      fromDate,
-      toDate: new Date().toISOString(),
-    },
-    pagination: { maxRecords: 50000 },
-  });
-
-  // Update last extraction timestamp
-  await state.set(`lastExtraction_${entityType}`, new Date().toISOString());
-
-  return result.data.inventoryPositions.edges.map(e => e.node);
-}
-```
-
-## Streaming Extraction
-
-```typescript
-async function* streamExtraction(query: string, pageSize = 100) {
-  let hasNextPage = true;
-  let cursor = null;
-
-  while (hasNextPage) {
-    const result = await client.graphql({
-      query,
-      variables: { first: pageSize, after: cursor },
-    });
-
-    const edges = result.data.inventoryPositions.edges;
-    yield edges.map(e => e.node);
-
-    hasNextPage = result.data.inventoryPositions.pageInfo.hasNextPage;
-    cursor = edges[edges.length - 1]?.cursor;
-  }
-}
-
-// Usage
-for await (const batch of streamExtraction(query)) {
-  await processBatch(batch);
-}
-```
-
-## Parallel Extraction
-
-```typescript
-async function extractInParallel(queries: Array<{ name: string; query: string }>) {
-  const results = await Promise.all(
-    queries.map(async ({ name, query }) => {
-      const result = await client.graphql({ query });
-      return { name, data: result.data };
-    })
-  );
-
-  return Object.fromEntries(results.map(({ name, data }) => [name, data]));
-}
-
-// Usage
-const data = await extractInParallel([
-  { name: 'inventory', query: inventoryQuery },
-  { name: 'products', query: productsQuery },
-  { name: 'locations', query: locationsQuery },
-]);
-```
-
-## Error Handling
-
-### Retry with Exponential Backoff
-
-```typescript
-async function extractWithRetry(operation: () => Promise<any>, maxRetries = 3) {
-  let lastError;
-
-  for (let i = 0; i < maxRetries; i++) {
-    try {
-      return await operation();
-    } catch (error) {
-      lastError = error;
-      await sleep(Math.pow(2, i) * 1000);
-    }
-  }
-
-  throw lastError;
-}
-```
-
-### Validation
-
-```typescript
-function validateExtraction(result: any): boolean {
-  if (!result.data) {
-    throw new Error('No data in response');
-  }
-
-  if (result.errors?.length > 0) {
-    throw new Error(`GraphQL errors: ${JSON.stringify(result.errors)}`);
-  }
-
-  return true;
-}
-```
-
-## Performance Optimization
-
-### Caching
-
-```typescript
-const cache = new Map<string, { data: any; expiry: number }>();
-
-async function getWithCache(key: string, fetcher: () => Promise<any>, ttl = 3600000) {
-  const cached = cache.get(key);
-
-  if (cached && cached.expiry > Date.now()) {
-    return cached.data;
-  }
-
-  const data = await fetcher();
-
-  cache.set(key, {
-    data,
-    expiry: Date.now() + ttl,
-  });
-
-  return data;
-}
-```
-
-### Field Selection Optimization
-
-```typescript
-// ❌ BAD: Fetch all fields (large payload)
-query GetProducts {
-  products(first: 100) {
-    edges {
-      node {
-        id ref name description gtin
-        catalogue { ... }
-        attributes { ... }
-        categories { ... }
-      }
-    }
-  }
-}
-
-// ✅ GOOD: Fetch only needed fields
-query GetProducts {
-  products(first: 100) {
-    edges {
-      node {
-        ref
-        name
-      }
-    }
-  }
-}
-```
-
-## ExtractionOrchestrator Advanced Patterns
-
-### With Validation
-
-```typescript
-const result = await orchestrator.extract({
-  query: inventoryQuery,
-  resultPath: 'inventoryPositions.edges.node',
-  pageSize: 200,
-  maxRecords: 50000,
-
-  // Validate each item during extraction
-  validateItem: (item) => {
-    return item.ref && item.productRef && typeof item.qty === 'number' && item.qty >= 0;
-  }
-});
-
-console.log(`Valid: ${result.stats.validRecords}, Invalid: ${result.stats.invalidRecords}`);
-```
-
-### With Extraction Limits
-
-```typescript
-const result = await orchestrator.extract({
-  query: largeDatasetQuery,
-  resultPath: 'data.edges.node',
-  maxRecords: 100000,  // Stop after 100K records
-  maxPages: 200,       // OR stop after 200 pages
-  timeout: 300000      // 5 minute timeout
-});
-
-if (result.stats.truncated) {
-  console.log(`Extraction truncated: ${result.stats.truncationReason}`);
-}
-```
-
-### With Variables
-
-```typescript
-const result = await orchestrator.extract({
-  query: orderQuery,
-  resultPath: 'orders.edges.node',
-  variables: {
-    startDate: '2025-01-01T00:00:00Z',
-    status: 'COMPLETE'
-  },
-  pageSize: 100
-});
-```
-
-## Common Patterns Summary
-
-| Pattern                    | Use Case                          | Complexity | Recommended Approach         |
-| -------------------------- | --------------------------------- | ---------- | ---------------------------- |
-| Basic Extraction           | Simple data retrieval             | Low        | ExtractionOrchestrator       |
-| Extraction with Validation | Data quality checks               | Low        | ExtractionOrchestrator       |
-| Parquet Processing         | Large file processing             | Medium     | ParquetParserService         |
-| Batch Enrichment           | Add related data efficiently      | Medium     | Manual GraphQL               |
-| Delta Extraction           | Incremental sync                  | Medium     | StateService + Orchestrator  |
-| Streaming                  | Large datasets, memory efficiency | High       | Manual GraphQL with iterator |
-| Parallel Extraction        | Multiple entity types at once     | High       | Promise.all + Orchestrator   |
-| Custom Transformation      | Complex business logic            | High       | UniversalMapper              |
-
-## Links
-
-- [Module 1: Foundations](../auto-pagination/modules/auto-pagination-01-foundations.md)
-- [Module 2: Basic Extraction](./modules/02-core-guides-extraction-02-basic-extraction.md)
-- [Module 3: Parquet Processing](./modules/02-core-guides-extraction-03-parquet-processing.md)
-- [Module 4: Data Enrichment](./modules/02-core-guides-extraction-04-data-enrichment.md)
-- [Module 5: Data Transformation](./modules/02-core-guides-extraction-05-transformation.md)
-- [Module 6: Export Formats](./modules/02-core-guides-extraction-06-export-formats.md)
-- [Module 7: Optimization](./modules/02-core-guides-extraction-07-optimization.md)
+# Extraction Quick Reference
+
+> **One-page cheat sheet for data extraction patterns**
+
+## ExtractionOrchestrator Pattern (Recommended)
+
+```typescript
+import { createClient, ExtractionOrchestrator } from '@fluentcommerce/fc-connect-sdk';
+
+const client = await createClient({ config });
+const orchestrator = new ExtractionOrchestrator(client, console);
+
+const result = await orchestrator.extract({
+  query: `
+    query ExtractData($first: Int!, $after: String) {
+      inventoryPositions(first: $first, after: $after) {
+        edges {
+          node { id ref qty }
+          cursor
+        }
+        pageInfo { hasNextPage }
+      }
+    }
+  `,
+  resultPath: 'inventoryPositions.edges.node',
+  pageSize: 100,
+  maxRecords: 10000
+});
+
+// Access extracted data directly
+console.log(`Extracted ${result.data.length} records`);
+console.log(`Stats:`, result.stats);
+```
+
+## Manual Extraction Pattern (For Advanced Control)
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+const client = await createClient({ config });
+
+const result = await client.graphql({
+  query: `
+    query ExtractData($first: Int!, $after: String) {
+      inventoryPositions(first: $first, after: $after) {
+        edges {
+          node { id ref qty }
+          cursor
+        }
+        pageInfo { hasNextPage }
+      }
+    }
+  `,
+  variables: { first: 100 },
+  pagination: { maxRecords: 10000 },
+});
+
+// Manual extraction from edges
+const records = result.data.inventoryPositions.edges.map(e => e.node);
+```
+
+## Common Entity Queries
+
+### Inventory Positions
+
+```typescript
+query ExtractInventory($first: Int!, $after: String) {
+  inventoryPositions(first: $first, after: $after) {
+    edges {
+      node {
+        id ref productRef locationRef qty status
+        createdOn updatedOn
+      }
+      cursor
+    }
+    pageInfo { hasNextPage }
+  }
+}
+```
+
+### Virtual Positions
+
+```typescript
+query ExtractVirtualPositions($first: Int!, $after: String) {
+  virtualPositions(first: $first, after: $after) {
+    edges {
+      node {
+        id ref productRef groupRef quantity status
+        createdOn updatedOn
+      }
+      cursor
+    }
+    pageInfo { hasNextPage }
+  }
+}
+```
+
+### Products with Relations
+
+```typescript
+query ExtractProducts($first: Int!, $after: String) {
+  products(first: $first, after: $after) {
+    edges {
+      node {
+        id ref name gtin description
+        catalogue { ref name }
+        attributes { name value type }
+      }
+      cursor
+    }
+    pageInfo { hasNextPage }
+  }
+}
+```
+
+### Orders with Items
+
+```typescript
+query ExtractOrders($first: Int!, $after: String) {
+  orders(first: $first, after: $after) {
+    edges {
+      node {
+        id ref type status totalPrice currency
+        customer { ref email firstName lastName }
+        items {
+          edges {
+            node { ref productRef quantity price }
+          }
+        }
+      }
+      cursor
+    }
+    pageInfo { hasNextPage }
+  }
+}
+```
+
+## Parquet Processing
+
+### Read Parquet from S3
+
+```typescript
+import { S3DataSource, ParquetParserService } from '@fluentcommerce/fc-connect-sdk';
+
+const s3 = new S3DataSource(s3Config);
+const parser = new ParquetParserService(logger);
+
+const buffer = await s3.downloadFile('file.parquet', { encoding: 'binary' });
+const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+
+const { records, stats } = await parser.parse(arrayBuffer, 'file.parquet', {
+  validation: {
+    enabled: true,
+    requiredColumns: ['id', 'ref', 'qty'],
+  },
+});
+```
+
+### Stream Large Parquet Files
+
+```typescript
+const streamResult = await parser.parseStreaming(arrayBuffer, 'large.parquet', {
+  batchSize: 5000,
+});
+
+for await (const batch of streamResult.records) {
+  for (const record of batch) {
+    // Process each record
+    await processRecord(record);
+  }
+}
+```
+
+## Data Enrichment
+
+### Batch Enrichment
+
+```typescript
+async function enrichBatch(records: any[], batchSize = 50) {
+  const enriched = [];
+
+  for (let i = 0; i < records.length; i += batchSize) {
+    const batch = records.slice(i, i + batchSize);
+    const refs = batch.map(r => r.ref);
+
+    const result = await client.graphql({
+      query: `
+        query BatchEnrichment($refs: [String!]!) {
+          products(filter: { ref: { in: $refs } }, first: ${batchSize}) {
+            edges {
+              node {
+                ref name catalogue { ref name }
+              }
+            }
+          }
+        }
+      `,
+      variables: { refs },
+    });
+
+    const productMap = new Map(result.data.products.edges.map(e => [e.node.ref, e.node]));
+
+    enriched.push(
+      ...batch.map(record => ({
+        ...record,
+        ...(productMap.get(record.ref) || {}),
+      }))
+    );
+  }
+
+  return enriched;
+}
+```
+
+### Single Record Enrichment
+
+```typescript
+async function enrichRecord(record: any) {
+  const result = await client.graphql({
+    query: `
+      query GetProduct($ref: String!) {
+        product(ref: $ref) {
+          ref name gtin
+          catalogue { ref name }
+          attributes { name value }
+        }
+      }
+    `,
+    variables: { ref: record.productRef },
+  });
+
+  return {
+    ...record,
+    product: result.data.product,
+  };
+}
+```
+
+## Data Transformation
+
+### UniversalMapper
+
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const mapper = new UniversalMapper({
+  fields: {
+    sku: { source: 'productRef', required: true },
+    warehouse: { source: 'locationRef', required: true },
+    quantity: { source: 'qty', resolver: 'sdk.parseInt' },
+    status: { source: 'status', resolver: 'sdk.lowercase' },
+    productName: { source: 'product.name' },
+    lastUpdated: { source: 'updatedOn', resolver: 'sdk.formatDate' },
+  },
+});
+
+const result = await mapper.map(records);
+
+if (!result.success) {
+  console.error('Errors:', result.errors);
+}
+```
+
+### Custom Transformer
+
+```typescript
+class CustomTransformer {
+  transform(records: any[]): any[] {
+    return records.map(record => ({
+      sku: record.productRef,
+      warehouse: record.locationRef,
+      available_quantity: parseInt(record.qty) || 0,
+      status: this.mapStatus(record.status),
+      last_updated: record.updatedOn || new Date().toISOString(),
+    }));
+  }
+
+  private mapStatus(status: string): string {
+    const statusMap = {
+      AVAILABLE: 'in_stock',
+      OUT_OF_STOCK: 'out_of_stock',
+    };
+    return statusMap[status] || status.toLowerCase();
+  }
+}
+```
+
+## Export Formats
+
+### JSON Export
+
+```typescript
+import { S3DataSource } from '@fluentcommerce/fc-connect-sdk';
+
+const s3 = new S3DataSource(s3Config);
+
+await s3.uploadFile('output.json', JSON.stringify(data, null, 2), { contentType: 'application/json' });
+```
+
+### JSONL Streaming Export
+
+```typescript
+const jsonl = data.map(record => JSON.stringify(record)).join('\n');
+
+await s3.uploadFile('output.jsonl', jsonl, { contentType: 'application/x-ndjson' });
+```
+
+### CSV Export
+
+```typescript
+import { stringify } from 'csv-stringify/sync';
+
+const csv = stringify(data, {
+  header: true,
+  columns: ['sku', 'warehouse', 'quantity', 'status'],
+});
+
+await s3.uploadFile('output.csv', csv, { contentType: 'text/csv' });
+```
+
+### Parquet Export
+
+```typescript
+import { ParquetWriter } from 'parquetjs';
+
+const schema = new ParquetSchema({
+  sku: { type: 'UTF8' },
+  warehouse: { type: 'UTF8' },
+  quantity: { type: 'INT32' },
+  status: { type: 'UTF8' },
+});
+
+const writer = await ParquetWriter.openFile(schema, 'output.parquet');
+
+for (const record of data) {
+  await writer.appendRow(record);
+}
+
+await writer.close();
+```
+
+## Delta Extraction
+
+```typescript
+import { StateService } from '@fluentcommerce/fc-connect-sdk';
+
+async function extractDelta(entityType: string) {
+  const state = new StateService(kvAdapter);
+
+  // Get last extraction time
+  const lastExtraction = await state.get(`lastExtraction_${entityType}`);
+  const fromDate = lastExtraction || new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+
+  // Query only changed records
+  const result = await client.graphql({
+    query: `
+      query DeltaExtraction($fromDate: DateTime!, $toDate: DateTime!) {
+        inventoryPositions(
+          updatedOn: { from: $fromDate, to: $toDate }
+          first: 100
+        ) {
+          edges {
+            node { id ref qty status updatedOn }
+            cursor
+          }
+          pageInfo { hasNextPage }
+        }
+      }
+    `,
+    variables: {
+      fromDate,
+      toDate: new Date().toISOString(),
+    },
+    pagination: { maxRecords: 50000 },
+  });
+
+  // Update last extraction timestamp
+  await state.set(`lastExtraction_${entityType}`, new Date().toISOString());
+
+  return result.data.inventoryPositions.edges.map(e => e.node);
+}
+```
+
+## Streaming Extraction
+
+```typescript
+async function* streamExtraction(query: string, pageSize = 100) {
+  let hasNextPage = true;
+  let cursor = null;
+
+  while (hasNextPage) {
+    const result = await client.graphql({
+      query,
+      variables: { first: pageSize, after: cursor },
+    });
+
+    const edges = result.data.inventoryPositions.edges;
+    yield edges.map(e => e.node);
+
+    hasNextPage = result.data.inventoryPositions.pageInfo.hasNextPage;
+    cursor = edges[edges.length - 1]?.cursor;
+  }
+}
+
+// Usage
+for await (const batch of streamExtraction(query)) {
+  await processBatch(batch);
+}
+```
+
+## Parallel Extraction
+
+```typescript
+async function extractInParallel(queries: Array<{ name: string; query: string }>) {
+  const results = await Promise.all(
+    queries.map(async ({ name, query }) => {
+      const result = await client.graphql({ query });
+      return { name, data: result.data };
+    })
+  );
+
+  return Object.fromEntries(results.map(({ name, data }) => [name, data]));
+}
+
+// Usage
+const data = await extractInParallel([
+  { name: 'inventory', query: inventoryQuery },
+  { name: 'products', query: productsQuery },
+  { name: 'locations', query: locationsQuery },
+]);
+```
+
+## Error Handling
+
+### Retry with Exponential Backoff
+
+```typescript
+async function extractWithRetry(operation: () => Promise<any>, maxRetries = 3) {
+  let lastError;
+
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+      await sleep(Math.pow(2, i) * 1000);
+    }
+  }
+
+  throw lastError;
+}
+```
+
+### Validation
+
+```typescript
+function validateExtraction(result: any): boolean {
+  if (!result.data) {
+    throw new Error('No data in response');
+  }
+
+  if (result.errors?.length > 0) {
+    throw new Error(`GraphQL errors: ${JSON.stringify(result.errors)}`);
+  }
+
+  return true;
+}
+```
+
+## Performance Optimization
+
+### Caching
+
+```typescript
+const cache = new Map<string, { data: any; expiry: number }>();
+
+async function getWithCache(key: string, fetcher: () => Promise<any>, ttl = 3600000) {
+  const cached = cache.get(key);
+
+  if (cached && cached.expiry > Date.now()) {
+    return cached.data;
+  }
+
+  const data = await fetcher();
+
+  cache.set(key, {
+    data,
+    expiry: Date.now() + ttl,
+  });
+
+  return data;
+}
+```
+
+### Field Selection Optimization
+
+```typescript
+// ❌ BAD: Fetch all fields (large payload)
+query GetProducts {
+  products(first: 100) {
+    edges {
+      node {
+        id ref name description gtin
+        catalogue { ... }
+        attributes { ... }
+        categories { ... }
+      }
+    }
+  }
+}
+
+// ✅ GOOD: Fetch only needed fields
+query GetProducts {
+  products(first: 100) {
+    edges {
+      node {
+        ref
+        name
+      }
+    }
+  }
+}
+```
+
+## ExtractionOrchestrator Advanced Patterns
+
+### With Validation
+
+```typescript
+const result = await orchestrator.extract({
+  query: inventoryQuery,
+  resultPath: 'inventoryPositions.edges.node',
+  pageSize: 200,
+  maxRecords: 50000,
+
+  // Validate each item during extraction
+  validateItem: (item) => {
+    return item.ref && item.productRef && typeof item.qty === 'number' && item.qty >= 0;
+  }
+});
+
+console.log(`Valid: ${result.stats.validRecords}, Invalid: ${result.stats.invalidRecords}`);
+```
+
+### With Extraction Limits
+
+```typescript
+const result = await orchestrator.extract({
+  query: largeDatasetQuery,
+  resultPath: 'data.edges.node',
+  maxRecords: 100000,  // Stop after 100K records
+  maxPages: 200,       // OR stop after 200 pages
+  timeout: 300000      // 5 minute timeout
+});
+
+if (result.stats.truncated) {
+  console.log(`Extraction truncated: ${result.stats.truncationReason}`);
+}
+```
+
+### With Variables
+
+```typescript
+const result = await orchestrator.extract({
+  query: orderQuery,
+  resultPath: 'orders.edges.node',
+  variables: {
+    startDate: '2025-01-01T00:00:00Z',
+    status: 'COMPLETE'
+  },
+  pageSize: 100
+});
+```
+
+## Common Patterns Summary
+
+| Pattern                    | Use Case                          | Complexity | Recommended Approach         |
+| -------------------------- | --------------------------------- | ---------- | ---------------------------- |
+| Basic Extraction           | Simple data retrieval             | Low        | ExtractionOrchestrator       |
+| Extraction with Validation | Data quality checks               | Low        | ExtractionOrchestrator       |
+| Parquet Processing         | Large file processing             | Medium     | ParquetParserService         |
+| Batch Enrichment           | Add related data efficiently      | Medium     | Manual GraphQL               |
+| Delta Extraction           | Incremental sync                  | Medium     | StateService + Orchestrator  |
+| Streaming                  | Large datasets, memory efficiency | High       | Manual GraphQL with iterator |
+| Parallel Extraction        | Multiple entity types at once     | High       | Promise.all + Orchestrator   |
+| Custom Transformation      | Complex business logic            | High       | UniversalMapper              |
+
+## Links
+
+- [Module 1: Foundations](../auto-pagination/modules/auto-pagination-01-foundations.md)
+- [Module 2: Basic Extraction](./modules/02-core-guides-extraction-02-basic-extraction.md)
+- [Module 3: Parquet Processing](./modules/02-core-guides-extraction-03-parquet-processing.md)
+- [Module 4: Data Enrichment](./modules/02-core-guides-extraction-04-data-enrichment.md)
+- [Module 5: Data Transformation](./modules/02-core-guides-extraction-05-transformation.md)
+- [Module 6: Export Formats](./modules/02-core-guides-extraction-06-export-formats.md)
+- [Module 7: Optimization](./modules/02-core-guides-extraction-07-optimization.md)