/**
 * Performance benchmarking utilities for CLI operations.
 *
 * Provides timing measurement and optional logging for tracking
 * execution duration of key operations.
 */
/**
 * Result of a benchmarked operation
 */
export interface BenchmarkResult<T> {
    /** The result returned by the benchmarked function */
    result: T;
    /** Execution duration in milliseconds */
    durationMs: number;
    /** Human-readable duration string */
    durationFormatted: string;
}
/**
 * Options for benchmark execution
 */
export interface BenchmarkOptions {
    /** Label for the operation being benchmarked */
    label?: string;
    /** Whether to log timing to console */
    log?: boolean;
    /** Custom logger function (defaults to console.log) */
    logger?: (message: string) => void;
}
/**
 * Formats a duration in milliseconds to a human-readable string.
 *
 * @param ms - Duration in milliseconds
 * @returns Formatted duration string (e.g., "1.23s", "456ms")
 */
export declare function formatDuration(ms: number): string;
/**
 * Measures the execution time of a synchronous function.
 *
 * @param fn - The function to benchmark
 * @param options - Optional benchmark configuration
 * @returns The function result along with timing information
 *
 * @example
 * ```ts
 * const { result, durationMs } = benchmarkSync(() => {
 *   return heavyComputation();
 * }, { label: 'Heavy computation', log: true });
 * ```
 */
export declare function benchmarkSync<T>(fn: () => T, options?: BenchmarkOptions): BenchmarkResult<T>;
/**
 * Measures the execution time of an asynchronous function.
 *
 * @param fn - The async function to benchmark
 * @param options - Optional benchmark configuration
 * @returns Promise resolving to the function result along with timing information
 *
 * @example
 * ```ts
 * const { result, durationMs } = await benchmark(async () => {
 *   return await fetchData();
 * }, { label: 'API fetch', log: true });
 * ```
 */
export declare function benchmark<T>(fn: () => Promise<T>, options?: BenchmarkOptions): Promise<BenchmarkResult<T>>;
/**
 * Creates a timer for manual timing control.
 *
 * @returns Timer object with start, stop, and elapsed methods
 *
 * @example
 * ```ts
 * const timer = createTimer();
 * timer.start();
 * // ... do work ...
 * const elapsed = timer.stop();
 * console.log(`Operation took ${elapsed.durationFormatted}`);
 * ```
 */
export declare function createTimer(): {
    start: () => void;
    stop: () => {
        durationMs: number;
        durationFormatted: string;
    };
    elapsed: () => number;
    isRunning: () => boolean;
};
/**
 * Aggregates multiple benchmark results for statistical analysis.
 */
export interface BenchmarkStats {
    /** Number of samples */
    count: number;
    /** Total duration in milliseconds */
    totalMs: number;
    /** Average duration in milliseconds */
    avgMs: number;
    /** Minimum duration in milliseconds */
    minMs: number;
    /** Maximum duration in milliseconds */
    maxMs: number;
    /** Formatted average duration */
    avgFormatted: string;
}
/**
 * Calculates statistics from an array of benchmark durations.
 *
 * @param durations - Array of duration values in milliseconds
 * @returns Statistical summary of the benchmarks
 *
 * @example
 * ```ts
 * const durations = [100, 150, 120, 130, 110];
 * const stats = calculateStats(durations);
 * console.log(`Average: ${stats.avgFormatted}`);
 * ```
 */
export declare function calculateStats(durations: number[]): BenchmarkStats;