@fuzdev/fuz_util 0.42.0 → 0.44.0

package/dist/stats.js

@@ -0,0 +1,402 @@
+/**
+ * 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) => {
+    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) => {
+    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, mean) => {
+    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, mean) => {
+    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, p) => {
+    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, std_dev) => {
+    if (mean === 0)
+        return NaN;
+    return std_dev / mean;
+};
+/**
+ * Calculate min and max values.
+ */
+export const stats_min_max = (values) => {
+    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 };
+};
+/**
+ * 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, options) => {
+    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 = [];
+    const outliers = [];
+    for (const value of values) {
+        if (value < lower_bound || value > upper_bound) {
+            outliers.push(value);
+        }
+        else {
+            cleaned.push(value);
+        }
+    }
+    return { cleaned, outliers };
+};
+/**
+ * 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, options) => {
+    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 = [];
+    let outliers = [];
+    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 STATS_CONFIDENCE_Z_SCORES = {
+    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
+ * stats_confidence_level_to_z_score(0.95); // 1.96
+ * stats_confidence_level_to_z_score(0.99); // 2.576
+ * ```
+ */
+export const stats_confidence_level_to_z_score = (level) => {
+    if (level <= 0 || level >= 1) {
+        throw new Error('Confidence level must be between 0 and 1 (exclusive)');
+    }
+    // Check lookup table first
+    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
+    // 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;
+};
+/**
+ * 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, options) => {
+    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, std_dev, sample_size, options) => {
+    // z_score takes precedence, then confidence_level, then default
+    const z_score = options?.z_score ??
+        (options?.confidence_level
+            ? stats_confidence_level_to_z_score(options.confidence_level)
+            : null) ??
+        DEFAULT_CONFIDENCE_Z;
+    if (sample_size === 0)
+        return [NaN, NaN];
+    const se = std_dev / Math.sqrt(sample_size);
+    const margin = z_score * se;
+    return [mean - margin, mean + margin];
+};
+/**
+ * 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, std1, n1, mean2, std2, n2) => {
+    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) => {
+    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) => {
+    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, a, b) => {
+    // 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, df) => {
+    // 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/dist/string.d.ts

@@ -48,4 +48,17 @@ export declare const strip_ansi: (str: string) => string;
  * @source https://2ality.com/2025/04/stringification-javascript.html
  */
 export declare const stringify: (value: unknown) => string;
+/**
+ * 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 declare const string_display_width: (str: string) => number;
+/**
+ * Pad a string to a target display width (accounting for wide characters).
+ */
+export declare const pad_width: (str: string, target_width: number, align?: "left" | "right") => string;
 //# sourceMappingURL=string.d.ts.map

package/dist/string.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"string.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/string.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,EAAE,WAAW,MAAM,EAAE,eAAc,KAAG,MAMzE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAG9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAG5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAK9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAK/D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,MAG9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,MAG5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,KAAG,MAK1B,CAAC;AAEd;;GAEG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,eAAY,KAAG,MAC9C,CAAC;AAE3B;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,KAAG,MACI,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,MAAsD,CAAC;AAEhG;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,MACwC,CAAC"}
+{"version":3,"file":"string.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/string.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,EAAE,WAAW,MAAM,EAAE,eAAc,KAAG,MAMzE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAG9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAG5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAK9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAK/D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,MAG9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,MAG5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,KAAG,MAK1B,CAAC;AAEd;;GAEG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,eAAY,KAAG,MAC9C,CAAC;AAE3B;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,KAAG,MACI,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,MAAsD,CAAC;AAEhG;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,MACwC,CAAC;AAEpF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,MAAM,KAAG,MAuClD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS,GACrB,KAAK,MAAM,EACX,cAAc,MAAM,EACpB,QAAO,MAAM,GAAG,OAAgB,KAC9B,MAQF,CAAC"}

package/dist/string.js

