/**
 * Benchmark utilities for performance testing
 *
 * Provides easy-to-use tools for measuring function performance,
 * memory usage, and creating performance comparisons.
 *
 * @example
 * ```typescript
 * import { benchmark, createBenchmarkSuite } from './benchmark';
 *
 * // Simple benchmark
 * const result = await benchmark('myFunction', () => myFunction(data));
 * console.log(`Duration: ${result.duration}ms`);
 *
 * // Benchmark suite
 * const suite = createBenchmarkSuite('Array Operations');
 * suite.add('native map', () => data.map(x => x * 2));
 * suite.add('custom map', () => customMap(data, x => x * 2));
 * await suite.run();
 * ```
 */
/**
 * Result of a benchmark measurement
 */
export type BenchmarkResult = {
    /** Name of the benchmark */
    name: string;
    /** Total duration in milliseconds */
    duration: number;
    /** Operations per second */
    opsPerSecond: number;
    /** Memory used in bytes (heap difference) */
    memoryUsed: number;
    /** Number of iterations run */
    iterations: number;
    /** Average duration per iteration in milliseconds */
    avgDuration: number;
    /** Standard deviation of durations */
    stdDev: number;
    /** Minimum duration observed */
    minDuration: number;
    /** Maximum duration observed */
    maxDuration: number;
};
/**
 * Configuration options for benchmarks
 */
export type BenchmarkOptions = {
    /** Number of iterations to run (default: 1) */
    iterations?: number;
    /** Number of warmup runs before measuring (default: 1) */
    warmupRuns?: number;
    /** Whether to force garbage collection between runs (default: false) */
    forceGC?: boolean;
    /** Whether to measure memory usage (default: true) */
    measureMemory?: boolean;
    /** Timeout in milliseconds for the entire benchmark (default: 30000) */
    timeout?: number;
};
/**
 * Benchmark function type
 */
export type BenchmarkFunction<T = unknown> = () => T | Promise<T>;
/**
 * Run a benchmark for a single function
 *
 * @param name - Name of the benchmark
 * @param fn - Function to benchmark
 * @param options - Benchmark configuration options
 * @returns Promise resolving to benchmark results
 *
 * @example
 * ```typescript
 * const result = await benchmark('Array.map', () => {
 *   return largeArray.map(x => x * 2);
 * }, { iterations: 10, warmupRuns: 3 });
 *
 * console.log(`${result.name}: ${result.avgDuration.toFixed(2)}ms avg`);
 * ```
 */
export declare function benchmark(name: string, fn: BenchmarkFunction, options?: BenchmarkOptions): Promise<BenchmarkResult>;
/**
 * Compare multiple functions with the same benchmark configuration
 *
 * @param benchmarks - Object with benchmark names and functions
 * @param options - Benchmark configuration options
 * @returns Promise resolving to array of benchmark results
 *
 * @example
 * ```typescript
 * const results = await compareBenchmarks({
 *   'native map': () => data.map(x => x * 2),
 *   'for loop': () => {
 *     const result = [];
 *     for (let i = 0; i < data.length; i++) {
 *       result.push(data[i] * 2);
 *     }
 *     return result;
 *   }
 * }, { iterations: 5 });
 *
 * results.forEach(result => {
 *   console.log(`${result.name}: ${result.avgDuration.toFixed(2)}ms`);
 * });
 * ```
 */
export declare function compareBenchmarks(benchmarks: Record<string, BenchmarkFunction>, options?: BenchmarkOptions): Promise<BenchmarkResult[]>;
/**
 * Benchmark suite for organizing and running multiple related benchmarks
 */
export declare class BenchmarkSuite {
    readonly suiteName: string;
    private benchmarks;
    private options;
    constructor(suiteName: string, options?: BenchmarkOptions);
    /**
     * Add a benchmark to the suite
     *
     * @param name - Name of the benchmark
     * @param fn - Function to benchmark
     * @returns This suite instance for chaining
     */
    add(name: string, fn: BenchmarkFunction): this;
    /**
     * Run all benchmarks in the suite
     *
     * @param customOptions - Override suite options for this run
     * @returns Promise resolving to array of benchmark results
     */
    run(customOptions?: BenchmarkOptions): Promise<BenchmarkResult[]>;
    /**
     * Get the number of benchmarks in the suite
     */
    get size(): number;
    /**
     * Clear all benchmarks from the suite
     */
    clear(): this;
}
/**
 * Create a new benchmark suite
 *
 * @param suiteName - Name of the benchmark suite
 * @param options - Default options for all benchmarks in the suite
 * @returns New BenchmarkSuite instance
 *
 * @example
 * ```typescript
 * const suite = createBenchmarkSuite('String Operations', {
 *   iterations: 10,
 *   warmupRuns: 2
 * });
 *
 * suite
 *   .add('concat', () => str1 + str2)
 *   .add('template', () => `${str1}${str2}`)
 *   .add('join', () => [str1, str2].join(''));
 *
 * await suite.run();
 * ```
 */
export declare function createBenchmarkSuite(suiteName: string, options?: BenchmarkOptions): BenchmarkSuite;
/**
 * Utility to measure memory usage of a function
 *
 * @param fn - Function to measure
 * @param forceGC - Whether to force garbage collection before measuring
 * @returns Memory usage in bytes
 *
 * @example
 * ```typescript
 * const memoryUsed = await measureMemory(() => {
 *   return new Array(100000).fill(0).map(x => ({ value: x }));
 * });
 *
 * console.log(`Memory used: ${(memoryUsed / 1024 / 1024).toFixed(2)}MB`);
 * ```
 */
export declare function measureMemory(fn: BenchmarkFunction, forceGC?: boolean): Promise<number>;
//# sourceMappingURL=benchmark.d.ts.map