@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/parsers/modules/02-core-guides-parsers-03-json-parser.md

@@ -1,789 +1,789 @@
-# Module 3: JSON Parser
-
-**Level:** Beginner
-**Estimated Time:** 25 minutes
-
-## Overview
-
-This module covers the JSON Parser (`JSONParserService`), essential for processing API responses, webhooks, and modern data formats. You'll learn how to parse JSON and JSONL, extract nested data, handle large files with streaming, and validate data structures.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Parse JSON and JSONL (JSON Lines) formats
-- ✅ Extract nested data with path queries
-- ✅ Stream large JSON files efficiently
-- ✅ Validate JSON against schemas
-- ✅ Parse and transform dates automatically
-- ✅ Integrate with SDK transformation services
-
-## What is JSON?
-
-**JSON (JavaScript Object Notation)** is a lightweight data format that:
-- Supports nested objects and arrays
-- Uses key-value pairs
-- Includes native types: string, number, boolean, null
-- Is the standard format for modern APIs
-
-**Example:**
-```json
-{
-  "products": [
-    {
-      "sku": "SKU001",
-      "name": "Wireless Mouse",
-      "price": 29.99,
-      "stock": {
-        "qty": 150,
-        "locations": ["WH-01", "WH-02"]
-      }
-    }
-  ]
-}
-```
-
-## Basic JSON Parsing
-
-### Simple Parsing
-
-```typescript
-import { JSONParserService } from '@fluentcommerce/fc-connect-sdk';
-
-const jsonParser = new JSONParserService();
-
-// Sample JSON data
-const jsonContent = `{
-  "products": [
-    {
-      "sku": "SKU001",
-      "name": "Wireless Mouse",
-      "price": 29.99,
-      "stock": 150
-    },
-    {
-      "sku": "SKU002",
-      "name": "Keyboard",
-      "price": 79.99,
-      "stock": 75
-    }
-  ]
-}`;
-
-// Parse JSON
-const parsed = await jsonParser.parse(jsonContent);
-
-console.log('Parsed data:', parsed);
-console.log(`Found ${parsed.products.length} products`);
-```
-
-### Type Safety with TypeScript
-
-```typescript
-// Define your data structure
-interface Product {
-  sku: string;
-  name: string;
-  price: number;
-  stock: number;
-}
-
-interface ProductCatalog {
-  products: Product[];
-}
-
-// Parse with type assertion
-const catalog = await jsonParser.parse<ProductCatalog>(jsonContent);
-
-// Now you have full type safety
-catalog.products.forEach(product => {
-  console.log(`${product.sku}: ${product.name} - $${product.price}`);
-});
-```
-
-### Nested Data Extraction
-
-Extract specific parts of nested JSON using `dataPath`:
-
-```typescript
-const nestedJSON = `{
-  "response": {
-    "status": "success",
-    "data": {
-      "inventory": {
-        "items": [
-          {"sku": "A001", "qty": 100},
-          {"sku": "A002", "qty": 50}
-        ]
-      }
-    }
-  }
-}`;
-
-// Extract nested data using dataPath
-const items = await jsonParser.parse(nestedJSON, {
-  dataPath: 'response.data.inventory.items'
-});
-
-console.log('Extracted items:', items);
-// Output: [{"sku": "A001", "qty": 100}, {"sku": "A002", "qty": 50}]
-```
-
-## JSONL Format Support
-
-**JSONL (JSON Lines)** is perfect for streaming large datasets where each line is a valid JSON object.
-
-### Basic JSONL Parsing
-
-```typescript
-const jsonlContent = `{"id": 1, "name": "Product 1", "price": 10.99}
-{"id": 2, "name": "Product 2", "price": 20.99}
-{"id": 3, "name": "Product 3", "price": 30.99}
-{"id": 4, "name": "Product 4", "price": 40.99}`;
-
-// Process each line individually
-for await (const item of jsonParser.parseStreaming(jsonlContent, {
-  jsonLines: true,
-  batchSize: 1
-})) {
-  console.log('Processing item:', item);
-  // Process each item as it's parsed
-}
-```
-
-### Batch Processing JSONL
-
-```typescript
-async function processBatchedJSONL(jsonlContent: string) {
-  const jsonParser = new JSONParserService();
-
-  // Process in batches of 100
-  for await (const batch of jsonParser.parseStreaming(jsonlContent, {
-    jsonLines: true,
-    batchSize: 100
-  })) {
-    console.log(`Processing batch of ${batch.length} items`);
-    await processBatch(batch);
-  }
-}
-
-async function processBatch(items: unknown[]) {
-  // Send batch to Fluent Commerce
-  console.log(`Sending ${items.length} items to Fluent`);
-}
-```
-
-## Streaming for Large Files
-
-Handle large JSON files without loading everything into memory.
-
-### Memory-Efficient Streaming
-
-```typescript
-import { Readable } from 'stream';
-import { JSONParserService } from '@fluentcommerce/fc-connect-sdk';
-
-async function streamLargeFile(fileStream: Readable) {
-  const jsonParser = new JSONParserService();
-
-  // Configure streaming options
-  const streamOptions = {
-    batchSize: 50,
-    memoryLimit: 10 * 1024 * 1024, // 10MB limit
-    parseDates: true
-  };
-
-  let totalProcessed = 0;
-
-  for await (const batch of jsonParser.parseStreaming(fileStream, streamOptions)) {
-    // Process each batch
-    await processInventoryBatch(batch);
-
-    totalProcessed += Array.isArray(batch) ? batch.length : 1;
-    console.log(`Processed ${totalProcessed} items`);
-  }
-}
-
-async function processInventoryBatch(items: unknown) {
-  // Transform and send to Fluent
-  console.log('Processing batch...');
-}
-```
-
-### Streaming with Progress Tracking
-
-```typescript
-async function streamWithProgress(jsonContent: string) {
-  const jsonParser = new JSONParserService();
-  const startTime = Date.now();
-  let itemCount = 0;
-
-  for await (const item of jsonParser.parseStreaming(jsonContent, {
-    batchSize: 1
-  })) {
-    itemCount++;
-
-    // Process item
-    await processItem(item);
-
-    // Report progress every 100 items
-    if (itemCount % 100 === 0) {
-      const elapsed = (Date.now() - startTime) / 1000;
-      const rate = itemCount / elapsed;
-      console.log(`Processed ${itemCount} items (${rate.toFixed(2)} items/sec)`);
-    }
-  }
-
-  console.log(`Completed: ${itemCount} total items`);
-}
-```
-
-## Schema Validation
-
-Validate JSON against a schema to ensure data integrity.
-
-### Basic Schema Validation
-
-```typescript
-const schema = {
-  type: 'object',
-  required: ['sku', 'name', 'price'],
-  properties: {
-    sku: { type: 'string' },
-    name: { type: 'string' },
-    price: { type: 'number' },
-    stock: { type: 'number' }
-  }
-};
-
-const productJSON = `{
-  "sku": "PROD001",
-  "name": "Test Product",
-  "price": 29.99
-}`;
-
-async function validateAndParse() {
-  const jsonParser = new JSONParserService();
-
-  try {
-    const parsed = await jsonParser.parse(productJSON, {
-      validateSchema: true,
-      schema: schema
-    });
-    console.log('Valid product:', parsed);
-  } catch (error) {
-    console.error('Validation failed:', error);
-  }
-}
-```
-
-### Complex Schema Validation
-
-```typescript
-const orderSchema = {
-  type: 'object',
-  required: ['orderId', 'customer', 'items'],
-  properties: {
-    orderId: { type: 'string' },
-    customer: {
-      type: 'object',
-      required: ['email'],
-      properties: {
-        email: { type: 'string' },
-        name: { type: 'string' }
-      }
-    },
-    items: {
-      type: 'array',
-      items: {
-        type: 'object',
-        required: ['sku', 'quantity'],
-        properties: {
-          sku: { type: 'string' },
-          quantity: { type: 'number' },
-          price: { type: 'number' }
-        }
-      }
-    }
-  }
-};
-
-// Validate order data
-const orderJSON = `{
-  "orderId": "ORD001",
-  "customer": {
-    "email": "customer@example.com",
-    "name": "John Doe"
-  },
-  "items": [
-    {"sku": "SKU001", "quantity": 2, "price": 29.99},
-    {"sku": "SKU002", "quantity": 1, "price": 49.99}
-  ]
-}`;
-
-const order = await jsonParser.parse(orderJSON, {
-  validateSchema: true,
-  schema: orderSchema
-});
-```
-
-## JSONPath Queries
-
-Extract specific data using JSONPath-like syntax.
-
-### Basic Queries
-
-```typescript
-const data = {
-  store: {
-    name: "Electronics Store",
-    inventory: {
-      laptops: [
-        { brand: "Dell", model: "XPS", price: 1200 },
-        { brand: "Apple", model: "MacBook", price: 2000 },
-        { brand: "Lenovo", model: "ThinkPad", price: 1500 }
-      ],
-      phones: [
-        { brand: "Apple", model: "iPhone", price: 999 },
-        { brand: "Samsung", model: "Galaxy", price: 899 }
-      ]
-    }
-  }
-};
-
-const jsonParser = new JSONParserService();
-
-// Query specific paths
-const storeName = jsonParser.query(data, 'store.name');
-console.log('Store:', storeName); // "Electronics Store"
-
-const laptops = jsonParser.query(data, 'store.inventory.laptops');
-console.log('Laptops:', laptops); // Array of laptops
-
-const firstLaptop = jsonParser.query(data, 'store.inventory.laptops[0]');
-console.log('First laptop:', firstLaptop); // Dell XPS
-
-// Wildcard queries
-const allInventory = jsonParser.query(data, 'store.inventory.*');
-console.log('All inventory:', allInventory); // All inventory items
-```
-
-### Advanced Queries
-
-```typescript
-// Complex nested structures
-const orderData = {
-  orders: [
-    {
-      id: "ORD001",
-      customer: { name: "John", tier: "gold" },
-      items: [
-        { sku: "A1", qty: 2 },
-        { sku: "A2", qty: 1 }
-      ]
-    },
-    {
-      id: "ORD002",
-      customer: { name: "Jane", tier: "silver" },
-      items: [
-        { sku: "B1", qty: 3 }
-      ]
-    }
-  ]
-};
-
-// Query nested arrays
-const firstOrderItems = jsonParser.query(orderData, 'orders[0].items');
-const allCustomerNames = jsonParser.query(orderData, 'orders.*.customer.name');
-```
-
-## Date Parsing
-
-### Automatic Date Parsing
-
-```typescript
-const jsonWithDates = `{
-  "createdAt": "2025-01-15T10:30:00Z",
-  "updatedAt": "2025-01-15T14:45:00.000Z",
-  "shipDate": "2025-01-20",
-  "customDate": "15/01/2025"
-}`;
-
-// Parse with automatic date detection
-const parsed = await jsonParser.parse(jsonWithDates, {
-  parseDates: true,
-  dateFormats: ['YYYY-MM-DD', 'DD/MM/YYYY']
-});
-
-console.log('Created:', parsed.createdAt); // Date object
-console.log('Ship date:', parsed.shipDate); // Date object
-```
-
-### Custom Reviver Functions
-
-```typescript
-// Custom reviver for special transformations
-const customReviver = (key: string, value: unknown): unknown => {
-  // Convert price strings to numbers
-  if (key === 'price' && typeof value === 'string') {
-    return parseFloat(value.replace('$', ''));
-  }
-
-  // Convert ISO dates to Date objects
-  if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(value)) {
-    return new Date(value);
-  }
-
-  // Convert "null" strings to actual null
-  if (value === "null") {
-    return null;
-  }
-
-  return value;
-};
-
-const jsonData = `{
-  "product": "Widget",
-  "price": "$29.99",
-  "lastUpdated": "2025-01-15T10:00:00Z",
-  "discontinued": "null"
-}`;
-
-const result = await jsonParser.parse(jsonData, {
-  reviver: customReviver
-});
-
-console.log(result);
-// {
-//   product: "Widget",
-//   price: 29.99,
-//   lastUpdated: Date object,
-//   discontinued: null
-// }
-```
-
-## Transformation Examples
-
-### E-commerce Platform Migration
-
-```typescript
-// Shopify to Fluent Commerce transformation
-async function transformShopifyData() {
-  const shopifyJSON = `{
-    "products": [
-      {
-        "id": 123456,
-        "title": "Wireless Mouse",
-        "variants": [
-          {
-            "sku": "WM-001",
-            "inventory_quantity": 150,
-            "price": "29.99"
-          }
-        ]
-      }
-    ]
-  }`;
-
-  const jsonParser = new JSONParserService();
-  const mapper = new UniversalMapper({
-    fields: {
-      ref: { source: 'variants[0].sku', required: true },
-      name: { source: 'title', required: true },
-      qty: { source: 'variants[0].inventory_quantity', resolver: 'sdk.parseInt' },
-      price: { source: 'variants[0].price', resolver: 'sdk.parseFloat' }
-    }
-  });
-
-  // Parse Shopify data
-  const shopifyData = await jsonParser.parse(shopifyJSON);
-
-  // Transform to Fluent format using UniversalMapper
-  const fluentProducts = [];
-
-  for (const product of shopifyData.products) {
-    for (const variant of product.variants) {
-      const result = await mapper.map({
-        ...product,
-        variants: [variant] // Map each variant individually
-      });
-
-      if (result.success) {
-        fluentProducts.push(result.data);
-      }
-    }
-  }
-
-  return fluentProducts;
-}
-```
-
-### WooCommerce Integration
-
-```typescript
-async function processWooCommerceWebhook(webhookPayload: string) {
-  const jsonParser = new JSONParserService();
-
-  // Parse webhook payload
-  const order = await jsonParser.parse(webhookPayload, {
-    parseDates: true,
-    dataPath: 'order' // If nested
-  });
-
-  // Transform to Fluent format
-  const fluentOrder = {
-    ref: `WC-${order.id}`,
-    type: 'HD',
-    retailerId: '1',
-    customer: {
-      email: order.billing.email,
-      firstName: order.billing.first_name,
-      lastName: order.billing.last_name
-    },
-    items: order.line_items.map(item => ({
-      ref: item.sku,
-      quantity: item.quantity,
-      price: parseFloat(item.price)
-    }))
-  };
-
-  return fluentOrder;
-}
-```
-
-## Integration with SDK Features
-
-### With Field Mapping
-
-```typescript
-import { JSONParserService, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-async function parseAndMap(jsonContent: string) {
-  const jsonParser = new JSONParserService();
-
-  // Parse JSON
-  const data = await jsonParser.parse(jsonContent, {
-    parseDates: true,
-    dataPath: 'data.products'
-  });
-
-  // Define mapping configuration using UniversalMapper structure
-  const mappingConfig = {
-    fields: {
-      ref: { source: 'product_id', required: true },
-      qty: { source: 'quantity_available', resolver: 'sdk.parseInt' },
-      locationRef: { source: 'warehouse_location' }
-    }
-  };
-
-  const mapper = new UniversalMapper(mappingConfig);
-  const result = await mapper.map(data);
-
-  if (!result.success) {
-    console.error('Mapping errors:', result.errors);
-    throw new Error('Mapping failed');
-  }
-
-  return result.data;
-}
-```
-
-### With Fluent Client
-
-```typescript
-async function processJSONToFluent(jsonContent: string) {
-  const jsonParser = new JSONParserService();
-  const fluentClient = await createClient({ config });
-
-  // Parse and validate
-  const products = await jsonParser.parse(jsonContent, {
-    validateSchema: true,
-    schema: productSchema
-  });
-
-  // Send to Fluent using GraphQL mutations (NOT Batch API for PRODUCT!)
-  // Batch API only supports INVENTORY
-  const batchSize = 100;
-  for (let i = 0; i < products.length; i += batchSize) {
-    const batch = products.slice(i, i + batchSize);
-
-    // Process each product with GraphQL mutation
-    for (const product of batch) {
-      await fluentClient.graphql({
-        query: `
-          mutation CreateProduct($input: CreateStandardProductInput!) {
-            createStandardProduct(input: $input) {
-              id
-              ref
-              status
-            }
-          }
-        `,
-        variables: {
-          input: {
-            ref: product.ref || product.sku,
-            type: 'STANDARD',
-            status: product.status || 'ACTIVE',
-            attributes: [
-              { name: 'name', type: 'STRING', value: product.name }
-            ]
-          }
-        }
-      });
-    }
-
-    console.log(`Processed batch ${Math.floor(i / batchSize) + 1} using GraphQL mutations`);
-  }
-}
-```
-
-## Error Handling
-
-### Comprehensive Error Handling
-
-```typescript
-import { FileParsingError } from '@fluentcommerce/fc-connect-sdk';
-
-async function robustJSONParsing(jsonContent: string) {
-  const jsonParser = new JSONParserService();
-
-  try {
-    // Validate first
-    const validation = jsonParser.validate(jsonContent);
-
-    if (!validation.valid) {
-      console.error('Validation errors:', validation.errors);
-
-      if (validation.warnings) {
-        console.warn('Warnings:', validation.warnings);
-      }
-
-      // Decide whether to proceed
-      if (validation.errors.some(e => e.includes('syntax error'))) {
-        throw new Error('Cannot parse invalid JSON');
-      }
-    }
-
-    // Parse with error recovery
-    const parsed = await jsonParser.parse(jsonContent, {
-      allowComments: true,        // Allow // and /* */ comments
-      allowTrailingCommas: true,  // Allow trailing commas
-      parseDates: true
-    });
-
-    return parsed;
-
-  } catch (error) {
-    if (error instanceof FileParsingError) {
-      console.error('Parsing error:', error.message);
-      console.error('Context:', error.context);
-
-      // Try to extract line/column info
-      const match = error.message.match(/line (\d+), column (\d+)/);
-      if (match) {
-        const [, line, column] = match;
-        console.error(`Error at line ${line}, column ${column}`);
-
-        // Show the problematic line
-        const lines = jsonContent.split('\n');
-        if (lines[parseInt(line) - 1]) {
-          console.error('Problematic line:', lines[parseInt(line) - 1]);
-        }
-      }
-    }
-
-    throw error;
-  }
-}
-```
-
-## Performance Tips
-
-### 1. Use Streaming for Large Files
-
-```typescript
-// ❌ BAD: Load everything at once
-const allData = await jsonParser.parse(jsonContent); // May cause memory issues
-
-// ✅ GOOD: Stream and process
-for await (const batch of jsonParser.parseStreaming(jsonContent, {
-  batchSize: 100
-})) {
-  await processBatch(batch);
-}
-```
-
-### 2. Optimize Parsing Options
-
-```typescript
-// Disable unnecessary features for better performance
-const optimizedOptions = {
-  parseDates: false,      // Skip if not needed
-  validateSchema: false,  // Skip validation if data is trusted
-  maxDepth: 10           // Limit nesting depth
-};
-
-const parsed = await jsonParser.parse(jsonContent, optimizedOptions);
-```
-
-### 3. Parallel Processing
-
-```typescript
-async function parallelProcessing(jsonArrays: string[]) {
-  const jsonParser = new JSONParserService();
-
-  // Process multiple JSON files in parallel
-  const promises = jsonArrays.map(async (json) => {
-    return await jsonParser.parse(json);
-  });
-
-  const results = await Promise.all(promises);
-  return results;
-}
-```
-
-## Key Takeaways
-
-- 🎯 JSON Parser handles modern API responses and nested structures
-- 🎯 Use JSONL format for streaming large datasets line-by-line
-- 🎯 Extract nested data with `dataPath` option
-- 🎯 Validate structure with schema validation
-- 🎯 Parse dates automatically with `parseDates` option
-- 🎯 Stream large files with `parseStreaming()` for memory efficiency
-- 🎯 Combine with UniversalMapper for transformations
-
-## Practice Exercise
-
-**Challenge:** Parse this Shopify webhook and transform it for Fluent:
-
-```json
-{
-  "order": {
-    "id": 12345,
-    "email": "customer@example.com",
-    "created_at": "2025-01-15T10:30:00Z",
-    "line_items": [
-      {
-        "sku": "SKU001",
-        "quantity": 2,
-        "price": "29.99"
-      }
-    ]
-  }
-}
-```
-
-**Requirements:**
-1. Parse the JSON
-2. Extract the order object
-3. Transform to: `{ ref, customer: { email }, items: [{ ref, quantity, price }] }`
-4. Parse the date and convert price to number
-
-**Solution:** See [JSON Examples](../examples/json-parser-examples.ts)
-
-## Next Steps
-
-Continue to [Module 4: XML Parser →](./02-core-guides-parsers-04-xml-parser.md) to learn XML parsing and generation.
-
----
-
-**Module 3 Complete!** ✅
+# Module 3: JSON Parser
+
+**Level:** Beginner
+**Estimated Time:** 25 minutes
+
+## Overview
+
+This module covers the JSON Parser (`JSONParserService`), essential for processing API responses, webhooks, and modern data formats. You'll learn how to parse JSON and JSONL, extract nested data, handle large files with streaming, and validate data structures.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Parse JSON and JSONL (JSON Lines) formats
+- ✅ Extract nested data with path queries
+- ✅ Stream large JSON files efficiently
+- ✅ Validate JSON against schemas
+- ✅ Parse and transform dates automatically
+- ✅ Integrate with SDK transformation services
+
+## What is JSON?
+
+**JSON (JavaScript Object Notation)** is a lightweight data format that:
+- Supports nested objects and arrays
+- Uses key-value pairs
+- Includes native types: string, number, boolean, null
+- Is the standard format for modern APIs
+
+**Example:**
+```json
+{
+  "products": [
+    {
+      "sku": "SKU001",
+      "name": "Wireless Mouse",
+      "price": 29.99,
+      "stock": {
+        "qty": 150,
+        "locations": ["WH-01", "WH-02"]
+      }
+    }
+  ]
+}
+```
+
+## Basic JSON Parsing
+
+### Simple Parsing
+
+```typescript
+import { JSONParserService } from '@fluentcommerce/fc-connect-sdk';
+
+const jsonParser = new JSONParserService();
+
+// Sample JSON data
+const jsonContent = `{
+  "products": [
+    {
+      "sku": "SKU001",
+      "name": "Wireless Mouse",
+      "price": 29.99,
+      "stock": 150
+    },
+    {
+      "sku": "SKU002",
+      "name": "Keyboard",
+      "price": 79.99,
+      "stock": 75
+    }
+  ]
+}`;
+
+// Parse JSON
+const parsed = await jsonParser.parse(jsonContent);
+
+console.log('Parsed data:', parsed);
+console.log(`Found ${parsed.products.length} products`);
+```
+
+### Type Safety with TypeScript
+
+```typescript
+// Define your data structure
+interface Product {
+  sku: string;
+  name: string;
+  price: number;
+  stock: number;
+}
+
+interface ProductCatalog {
+  products: Product[];
+}
+
+// Parse with type assertion
+const catalog = await jsonParser.parse<ProductCatalog>(jsonContent);
+
+// Now you have full type safety
+catalog.products.forEach(product => {
+  console.log(`${product.sku}: ${product.name} - $${product.price}`);
+});
+```
+
+### Nested Data Extraction
+
+Extract specific parts of nested JSON using `dataPath`:
+
+```typescript
+const nestedJSON = `{
+  "response": {
+    "status": "success",
+    "data": {
+      "inventory": {
+        "items": [
+          {"sku": "A001", "qty": 100},
+          {"sku": "A002", "qty": 50}
+        ]
+      }
+    }
+  }
+}`;
+
+// Extract nested data using dataPath
+const items = await jsonParser.parse(nestedJSON, {
+  dataPath: 'response.data.inventory.items'
+});
+
+console.log('Extracted items:', items);
+// Output: [{"sku": "A001", "qty": 100}, {"sku": "A002", "qty": 50}]
+```
+
+## JSONL Format Support
+
+**JSONL (JSON Lines)** is perfect for streaming large datasets where each line is a valid JSON object.
+
+### Basic JSONL Parsing
+
+```typescript
+const jsonlContent = `{"id": 1, "name": "Product 1", "price": 10.99}
+{"id": 2, "name": "Product 2", "price": 20.99}
+{"id": 3, "name": "Product 3", "price": 30.99}
+{"id": 4, "name": "Product 4", "price": 40.99}`;
+
+// Process each line individually
+for await (const item of jsonParser.parseStreaming(jsonlContent, {
+  jsonLines: true,
+  batchSize: 1
+})) {
+  console.log('Processing item:', item);
+  // Process each item as it's parsed
+}
+```
+
+### Batch Processing JSONL
+
+```typescript
+async function processBatchedJSONL(jsonlContent: string) {
+  const jsonParser = new JSONParserService();
+
+  // Process in batches of 100
+  for await (const batch of jsonParser.parseStreaming(jsonlContent, {
+    jsonLines: true,
+    batchSize: 100
+  })) {
+    console.log(`Processing batch of ${batch.length} items`);
+    await processBatch(batch);
+  }
+}
+
+async function processBatch(items: unknown[]) {
+  // Send batch to Fluent Commerce
+  console.log(`Sending ${items.length} items to Fluent`);
+}
+```
+
+## Streaming for Large Files
+
+Handle large JSON files without loading everything into memory.
+
+### Memory-Efficient Streaming
+
+```typescript
+import { Readable } from 'stream';
+import { JSONParserService } from '@fluentcommerce/fc-connect-sdk';
+
+async function streamLargeFile(fileStream: Readable) {
+  const jsonParser = new JSONParserService();
+
+  // Configure streaming options
+  const streamOptions = {
+    batchSize: 50,
+    memoryLimit: 10 * 1024 * 1024, // 10MB limit
+    parseDates: true
+  };
+
+  let totalProcessed = 0;
+
+  for await (const batch of jsonParser.parseStreaming(fileStream, streamOptions)) {
+    // Process each batch
+    await processInventoryBatch(batch);
+
+    totalProcessed += Array.isArray(batch) ? batch.length : 1;
+    console.log(`Processed ${totalProcessed} items`);
+  }
+}
+
+async function processInventoryBatch(items: unknown) {
+  // Transform and send to Fluent
+  console.log('Processing batch...');
+}
+```
+
+### Streaming with Progress Tracking
+
+```typescript
+async function streamWithProgress(jsonContent: string) {
+  const jsonParser = new JSONParserService();
+  const startTime = Date.now();
+  let itemCount = 0;
+
+  for await (const item of jsonParser.parseStreaming(jsonContent, {
+    batchSize: 1
+  })) {
+    itemCount++;
+
+    // Process item
+    await processItem(item);
+
+    // Report progress every 100 items
+    if (itemCount % 100 === 0) {
+      const elapsed = (Date.now() - startTime) / 1000;
+      const rate = itemCount / elapsed;
+      console.log(`Processed ${itemCount} items (${rate.toFixed(2)} items/sec)`);
+    }
+  }
+
+  console.log(`Completed: ${itemCount} total items`);
+}
+```
+
+## Schema Validation
+
+Validate JSON against a schema to ensure data integrity.
+
+### Basic Schema Validation
+
+```typescript
+const schema = {
+  type: 'object',
+  required: ['sku', 'name', 'price'],
+  properties: {
+    sku: { type: 'string' },
+    name: { type: 'string' },
+    price: { type: 'number' },
+    stock: { type: 'number' }
+  }
+};
+
+const productJSON = `{
+  "sku": "PROD001",
+  "name": "Test Product",
+  "price": 29.99
+}`;
+
+async function validateAndParse() {
+  const jsonParser = new JSONParserService();
+
+  try {
+    const parsed = await jsonParser.parse(productJSON, {
+      validateSchema: true,
+      schema: schema
+    });
+    console.log('Valid product:', parsed);
+  } catch (error) {
+    console.error('Validation failed:', error);
+  }
+}
+```
+
+### Complex Schema Validation
+
+```typescript
+const orderSchema = {
+  type: 'object',
+  required: ['orderId', 'customer', 'items'],
+  properties: {
+    orderId: { type: 'string' },
+    customer: {
+      type: 'object',
+      required: ['email'],
+      properties: {
+        email: { type: 'string' },
+        name: { type: 'string' }
+      }
+    },
+    items: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['sku', 'quantity'],
+        properties: {
+          sku: { type: 'string' },
+          quantity: { type: 'number' },
+          price: { type: 'number' }
+        }
+      }
+    }
+  }
+};
+
+// Validate order data
+const orderJSON = `{
+  "orderId": "ORD001",
+  "customer": {
+    "email": "customer@example.com",
+    "name": "John Doe"
+  },
+  "items": [
+    {"sku": "SKU001", "quantity": 2, "price": 29.99},
+    {"sku": "SKU002", "quantity": 1, "price": 49.99}
+  ]
+}`;
+
+const order = await jsonParser.parse(orderJSON, {
+  validateSchema: true,
+  schema: orderSchema
+});
+```
+
+## JSONPath Queries
+
+Extract specific data using JSONPath-like syntax.
+
+### Basic Queries
+
+```typescript
+const data = {
+  store: {
+    name: "Electronics Store",
+    inventory: {
+      laptops: [
+        { brand: "Dell", model: "XPS", price: 1200 },
+        { brand: "Apple", model: "MacBook", price: 2000 },
+        { brand: "Lenovo", model: "ThinkPad", price: 1500 }
+      ],
+      phones: [
+        { brand: "Apple", model: "iPhone", price: 999 },
+        { brand: "Samsung", model: "Galaxy", price: 899 }
+      ]
+    }
+  }
+};
+
+const jsonParser = new JSONParserService();
+
+// Query specific paths
+const storeName = jsonParser.query(data, 'store.name');
+console.log('Store:', storeName); // "Electronics Store"
+
+const laptops = jsonParser.query(data, 'store.inventory.laptops');
+console.log('Laptops:', laptops); // Array of laptops
+
+const firstLaptop = jsonParser.query(data, 'store.inventory.laptops[0]');
+console.log('First laptop:', firstLaptop); // Dell XPS
+
+// Wildcard queries
+const allInventory = jsonParser.query(data, 'store.inventory.*');
+console.log('All inventory:', allInventory); // All inventory items
+```
+
+### Advanced Queries
+
+```typescript
+// Complex nested structures
+const orderData = {
+  orders: [
+    {
+      id: "ORD001",
+      customer: { name: "John", tier: "gold" },
+      items: [
+        { sku: "A1", qty: 2 },
+        { sku: "A2", qty: 1 }
+      ]
+    },
+    {
+      id: "ORD002",
+      customer: { name: "Jane", tier: "silver" },
+      items: [
+        { sku: "B1", qty: 3 }
+      ]
+    }
+  ]
+};
+
+// Query nested arrays
+const firstOrderItems = jsonParser.query(orderData, 'orders[0].items');
+const allCustomerNames = jsonParser.query(orderData, 'orders.*.customer.name');
+```
+
+## Date Parsing
+
+### Automatic Date Parsing
+
+```typescript
+const jsonWithDates = `{
+  "createdAt": "2025-01-15T10:30:00Z",
+  "updatedAt": "2025-01-15T14:45:00.000Z",
+  "shipDate": "2025-01-20",
+  "customDate": "15/01/2025"
+}`;
+
+// Parse with automatic date detection
+const parsed = await jsonParser.parse(jsonWithDates, {
+  parseDates: true,
+  dateFormats: ['YYYY-MM-DD', 'DD/MM/YYYY']
+});
+
+console.log('Created:', parsed.createdAt); // Date object
+console.log('Ship date:', parsed.shipDate); // Date object
+```
+
+### Custom Reviver Functions
+
+```typescript
+// Custom reviver for special transformations
+const customReviver = (key: string, value: unknown): unknown => {
+  // Convert price strings to numbers
+  if (key === 'price' && typeof value === 'string') {
+    return parseFloat(value.replace('$', ''));
+  }
+
+  // Convert ISO dates to Date objects
+  if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(value)) {
+    return new Date(value);
+  }
+
+  // Convert "null" strings to actual null
+  if (value === "null") {
+    return null;
+  }
+
+  return value;
+};
+
+const jsonData = `{
+  "product": "Widget",
+  "price": "$29.99",
+  "lastUpdated": "2025-01-15T10:00:00Z",
+  "discontinued": "null"
+}`;
+
+const result = await jsonParser.parse(jsonData, {
+  reviver: customReviver
+});
+
+console.log(result);
+// {
+//   product: "Widget",
+//   price: 29.99,
+//   lastUpdated: Date object,
+//   discontinued: null
+// }
+```
+
+## Transformation Examples
+
+### E-commerce Platform Migration
+
+```typescript
+// Shopify to Fluent Commerce transformation
+async function transformShopifyData() {
+  const shopifyJSON = `{
+    "products": [
+      {
+        "id": 123456,
+        "title": "Wireless Mouse",
+        "variants": [
+          {
+            "sku": "WM-001",
+            "inventory_quantity": 150,
+            "price": "29.99"
+          }
+        ]
+      }
+    ]
+  }`;
+
+  const jsonParser = new JSONParserService();
+  const mapper = new UniversalMapper({
+    fields: {
+      ref: { source: 'variants[0].sku', required: true },
+      name: { source: 'title', required: true },
+      qty: { source: 'variants[0].inventory_quantity', resolver: 'sdk.parseInt' },
+      price: { source: 'variants[0].price', resolver: 'sdk.parseFloat' }
+    }
+  });
+
+  // Parse Shopify data
+  const shopifyData = await jsonParser.parse(shopifyJSON);
+
+  // Transform to Fluent format using UniversalMapper
+  const fluentProducts = [];
+
+  for (const product of shopifyData.products) {
+    for (const variant of product.variants) {
+      const result = await mapper.map({
+        ...product,
+        variants: [variant] // Map each variant individually
+      });
+
+      if (result.success) {
+        fluentProducts.push(result.data);
+      }
+    }
+  }
+
+  return fluentProducts;
+}
+```
+
+### WooCommerce Integration
+
+```typescript
+async function processWooCommerceWebhook(webhookPayload: string) {
+  const jsonParser = new JSONParserService();
+
+  // Parse webhook payload
+  const order = await jsonParser.parse(webhookPayload, {
+    parseDates: true,
+    dataPath: 'order' // If nested
+  });
+
+  // Transform to Fluent format
+  const fluentOrder = {
+    ref: `WC-${order.id}`,
+    type: 'HD',
+    retailerId: '1',
+    customer: {
+      email: order.billing.email,
+      firstName: order.billing.first_name,
+      lastName: order.billing.last_name
+    },
+    items: order.line_items.map(item => ({
+      ref: item.sku,
+      quantity: item.quantity,
+      price: parseFloat(item.price)
+    }))
+  };
+
+  return fluentOrder;
+}
+```
+
+## Integration with SDK Features
+
+### With Field Mapping
+
+```typescript
+import { JSONParserService, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+async function parseAndMap(jsonContent: string) {
+  const jsonParser = new JSONParserService();
+
+  // Parse JSON
+  const data = await jsonParser.parse(jsonContent, {
+    parseDates: true,
+    dataPath: 'data.products'
+  });
+
+  // Define mapping configuration using UniversalMapper structure
+  const mappingConfig = {
+    fields: {
+      ref: { source: 'product_id', required: true },
+      qty: { source: 'quantity_available', resolver: 'sdk.parseInt' },
+      locationRef: { source: 'warehouse_location' }
+    }
+  };
+
+  const mapper = new UniversalMapper(mappingConfig);
+  const result = await mapper.map(data);
+
+  if (!result.success) {
+    console.error('Mapping errors:', result.errors);
+    throw new Error('Mapping failed');
+  }
+
+  return result.data;
+}
+```
+
+### With Fluent Client
+
+```typescript
+async function processJSONToFluent(jsonContent: string) {
+  const jsonParser = new JSONParserService();
+  const fluentClient = await createClient({ config });
+
+  // Parse and validate
+  const products = await jsonParser.parse(jsonContent, {
+    validateSchema: true,
+    schema: productSchema
+  });
+
+  // Send to Fluent using GraphQL mutations (NOT Batch API for PRODUCT!)
+  // Batch API only supports INVENTORY
+  const batchSize = 100;
+  for (let i = 0; i < products.length; i += batchSize) {
+    const batch = products.slice(i, i + batchSize);
+
+    // Process each product with GraphQL mutation
+    for (const product of batch) {
+      await fluentClient.graphql({
+        query: `
+          mutation CreateProduct($input: CreateStandardProductInput!) {
+            createStandardProduct(input: $input) {
+              id
+              ref
+              status
+            }
+          }
+        `,
+        variables: {
+          input: {
+            ref: product.ref || product.sku,
+            type: 'STANDARD',
+            status: product.status || 'ACTIVE',
+            attributes: [
+              { name: 'name', type: 'STRING', value: product.name }
+            ]
+          }
+        }
+      });
+    }
+
+    console.log(`Processed batch ${Math.floor(i / batchSize) + 1} using GraphQL mutations`);
+  }
+}
+```
+
+## Error Handling
+
+### Comprehensive Error Handling
+
+```typescript
+import { FileParsingError } from '@fluentcommerce/fc-connect-sdk';
+
+async function robustJSONParsing(jsonContent: string) {
+  const jsonParser = new JSONParserService();
+
+  try {
+    // Validate first
+    const validation = jsonParser.validate(jsonContent);
+
+    if (!validation.valid) {
+      console.error('Validation errors:', validation.errors);
+
+      if (validation.warnings) {
+        console.warn('Warnings:', validation.warnings);
+      }
+
+      // Decide whether to proceed
+      if (validation.errors.some(e => e.includes('syntax error'))) {
+        throw new Error('Cannot parse invalid JSON');
+      }
+    }
+
+    // Parse with error recovery
+    const parsed = await jsonParser.parse(jsonContent, {
+      allowComments: true,        // Allow // and /* */ comments
+      allowTrailingCommas: true,  // Allow trailing commas
+      parseDates: true
+    });
+
+    return parsed;
+
+  } catch (error) {
+    if (error instanceof FileParsingError) {
+      console.error('Parsing error:', error.message);
+      console.error('Context:', error.context);
+
+      // Try to extract line/column info
+      const match = error.message.match(/line (\d+), column (\d+)/);
+      if (match) {
+        const [, line, column] = match;
+        console.error(`Error at line ${line}, column ${column}`);
+
+        // Show the problematic line
+        const lines = jsonContent.split('\n');
+        if (lines[parseInt(line) - 1]) {
+          console.error('Problematic line:', lines[parseInt(line) - 1]);
+        }
+      }
+    }
+
+    throw error;
+  }
+}
+```
+
+## Performance Tips
+
+### 1. Use Streaming for Large Files
+
+```typescript
+// ❌ BAD: Load everything at once
+const allData = await jsonParser.parse(jsonContent); // May cause memory issues
+
+// ✅ GOOD: Stream and process
+for await (const batch of jsonParser.parseStreaming(jsonContent, {
+  batchSize: 100
+})) {
+  await processBatch(batch);
+}
+```
+
+### 2. Optimize Parsing Options
+
+```typescript
+// Disable unnecessary features for better performance
+const optimizedOptions = {
+  parseDates: false,      // Skip if not needed
+  validateSchema: false,  // Skip validation if data is trusted
+  maxDepth: 10           // Limit nesting depth
+};
+
+const parsed = await jsonParser.parse(jsonContent, optimizedOptions);
+```
+
+### 3. Parallel Processing
+
+```typescript
+async function parallelProcessing(jsonArrays: string[]) {
+  const jsonParser = new JSONParserService();
+
+  // Process multiple JSON files in parallel
+  const promises = jsonArrays.map(async (json) => {
+    return await jsonParser.parse(json);
+  });
+
+  const results = await Promise.all(promises);
+  return results;
+}
+```
+
+## Key Takeaways
+
+- 🎯 JSON Parser handles modern API responses and nested structures
+- 🎯 Use JSONL format for streaming large datasets line-by-line
+- 🎯 Extract nested data with `dataPath` option
+- 🎯 Validate structure with schema validation
+- 🎯 Parse dates automatically with `parseDates` option
+- 🎯 Stream large files with `parseStreaming()` for memory efficiency
+- 🎯 Combine with UniversalMapper for transformations
+
+## Practice Exercise
+
+**Challenge:** Parse this Shopify webhook and transform it for Fluent:
+
+```json
+{
+  "order": {
+    "id": 12345,
+    "email": "customer@example.com",
+    "created_at": "2025-01-15T10:30:00Z",
+    "line_items": [
+      {
+        "sku": "SKU001",
+        "quantity": 2,
+        "price": "29.99"
+      }
+    ]
+  }
+}
+```
+
+**Requirements:**
+1. Parse the JSON
+2. Extract the order object
+3. Transform to: `{ ref, customer: { email }, items: [{ ref, quantity, price }] }`
+4. Parse the date and convert price to number
+
+**Solution:** See [JSON Examples](../examples/json-parser-examples.ts)
+
+## Next Steps
+
+Continue to [Module 4: XML Parser →](./02-core-guides-parsers-04-xml-parser.md) to learn XML parsing and generation.
+
+---
+
+**Module 3 Complete!** ✅