@@ -90,3 +90,61 @@ export const strip_ansi = (str) => str.replaceAll(/\x1B\[[0-9;]*[a-zA-Z]/g, '');
  * @source https://2ality.com/2025/04/stringification-javascript.html
  */
 export const stringify = (value) => 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) => {
+    // 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, target_width, align = 'left') => {
+    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;
+    }
+};

package/dist/time.d.ts

@@ -0,0 +1,165 @@
+/**
+ * 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 declare const timer_node: Timer;
+/**
+ * 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 declare const timer_browser: Timer;
+/**
+ * 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 declare const timer_default: Timer;
+/**
+ * Time units and conversions.
+ */
+export declare const TIME_NS_PER_US = 1000;
+export declare const TIME_NS_PER_MS = 1000000;
+export declare const TIME_NS_PER_SEC = 1000000000;
+/**
+ * Convert nanoseconds to microseconds.
+ */
+export declare const time_ns_to_us: (ns: number) => number;
+/**
+ * Convert nanoseconds to milliseconds.
+ */
+export declare const time_ns_to_ms: (ns: number) => number;
+/**
+ * Convert nanoseconds to seconds.
+ */
+export declare const time_ns_to_sec: (ns: number) => number;
+/**
+ * Time unit for formatting.
+ */
+export type TimeUnit = 'ns' | 'us' | 'ms' | 's';
+/**
+ * Display labels for time units (uses proper Unicode μ for microseconds).
+ */
+export declare const TIME_UNIT_DISPLAY: Record<TimeUnit, string>;
+/**
+ * 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 declare const time_unit_detect_best: (values_ns: Array<number>) => TimeUnit;
+/**
+ * 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 declare const time_format: (ns: number, unit: TimeUnit, decimals?: number) => string;
+/**
+ * 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 declare const time_format_adaptive: (ns: number, decimals?: number) => string;
+/**
+ * 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 declare const time_async: <T>(fn: () => Promise<T>, timer?: Timer) => Promise<{
+    result: T;
+    timing: TimeResult;
+}>;
+/**
+ * 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 declare const time_sync: <T>(fn: () => T, timer?: Timer) => {
+    result: T;
+    timing: TimeResult;
+};
+/**
+ * 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 declare const time_measure: (fn: () => unknown, iterations: number, timer?: Timer) => Promise<Array<number>>;
+//# sourceMappingURL=time.d.ts.map

package/dist/time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/time.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,WAAW,KAAK;IACrB,sCAAsC;IACtC,GAAG,EAAE,MAAM,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,KAKxB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,EAAE,KAI3B,CAAC;AAmCF;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,KAE3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,OAAQ,CAAC;AACpC,eAAO,MAAM,cAAc,UAAY,CAAC;AACxC,eAAO,MAAM,eAAe,aAAgB,CAAC;AAE7C;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,IAAI,MAAM,KAAG,MAA6B,CAAC;AAEzE;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,IAAI,MAAM,KAAG,MAA6B,CAAC;AAEzE;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,IAAI,MAAM,KAAG,MAA8B,CAAC;AAE3E;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,GAAG,CAAC;AAEhD;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAA0C,CAAC;AAElG;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,WAAW,KAAK,CAAC,MAAM,CAAC,KAAG,QAqBhE,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,IAAI,MAAM,EAAE,MAAM,QAAQ,EAAE,WAAU,MAAU,KAAG,MAa9E,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,GAAI,IAAI,MAAM,EAAE,WAAU,MAAU,KAAG,MAavE,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,UAAU,GAAU,CAAC,EACjC,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,QAAO,KAAqB,KAC1B,OAAO,CAAC;IAAC,MAAM,EAAE,CAAC,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAC,CAgBzC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,EAC1B,IAAI,MAAM,CAAC,EACX,QAAO,KAAqB,KAC1B;IAAC,MAAM,EAAE,CAAC,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAgBhC,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,YAAY,GACxB,IAAI,MAAM,OAAO,EACjB,YAAY,MAAM,EAClB,QAAO,KAAqB,KAC1B,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAWvB,CAAC"}