@fuzdev/fuz_util 0.42.0 → 0.44.0

package/dist/benchmark_format.js

@@ -0,0 +1,266 @@
+import { time_unit_detect_best, time_format, TIME_UNIT_DISPLAY } from './time.js';
+import { string_display_width, pad_width } from './string.js';
+import { format_number } from './maths.js';
+/**
+ * Format results as an ASCII table with percentiles, min/max, and relative performance.
+ * All times use the same unit for easy comparison.
+ * @param results - Array of benchmark results
+ * @returns Formatted table string with enhanced metrics
+ *
+ * @example
+ * ```ts
+ * console.log(benchmark_format_table(results));
+ * // ┌─────────────┬────────────┬────────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┐
+ * // │ Task Name   │  ops/sec   │ median(μs) │ p75 (μs) │ p90 (μs) │ p95 (μs) │ p99 (μs) │ min (μs) │ max (μs) │ vs Best  │
+ * // ├─────────────┼────────────┼────────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┤
+ * // │ slugify v2  │ 1,237,144  │    0.81    │   0.85   │   0.89   │   0.95   │   1.20   │   0.72   │    2.45  │ baseline │
+ * // │ slugify     │   261,619  │    3.82    │   3.95   │   4.12   │   4.35   │   5.10   │   3.21   │   12.45  │   4.73x  │
+ * // └─────────────┴────────────┴────────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┘
+ * ```
+ */
+export const benchmark_format_table = (results) => {
+    if (results.length === 0)
+        return '(no results)';
+    // Detect best unit for all results
+    const mean_times = results.map((r) => r.stats.mean_ns);
+    const unit = time_unit_detect_best(mean_times);
+    const unit_str = TIME_UNIT_DISPLAY[unit];
+    // Find fastest for relative comparison
+    const fastest_ops = Math.max(...results.map((r) => r.stats.ops_per_second));
+    const rows = [];
+    // Header with unit
+    rows.push([
+        'Task Name',
+        'ops/sec',
+        `median (${unit_str})`,
+        `p75 (${unit_str})`,
+        `p90 (${unit_str})`,
+        `p95 (${unit_str})`,
+        `p99 (${unit_str})`,
+        `min (${unit_str})`,
+        `max (${unit_str})`,
+        'vs Best',
+    ]);
+    // Data rows - all use same unit
+    results.forEach((r) => {
+        const ops_sec = benchmark_format_number(r.stats.ops_per_second, 2);
+        const median = time_format(r.stats.median_ns, unit, 2).replace(unit_str, '').trim();
+        const p75 = time_format(r.stats.p75_ns, unit, 2).replace(unit_str, '').trim();
+        const p90 = time_format(r.stats.p90_ns, unit, 2).replace(unit_str, '').trim();
+        const p95 = time_format(r.stats.p95_ns, unit, 2).replace(unit_str, '').trim();
+        const p99 = time_format(r.stats.p99_ns, unit, 2).replace(unit_str, '').trim();
+        const min = time_format(r.stats.min_ns, unit, 2).replace(unit_str, '').trim();
+        const max = time_format(r.stats.max_ns, unit, 2).replace(unit_str, '').trim();
+        // Calculate relative performance
+        const ratio = fastest_ops / r.stats.ops_per_second;
+        const vs_best = ratio === 1.0 ? 'baseline' : `${ratio.toFixed(2)}x`;
+        rows.push([r.name, ops_sec, median, p75, p90, p95, p99, min, max, vs_best]);
+    });
+    // Calculate column widths (using display width for proper emoji handling)
+    const widths = rows[0].map((_, col_i) => {
+        return Math.max(...rows.map((row) => string_display_width(row[col_i])));
+    });
+    // Build table
+    const lines = [];
+    // Top border
+    lines.push('┌' + widths.map((w) => '─'.repeat(w + 2)).join('┬') + '┐');
+    // Header
+    const header = rows[0].map((cell, i) => ' ' + pad_width(cell, widths[i]) + ' ').join('│');
+    lines.push('│' + header + '│');
+    // Header separator
+    lines.push('├' + widths.map((w) => '─'.repeat(w + 2)).join('┼') + '┤');
+    // Data rows
+    for (let i = 1; i < rows.length; i++) {
+        const row = rows[i].map((cell, col_i) => {
+            const width = widths[col_i];
+            // Left-align task name, right-align numbers
+            if (col_i === 0) {
+                return ' ' + pad_width(cell, width, 'left') + ' ';
+            }
+            else {
+                return ' ' + pad_width(cell, width, 'right') + ' ';
+            }
+        }).join('│');
+        lines.push('│' + row + '│');
+    }
+    // Bottom border
+    lines.push('└' + widths.map((w) => '─'.repeat(w + 2)).join('┴') + '┘');
+    return lines.join('\n');
+};
+/**
+ * Format results as a Markdown table with key metrics.
+ * All times use the same unit for easy comparison.
+ * @param results - Array of benchmark results
+ * @returns Formatted markdown table string
+ *
+ * @example
+ * ```ts
+ * console.log(benchmark_format_markdown(results));
+ * // | Task Name  | ops/sec    | median (μs) | p75 (μs) | p90 (μs) | p95 (μs) | p99 (μs) | min (μs) | max (μs) | vs Best  |
+ * // |------------|------------|-------------|----------|----------|----------|----------|----------|----------|----------|
+ * // | slugify v2 | 1,237,144  | 0.81        | 0.85     | 0.89     | 0.95     | 1.20     | 0.72     | 2.45     | baseline |
+ * // | slugify    |   261,619  | 3.82        | 3.95     | 4.12     | 4.35     | 5.10     | 3.21     | 12.45    | 4.73x    |
+ * ```
+ */
+export const benchmark_format_markdown = (results) => {
+    if (results.length === 0)
+        return '(no results)';
+    // Detect best unit for all results
+    const mean_times = results.map((r) => r.stats.mean_ns);
+    const unit = time_unit_detect_best(mean_times);
+    const unit_str = TIME_UNIT_DISPLAY[unit];
+    // Find fastest for relative comparison
+    const fastest_ops = Math.max(...results.map((r) => r.stats.ops_per_second));
+    const rows = [];
+    // Header with unit
+    rows.push([
+        'Task Name',
+        'ops/sec',
+        `median (${unit_str})`,
+        `p75 (${unit_str})`,
+        `p90 (${unit_str})`,
+        `p95 (${unit_str})`,
+        `p99 (${unit_str})`,
+        `min (${unit_str})`,
+        `max (${unit_str})`,
+        'vs Best',
+    ]);
+    // Data rows - all use same unit
+    results.forEach((r) => {
+        const ops_sec = benchmark_format_number(r.stats.ops_per_second, 2);
+        const median = time_format(r.stats.median_ns, unit, 2).replace(unit_str, '').trim();
+        const p75 = time_format(r.stats.p75_ns, unit, 2).replace(unit_str, '').trim();
+        const p90 = time_format(r.stats.p90_ns, unit, 2).replace(unit_str, '').trim();
+        const p95 = time_format(r.stats.p95_ns, unit, 2).replace(unit_str, '').trim();
+        const p99 = time_format(r.stats.p99_ns, unit, 2).replace(unit_str, '').trim();
+        const min = time_format(r.stats.min_ns, unit, 2).replace(unit_str, '').trim();
+        const max = time_format(r.stats.max_ns, unit, 2).replace(unit_str, '').trim();
+        // Calculate relative performance
+        const ratio = fastest_ops / r.stats.ops_per_second;
+        const vs_best = ratio === 1.0 ? 'baseline' : `${ratio.toFixed(2)}x`;
+        rows.push([r.name, ops_sec, median, p75, p90, p95, p99, min, max, vs_best]);
+    });
+    // Calculate column widths
+    const widths = rows[0].map((_, col_i) => {
+        return Math.max(...rows.map((row) => row[col_i].length));
+    });
+    // Build table
+    const lines = [];
+    // Header
+    const header = rows[0].map((cell, i) => cell.padEnd(widths[i])).join(' | ');
+    lines.push('| ' + header + ' |');
+    // Separator
+    const separator = widths.map((w) => '-'.repeat(w)).join(' | ');
+    lines.push('| ' + separator + ' |');
+    // Data rows
+    for (let i = 1; i < rows.length; i++) {
+        const row = rows[i].map((cell, col_i) => {
+            const width = widths[col_i];
+            // Right-align numbers, left-align names
+            if (col_i === 0) {
+                return cell.padEnd(width);
+            }
+            else {
+                return cell.padStart(width);
+            }
+        }).join(' | ');
+        lines.push('| ' + row + ' |');
+    }
+    return lines.join('\n');
+};
+/**
+ * Format results as JSON.
+ * @param results - Array of benchmark results
+ * @param options - Formatting options
+ * @returns JSON string
+ *
+ * @example
+ * ```ts
+ * console.log(format_json(results));
+ * console.log(format_json(results, {pretty: false}));
+ * console.log(format_json(results, {include_timings: true}));
+ * ```
+ */
+export const benchmark_format_json = (results, options) => {
+    const pretty = options?.pretty ?? true;
+    const include_timings = options?.include_timings ?? false;
+    // Flatten stats into result object for easier consumption
+    const flattened = results.map((r) => ({
+        name: r.name,
+        iterations: r.iterations,
+        total_time_ms: r.total_time_ms,
+        ops_per_second: r.stats.ops_per_second,
+        mean_ns: r.stats.mean_ns,
+        median_ns: r.stats.median_ns,
+        std_dev_ns: r.stats.std_dev_ns,
+        min_ns: r.stats.min_ns,
+        max_ns: r.stats.max_ns,
+        p75_ns: r.stats.p75_ns,
+        p90_ns: r.stats.p90_ns,
+        p95_ns: r.stats.p95_ns,
+        p99_ns: r.stats.p99_ns,
+        cv: r.stats.cv,
+        confidence_interval_ns: r.stats.confidence_interval_ns,
+        outliers: r.stats.outliers_ns.length,
+        outlier_ratio: r.stats.outlier_ratio,
+        sample_size: r.stats.sample_size,
+        raw_sample_size: r.stats.raw_sample_size,
+        failed_iterations: r.stats.failed_iterations,
+        ...(include_timings ? { timings_ns: r.timings_ns } : {}),
+    }));
+    return pretty ? JSON.stringify(flattened, null, 2) : JSON.stringify(flattened);
+};
+/**
+ * Format results as a grouped table with visual separators between groups.
+ * @param results - Array of benchmark results
+ * @param groups - Array of group definitions
+ * @returns Formatted table string with group separators
+ *
+ * @example
+ * ```ts
+ * const groups = [
+ *   { name: 'FAST PATHS', filter: (r) => r.name.includes('fast') },
+ *   { name: 'SLOW PATHS', filter: (r) => r.name.includes('slow') },
+ * ];
+ * console.log(benchmark_format_table_grouped(results, groups));
+ * // 📦 FAST PATHS
+ * // ┌────┬─────────────┬────────────┬...┐
+ * // │ 🐆 │ fast test 1 │ 1,237,144  │...│
+ * // │ 🐇 │ fast test 2 │   261,619  │...│
+ * // └────┴─────────────┴────────────┴...┘
+ * //
+ * // 📦 SLOW PATHS
+ * // ┌────┬─────────────┬────────────┬...┐
+ * // │ 🐢 │ slow test 1 │    10,123  │...│
+ * // └────┴─────────────┴────────────┴...┘
+ * ```
+ */
+export const benchmark_format_table_grouped = (results, groups) => {
+    if (results.length === 0)
+        return '(no results)';
+    const sections = [];
+    for (const group of groups) {
+        const group_results = results.filter(group.filter);
+        if (group_results.length === 0)
+            continue;
+        // Add group header and table
+        const header = group.description
+            ? `\n📦 ${group.name}\n   ${group.description}`
+            : `\n📦 ${group.name}`;
+        sections.push(header);
+        sections.push(benchmark_format_table(group_results));
+    }
+    // Handle ungrouped results (those that don't match any group)
+    const grouped_names = new Set(groups.flatMap((g) => results.filter(g.filter).map((r) => r.name)));
+    const ungrouped = results.filter((r) => !grouped_names.has(r.name));
+    if (ungrouped.length > 0) {
+        sections.push('\n📦 Other');
+        sections.push(benchmark_format_table(ungrouped));
+    }
+    return sections.join('\n');
+};
+/**
+ * Format a number with fixed decimal places and thousands separators.
+ * @see {@link format_number} in maths.ts for the underlying implementation.
+ */
+export const benchmark_format_number = format_number;

