@fuzdev/fuz_util 0.42.0 → 0.44.0

package/src/lib/benchmark_format.ts

@@ -0,0 +1,314 @@
+import type {BenchmarkResult, BenchmarkGroup} from './benchmark_types.js';
+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: Array<BenchmarkResult>): string => {
+	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: Array<Array<string>> = [];
+
+	// 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: Array<string> = [];
+
+	// 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: Array<BenchmarkResult>): string => {
+	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: Array<Array<string>> = [];
+
+	// 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: Array<string> = [];
+
+	// 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');
+};
+
+export interface BenchmarkFormatJsonOptions {
+	/** Whether to pretty-print (default: true) */
+	pretty?: boolean;
+	/** Whether to include raw timings array (default: false, can be large) */
+	include_timings?: boolean;
+}
+
+/**
+ * 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: Array<BenchmarkResult>,
+	options?: BenchmarkFormatJsonOptions,
+): string => {
+	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: Array<BenchmarkResult>,
+	groups: Array<BenchmarkGroup>,
+): string => {
+	if (results.length === 0) return '(no results)';
+
+	const sections: Array<string> = [];
+
+	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/src/lib/benchmark_stats.ts

@@ -0,0 +1,311 @@
+/**
+ * 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';
+
+/**
+ * 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 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>) {
+		// Filter out invalid values (NaN, Infinity, negative)
+		const valid_timings: Array<number> = [];
+		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(): string {
+		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: BenchmarkStatsComparable,
+	b: BenchmarkStatsComparable,
+	options?: BenchmarkCompareOptions,
+): BenchmarkComparison => {
+	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' | 'b' | 'equal' =
+		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: number;
+	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: number;
+	let effect_magnitude: EffectMagnitude;
+
+	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: string;
+	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,
+	};
+};