/**
 * Benchmarking library.
 *
 * @example
 * ```ts
 * import {Benchmark} from './benchmark.js';
 *
 * const bench = new Benchmark({
 *   duration_ms: 5000,
 *   warmup_iterations: 5,
 * });
 *
 * bench
 *   .add('slugify', () => slugify(title))
 *   .add('slugify_slower', () => slugify_slower(title));
 *
 * const results = await bench.run();
 * console.log(bench.table());
 * ```
 *
 * @module
 */
import { type BenchmarkFormatJsonOptions } from './benchmark_format.js';
import type { BenchmarkConfig, BenchmarkTask, BenchmarkResult, BenchmarkFormatTableOptions } from './benchmark_types.js';
/**
 * Warmup function by running it multiple times.
 * Detects whether the function is async based on return value.
 *
 * When no `async_hint` is provided, at least one detection iteration runs even
 * if `iterations` is 0 — otherwise async detection would be impossible and
 * async functions would have their returned promises leaked as unhandled.
 *
 * @param fn - function to warmup (sync or async)
 * @param async_hint - if provided, use this instead of detecting
 * @returns whether the function is async
 *
 * @example
 * ```ts
 * const is_async = await benchmark_warmup(() => expensive_operation(), 10);
 * ```
 */
export declare const benchmark_warmup: (fn: () => unknown, iterations: number, async_hint?: boolean) => Promise<boolean>;
/**
 * Benchmark class for measuring and comparing function performance.
 */
export declare class Benchmark {
    #private;
    constructor(config?: BenchmarkConfig);
    /**
     * Add a benchmark task.
     * @param name - task name or full task object
     * @param fn - Function to benchmark (if name is string). Return values are ignored.
     * @returns this `Benchmark` instance for chaining
     * @throws Error if a task with the same name already exists, or if `fn` is missing when `name` is a string
     *
     * @example
     * ```ts
     * bench.add('simple', () => fn());
     *
     * // Or with setup/teardown:
     * bench.add({
     *   name: 'with setup',
     *   fn: () => process(data),
     *   setup: () => { data = load() },
     *   teardown: () => { cleanup() },
     * });
     * ```
     */
    add(name: string, fn: () => unknown): this;
    add(task: BenchmarkTask): this;
    /**
     * Remove a benchmark task by name.
     * @returns this `Benchmark` instance for chaining
     * @throws Error if task with given name doesn't exist
     *
     * @example
     * ```ts
     * bench.add('task1', () => fn1());
     * bench.add('task2', () => fn2());
     * bench.remove('task1');
     * // Only task2 remains
     * ```
     */
    remove(name: string): this;
    /**
     * Run all benchmark tasks.
     *
     * Tasks execute in `add()` order. The first task runs against a colder
     * runtime than subsequent ones (uncompiled JS, cold caches) — a
     * property of in-process benchmarking that matters more when an early
     * task has aggressive overrides like low `warmup_iterations` or
     * `min_iterations`. If first-position bias is a concern, put a
     * throwaway warm-up task first, or call `run()` twice and use the
     * second result set.
     */
    run(): Promise<Array<BenchmarkResult>>;
    /**
     * Format results as an ASCII table with percentiles, min/max, and relative performance.
     *
     * @example
     * ```ts
     * // Standard table
     * console.log(bench.table());
     *
     * // Grouped by category
     * console.log(bench.table({
     *   groups: [
     *     { name: 'FAST PATHS', filter: (r) => r.name.includes('fast') },
     *     { name: 'SLOW PATHS', filter: (r) => r.name.includes('slow') },
     *   ]
     * }));
     * ```
     */
    table(options?: BenchmarkFormatTableOptions): string;
    /**
     * Format results as a Markdown table.
     * @param options - formatting options (groups for organized output with optional baselines)
     * @returns formatted markdown string
     *
     * @example
     * ```ts
     * // Standard table
     * console.log(bench.markdown());
     *
     * // Grouped by category with custom baseline
     * console.log(bench.markdown({
     *   groups: [
     *     { name: 'Format', filter: (r) => r.name.startsWith('format/'), baseline: 'format/prettier' },
     *     { name: 'Parse', filter: (r) => r.name.startsWith('parse/') },
     *   ]
     * }));
     * ```
     */
    markdown(options?: BenchmarkFormatTableOptions): string;
    /**
     * Format results as JSON.
     * @param options - formatting options (pretty, include_timings)
     * @returns JSON string
     */
    json(options?: BenchmarkFormatJsonOptions): string;
    /**
     * Get the benchmark results.
     * @returns shallow copy of the results array (prevents external mutation)
     */
    results(): Array<BenchmarkResult>;
    /**
     * Check if the benchmark has been run and has results.
     * @returns true if results are available
     *
     * @example
     * ```ts
     * if (bench.has_results) {
     *   console.log(bench.table());
     * }
     * ```
     */
    get has_results(): boolean;
    /**
     * Get results as a map for convenient lookup by task name.
     * @returns fresh `Map` of task name to benchmark result (prevents external mutation)
     *
     * @example
     * ```ts
     * const results_map = bench.results_by_name();
     * const slugify_result = results_map.get('slugify');
     * if (slugify_result) {
     *   console.log(`slugify: ${slugify_result.stats.ops_per_second} ops/sec`);
     * }
     * ```
     */
    results_by_name(): Map<string, BenchmarkResult>;
    /**
     * Reset the benchmark results.
     * Keeps tasks intact so benchmarks can be rerun.
     * @returns this `Benchmark` instance for chaining
     */
    reset(): this;
    /**
     * Clear everything (results and tasks).
     * @returns this `Benchmark` instance for chaining
     */
    clear(): this;
    /**
     * Get a quick text summary of the fastest task.
     * @returns human-readable summary string
     *
     * @example
     * ```ts
     * console.log(bench.summary());
     * // "Fastest: slugify_v2 (1,285,515.00 ops/sec, 786.52ns per op)"
     * // "Slowest: slugify (252,955.00 ops/sec, 3.95μs per op)"
     * // "Speed difference: 5.08x"
     * ```
     */
    summary(): string;
}
//# sourceMappingURL=benchmark.d.ts.map