package/dist/benchmark_stats.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Benchmark-specific statistical analysis.
+ * Uses the general stats utilities from stats.ts for timing/performance analysis.
+ * All timing values are in nanoseconds.
+ */
+/**
+ * Minimal stats interface for comparison.
+ * This allows comparing stats from different sources (e.g., loaded baselines).
+ */
+export interface BenchmarkStatsComparable {
+    mean_ns: number;
+    std_dev_ns: number;
+    sample_size: number;
+    confidence_interval_ns: [number, number];
+}
+/**
+ * Effect size magnitude interpretation (Cohen's d).
+ */
+export type EffectMagnitude = 'negligible' | 'small' | 'medium' | 'large';
+/**
+ * Result from comparing two benchmark stats.
+ */
+export interface BenchmarkComparison {
+    /** Which benchmark is faster ('a', 'b', or 'equal' if difference is negligible) */
+    faster: 'a' | 'b' | 'equal';
+    /** How much faster the winner is (e.g., 1.5 means 1.5x faster) */
+    speedup_ratio: number;
+    /** Whether the difference is statistically significant at the given alpha */
+    significant: boolean;
+    /** P-value from Welch's t-test (lower = more confident the difference is real) */
+    p_value: number;
+    /** Cohen's d effect size (magnitude of difference independent of sample size) */
+    effect_size: number;
+    /** Interpretation of effect size */
+    effect_magnitude: EffectMagnitude;
+    /** Whether the 95% confidence intervals overlap */
+    ci_overlap: boolean;
+    /** Human-readable interpretation of the comparison */
+    recommendation: string;
+}
+/**
+ * Options for benchmark comparison.
+ */
+export interface BenchmarkCompareOptions {
+    /** Significance level for hypothesis testing (default: 0.05) */
+    alpha?: number;
+}
+/**
+ * Complete statistical analysis of timing measurements.
+ * Includes outlier detection, descriptive statistics, and performance metrics.
+ * All timing values are in nanoseconds.
+ */
+export declare class BenchmarkStats {
+    /** Mean (average) time in nanoseconds */
+    readonly mean_ns: number;
+    /** Median time in nanoseconds */
+    readonly median_ns: number;
+    /** Standard deviation in nanoseconds */
+    readonly std_dev_ns: number;
+    /** Minimum time in nanoseconds */
+    readonly min_ns: number;
+    /** Maximum time in nanoseconds */
+    readonly max_ns: number;
+    /** 75th percentile in nanoseconds */
+    readonly p75_ns: number;
+    /** 90th percentile in nanoseconds */
+    readonly p90_ns: number;
+    /** 95th percentile in nanoseconds */
+    readonly p95_ns: number;
+    /** 99th percentile in nanoseconds */
+    readonly p99_ns: number;
+    /** Coefficient of variation (std_dev / mean) */
+    readonly cv: number;
+    /** 95% confidence interval for the mean in nanoseconds */
+    readonly confidence_interval_ns: [number, number];
+    /** Array of detected outlier values in nanoseconds */
+    readonly outliers_ns: Array<number>;
+    /** Ratio of outliers to total samples */
+    readonly outlier_ratio: number;
+    /** Number of samples after outlier removal */
+    readonly sample_size: number;
+    /** Original number of samples (before outlier removal) */
+    readonly raw_sample_size: number;
+    /** Operations per second (NS_PER_SEC / mean_ns) */
+    readonly ops_per_second: number;
+    /** Number of failed iterations (NaN, Infinity, or negative values) */
+    readonly failed_iterations: number;
+    constructor(timings_ns: Array<number>);
+    /**
+     * Format stats as a human-readable string.
+     */
+    toString(): string;
+}
+/**
+ * Compare two benchmark results for statistical significance.
+ * Uses Welch's t-test (handles unequal variances) and Cohen's d effect size.
+ *
+ * @param a - First benchmark stats (or any object with required properties)
+ * @param b - Second benchmark stats (or any object with required properties)
+ * @param options - Comparison options
+ * @returns Comparison result with significance, effect size, and recommendation
+ *
+ * @example
+ * ```ts
+ * const comparison = benchmark_stats_compare(result_a.stats, result_b.stats);
+ * if (comparison.significant) {
+ *   console.log(`${comparison.faster} is ${comparison.speedup_ratio.toFixed(2)}x faster`);
+ * }
+ * ```
+ */
+export declare const benchmark_stats_compare: (a: BenchmarkStatsComparable, b: BenchmarkStatsComparable, options?: BenchmarkCompareOptions) => BenchmarkComparison;
+//# sourceMappingURL=benchmark_stats.d.ts.map

