@algochad/prisma-core/docs/api-reference.md

A comprehensive NestJS library that provides EF-Core-like operations using Prisma and GraphQL. Features LINQ-style query builders, advanced data manipulation, GraphQL integration with genql, and a unified API for both Prisma and GraphQL operations. Includ

# API Reference

## 🛠️ API Reference

### Core Components

The `PrismaCoreModule` provides these essential components:

- **`PrismaCoreService`** - Core service with Prisma client integration
- **`PrismaRepository`** - Universal repository base class with dynamic model access
- **`PrismaUnifiedBuilder`** - Unified query and mutation builder
- **`Enumerable`** - Synchronous LINQ operations
- **`AsyncEnumerable`** - Asynchronous LINQ operations for performance
- **`BenchmarkUtils`** - Performance testing and optimization utilities

### Configuration Options

```typescript
// Basic configuration
PrismaCoreModule.forRoot({
    prismaClientProvider: {
        provide: 'PRISMA_CLIENT',
        useFactory: () => new PrismaClient(),
    },
});

// Advanced configuration with options
PrismaCoreModule.forRoot({
    prismaClientProvider: PRISMA_CLIENT_PROVIDER,
    options: {
        enableBenchmarking: true,
        defaultTimeout: 30000,
        enableQueryLogging: process.env.NODE_ENV === 'development',
    },
});
```

### PrismaCoreService

The core service that provides Prisma client integration.

```typescript
class PrismaCoreService {
    constructor(prismaClient: PrismaClient, options?: PrismaCoreOptions);

    // Get the Prisma client instance
    get client(): PrismaClient;

    // Execute within a transaction
    transaction<T>(fn: (tx: PrismaClient) => Promise<T>): Promise<T>;

    // Health check
    isHealthy(): Promise<boolean>;
}
```

### PrismaRepository

Base repository class with universal model access.

```typescript
abstract class PrismaRepository {
    constructor(databaseService: PrismaCoreService);

    // Dynamic model access
    model<T>(modelName: string): PrismaUnifiedBuilder<T>;

    // Get available model names
    getModelNames(): string[];

    // Clear internal cache
    clearCache(): void;

    // Direct client access
    get client(): PrismaClient;
}
```

### PrismaUnifiedBuilder

Unified query and mutation builder with LINQ-style operations.

```typescript
class PrismaUnifiedBuilder<T> {
    // Query operations
    Where(condition: WhereInput): PrismaUnifiedBuilder<T>;
    Select(fields: SelectInput): PrismaUnifiedBuilder<T>;
    Include(relations: IncludeInput): PrismaUnifiedBuilder<T>;
    OrderBy(sort: OrderByInput): PrismaUnifiedBuilder<T>;
    Take(count: number): PrismaUnifiedBuilder<T>;
    Skip(count: number): PrismaUnifiedBuilder<T>;

    // Execution methods
    ToArray(): Promise<T[]>;
    ToEnumerable(): Promise<Enumerable<T>>;
    ToAsyncEnumerable(): Promise<AsyncEnumerable<T>>;
    First(): Promise<T | null>;
    Count(): Promise<number>;

    // Mutation operations
    Create(data: CreateInput): Promise<T>;
    Update(where: WhereUniqueInput, data: UpdateInput): Promise<T>;
    Delete(where: WhereUniqueInput): Promise<T>;
    CreateMany(data: CreateInput[]): Promise<{ count: number }>;
    UpdateMany(
        where: WhereInput,
        data: UpdateInput,
    ): Promise<{ count: number }>;
    DeleteMany(where: WhereInput): Promise<{ count: number }>;

    // Transaction support
    Transaction<R>(fn: (tx: PrismaUnifiedBuilder<T>) => Promise<R>): Promise<R>;
}
```

### Enumerable (Synchronous LINQ)

Synchronous LINQ operations for collections.

