import type { BenchmarkReport, CompareOptions, ComparisonResult, OutputFormat, SuiteReport } from './types.js';
/**
 * Represents a function that handles the output of the comparison results.
 */
export type OutputHandler = (results: ComparisonResult[]) => void;
/**
 * Compares two benchmark reports and returns the comparison result.
 *
 * The function compares benchmark reports primarily using the independent two-sample t-test (Welch's t-test).
 * This is a good choice because:
 *
 * - **Compares Means**: It focuses on comparing the means (average execution times) of the two benchmark runs.
 * - **Considers Variability**: It takes into account the variability (standard deviation) within
 *   each benchmark's results.
 * - **Handles Unequal Variances**: Welch's t-test handles situations where the variances of the two samples
 *   are different.
 * - **Statistical Significance**: It provides a p-value, which helps determine if the observed difference between
 *   the means is likely due to a real difference in performance or just random chance.
 *
 * @param a The first benchmark report to compare.
 * @param b The second benchmark report to compare.
 * @returns The comparison result.
 */
export declare function compare(a: BenchmarkReport, b: BenchmarkReport): ComparisonResult;
/**
 * Compares the performance of a specific function across multiple suite reports, enabling time-series analysis.
 *
 * This function is designed to track how the performance of a single function changes over time.
 * It takes a function name and an array of `SuiteReport` objects, each representing a benchmark run at a different
 * point in time. It then extracts the benchmark results for the specified function from each suite report and
 * performs pairwise comparisons.
 *
 * **Time-Series Comparison:**
 *
 * The core idea is to treat each `SuiteReport` as a snapshot of performance at a particular time.
 * By comparing the same function across these snapshots, we can observe trends and identify performance
 * regressions or improvements.
 *
 * **Benefits:**
 *
 * - **Performance Tracking:** Easily monitor how changes to your code affect the performance of specific
 *   functions over time.
 * - **Regression Detection:** Quickly identify if a recent change has introduced a performance regression.
 * - **Improvement Validation:** Verify that optimizations have indeed improved performance.
 * - **Long-Term Analysis:** Analyze performance trends over extended periods.
 *
 * **How it Works:**
 *
 * 1.  **Function Identification:** It takes the name of the function you want to analyze.
 * 2.  **Report Extraction:** It searches each `SuiteReport` for a `BenchmarkReport` with the matching function name.
 * 3.  **Pairwise Comparison:** It performs pairwise comparisons between the extracted `BenchmarkReport` objects.
 *     Each comparison is done using the `compare` function, which uses a t-test to determine statistical significance.
 * 4.  **Trend Analysis:** By examining the results of the pairwise comparisons, you can infer whether the function's
 *     performance has improved, degraded, or remained the same over time.
 *
 * **Example:**
 *
 * Suppose you have three `SuiteReport` objects: `report_v1`, `report_v2`, and `report_v3`, representing benchmark
 * runs at different times. You want to see how the performance of the function `myFunction` has changed.
 *
 * ```typescript
 * compareFunction('myFunction', [report_v1, report_v2, report_v3]);
 * ```
 *
 * This will compare `myFunction` in `report_v1` vs. `report_v2`, `report_v1` vs. `report_v3`,
 * and `report_v2` vs. `report_v3`.
 *
 * **Further Improvements:**
 *
 * - **Visualization:** Consider adding a visualization of the comparison (e.g., a graph).
 * - **More Statistical Measures:** Consider adding more statistical measures (e.g., effect size) if needed.
 * - **CLI integration:** Add a CLI command to compare functions.
 *
 * @param functionName - The name of the function to compare.
 * @param suiteReports - An array of suite reports to compare against.
 * @param options - Options for the comparison.
 */
export declare function compareFunction(functionName: string, suiteReports: SuiteReport[], options?: CompareOptions): ComparisonResult[];
/**
 * Outputs the comparison results in the specified format.
 *
 * This function takes an array of `ComparisonResult` objects, produced by the `compareFunction`,
 * and outputs them to the console in the specified format. It supports 'table', 'json', and 'csv' formats.
 *
 * The 'table' format provides a human-readable, formatted table output to the console.
 * The 'json' format outputs the results as a JSON string.
 * The 'csv' format outputs the results as a comma-separated values string.
 *
 * If an invalid format is provided, it will log an error to the console and default to the 'table' format.
 *
 * @param results - An array of `ComparisonResult` objects to output.
 * @param format - The desired output format ('table', 'json', or 'csv').
 * @throws Will throw an error if the results array is empty.
 * @throws Will log an error to the console if the format is invalid.
 *
 * @example
 * ```typescript
 * import { compareFunction, outputCompareFunction, SuiteReport, OutputFormat } from '@pawel-up/benchmark';
 * import * as fs from 'fs/promises';
 *
 * async function main() {
 *   // Load suite reports from files (example)
 *   const suiteReport1 = JSON.parse(await fs.readFile('suite_report_1.json', 'utf-8')) as SuiteReport;
 *   const suiteReport2 = JSON.parse(await fs.readFile('suite_report_2.json', 'utf-8')) as SuiteReport;
 *   const suiteReport3 = JSON.parse(await fs.readFile('suite_report_3.json', 'utf-8')) as SuiteReport;
 *   const suiteReport4 = JSON.parse(await fs.readFile('suite_report_4.json', 'utf-8')) as SuiteReport;
 *
 *   const suiteReports = [suiteReport1, suiteReport2, suiteReport3, suiteReport4];
 *
 *   // Get the comparison results
 *   const results = compareFunction('myFunction', suiteReports);
 *
 *   // Output the results in JSON format
 *   outputCompareFunction(results, 'json');
 *
 *   // Output the results in CSV format
 *   outputCompareFunction(results, 'csv');
 *
 *   // Output the results in table format (default)
 *   outputCompareFunction(results, 'table');
 *
 *   // Output the results in an invalid format (will default to table)
 *   outputCompareFunction(results, 'invalid' as OutputFormat);
 * }
 *
 * main().catch(console.error);
 * ```
 */
export declare function outputCompareFunction(results: ComparisonResult[], format: OutputFormat): void;
/**
 * Compares two SuiteReport objects, comparing benchmarks with matching names.
 *
 * Outputs a single line for each comparison indicating whether there's a
 * significant difference and, if so, whether it's a regression or improvement.
 *
 * This function compares only benchmarks that have a matching name in both
 * SuiteReport objects. Benchmarks that are present in one suite but not the
 * other are skipped.
 *
 * @param suiteA - The first SuiteReport to compare (presumably the newer report).
 * @param suiteB - The second SuiteReport to compare (presumably the older report).
 * @param options - Options for the comparison (optional).
 */
export declare function compareSuites(suiteA: SuiteReport, suiteB: SuiteReport, options?: CompareOptions): void;
//# sourceMappingURL=compare.d.ts.map