@fuzdev/fuz_util 0.42.0 → 0.43.0

package/src/lib/stats.ts

@@ -0,0 +1,353 @@
+/**
+ * Statistical analysis utilities.
+ * Pure functions with zero dependencies - can be used standalone for any data analysis.
+ */
+
+// Statistical constants (defaults)
+const DEFAULT_IQR_MULTIPLIER = 1.5;
+const DEFAULT_MAD_Z_SCORE_THRESHOLD = 3.5;
+const DEFAULT_MAD_Z_SCORE_EXTREME = 5.0;
+const DEFAULT_MAD_CONSTANT = 0.6745; // For normal distribution approximation
+const DEFAULT_OUTLIER_RATIO_HIGH = 0.3;
+const DEFAULT_OUTLIER_RATIO_EXTREME = 0.4;
+const DEFAULT_OUTLIER_KEEP_RATIO = 0.8;
+const DEFAULT_CONFIDENCE_Z = 1.96; // 95% confidence
+const DEFAULT_MIN_SAMPLE_SIZE = 3;
+
+/**
+ * Calculate the mean (average) of an array of numbers.
+ */
+export const stats_mean = (values: Array<number>): number => {
+	if (values.length === 0) return NaN;
+	return values.reduce((sum, val) => sum + val, 0) / values.length;
+};
+
+/**
+ * Calculate the median of an array of numbers.
+ */
+export const stats_median = (values: Array<number>): number => {
+	if (values.length === 0) return NaN;
+	const sorted = [...values].sort((a, b) => a - b);
+	const mid = Math.floor(sorted.length / 2);
+	return sorted.length % 2 === 0 ? (sorted[mid - 1]! + sorted[mid]!) / 2 : sorted[mid]!;
+};
+
+/**
+ * Calculate the standard deviation of an array of numbers.
+ * Uses population standard deviation (divides by n, not n-1).
+ * For benchmarks with many samples, this is typically appropriate.
+ */
+export const stats_std_dev = (values: Array<number>, mean?: number): number => {
+	if (values.length === 0) return NaN;
+	const m = mean ?? stats_mean(values);
+	const variance = values.reduce((sum, val) => sum + (val - m) ** 2, 0) / values.length;
+	return Math.sqrt(variance);
+};
+
+/**
+ * Calculate the variance of an array of numbers.
+ */
+export const stats_variance = (values: Array<number>, mean?: number): number => {
+	if (values.length === 0) return NaN;
+	const m = mean ?? stats_mean(values);
+	return values.reduce((sum, val) => sum + (val - m) ** 2, 0) / values.length;
+};
+
+/**
+ * Calculate a percentile of an array of numbers using linear interpolation.
+ * Uses the "R-7" method (default in R, NumPy, Excel) which interpolates between
+ * data points for more accurate percentile estimates, especially with smaller samples.
+ * @param values - Array of numbers
+ * @param p - Percentile (0-1, e.g., 0.95 for 95th percentile)
+ */
+export const stats_percentile = (values: Array<number>, p: number): number => {
+	if (values.length === 0) return NaN;
+	if (values.length === 1) return values[0]!;
+
+	const sorted = [...values].sort((a, b) => a - b);
+	const n = sorted.length;
+
+	// R-7 method: index = (n - 1) * p
+	const index = (n - 1) * p;
+	const lower = Math.floor(index);
+	const upper = Math.ceil(index);
+
+	if (lower === upper) {
+		return sorted[lower]!;
+	}
+
+	// Linear interpolation between the two nearest values
+	const fraction = index - lower;
+	return sorted[lower]! + fraction * (sorted[upper]! - sorted[lower]!);
+};
+
+/**
+ * Calculate the coefficient of variation (CV).
+ * CV = standard deviation / mean, expressed as a ratio.
+ * Useful for comparing relative variability between datasets.
+ */
+export const stats_cv = (mean: number, std_dev: number): number => {
+	if (mean === 0) return NaN;
+	return std_dev / mean;
+};
+
+/**
+ * Calculate min and max values.
+ */
+export const stats_min_max = (values: Array<number>): {min: number; max: number} => {
+	if (values.length === 0) return {min: NaN, max: NaN};
+	let min = values[0]!;
+	let max = values[0]!;
+	for (let i = 1; i < values.length; i++) {
+		const val = values[i]!;
+		if (val < min) min = val;
+		if (val > max) max = val;
+	}
+	return {min, max};
+};
+
+/**
+ * Result from outlier detection.
+ */
+export interface StatsOutlierResult {
+	/** Values after removing outliers */
+	cleaned: Array<number>;
+	/** Detected outlier values */
+	outliers: Array<number>;
+}
+
+/**
+ * Configuration options for IQR outlier detection.
+ */
+export interface StatsOutliersIqrOptions {
+	/** Multiplier for IQR bounds (default: 1.5) */
+	iqr_multiplier?: number;
+	/** Minimum sample size to perform outlier detection (default: 3) */
+	min_sample_size?: number;
+}
+
+/**
+ * Detect outliers using the IQR (Interquartile Range) method.
+ * Values outside [Q1 - multiplier*IQR, Q3 + multiplier*IQR] are considered outliers.
+ */
+export const stats_outliers_iqr = (
+	values: Array<number>,
+	options?: StatsOutliersIqrOptions,
+): StatsOutlierResult => {
+	const iqr_multiplier = options?.iqr_multiplier ?? DEFAULT_IQR_MULTIPLIER;
+	const min_sample_size = options?.min_sample_size ?? DEFAULT_MIN_SAMPLE_SIZE;
+
+	if (values.length < min_sample_size) {
+		return {cleaned: values, outliers: []};
+	}
+
+	const sorted = [...values].sort((a, b) => a - b);
+	const q1 = sorted[Math.floor(sorted.length * 0.25)]!;
+	const q3 = sorted[Math.floor(sorted.length * 0.75)]!;
+	const iqr = q3 - q1;
+
+	if (iqr === 0) {
+		return {cleaned: values, outliers: []};
+	}
+
+	const lower_bound = q1 - iqr_multiplier * iqr;
+	const upper_bound = q3 + iqr_multiplier * iqr;
+
+	const cleaned: Array<number> = [];
+	const outliers: Array<number> = [];
+
+	for (const value of values) {
+		if (value < lower_bound || value > upper_bound) {
+			outliers.push(value);
+		} else {
+			cleaned.push(value);
+		}
+	}
+
+	return {cleaned, outliers};
+};
+
+/**
+ * Configuration options for MAD outlier detection.
+ */
+export interface StatsOutliersMadOptions {
+	/** Modified Z-score threshold for outlier detection (default: 3.5) */
+	z_score_threshold?: number;
+	/** Extreme Z-score threshold when too many outliers detected (default: 5.0) */
+	z_score_extreme?: number;
+	/** MAD constant for normal distribution (default: 0.6745) */
+	mad_constant?: number;
+	/** Ratio threshold to switch to extreme mode (default: 0.3) */
+	outlier_ratio_high?: number;
+	/** Ratio threshold to switch to keep-closest mode (default: 0.4) */
+	outlier_ratio_extreme?: number;
+	/** Ratio of values to keep in keep-closest mode (default: 0.8) */
+	outlier_keep_ratio?: number;
+	/** Minimum sample size to perform outlier detection (default: 3) */
+	min_sample_size?: number;
+	/** Options to pass to IQR fallback when MAD is zero */
+	iqr_options?: StatsOutliersIqrOptions;
+}
+
+/**
+ * Detect outliers using the MAD (Median Absolute Deviation) method.
+ * More robust than IQR for skewed distributions.
+ * Uses modified Z-score: |0.6745 * (x - median) / MAD|
+ * Values with modified Z-score > threshold are considered outliers.
+ */
+export const stats_outliers_mad = (
+	values: Array<number>,
+	options?: StatsOutliersMadOptions,
+): StatsOutlierResult => {
+	const z_score_threshold = options?.z_score_threshold ?? DEFAULT_MAD_Z_SCORE_THRESHOLD;
+	const z_score_extreme = options?.z_score_extreme ?? DEFAULT_MAD_Z_SCORE_EXTREME;
+	const mad_constant = options?.mad_constant ?? DEFAULT_MAD_CONSTANT;
+	const outlier_ratio_high = options?.outlier_ratio_high ?? DEFAULT_OUTLIER_RATIO_HIGH;
+	const outlier_ratio_extreme = options?.outlier_ratio_extreme ?? DEFAULT_OUTLIER_RATIO_EXTREME;
+	const outlier_keep_ratio = options?.outlier_keep_ratio ?? DEFAULT_OUTLIER_KEEP_RATIO;
+	const min_sample_size = options?.min_sample_size ?? DEFAULT_MIN_SAMPLE_SIZE;
+	const iqr_options = options?.iqr_options;
+
+	if (values.length < min_sample_size) {
+		return {cleaned: values, outliers: []};
+	}
+
+	const sorted = [...values].sort((a, b) => a - b);
+	const median = stats_median(sorted);
+
+	// Calculate MAD (Median Absolute Deviation)
+	const deviations = values.map((v) => Math.abs(v - median));
+	const sorted_deviations = [...deviations].sort((a, b) => a - b);
+	const mad = stats_median(sorted_deviations);
+
+	// If MAD is zero, fall back to IQR method
+	if (mad === 0) {
+		return stats_outliers_iqr(values, iqr_options);
+	}
+
+	// Use modified Z-score with MAD
+	let cleaned: Array<number> = [];
+	let outliers: Array<number> = [];
+
+	for (const value of values) {
+		const modified_z_score = (mad_constant * (value - median)) / mad;
+		if (Math.abs(modified_z_score) > z_score_threshold) {
+			outliers.push(value);
+		} else {
+			cleaned.push(value);
+		}
+	}
+
+	// If too many outliers, increase threshold and try again
+	if (outliers.length > values.length * outlier_ratio_high) {
+		cleaned = [];
+		outliers = [];
+
+		for (const value of values) {
+			const modified_z_score = (mad_constant * (value - median)) / mad;
+			if (Math.abs(modified_z_score) > z_score_extreme) {
+				outliers.push(value);
+			} else {
+				cleaned.push(value);
+			}
+		}
+
+		// If still too many outliers, keep closest values to median
+		if (outliers.length > values.length * outlier_ratio_extreme) {
+			const with_distances = values.map((v) => ({
+				value: v,
+				distance: Math.abs(v - median),
+			}));
+			with_distances.sort((a, b) => a.distance - b.distance);
+
+			const keep_count = Math.floor(values.length * outlier_keep_ratio);
+			cleaned = with_distances.slice(0, keep_count).map((d) => d.value);
+			outliers = with_distances.slice(keep_count).map((d) => d.value);
+		}
+	}
+
+	return {cleaned, outliers};
+};
+
+/**
+ * Common z-scores for confidence intervals.
+ */
+export const CONFIDENCE_Z_SCORES: Record<number, number> = {
+	0.8: 1.282,
+	0.9: 1.645,
+	0.95: 1.96,
+	0.99: 2.576,
+	0.999: 3.291,
+};
+
+/**
+ * Convert a confidence level (0-1) to a z-score.
+ * Uses a lookup table for common values, approximates others.
+ *
+ * @example
+ * ```ts
+ * confidence_level_to_z_score(0.95); // 1.96
+ * confidence_level_to_z_score(0.99); // 2.576
+ * ```
+ */
+export const 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]!;
+	}
+
+	// For confidence level c, we want z such that P(-z < Z < z) = c
+	// This means Φ(z) = (1 + c) / 2, so z = Φ⁻¹((1 + c) / 2)
+	// Using Φ⁻¹(p) = √2 * erfinv(2p - 1)
+	const p = (1 + level) / 2; // e.g., 0.95 -> 0.975
+	const x = 2 * p - 1; // Argument for erfinv, e.g., 0.975 -> 0.95
+
+	// Winitzki approximation for erfinv
+	const a = 0.147;
+	const ln_term = Math.log(1 - x * x);
+	const term1 = 2 / (Math.PI * a) + ln_term / 2;
+	const erfinv = Math.sign(x) * Math.sqrt(Math.sqrt(term1 * term1 - ln_term / a) - term1);
+
+	return Math.SQRT2 * erfinv;
+};
+
+/**
+ * Configuration options for confidence interval calculation.
+ */
+export interface StatsConfidenceIntervalOptions {
+	/** Z-score for confidence level (default: 1.96 for 95% CI) */
+	z_score?: number;
+	/** Confidence level (0-1), alternative to z_score. If both provided, z_score takes precedence. */
+	confidence_level?: number;
+}
+
+/**
+ * Calculate confidence interval for the mean.
+ * @param values - Array of numbers
+ * @param options - Configuration options
+ * @returns [lower_bound, upper_bound]
+ */
+export const stats_confidence_interval = (
+	values: Array<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) ??
+		DEFAULT_CONFIDENCE_Z;
+
+	if (values.length === 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 margin = z_score * se;
+
+	return [mean - margin, mean + margin];
+};