package/dist/benchmark_stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark_stats.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/benchmark_stats.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAgBH;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE1E;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,mFAAmF;IACnF,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,OAAO,CAAC;IAC5B,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,WAAW,EAAE,OAAO,CAAC;IACrB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,gBAAgB,EAAE,eAAe,CAAC;IAClC,mDAAmD;IACnD,UAAU,EAAE,OAAO,CAAC;IACpB,sDAAsD;IACtD,cAAc,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,qBAAa,cAAc;IAC1B,yCAAyC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iCAAiC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wCAAwC;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,QAAQ,CAAC,sBAAsB,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD,sDAAsD;IACtD,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACpC,yCAAyC;IACzC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,mDAAmD;IACnD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,sEAAsE;IACtE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;gBAEvB,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC;IAiErC;;OAEG;IACH,QAAQ,IAAI,MAAM;CAGlB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uBAAuB,GACnC,GAAG,wBAAwB,EAC3B,GAAG,wBAAwB,EAC3B,UAAU,uBAAuB,KAC/B,mBA6GF,CAAC"}

package/dist/benchmark_stats.js

@@ -0,0 +1,219 @@
+/**
+ * Benchmark-specific statistical analysis.
+ * Uses the general stats utilities from stats.ts for timing/performance analysis.
+ * All timing values are in nanoseconds.
+ */
+import { TIME_NS_PER_SEC, time_format_adaptive } from './time.js';
+import { stats_mean, stats_median, stats_std_dev, stats_percentile, stats_cv, stats_min_max, stats_confidence_interval, stats_outliers_mad, stats_welch_t_test, stats_t_distribution_p_value, } from './stats.js';
+/**
+ * Complete statistical analysis of timing measurements.
+ * Includes outlier detection, descriptive statistics, and performance metrics.
+ * All timing values are in nanoseconds.
+ */
+export class BenchmarkStats {
+    /** Mean (average) time in nanoseconds */
+    mean_ns;
+    /** Median time in nanoseconds */
+    median_ns;
+    /** Standard deviation in nanoseconds */
+    std_dev_ns;
+    /** Minimum time in nanoseconds */
+    min_ns;
+    /** Maximum time in nanoseconds */
+    max_ns;
+    /** 75th percentile in nanoseconds */
+    p75_ns;
+    /** 90th percentile in nanoseconds */
+    p90_ns;
+    /** 95th percentile in nanoseconds */
+    p95_ns;
+    /** 99th percentile in nanoseconds */
+    p99_ns;
+    /** Coefficient of variation (std_dev / mean) */
+    cv;
+    /** 95% confidence interval for the mean in nanoseconds */
+    confidence_interval_ns;
+    /** Array of detected outlier values in nanoseconds */
+    outliers_ns;
+    /** Ratio of outliers to total samples */
+    outlier_ratio;
+    /** Number of samples after outlier removal */
+    sample_size;
+    /** Original number of samples (before outlier removal) */
+    raw_sample_size;
+    /** Operations per second (NS_PER_SEC / mean_ns) */
+    ops_per_second;
+    /** Number of failed iterations (NaN, Infinity, or negative values) */
+    failed_iterations;
+    constructor(timings_ns) {
+        // Filter out invalid values (NaN, Infinity, negative)
+        const valid_timings = [];
+        let failed_count = 0;
+        for (const t of timings_ns) {
+            if (!isNaN(t) && isFinite(t) && t > 0) {
+                valid_timings.push(t);
+            }
+            else {
+                failed_count++;
+            }
+        }
+        this.failed_iterations = failed_count;
+        this.raw_sample_size = timings_ns.length;
+        // If no valid timings, return empty stats
+        if (valid_timings.length === 0) {
+            this.mean_ns = NaN;
+            this.median_ns = NaN;
+            this.std_dev_ns = NaN;
+            this.min_ns = NaN;
+            this.max_ns = NaN;
+            this.p75_ns = NaN;
+            this.p90_ns = NaN;
+            this.p95_ns = NaN;
+            this.p99_ns = NaN;
+            this.cv = NaN;
+            this.confidence_interval_ns = [NaN, NaN];
+            this.outliers_ns = [];
+            this.outlier_ratio = 0;
+            this.sample_size = 0;
+            this.ops_per_second = 0;
+            return;
+        }
+        // Detect and remove outliers
+        const { cleaned, outliers } = stats_outliers_mad(valid_timings);
+        const sorted_cleaned = [...cleaned].sort((a, b) => a - b);
+        this.outliers_ns = outliers;
+        this.outlier_ratio = outliers.length / valid_timings.length;
+        this.sample_size = cleaned.length;
+        // Calculate statistics on cleaned data
+        this.mean_ns = stats_mean(cleaned);
+        this.median_ns = stats_median(sorted_cleaned);
+        this.std_dev_ns = stats_std_dev(cleaned, this.mean_ns);
+        const { min, max } = stats_min_max(sorted_cleaned);
+        this.min_ns = min;
+        this.max_ns = max;
+        this.p75_ns = stats_percentile(sorted_cleaned, 0.75);
+        this.p90_ns = stats_percentile(sorted_cleaned, 0.9);
+        this.p95_ns = stats_percentile(sorted_cleaned, 0.95);
+        this.p99_ns = stats_percentile(sorted_cleaned, 0.99);
+        this.cv = stats_cv(this.mean_ns, this.std_dev_ns);
+        this.confidence_interval_ns = stats_confidence_interval(cleaned);
+        // Calculate throughput (operations per second)
+        this.ops_per_second = this.mean_ns > 0 ? TIME_NS_PER_SEC / this.mean_ns : 0;
+    }
+    /**
+     * Format stats as a human-readable string.
+     */
+    toString() {
+        return `BenchmarkStats(mean=${time_format_adaptive(this.mean_ns)}, ops/sec=${this.ops_per_second.toFixed(2)}, cv=${(this.cv * 100).toFixed(1)}%, samples=${this.sample_size})`;
+    }
+}
+/**
+ * Compare two benchmark results for statistical significance.
+ * Uses Welch's t-test (handles unequal variances) and Cohen's d effect size.
+ *
+ * @param a - First benchmark stats (or any object with required properties)
+ * @param b - Second benchmark stats (or any object with required properties)
+ * @param options - Comparison options
+ * @returns Comparison result with significance, effect size, and recommendation
+ *
+ * @example
+ * ```ts
+ * const comparison = benchmark_stats_compare(result_a.stats, result_b.stats);
+ * if (comparison.significant) {
+ *   console.log(`${comparison.faster} is ${comparison.speedup_ratio.toFixed(2)}x faster`);
+ * }
+ * ```
+ */
+export const benchmark_stats_compare = (a, b, options) => {
+    const alpha = options?.alpha ?? 0.05;
+    // Handle edge cases
+    if (a.sample_size === 0 || b.sample_size === 0) {
+        return {
+            faster: 'equal',
+            speedup_ratio: 1,
+            significant: false,
+            p_value: 1,
+            effect_size: 0,
+            effect_magnitude: 'negligible',
+            ci_overlap: true,
+            recommendation: 'Insufficient data for comparison',
+        };
+    }
+    // Calculate speedup ratio (lower time = faster, so compare by time not ops/sec)
+    const speedup_ratio = a.mean_ns < b.mean_ns ? b.mean_ns / a.mean_ns : a.mean_ns / b.mean_ns;
+    const faster = a.mean_ns < b.mean_ns ? 'a' : a.mean_ns > b.mean_ns ? 'b' : 'equal';
+    // Welch's t-test (handles unequal variances)
+    // Special case: if both have zero variance, t-test is undefined
+    let p_value;
+    if (a.std_dev_ns === 0 && b.std_dev_ns === 0) {
+        // When there's no variance, any difference is 100% reliable (p=0) or identical (p=1)
+        p_value = a.mean_ns === b.mean_ns ? 1 : 0;
+    }
+    else {
+        const { t_statistic, degrees_of_freedom } = stats_welch_t_test(a.mean_ns, a.std_dev_ns, a.sample_size, b.mean_ns, b.std_dev_ns, b.sample_size);
+        // Calculate two-tailed p-value using t-distribution approximation
+        p_value = stats_t_distribution_p_value(Math.abs(t_statistic), degrees_of_freedom);
+    }
+    // Cohen's d effect size
+    const pooled_std_dev = Math.sqrt(((a.sample_size - 1) * a.std_dev_ns ** 2 + (b.sample_size - 1) * b.std_dev_ns ** 2) /
+        (a.sample_size + b.sample_size - 2));
+    // When pooled_std_dev is 0 but means differ, effect is maximal (infinite)
+    // When means are equal, effect is 0
+    let effect_size;
+    let effect_magnitude;
+    if (pooled_std_dev === 0) {
+        // Zero variance case - if means differ, it's a definitive difference
+        if (a.mean_ns === b.mean_ns) {
+            effect_size = 0;
+            effect_magnitude = 'negligible';
+        }
+        else {
+            // Any difference is 100% reliable when there's no variance
+            effect_size = Infinity;
+            effect_magnitude = 'large';
+        }
+    }
+    else {
+        effect_size = Math.abs(a.mean_ns - b.mean_ns) / pooled_std_dev;
+        // Interpret effect size (Cohen's conventions)
+        effect_magnitude =
+            effect_size < 0.2
+                ? 'negligible'
+                : effect_size < 0.5
+                    ? 'small'
+                    : effect_size < 0.8
+                        ? 'medium'
+                        : 'large';
+    }
+    // Check confidence interval overlap
+    const ci_overlap = a.confidence_interval_ns[0] <= b.confidence_interval_ns[1] &&
+        b.confidence_interval_ns[0] <= a.confidence_interval_ns[1];
+    // Determine significance
+    const significant = p_value < alpha;
+    // Generate recommendation
+    let recommendation;
+    if (!significant) {
+        recommendation =
+            effect_magnitude === 'negligible'
+                ? 'No meaningful difference detected'
+                : `Difference not statistically significant (p=${p_value.toFixed(3)}), but effect size suggests ${effect_magnitude} practical difference`;
+    }
+    else if (effect_magnitude === 'negligible') {
+        recommendation = `Statistically significant but negligible practical difference (${speedup_ratio.toFixed(2)}x)`;
+    }
+    else {
+        recommendation = `${faster === 'a' ? 'First' : 'Second'} is ${speedup_ratio.toFixed(2)}x faster with ${effect_magnitude} effect size (p=${p_value.toFixed(3)})`;
+    }
+    // Adjust 'faster' to 'equal' if effect is negligible
+    const adjusted_faster = effect_magnitude === 'negligible' ? 'equal' : faster;
+    return {
+        faster: adjusted_faster,
+        speedup_ratio,
+        significant,
+        p_value,
+        effect_size,
+        effect_magnitude,
+        ci_overlap,
+        recommendation,
+    };
+};