/**
 * ===============================================================================
 * BATCH OPERATION UTILITIES
 * ===============================================================================
 *
 * Utilities for running batch operations that return Results.
 * Provides consistent handling of multiple operations with timing
 * metadata and summary statistics.
 *
 * ===============================================================================
 */
import type { Result, BatchResult, BatchResultEntry } from './types.js';
/**
 * Creates a BatchResult from an array of keyed results.
 *
 * @param results - Array of keyed results
 * @param startTime - Start timestamp for calculating execution time
 * @returns A complete BatchResult with summary statistics
 *
 * @example
 * ```typescript
 * const startTime = Date.now();
 * const results = items.map(item => ({
 *   key: item.id,
 *   result: processItem(item)
 * }));
 * const batchResult = createBatchResult(results, startTime);
 * ```
 */
export declare function createBatchResult<T>(results: Array<BatchResultEntry<T>>, startTime: number): BatchResult<T>;
/**
 * Options for batch execution.
 */
export interface BatchExecutionOptions {
    /** Stop processing on first failure */
    stopOnFirstError?: boolean;
    /** Maximum number of concurrent operations (default: no limit) */
    concurrency?: number;
    /** Timeout for each individual operation in ms */
    operationTimeoutMs?: number;
    /** Continue processing even if some operations fail */
    continueOnError?: boolean;
}
/**
 * Runs a batch operation over an array of items.
 *
 * @param items - Array of items to process
 * @param keyFn - Function to extract a unique key from each item
 * @param operation - Async function that processes each item and returns a Result
 * @param options - Batch execution options
 * @returns A BatchResult containing all individual results and summary
 *
 * @example
 * ```typescript
 * const batchResult = await runBatch(
 *   users,
 *   user => user.id,
 *   async user => validateUser(user)
 * );
 *
 * if (batchResult.allSucceeded) {
 *   console.log('All users validated');
 * } else {
 *   console.log(`Failed: ${batchResult.failedKeys.join(', ')}`);
 * }
 * ```
 */
export declare function runBatch<T, R>(items: T[], keyFn: (item: T) => string, operation: (item: T) => Promise<Result<R>>, options?: BatchExecutionOptions): Promise<BatchResult<R>>;
/**
 * Runs a synchronous batch operation over an array of items.
 *
 * @param items - Array of items to process
 * @param keyFn - Function to extract a unique key from each item
 * @param operation - Sync function that processes each item and returns a Result
 * @param options - Batch execution options
 * @returns A BatchResult containing all individual results and summary
 */
export declare function runBatchSync<T, R>(items: T[], keyFn: (item: T) => string, operation: (item: T) => Result<R>, options?: Pick<BatchExecutionOptions, 'stopOnFirstError'>): BatchResult<R>;
/**
 * Extracts all successful results from a BatchResult.
 *
 * @param batchResult - The batch result to extract from
 * @returns Array of successful data values with their keys
 */
export declare function extractSuccesses<T>(batchResult: BatchResult<T>): Array<{
    key: string;
    data: T;
}>;
/**
 * Extracts all failures from a BatchResult.
 *
 * @param batchResult - The batch result to extract from
 * @returns Array of failure errors with their keys
 */
export declare function extractFailures<T>(batchResult: BatchResult<T>): Array<{
    key: string;
    error: {
        code: string;
        message: string;
    };
}>;
/**
 * Gets a specific result by key from a BatchResult.
 *
 * @param batchResult - The batch result to search
 * @param key - The key to find
 * @returns The result for the given key, or undefined if not found
 */
export declare function getResultByKey<T>(batchResult: BatchResult<T>, key: string): Result<T> | undefined;
/**
 * Converts a BatchResult to a Map for easy lookup.
 *
 * @param batchResult - The batch result to convert
 * @returns A Map from key to Result
 */
export declare function toResultMap<T>(batchResult: BatchResult<T>): Map<string, Result<T>>;
/**
 * Filters a BatchResult to only include certain keys.
 *
 * @param batchResult - The batch result to filter
 * @param keys - Keys to include
 * @returns A new BatchResult with only the specified keys
 */
export declare function filterByKeys<T>(batchResult: BatchResult<T>, keys: string[]): BatchResult<T>;
/**
 * Merges multiple BatchResults into a single BatchResult.
 *
 * @param batchResults - Array of batch results to merge
 * @returns A combined BatchResult
 */
export declare function mergeBatchResults<T>(batchResults: Array<BatchResult<T>>): BatchResult<T>;
/**
 * Retries failed operations in a BatchResult.
 *
 * @param batchResult - The original batch result
 * @param items - Original items array (needed to re-run failed operations)
 * @param keyFn - Function to extract key from item
 * @param operation - The operation to retry
 * @param maxRetries - Maximum number of retry attempts per item
 * @returns A new BatchResult with retried operations
 */
export declare function retryFailed<T, R>(batchResult: BatchResult<R>, items: T[], keyFn: (item: T) => string, operation: (item: T) => Promise<Result<R>>, maxRetries?: number): Promise<BatchResult<R>>;
/**
 * Fluent builder for batch operations.
 * Provides a more readable way to configure and run batch operations.
 *
 * @example
 * ```typescript
 * const result = await batchBuilder(users)
 *   .keyBy(user => user.id)
 *   .withConcurrency(5)
 *   .stopOnFirstError()
 *   .run(async user => validateUser(user));
 * ```
 */
export declare function batchBuilder<T>(items: T[]): BatchBuilder<T>;
/**
 * Fluent builder class for batch operations.
 */
export declare class BatchBuilder<T> {
    private items;
    private options;
    private keyFunction?;
    constructor(items: T[]);
    /**
     * Sets the function to extract keys from items.
     */
    keyBy(fn: (item: T) => string): this;
    /**
     * Sets the maximum concurrency for parallel execution.
     */
    withConcurrency(limit: number): this;
    /**
     * Enables stopping on the first error.
     */
    stopOnFirstError(enabled?: boolean): this;
    /**
     * Sets a timeout for each individual operation.
     */
    withTimeout(ms: number): this;
    /**
     * Runs the batch operation.
     */
    run<R>(operation: (item: T) => Promise<Result<R>>): Promise<BatchResult<R>>;
    /**
     * Runs a synchronous batch operation.
     */
    runSync<R>(operation: (item: T) => Result<R>): BatchResult<R>;
}
//# sourceMappingURL=batch.d.ts.map