```typescript
class Enumerable<T> {
    static from<T>(source: T[]): Enumerable<T>;

    // Filtering
    Where(predicate: (item: T) => boolean): Enumerable<T>;

    // Projection
    Select<R>(selector: (item: T) => R): Enumerable<R>;
    SelectMany<R>(selector: (item: T) => R[]): Enumerable<R>;

    // Ordering
    OrderBy<K>(keySelector: (item: T) => K): OrderedEnumerable<T>;
    OrderByDescending<K>(keySelector: (item: T) => K): OrderedEnumerable<T>;

    // Aggregation
    Sum(selector?: (item: T) => number): number;
    Average(selector?: (item: T) => number): number;
    Min<K>(selector?: (item: T) => K): K;
    Max<K>(selector?: (item: T) => K): K;
    Count(predicate?: (item: T) => boolean): number;

    // Existence
    Any(predicate?: (item: T) => boolean): boolean;
    All(predicate: (item: T) => boolean): boolean;

    // Set operations
    Distinct(keySelector?: (item: T) => any): Enumerable<T>;
    Union(other: Enumerable<T>): Enumerable<T>;
    Intersect(other: Enumerable<T>): Enumerable<T>;
    Except(other: Enumerable<T>): Enumerable<T>;

    // Pagination
    Take(count: number): Enumerable<T>;
    Skip(count: number): Enumerable<T>;

    // Grouping
    GroupBy<K>(keySelector: (item: T) => K): Enumerable<Grouping<K, T>>;

    // Conversion
    ToArray(): T[];
    ToMap<K, V>(
        keySelector: (item: T) => K,
        valueSelector: (item: T) => V,
    ): Map<K, V>;

    // Custom aggregation
    Aggregate<R>(
        seed: R,
        accumulator: (acc: R, item: T) => R,
        resultSelector?: (result: R) => R,
    ): R;
}
```

### AsyncEnumerable (Asynchronous LINQ)

Asynchronous LINQ operations for performance-critical scenarios.

```typescript
class AsyncEnumerable<T> {
    static from<T>(source: T[]): AsyncEnumerable<T>;
    static fromAsync<T>(source: AsyncIterable<T>): AsyncEnumerable<T>;

    // Filtering
    Where(
        predicate: (item: T) => boolean | Promise<boolean>,
    ): AsyncEnumerable<T>;

    // Projection
    Select<R>(selector: (item: T) => R | Promise<R>): AsyncEnumerable<R>;
    SelectMany<R>(
        selector: (item: T) => R[] | Promise<R[]>,
    ): AsyncEnumerable<R>;

    // Ordering
    OrderBy<K>(keySelector: (item: T) => K): OrderedAsyncEnumerable<T>;
    OrderByDescending<K>(
        keySelector: (item: T) => K,
    ): OrderedAsyncEnumerable<T>;

    // Aggregation
    Sum(selector?: (item: T) => number): Promise<number>;
    Average(selector?: (item: T) => number): Promise<number>;
    Min<K>(selector?: (item: T) => K): Promise<K>;
    Max<K>(selector?: (item: T) => K): Promise<K>;
    Count(predicate?: (item: T) => boolean | Promise<boolean>): Promise<number>;

    // Existence
    Any(predicate?: (item: T) => boolean | Promise<boolean>): Promise<boolean>;
    All(predicate: (item: T) => boolean | Promise<boolean>): Promise<boolean>;

    // Set operations
    Distinct(keySelector?: (item: T) => any): AsyncEnumerable<T>;

    // Pagination
    Take(count: number): AsyncEnumerable<T>;
    Skip(count: number): AsyncEnumerable<T>;

    // Grouping
    GroupBy<K>(keySelector: (item: T) => K): AsyncEnumerable<Grouping<K, T>>;

    // Conversion
    ToArrayAsync(): Promise<T[]>;
    ToMapAsync<K, V>(
        keySelector: (item: T) => K,
        valueSelector: (item: T) => V,
    ): Promise<Map<K, V>>;

    // Custom aggregation
    Aggregate<R>(
        seed: R,
        accumulator: (acc: R, item: T) => R | Promise<R>,
        resultSelector?: (result: R) => R | Promise<R>,
    ): Promise<R>;
}
```

### BenchmarkUtils

Performance testing and optimization utilities.

```typescript
class BenchmarkUtils {
    // Comprehensive benchmarking
    static runComprehensiveBenchmark(
        dataSize: number,
    ): Promise<BenchmarkSummary>;
    static printBenchmarkSummary(summary: BenchmarkSummary): void;

    // Stress testing
    static runStressTest(dataSizes: number[]): Promise<void>;
    static runScalabilityTest(
        minSize: number,
        maxSize: number,
        steps: number,
    ): Promise<void>;
    static runEdgeCaseTests(): Promise<void>;
    static runFullBenchmarkSuite(): Promise<void>;

    // Custom benchmarking
    static benchmarkCustomOperation<T>(
        name: string,
        operation: () => Promise<T>,
        options?: BenchmarkOptions,
    ): Promise<BenchmarkResult>;

    static compareOperations(
        operations: OperationConfig[],
    ): Promise<ComparisonResult>;
    static printComparison(comparison: ComparisonResult): void;

    // Benchmark creation
    static createBenchmark(name: string): Benchmark;
}

interface BenchmarkOptions {
    iterations?: number;
    warmupIterations?: number;
    trackMemory?: boolean;
}

interface BenchmarkResult {
    name: string;
    averageTime: number;
    minTime: number;
    maxTime: number;
    memoryUsage: number;
    iterations: number;
}
```

## Next Steps

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