package/src/lib/time.ts

@@ -0,0 +1,314 @@
+/**
+ * Time utilities.
+ * Provides cross-platform high-resolution timing and measurement helpers.
+ */
+
+/**
+ * Timer interface for measuring elapsed time.
+ * Returns time in nanoseconds for maximum precision.
+ */
+export interface Timer {
+	/** Get current time in nanoseconds */
+	now: () => number;
+}
+
+/**
+ * Node.js high-resolution timer using process.hrtime.bigint().
+ * Provides true nanosecond precision.
+ */
+export const timer_node: Timer = {
+	now: (): number => {
+		const ns = process.hrtime.bigint();
+		return Number(ns); // Native nanoseconds
+	},
+};
+
+/**
+ * Browser high-resolution timer using performance.now().
+ * Converts milliseconds to nanoseconds for consistent API.
+ *
+ * **Precision varies by browser due to Spectre/Meltdown mitigations:**
+ * - Chrome: ~100μs (coarsened)
+ * - Firefox: ~1ms (rounded)
+ * - Safari: ~100μs
+ * - Node.js: ~1μs
+ *
+ * For nanosecond-precision benchmarks, use Node.js with `timer_node`.
+ */
+export const timer_browser: Timer = {
+	now: (): number => {
+		return performance.now() * 1_000_000; // Convert ms to ns
+	},
+};
+
+/**
+ * Detect the best available timer function for the current environment.
+ * Called once and cached for performance.
+ */
+const detect_timer_fn = (): (() => number) => {
+	// Check if we're in Node.js with hrtime.bigint support
+	// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+	if (typeof process !== 'undefined' && process.hrtime) {
+		try {
+			if (typeof process.hrtime.bigint !== 'undefined') {
+				return timer_node.now;
+			}
+		} catch {
+			// Ignore and fall through
+		}
+	}
+	// Fallback to performance.now() (works in browsers and modern Node.js)
+	if (typeof performance !== 'undefined' && typeof performance.now === 'function') {
+		return timer_browser.now;
+	}
+	// Last resort: Date.now() (millisecond precision only)
+	return () => Date.now() * 1_000_000;
+};
+
+// Cache the detected timer function
+let _cached_timer_fn: (() => number) | null = null;
+const get_timer_fn = (): (() => number) => {
+	if (_cached_timer_fn === null) {
+		_cached_timer_fn = detect_timer_fn();
+	}
+	return _cached_timer_fn;
+};
+
+/**
+ * Auto-detected timer based on environment.
+ * Uses process.hrtime in Node.js, performance.now() in browsers.
+ * The timer function is detected once and cached for performance.
+ */
+export const timer_default: Timer = {
+	now: (): number => get_timer_fn()(),
+};
+
+/**
+ * Time units and conversions.
+ */
+export const TIME_NS_PER_US = 1_000;
+export const TIME_NS_PER_MS = 1_000_000;
+export const TIME_NS_PER_SEC = 1_000_000_000;
+
+/**
+ * Convert nanoseconds to microseconds.
+ */
+export const time_ns_to_us = (ns: number): number => ns / TIME_NS_PER_US;
+
+/**
+ * Convert nanoseconds to milliseconds.
+ */
+export const time_ns_to_ms = (ns: number): number => ns / TIME_NS_PER_MS;
+
+/**
+ * Convert nanoseconds to seconds.
+ */
+export const time_ns_to_sec = (ns: number): number => ns / TIME_NS_PER_SEC;
+
+/**
+ * Time unit for formatting.
+ */
+export type TimeUnit = 'ns' | 'us' | 'ms' | 's';
+
+/**
+ * Detect the best time unit for a set of nanosecond values.
+ * Chooses the unit where most values fall in the range 1-9999.
+ * @param values_ns - Array of times in nanoseconds
+ * @returns Best unit to use for all values
+ */
+export const time_unit_detect_best = (values_ns: Array<number>): TimeUnit => {
+	if (values_ns.length === 0) return 'ms';
+
+	// Filter out invalid values
+	const valid = values_ns.filter((v) => isFinite(v) && v > 0);
+	if (valid.length === 0) return 'ms';
+
+	// Find the median value (more stable than mean for outliers)
+	const sorted = [...valid].sort((a, b) => a - b);
+	const median = sorted[Math.floor(sorted.length / 2)]!;
+
+	// Choose unit based on median magnitude
+	if (median < 1_000) {
+		return 'ns'; // < 1μs
+	} else if (median < 1_000_000) {
+		return 'us'; // < 1ms
+	} else if (median < 1_000_000_000) {
+		return 'ms'; // < 1s
+	} else {
+		return 's'; // >= 1s
+	}
+};
+
+/**
+ * Format time with a specific unit.
+ * @param ns - Time in nanoseconds
+ * @param unit - Unit to use ('ns', 'us', 'ms', 's')
+ * @param decimals - Number of decimal places (default: 2)
+ * @returns Formatted string like "3.87μs"
+ */
+export const time_format = (ns: number, unit: TimeUnit, decimals: number = 2): string => {
+	if (!isFinite(ns)) return String(ns);
+
+	switch (unit) {
+		case 'ns':
+			return `${ns.toFixed(decimals)}ns`;
+		case 'us':
+			return `${time_ns_to_us(ns).toFixed(decimals)}μs`;
+		case 'ms':
+			return `${time_ns_to_ms(ns).toFixed(decimals)}ms`;
+		case 's':
+			return `${time_ns_to_sec(ns).toFixed(decimals)}s`;
+	}
+};
+
+/**
+ * Format time with adaptive units (ns/μs/ms/s) based on magnitude.
+ * @param ns - Time in nanoseconds
+ * @param decimals - Number of decimal places (default: 2)
+ * @returns Formatted string like "3.87μs" or "1.23ms"
+ *
+ * @example
+ * ```ts
+ * time_format_adaptive(1500) // "1.50μs"
+ * time_format_adaptive(3870) // "3.87μs"
+ * time_format_adaptive(1500000) // "1.50ms"
+ * time_format_adaptive(1500000000) // "1.50s"
+ * ```
+ */
+export const time_format_adaptive = (ns: number, decimals: number = 2): string => {
+	if (!isFinite(ns)) return String(ns);
+
+	// Choose unit based on magnitude
+	if (ns < 1_000) {
+		return time_format(ns, 'ns', decimals);
+	} else if (ns < 1_000_000) {
+		return time_format(ns, 'us', decimals);
+	} else if (ns < 1_000_000_000) {
+		return time_format(ns, 'ms', decimals);
+	} else {
+		return time_format(ns, 's', decimals);
+	}
+};
+
+/**
+ * Result from timing a function execution.
+ * All times in nanoseconds for maximum precision.
+ */
+export interface TimeResult {
+	/** Elapsed time in nanoseconds */
+	elapsed_ns: number;
+	/** Elapsed time in microseconds (convenience) */
+	elapsed_us: number;
+	/** Elapsed time in milliseconds (convenience) */
+	elapsed_ms: number;
+	/** Start time in nanoseconds (from timer.now()) */
+	started_at_ns: number;
+	/** End time in nanoseconds (from timer.now()) */
+	ended_at_ns: number;
+}
+
+/**
+ * Time an asynchronous function execution.
+ * @param fn - Async function to time
+ * @param timer - Timer to use (defaults to timer_default)
+ * @returns Object containing the function result and timing information
+ *
+ * @example
+ * ```ts
+ * const {result, timing} = await time_async(async () => {
+ *   await fetch('https://api.example.com/data');
+ *   return 42;
+ * });
+ * console.log(`Result: ${result}, took ${time_format_adaptive(timing.elapsed_ns)}`);
+ * ```
+ */
+export const time_async = async <T>(
+	fn: () => Promise<T>,
+	timer: Timer = timer_default,
+): Promise<{result: T; timing: TimeResult}> => {
+	const started_at_ns = timer.now();
+	const result = await fn();
+	const ended_at_ns = timer.now();
+	const elapsed_ns = ended_at_ns - started_at_ns;
+
+	return {
+		result,
+		timing: {
+			elapsed_ns,
+			elapsed_us: time_ns_to_us(elapsed_ns),
+			elapsed_ms: time_ns_to_ms(elapsed_ns),
+			started_at_ns,
+			ended_at_ns,
+		},
+	};
+};
+
+/**
+ * Time a synchronous function execution.
+ * @param fn - Sync function to time
+ * @param timer - Timer to use (defaults to timer_default)
+ * @returns Object containing the function result and timing information
+ *
+ * @example
+ * ```ts
+ * const {result, timing} = time_sync(() => {
+ *   return expensive_computation();
+ * });
+ * console.log(`Result: ${result}, took ${time_format_adaptive(timing.elapsed_ns)}`);
+ * ```
+ */
+export const time_sync = <T>(
+	fn: () => T,
+	timer: Timer = timer_default,
+): {result: T; timing: TimeResult} => {
+	const started_at_ns = timer.now();
+	const result = fn();
+	const ended_at_ns = timer.now();
+	const elapsed_ns = ended_at_ns - started_at_ns;
+
+	return {
+		result,
+		timing: {
+			elapsed_ns,
+			elapsed_us: time_ns_to_us(elapsed_ns),
+			elapsed_ms: time_ns_to_ms(elapsed_ns),
+			started_at_ns,
+			ended_at_ns,
+		},
+	};
+};
+
+/**
+ * Measure multiple executions of a function and return all timings.
+ * @param fn - Function to measure (sync or async)
+ * @param iterations - Number of times to execute
+ * @param timer - Timer to use (defaults to timer_default)
+ * @returns Array of elapsed times in nanoseconds
+ *
+ * @example
+ * ```ts
+ * const timings_ns = await time_measure(async () => {
+ *   await process_data();
+ * }, 100);
+ *
+ * import {BenchmarkStats} from './benchmark_stats.js';
+ * const stats = new BenchmarkStats(timings_ns);
+ * console.log(`Mean: ${time_format_adaptive(stats.mean_ns)}`);
+ * ```
+ */
+export const time_measure = async (
+	fn: () => unknown,
+	iterations: number,
+	timer: Timer = timer_default,
+): Promise<Array<number>> => {
+	const timings: Array<number> = [];
+
+	for (let i = 0; i < iterations; i++) {
+		const started_at_ns = timer.now();
+		await fn(); // eslint-disable-line no-await-in-loop
+		const ended_at_ns = timer.now();
+		timings.push(ended_at_ns - started_at_ns);
+	}
+
+	return timings;
+};