/**
 * @file DataLoader Batching
 * @description DataLoader-inspired request batching with automatic coalescing,
 * caching, deduplication, and GraphQL batch query support.
 * Optimized for microservices with N+1 query prevention.
 */
/**
 * Batch function that processes multiple keys at once
 */
export type BatchFunction<K, V> = (keys: K[]) => Promise<Map<K, V> | V[] | (V | Error)[]>;
/**
 * Cache key serializer
 */
export type KeySerializer<K> = (key: K) => string;
/**
 * DataLoader configuration
 */
export interface DataLoaderConfig<K, V> {
    /** Maximum items per batch */
    maxBatchSize?: number;
    /** Maximum wait time before executing batch (ms) */
    batchInterval?: number;
    /** Batch execution function */
    batchFn: BatchFunction<K, V>;
    /** Enable caching */
    cache?: boolean;
    /** Cache TTL (ms) */
    cacheTtl?: number;
    /** Key serializer for cache */
    keySerializer?: KeySerializer<K>;
    /** Handle batch errors */
    onBatchError?: (error: Error, keys: K[]) => void;
    /** Handle individual item errors */
    onItemError?: (error: Error, key: K) => void;
    /** Enable coalescing of identical requests */
    coalesce?: boolean;
    /** Schedule batch on next tick */
    batchScheduler?: (callback: () => void) => ReturnType<typeof setTimeout>;
}
/**
 * DataLoader statistics
 */
export interface DataLoaderStats {
    /** Total loads requested */
    totalLoads: number;
    /** Cache hits */
    cacheHits: number;
    /** Cache misses */
    cacheMisses: number;
    /** Batches executed */
    batchesExecuted: number;
    /** Average batch size */
    avgBatchSize: number;
    /** Coalesced requests */
    coalescedRequests: number;
    /** Current cache size */
    cacheSize: number;
}
/**
 * DataLoader for batching and caching requests
 * Inspired by Facebook's DataLoader pattern
 */
export declare class DataLoader<K, V> {
    private config;
    private batch;
    private cache;
    private batchTimer;
    private cacheCleanupTimer;
    private stats;
    constructor(config: DataLoaderConfig<K, V>);
    /**
     * Dispose of the loader and clean up resources
     */
    dispose(): void;
    /**
     * Load a single value by key
     */
    load(key: K): Promise<V>;
    /**
     * Load multiple values by keys
     */
    loadMany(keys: K[]): Promise<(V | Error)[]>;
    /**
     * Prime the cache with a value
     */
    prime(key: K, value: V): this;
    /**
     * Prime multiple values
     */
    primeMany(entries: Array<[K, V]>): this;
    /**
     * Clear a specific key from cache
     */
    clear(key: K): this;
    /**
     * Clear multiple keys from cache
     */
    clearMany(keys: K[]): this;
    /**
     * Clear all cached values
     */
    clearAll(): this;
    /**
     * Clear expired cache entries
     */
    clearExpired(): this;
    /**
     * Get loader statistics
     */
    getStats(): DataLoaderStats;
    /**
     * Reset statistics
     */
    resetStats(): this;
    /**
     * Schedule batch execution
     */
    private scheduleBatch;
    /**
     * Execute the current batch
     */
    private executeBatch;
    /**
     * Process Map results from batch function
     */
    private processMapResults;
    /**
     * Process Array results from batch function
     */
    private processArrayResults;
}
/**
 * Request deduplication configuration
 */
export interface DeduplicatorConfig {
    /** Deduplication window (ms) */
    window?: number;
    /** Key generator for requests */
    getKey?: (url: string, options?: RequestInit) => string;
}
/**
 * Request deduplicator for preventing duplicate concurrent requests
 */
export declare class RequestDeduplicator {
    private inFlight;
    private config;
    constructor(config?: DeduplicatorConfig);
    /**
     * Execute request with deduplication
     */
    execute<T>(key: string, requestFn: () => Promise<T>): Promise<T>;
    /**
     * Execute fetch with deduplication
     *
     * Note: This method intentionally uses raw fetch() rather than apiClient because:
     * 1. This is a low-level utility that wraps the fetch API for deduplication
     * 2. Users may want to use this with non-API endpoints
     * 3. The apiClient already has its own deduplication built-in
     *
     * For API calls, prefer using apiClient directly which provides retry,
     * authentication, and error handling out of the box.
     *
     * @see {@link @/lib/api/api-client} for the recommended API client
     */
    fetch<T>(url: string, options?: RequestInit): Promise<T>;
    /**
     * Clear all in-flight requests
     */
    clear(): void;
    /**
     * Get deduplication statistics
     */
    getStats(): {
        inFlight: number;
    };
}
/**
 * GraphQL operation
 */
export interface GraphQLOperation {
    id: string;
    query: string;
    variables?: Record<string, unknown> | undefined;
    operationName?: string | undefined;
}
/**
 * GraphQL batch response
 */
export interface GraphQLBatchResponse {
    id: string;
    data?: unknown;
    errors?: Array<{
        message: string;
        path?: Array<string | number>;
    }>;
}
/**
 * GraphQL batcher configuration
 */
export interface GraphQLBatcherConfig {
    /** GraphQL endpoint */
    endpoint: string;
    /** Maximum batch size */
    maxBatchSize?: number;
    /** Batch interval (ms) */
    batchInterval?: number;
    /** Request headers */
    headers?: Record<string, string>;
    /** Fetch function */
    fetchFn?: typeof fetch;
}
/**
 * GraphQL request batcher
 */
export declare class GraphQLBatcher {
    private queries;
    private batchTimer;
    private config;
    constructor(config: GraphQLBatcherConfig);
    /**
     * Execute a GraphQL query
     */
    query<T>(query: string, variables?: Record<string, unknown>, operationName?: string): Promise<T>;
    /**
     * Execute a GraphQL mutation (not batched by default)
     */
    mutate<T>(mutation: string, variables?: Record<string, unknown>, operationName?: string): Promise<T>;
    /**
     * Flush pending queries immediately
     */
    flush(): Promise<void>;
    /**
     * Schedule batch execution
     */
    private scheduleBatch;
    /**
     * Execute batched queries
     */
    private executeBatch;
}
/**
 * Create a DataLoader for fetching resources by ID
 */
export declare function createResourceLoader<T extends {
    id: string;
}>(fetchMany: (ids: string[]) => Promise<T[]>, config?: Partial<DataLoaderConfig<string, T>>): DataLoader<string, T>;
/**
 * Create a DataLoader with automatic key serialization
 */
export declare function createKeyedLoader<K extends Record<string, unknown>, V>(batchFn: (keys: K[]) => Promise<Map<K, V> | V[]>, config?: Partial<DataLoaderConfig<K, V>>): DataLoader<K, V>;
/**
 * Global request deduplicator
 */
export declare const globalDeduplicator: RequestDeduplicator;
/**
 * Deduplicated fetch function
 */
export declare function deduplicatedFetch<T>(url: string, options?: RequestInit): Promise<T>;