@fuzdev/fuz_util 0.43.0 → 0.44.0

package/src/lib/benchmark_format.ts

@@ -1,48 +1,7 @@
 import type {BenchmarkResult, BenchmarkGroup} from './benchmark_types.js';
-import {time_unit_detect_best, time_format, type TimeUnit} from './time.js';
-
-/**
- * Calculate the display width of a string in terminal columns.
- * Emojis and other wide characters take 2 columns.
- */
-const string_display_width = (str: string): number => {
-	let width = 0;
-	for (const char of str) {
-		const code = char.codePointAt(0)!;
-		// Emoji and other wide characters (rough heuristic)
-		// - Most emoji are in range 0x1F300-0x1FAFF
-		// - Some are in 0x2600-0x27BF (misc symbols)
-		// - CJK characters 0x4E00-0x9FFF also double-width but not handling here
-		if (
-			(code >= 0x1f300 && code <= 0x1faff) ||
-			(code >= 0x2600 && code <= 0x27bf) ||
-			(code >= 0x1f600 && code <= 0x1f64f) ||
-			(code >= 0x1f680 && code <= 0x1f6ff)
-		) {
-			width += 2;
-		} else {
-			width += 1;
-		}
-	}
-	return width;
-};
-
-/**
- * Pad a string to a target display width (accounting for wide characters).
- */
-const pad_to_width = (
-	str: string,
-	target_width: number,
-	align: 'left' | 'right' = 'left',
-): string => {
-	const current_width = string_display_width(str);
-	const padding = Math.max(0, target_width - current_width);
-	if (align === 'left') {
-		return str + ' '.repeat(padding);
-	} else {
-		return ' '.repeat(padding) + str;
-	}
-};
+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.
@@ -53,19 +12,13 @@ const pad_to_width = (
  * @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  │
- * // └────┴─────────────┴────────────┴────────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┘
+ * // ┌─────────────┬────────────┬────────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┐
+ * // │ 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  │
+ * // └─────────────┴────────────┴────────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┘
  * ```
- *
- * **Performance tier animals:**
- * - 🐆 Cheetah: >1M ops/sec (extremely fast)
- * - 🐇 Rabbit: >100K ops/sec (fast)
- * - 🐢 Turtle: >10K ops/sec (moderate)
- * - 🐌 Snail: <10K ops/sec (slow)
  */
 export const benchmark_format_table = (results: Array<BenchmarkResult>): string => {
 	if (results.length === 0) return '(no results)';
@@ -73,7 +26,7 @@ export const benchmark_format_table = (results: Array<BenchmarkResult>): string
 	// 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 = UNIT_LABELS[unit];
+	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));
@@ -82,7 +35,6 @@ export const benchmark_format_table = (results: Array<BenchmarkResult>): string
 
 	// Header with unit
 	rows.push([
-		'',
 		'Task Name',
 		'ops/sec',
 		`median (${unit_str})`,
@@ -97,7 +49,6 @@ export const benchmark_format_table = (results: Array<BenchmarkResult>): string
 
 	// Data rows - all use same unit
 	results.forEach((r) => {
-		const tier = get_perf_tier(r.stats.ops_per_second);
 		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();
@@ -111,7 +62,7 @@ export const benchmark_format_table = (results: Array<BenchmarkResult>): string
 		const ratio = fastest_ops / r.stats.ops_per_second;
 		const vs_best = ratio === 1.0 ? 'baseline' : `${ratio.toFixed(2)}x`;
 
-		rows.push([tier, r.name, ops_sec, median, p75, p90, p95, p99, min, max, vs_best]);
+		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)
@@ -126,7 +77,7 @@ export const benchmark_format_table = (results: Array<BenchmarkResult>): string
 	lines.push('┌' + widths.map((w) => '─'.repeat(w + 2)).join('┬') + '┐');
 
 	// Header
-	const header = rows[0]!.map((cell, i) => ' ' + pad_to_width(cell, widths[i]!) + ' ').join('│');
+	const header = rows[0]!.map((cell, i) => ' ' + pad_width(cell, widths[i]!) + ' ').join('│');
 	lines.push('│' + header + '│');
 
 	// Header separator
@@ -136,11 +87,11 @@ export const benchmark_format_table = (results: Array<BenchmarkResult>): string
 	for (let i = 1; i < rows.length; i++) {
 		const row = rows[i]!.map((cell, col_i) => {
 			const width = widths[col_i]!;
-			// Left-align tier emoji and task name, right-align numbers
-			if (col_i === 0 || col_i === 1) {
-				return ' ' + pad_to_width(cell, width, 'left') + ' ';
+			// Left-align task name, right-align numbers
+			if (col_i === 0) {
+				return ' ' + pad_width(cell, width, 'left') + ' ';
 			} else {
-				return ' ' + pad_to_width(cell, width, 'right') + ' ';
+				return ' ' + pad_width(cell, width, 'right') + ' ';
 			}
 		}).join('│');
 		lines.push('│' + row + '│');
@@ -173,7 +124,7 @@ export const benchmark_format_markdown = (results: Array<BenchmarkResult>): stri
 	// 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 = UNIT_LABELS[unit];
+	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));
@@ -356,24 +307,8 @@ export const benchmark_format_table_grouped = (
 	return sections.join('\n');
 };
 
-// TODO consider extracting to a general format utility module when more formatters are needed
 /**
  * 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 = (n: number, decimals: number = 2): string => {
-	if (!isFinite(n)) return String(n);
-	return n.toFixed(decimals).replace(/\B(?=(\d{3})+(?!\d))/g, ',');
-};
-
-/**
- * Get performance tier symbol based on ops/sec.
- */
-const get_perf_tier = (ops_per_sec: number): string => {
-	if (ops_per_sec >= 1_000_000) return '🐆'; // > 1M ops/sec (cheetah - extremely fast)
-	if (ops_per_sec >= 100_000) return '🐇'; // > 100K ops/sec (rabbit - fast)
-	if (ops_per_sec >= 10_000) return '🐢'; // > 10K ops/sec (turtle - moderate)
-	return '🐌'; // < 10K ops/sec (snail - slow)
-};
-
-/** Unit labels for display (μs instead of us). */
-const UNIT_LABELS: Record<TimeUnit, string> = {ns: 'ns', us: 'μs', ms: 'ms', s: 's'};
+export const benchmark_format_number = format_number;

package/src/lib/benchmark_stats.ts

@@ -14,6 +14,8 @@ import {
 	stats_min_max,
 	stats_confidence_interval,
 	stats_outliers_mad,
+	stats_welch_t_test,
+	stats_t_distribution_p_value,
 } from './stats.js';
 
 /**
@@ -226,7 +228,7 @@ export const benchmark_stats_compare = (
 		// 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} = welch_t_test(
+		const {t_statistic, degrees_of_freedom} = stats_welch_t_test(
 			a.mean_ns,
 			a.std_dev_ns,
 			a.sample_size,
@@ -235,7 +237,7 @@ export const benchmark_stats_compare = (
 			b.sample_size,
 		);
 		// Calculate two-tailed p-value using t-distribution approximation
-		p_value = t_distribution_p_value(Math.abs(t_statistic), degrees_of_freedom);
+		p_value = stats_t_distribution_p_value(Math.abs(t_statistic), degrees_of_freedom);
 	}
 
 	// Cohen's d effect size
@@ -307,142 +309,3 @@ export const benchmark_stats_compare = (
 		recommendation,
 	};
 };
-
-/**
- * Calculate Welch's t-test statistic and degrees of freedom.
- * Welch's t-test is more robust than Student's t-test when variances are unequal.
- */
-const welch_t_test = (
-	mean1: number,
-	std1: number,
-	n1: number,
-	mean2: number,
-	std2: number,
-	n2: number,
-): {t_statistic: number; degrees_of_freedom: number} => {
-	const var1 = std1 ** 2;
-	const var2 = std2 ** 2;
-
-	const se1 = var1 / n1;
-	const se2 = var2 / n2;
-
-	const t_statistic = (mean1 - mean2) / Math.sqrt(se1 + se2);
-
-	// Welch-Satterthwaite degrees of freedom
-	const numerator = (se1 + se2) ** 2;
-	const denominator = se1 ** 2 / (n1 - 1) + se2 ** 2 / (n2 - 1);
-	const degrees_of_freedom = numerator / denominator;
-
-	return {t_statistic, degrees_of_freedom};
-};
-
-/**
- * Approximate p-value from t-distribution using the approximation formula.
- * This avoids requiring a full t-distribution table or library.
- * For large df (>30), this approximation is very accurate.
- */
-const t_distribution_p_value = (t: number, df: number): number => {
-	// Use normal approximation for large df
-	if (df > 100) {
-		// Standard normal CDF approximation
-		return 2 * (1 - normal_cdf(t));
-	}
-
-	// For smaller df, use a more accurate approximation
-	// Based on the incomplete beta function relationship
-	const x = df / (df + t * t);
-	const a = df / 2;
-	const b = 0.5;
-
-	// Approximation of regularized incomplete beta function
-	// This is accurate to about 4 decimal places for typical use cases
-	const beta_approx = incomplete_beta_approx(x, a, b);
-	return beta_approx;
-};
-
-/**
- * Standard normal CDF approximation (Abramowitz and Stegun formula 7.1.26).
- */
-const normal_cdf = (x: number): number => {
-	const t = 1 / (1 + 0.2316419 * Math.abs(x));
-	const d = 0.3989423 * Math.exp((-x * x) / 2);
-	const p =
-		d * t * (0.3193815 + t * (-0.3565638 + t * (1.781478 + t * (-1.821256 + t * 1.330274))));
-	return x > 0 ? 1 - p : p;
-};
-
-/**
- * Approximate regularized incomplete beta function for p-value calculation.
- * Uses continued fraction expansion for reasonable accuracy.
- */
-const incomplete_beta_approx = (x: number, a: number, b: number): number => {
-	// Simple approximation using the relationship between beta and normal distributions
-	// For our use case (t-distribution p-values), this provides sufficient accuracy
-	if (x <= 0) return 0;
-	if (x >= 1) return 1;
-
-	// Use symmetry if needed
-	if (x > (a + 1) / (a + b + 2)) {
-		return 1 - incomplete_beta_approx(1 - x, b, a);
-	}
-
-	// Continued fraction approximation (first few terms)
-	const lnBeta = ln_gamma(a) + ln_gamma(b) - ln_gamma(a + b);
-	const front = Math.exp(Math.log(x) * a + Math.log(1 - x) * b - lnBeta) / a;
-
-	// Simple continued fraction (limited iterations for speed)
-	let f = 1;
-	let c = 1;
-	let d = 0;
-
-	for (let m = 1; m <= 100; m++) {
-		const m2 = 2 * m;
-
-		// Even step
-		let aa = (m * (b - m) * x) / ((a + m2 - 1) * (a + m2));
-		d = 1 + aa * d;
-		if (Math.abs(d) < 1e-30) d = 1e-30;
-		c = 1 + aa / c;
-		if (Math.abs(c) < 1e-30) c = 1e-30;
-		d = 1 / d;
-		f *= d * c;
-
-		// Odd step
-		aa = (-(a + m) * (a + b + m) * x) / ((a + m2) * (a + m2 + 1));
-		d = 1 + aa * d;
-		if (Math.abs(d) < 1e-30) d = 1e-30;
-		c = 1 + aa / c;
-		if (Math.abs(c) < 1e-30) c = 1e-30;
-		d = 1 / d;
-		const delta = d * c;
-		f *= delta;
-
-		if (Math.abs(delta - 1) < 1e-8) break;
-	}
-
-	return front * f;
-};
-
-/**
- * Log gamma function approximation (Lanczos approximation).
- */
-const ln_gamma = (z: number): number => {
-	const g = 7;
-	const c = [
-		0.99999999999980993, 676.5203681218851, -1259.1392167224028, 771.32342877765313,
-		-176.61502916214059, 12.507343278686905, -0.13857109526572012, 9.9843695780195716e-6,
-		1.5056327351493116e-7,
-	];
-
-	if (z < 0.5) {
-		return Math.log(Math.PI / Math.sin(Math.PI * z)) - ln_gamma(1 - z);
-	}
-
-	const z_adj = z - 1;
-	let x = c[0]!;
-	for (let i = 1; i < g + 2; i++) {
-		x += c[i]! / (z_adj + i);
-	}
-	const t = z_adj + g + 0.5;
-	return 0.5 * Math.log(2 * Math.PI) + (z_adj + 0.5) * Math.log(t) - t + Math.log(x);
-};

package/src/lib/git.ts

@@ -6,6 +6,30 @@ import type {Flavored} from './types.js';
 import {to_file_path} from './path.js';
 import {fs_exists} from './fs.js';
 
+/**
+ * Basic git repository info.
+ */
+export interface GitInfo {
+	commit: string | null;
+	branch: string | null;
+}
+
+/**
+ * Get basic git info (commit hash and branch name) without throwing.
+ * Returns null values if git commands fail (e.g., not in a git repo).
+ */
+export const git_info_get = async (options?: SpawnOptions): Promise<GitInfo> => {
+	const [commit_result, branch_result] = await Promise.all([
+		spawn_out('git', ['rev-parse', 'HEAD'], options).catch(() => ({stdout: null})),
+		spawn_out('git', ['rev-parse', '--abbrev-ref', 'HEAD'], options).catch(() => ({stdout: null})),
+	]);
+
+	return {
+		commit: commit_result.stdout?.trim() || null,
+		branch: branch_result.stdout?.trim() || null,
+	};
+};
+
 export const GitOrigin = z.string();
 export type GitOrigin = Flavored<string, 'GitOrigin'>;
 

package/src/lib/maths.ts

@@ -89,3 +89,11 @@ export const GR_9 = 76.01315561749645;
  * golden ratio/mean constants, `1/(GR**9)`, useful for scaling: https://wikipedia.org/wiki/Golden_ratio
  */
 export const GR_9i = 0.013155617496424835;
+
+/**
+ * Format a number with fixed decimal places and thousands separators.
+ */
+export const format_number = (n: number, decimals: number = 2): string => {
+	if (!isFinite(n)) return String(n);
+	return n.toFixed(decimals).replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+};

package/src/lib/stats.ts

@@ -272,7 +272,7 @@ export const stats_outliers_mad = (
 /**
  * Common z-scores for confidence intervals.
  */
-export const CONFIDENCE_Z_SCORES: Record<number, number> = {
+export const STATS_CONFIDENCE_Z_SCORES: Record<number, number> = {
 	0.8: 1.282,
 	0.9: 1.645,
 	0.95: 1.96,
@@ -286,18 +286,18 @@ export const CONFIDENCE_Z_SCORES: Record<number, number> = {
  *
  * @example
  * ```ts
- * confidence_level_to_z_score(0.95); // 1.96
- * confidence_level_to_z_score(0.99); // 2.576
+ * stats_confidence_level_to_z_score(0.95); // 1.96
+ * stats_confidence_level_to_z_score(0.99); // 2.576
  * ```
  */
-export const confidence_level_to_z_score = (level: number): number => {
+export const stats_confidence_level_to_z_score = (level: number): number => {
 	if (level <= 0 || level >= 1) {
 		throw new Error('Confidence level must be between 0 and 1 (exclusive)');
 	}
 
 	// Check lookup table first
-	if (level in CONFIDENCE_Z_SCORES) {
-		return CONFIDENCE_Z_SCORES[level]!;
+	if (level in STATS_CONFIDENCE_Z_SCORES) {
+		return STATS_CONFIDENCE_Z_SCORES[level]!;
 	}
 
 	// For confidence level c, we want z such that P(-z < Z < z) = c
@@ -334,20 +334,201 @@ export interface StatsConfidenceIntervalOptions {
 export const stats_confidence_interval = (
 	values: Array<number>,
 	options?: StatsConfidenceIntervalOptions,
+): [number, number] => {
+	if (values.length === 0) return [NaN, NaN];
+
+	const mean = stats_mean(values);
+	const std_dev = stats_std_dev(values, mean);
+
+	return stats_confidence_interval_from_summary(mean, std_dev, values.length, options);
+};
+
+/**
+ * Calculate confidence interval from summary statistics (mean, std_dev, sample_size).
+ * Useful when raw data is not available.
+ * @param mean - Mean of the data
+ * @param std_dev - Standard deviation of the data
+ * @param sample_size - Number of samples
+ * @param options - Configuration options
+ * @returns [lower_bound, upper_bound]
+ */
+export const stats_confidence_interval_from_summary = (
+	mean: number,
+	std_dev: number,
+	sample_size: number,
+	options?: StatsConfidenceIntervalOptions,
 ): [number, number] => {
 	// z_score takes precedence, then confidence_level, then default
 	const z_score =
 		options?.z_score ??
-		(options?.confidence_level ? confidence_level_to_z_score(options.confidence_level) : null) ??
+		(options?.confidence_level
+			? stats_confidence_level_to_z_score(options.confidence_level)
+			: null) ??
 		DEFAULT_CONFIDENCE_Z;
 
-	if (values.length === 0) return [NaN, NaN];
+	if (sample_size === 0) return [NaN, NaN];
 
-	const mean = stats_mean(values);
-	const std_dev = stats_std_dev(values, mean);
-
-	const se = std_dev / Math.sqrt(values.length);
+	const se = std_dev / Math.sqrt(sample_size);
 	const margin = z_score * se;
 
 	return [mean - margin, mean + margin];
 };
+
+// Hypothesis Testing Utilities
+// These functions support statistical significance testing (t-tests, p-values, etc.)
+
+/**
+ * Result from Welch's t-test calculation.
+ */
+export interface StatsWelchTTestResult {
+	/** The t-statistic */
+	t_statistic: number;
+	/** Welch-Satterthwaite degrees of freedom */
+	degrees_of_freedom: number;
+}
+
+/**
+ * Calculate Welch's t-test statistic and degrees of freedom.
+ * Welch's t-test is more robust than Student's t-test when variances are unequal.
+ *
+ * @param mean1 - Mean of first sample
+ * @param std1 - Standard deviation of first sample
+ * @param n1 - Size of first sample
+ * @param mean2 - Mean of second sample
+ * @param std2 - Standard deviation of second sample
+ * @param n2 - Size of second sample
+ */
+export const stats_welch_t_test = (
+	mean1: number,
+	std1: number,
+	n1: number,
+	mean2: number,
+	std2: number,
+	n2: number,
+): StatsWelchTTestResult => {
+	const var1 = std1 ** 2;
+	const var2 = std2 ** 2;
+
+	const se1 = var1 / n1;
+	const se2 = var2 / n2;
+
+	const t_statistic = (mean1 - mean2) / Math.sqrt(se1 + se2);
+
+	// Welch-Satterthwaite degrees of freedom
+	const numerator = (se1 + se2) ** 2;
+	const denominator = se1 ** 2 / (n1 - 1) + se2 ** 2 / (n2 - 1);
+	const degrees_of_freedom = numerator / denominator;
+
+	return {t_statistic, degrees_of_freedom};
+};
+
+/**
+ * Standard normal CDF approximation (Abramowitz and Stegun formula 7.1.26).
+ */
+export const stats_normal_cdf = (x: number): number => {
+	const t = 1 / (1 + 0.2316419 * Math.abs(x));
+	const d = 0.3989423 * Math.exp((-x * x) / 2);
+	const p =
+		d * t * (0.3193815 + t * (-0.3565638 + t * (1.781478 + t * (-1.821256 + t * 1.330274))));
+	return x > 0 ? 1 - p : p;
+};
+
+/**
+ * Log gamma function approximation (Lanczos approximation).
+ */
+export const stats_ln_gamma = (z: number): number => {
+	const g = 7;
+	const c = [
+		0.99999999999980993, 676.5203681218851, -1259.1392167224028, 771.32342877765313,
+		-176.61502916214059, 12.507343278686905, -0.13857109526572012, 9.9843695780195716e-6,
+		1.5056327351493116e-7,
+	];
+
+	if (z < 0.5) {
+		return Math.log(Math.PI / Math.sin(Math.PI * z)) - stats_ln_gamma(1 - z);
+	}
+
+	const z_adj = z - 1;
+	let x = c[0]!;
+	for (let i = 1; i < g + 2; i++) {
+		x += c[i]! / (z_adj + i);
+	}
+	const t = z_adj + g + 0.5;
+	return 0.5 * Math.log(2 * Math.PI) + (z_adj + 0.5) * Math.log(t) - t + Math.log(x);
+};
+
+/**
+ * Approximate regularized incomplete beta function for p-value calculation.
+ * Uses continued fraction expansion for reasonable accuracy.
+ */
+export const stats_incomplete_beta = (x: number, a: number, b: number): number => {
+	// Simple approximation using the relationship between beta and normal distributions
+	// For our use case (t-distribution p-values), this provides sufficient accuracy
+	if (x <= 0) return 0;
+	if (x >= 1) return 1;
+
+	// Use symmetry if needed
+	if (x > (a + 1) / (a + b + 2)) {
+		return 1 - stats_incomplete_beta(1 - x, b, a);
+	}
+
+	// Continued fraction approximation (first few terms)
+	const lnBeta = stats_ln_gamma(a) + stats_ln_gamma(b) - stats_ln_gamma(a + b);
+	const front = Math.exp(Math.log(x) * a + Math.log(1 - x) * b - lnBeta) / a;
+
+	// Simple continued fraction (limited iterations for speed)
+	let f = 1;
+	let c = 1;
+	let d = 0;
+
+	for (let m = 1; m <= 100; m++) {
+		const m2 = 2 * m;
+
+		// Even step
+		let aa = (m * (b - m) * x) / ((a + m2 - 1) * (a + m2));
+		d = 1 + aa * d;
+		if (Math.abs(d) < 1e-30) d = 1e-30;
+		c = 1 + aa / c;
+		if (Math.abs(c) < 1e-30) c = 1e-30;
+		d = 1 / d;
+		f *= d * c;
+
+		// Odd step
+		aa = (-(a + m) * (a + b + m) * x) / ((a + m2) * (a + m2 + 1));
+		d = 1 + aa * d;
+		if (Math.abs(d) < 1e-30) d = 1e-30;
+		c = 1 + aa / c;
+		if (Math.abs(c) < 1e-30) c = 1e-30;
+		d = 1 / d;
+		const delta = d * c;
+		f *= delta;
+
+		if (Math.abs(delta - 1) < 1e-8) break;
+	}
+
+	return front * f;
+};
+
+/**
+ * Approximate two-tailed p-value from t-distribution.
+ * For large df (>100), uses normal approximation.
+ * For smaller df, uses incomplete beta function.
+ *
+ * @param t - Absolute value of t-statistic
+ * @param df - Degrees of freedom
+ * @returns Two-tailed p-value
+ */
+export const stats_t_distribution_p_value = (t: number, df: number): number => {
+	// Use normal approximation for large df
+	if (df > 100) {
+		return 2 * (1 - stats_normal_cdf(t));
+	}
+
+	// For smaller df, use a more accurate approximation
+	// Based on the incomplete beta function relationship
+	const x = df / (df + t * t);
+	const a = df / 2;
+	const b = 0.5;
+
+	return stats_incomplete_beta(x, a, b);
+};

package/src/lib/string.ts

@@ -97,3 +97,69 @@ export const strip_ansi = (str: string): string => str.replaceAll(/\x1B\[[0-9;]*
  */
 export const stringify = (value: unknown): string =>
 	typeof value === 'bigint' ? value + 'n' : (JSON.stringify(value) ?? String(value)); // eslint-disable-line @typescript-eslint/no-unnecessary-condition
+
+/**
+ * Calculate the display width of a string in terminal columns.
+ * - Strips ANSI escape codes (they have 0 width)
+ * - Emojis and other wide characters take 2 columns
+ * - Tab characters take 4 columns
+ * - Newlines and other control characters take 0 columns
+ * - Uses `Intl.Segmenter` to properly handle grapheme clusters (e.g., family emoji "👨‍👩‍👧‍👦")
+ */
+export const string_display_width = (str: string): number => {
+	// Strip ANSI codes first (they have 0 display width)
+	const clean = strip_ansi(str);
+
+	let width = 0;
+	const segmenter = new Intl.Segmenter();
+	for (const {segment} of segmenter.segment(clean)) {
+		const code = segment.codePointAt(0)!;
+
+		// Handle control characters
+		if (code === 0x09) {
+			// Tab = 4 columns
+			width += 4;
+			continue;
+		}
+		if (code < 0x20 || (code >= 0x7f && code < 0xa0)) {
+			// Other control characters (including newline) = 0 width
+			continue;
+		}
+
+		// Emoji and other wide characters (rough heuristic)
+		// - Most emoji are in range 0x1F300-0x1FAFF
+		// - Some are in 0x2600-0x27BF (misc symbols)
+		// - CJK characters 0x4E00-0x9FFF also double-width
+		// - Grapheme clusters with multiple code points (like ZWJ sequences) are typically emoji
+		if (
+			segment.length > 1 || // Multi-codepoint graphemes (ZWJ sequences, etc.)
+			(code >= 0x1f300 && code <= 0x1faff) ||
+			(code >= 0x2600 && code <= 0x27bf) ||
+			(code >= 0x1f600 && code <= 0x1f64f) ||
+			(code >= 0x1f680 && code <= 0x1f6ff) ||
+			(code >= 0x4e00 && code <= 0x9fff) // CJK
+		) {
+			width += 2;
+		} else {
+			width += 1;
+		}
+	}
+	return width;
+};
+
+/**
+ * Pad a string to a target display width (accounting for wide characters).
+ */
+export const pad_width = (
+	str: string,
+	target_width: number,
+	align: 'left' | 'right' = 'left',
+): string => {
+	const current_width = string_display_width(str);
+	const padding = Math.max(0, target_width - current_width);
+	if (align === 'left') {
+		return str + ' '.repeat(padding);
+	} else {
+		return ' '.repeat(padding) + str;
+	}
+};