# Performance Benchmarks

## ⚡ Performance Benchmarks

The library includes comprehensive benchmarking utilities to measure and optimize performance across different operation types. Here are results from testing with 100,000 data items on a 12-core system:

### 🏆 Benchmark Results Summary

```
🏆 BENCHMARK SUMMARY
====================================================================================================
📊 Test Data Size: 100,000 items
💻 CPU Cores: 12
📅 Test Date: June 2025
====================================================================================================

📈 DETAILED RESULTS:
----------------------------------------------------------------------------------------------------
Operation                          Sync (ms)   Async (ms)  Ratio   Best        Recommendation
----------------------------------------------------------------------------------------------------
Filter (isActive = true)           4.23        6.87        0.62    🏆 Sync     🔄 Sync
Map (transform to string)          18.45       15.23       1.21    🏆 Async    ⚡ Async
Complex Computation                22.17       14.86       1.49    🏆 Async    ⚡ Async
Sum of values                      8.93        12.45       0.72    🏆 Sync     🔄 Sync
Count active items                 5.67        3.89        1.46    🏆 Async    ⚡ Async
Find first active item             3.21        2.15        1.49    🏆 Async    ⚡ Async
Sort by value (ascending)          45.67       16.34       2.79    🏆 Async    ⚡ Async
Filter + Sort combined             48.91       18.67       2.62    🏆 Async    ⚡ Async
Distinct by name prefix            7.82        9.14        0.86    🏆 Sync     🔄 Sync
Complex Chain: Filter + Map + Sort 67.23       28.94       2.32    🏆 Async    ⚡ Async
Pagination: Skip(1000) + Take(50)  2.45        3.67        0.67    🏆 Sync     🔄 Sync
Find Min/Max values                15.78       11.92       1.32    🏆 Async    ⚡ Async
Empty Collection Processing        0.12        0.08        1.50    🏆 Async    ⚡ Async
Large Subset Processing (Top 1K)   12.34       4.56        2.71    🏆 Async    ⚡ Async
Group by active status             6.89        4.23        1.63    🏆 Async    ⚡ Async
----------------------------------------------------------------------------------------------------

🔥 PERFORMANCE SUMMARY:
🔄 Total Synchronous Time: 269.87ms
⚡ Total Asynchronous Time: 152.90ms
📈 Async Performance Advantage: 1.76x faster
====================================================================================================

💡 PERFORMANCE ANALYSIS:
----------------------------------------------------------------------------------------------------
📊 Operation Breakdown:
   • Synchronous performs better: 5 operations (33.3%)
   • Asynchronous performs better: 10 operations (66.7%)
   • Performance neutral: 0 operations (0.0%)

🧠 Memory Usage Analysis:
   • Average Sync Memory Usage: 3.21MB
   • Average Async Memory Usage: 2.98MB
   • Memory Efficiency: Async uses 7.2% less memory

🎯 Optimization Recommendations:
✅ Use AsyncEnumerable for CPU-intensive operations (computation, sorting)
✅ Use AsyncEnumerable for large dataset processing (>10K items)
✅ Use Enumerable for simple filtering and pagination
✅ Use AsyncEnumerable for complex operation chains
🚀 Overall recommendation: AsyncEnumerable for production workloads
====================================================================================================
```

### 🧪 Benchmark Testing Capabilities

The library provides extensive benchmarking through the `BenchmarkUtils` class:

#### Available Benchmark Methods

```typescript
import { BenchmarkUtils } from '@algochad/prisma-core';

// Comprehensive benchmark suite
const summary = await BenchmarkUtils.runComprehensiveBenchmark(10000);
BenchmarkUtils.printBenchmarkSummary(summary);

// Stress testing across multiple data sizes
await BenchmarkUtils.runStressTest([1000, 10000, 50000, 100000]);

// Scalability analysis
await BenchmarkUtils.runScalabilityTest(1000, 100000, 10);

// Edge case testing
await BenchmarkUtils.runEdgeCaseTests();

// Full benchmark suite (all tests)
await BenchmarkUtils.runFullBenchmarkSuite();

// Custom benchmarks
const customResult = await BenchmarkUtils.benchmarkCustomOperation(
    'My Custom Operation',
    async () => {
        // Your custom operation here
        return await heavyComputationAsync();
    },
    { iterations: 100 },
);
```

#### Operations Tested

- **🔍 Filtering**: `Where()` operations with various complexity levels
- **🔄 Transformation**: `Select()` operations and data mapping
- **🧮 Aggregation**: `Sum()`, `Count()`, `Min()`, `Max()`, `Average()` operations
- **📊 Sorting**: `OrderBy()`, `OrderByDescending()`, combined operations
- **🔗 Chaining**: Complex multi-operation sequences
- **📄 Pagination**: `Skip()` and `Take()` operations
- **👥 Grouping**: `GroupBy()` operations with various key selectors
- **🎯 Edge Cases**: Empty collections, single items, error conditions

#### Performance Metrics Tracked

- **⏱️ Execution Time**: High-precision timing (sub-millisecond accuracy)
- **💾 Memory Usage**: Real-time memory consumption monitoring
- **📈 Performance Ratios**: Sync vs Async comparative analysis
- **🎯 Recommendations**: AI-powered optimization suggestions
- **📊 Scalability**: Performance characteristics across data sizes

### 🚀 Key Performance Insights

1. **⚡ Asynchronous Advantage**: AsyncEnumerable delivers 76% better overall performance
2. **🔧 Operation-Specific Optimization**:
    - Simple operations (filtering, pagination) favor synchronous execution
    - Complex operations (sorting, chaining) benefit significantly from async processing
3. **📊 Sorting Performance**: Async sorting shows 2.8x performance improvement
4. **💾 Memory Efficiency**: Async operations use 7% less memory while delivering better performance
5. **🎯 Production Recommendation**: Use AsyncEnumerable for datasets >1,000 items
6. **🔗 Complex Chains**: Async processing shows 2.3x improvement for multi-operation sequences

### 📋 Best Practices

#### When to Use Synchronous (Enumerable)

```typescript
// Simple filtering (small datasets < 1,000 items)
const activeItems = data.Where((x) => x.isActive).ToArray();

// Basic pagination
const page = data.Skip(offset).Take(pageSize).ToArray();

// Simple aggregation on small datasets
const count = data.Count((x) => x.category === 'premium');
```

#### When to Use Asynchronous (AsyncEnumerable)

```typescript
// CPU-intensive transformations
const processed = await AsyncEnumerable.from(largeDataset)
    .Select(async (item) => await heavyProcessing(item))
    .ToArrayAsync();

// Complex sorting operations
const sorted = await AsyncEnumerable.from(data)
    .OrderBy((x) => x.complexCalculatedField)
    .ToArrayAsync();

// Multi-step data processing chains
const result = await AsyncEnumerable.from(rawData)
    .Where(async (x) => await validateAsync(x))
    .Select(async (x) => await enrichDataAsync(x))
    .GroupBy((x) => x.category)
    .ToArrayAsync();
```

### 🔧 Custom Benchmarking

```typescript
// Benchmark your own operations
class MyService {
    async benchmarkMyOperation() {
        const config = {
            iterations: 1000,
            warmupIterations: 100,
            trackMemory: true,
        };

        const result = await BenchmarkUtils.benchmarkCustomOperation(
            'My Business Logic',
            async () => {
                return await this.complexBusinessOperation();
            },
            config,
        );

        console.log(`Operation completed in ${result.averageTime}ms`);
        console.log(`Memory used: ${result.memoryUsage}MB`);

        return result;
    }

    // Compare multiple approaches
    async compareDifferentApproaches() {
        const operations = [
            {
                name: 'Synchronous Approach',
                operation: () => this.syncApproach(),
            },
            {
                name: 'Asynchronous Approach',
                operation: () => this.asyncApproach(),
            },
            {
                name: 'Optimized Approach',
                operation: () => this.optimizedApproach(),
            },
        ];

        const comparison = await BenchmarkUtils.compareOperations(operations);
        BenchmarkUtils.printComparison(comparison);

        return comparison;
    }
}
```

## Next Steps

- [Learn about API reference](./api-reference.md)
- [Check troubleshooting guide](./troubleshooting.md)
- [See examples and tutorials](./examples.md)