@fuzdev/fuz_util 0.43.0 → 0.44.0

package/dist/stats.d.ts

@@ -95,18 +95,18 @@ export declare const stats_outliers_mad: (values: Array<number>, options?: Stats
 /**
  * Common z-scores for confidence intervals.
  */
-export declare const CONFIDENCE_Z_SCORES: Record<number, number>;
+export declare const STATS_CONFIDENCE_Z_SCORES: Record<number, number>;
 /**
  * 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
+ * stats_confidence_level_to_z_score(0.95); // 1.96
+ * stats_confidence_level_to_z_score(0.99); // 2.576
  * ```
  */
-export declare const confidence_level_to_z_score: (level: number) => number;
+export declare const stats_confidence_level_to_z_score: (level: number) => number;
 /**
  * Configuration options for confidence interval calculation.
  */
@@ -123,4 +123,58 @@ export interface StatsConfidenceIntervalOptions {
  * @returns [lower_bound, upper_bound]
  */
 export declare const stats_confidence_interval: (values: Array<number>, options?: StatsConfidenceIntervalOptions) => [number, number];
+/**
+ * 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 declare const stats_confidence_interval_from_summary: (mean: number, std_dev: number, sample_size: number, options?: StatsConfidenceIntervalOptions) => [number, number];
+/**
+ * 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 declare const stats_welch_t_test: (mean1: number, std1: number, n1: number, mean2: number, std2: number, n2: number) => StatsWelchTTestResult;
+/**
+ * Standard normal CDF approximation (Abramowitz and Stegun formula 7.1.26).
+ */
+export declare const stats_normal_cdf: (x: number) => number;
+/**
+ * Log gamma function approximation (Lanczos approximation).
+ */
+export declare const stats_ln_gamma: (z: number) => number;
+/**
+ * Approximate regularized incomplete beta function for p-value calculation.
+ * Uses continued fraction expansion for reasonable accuracy.
+ */
+export declare const stats_incomplete_beta: (x: number, a: number, b: number) => number;
+/**
+ * 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 declare const stats_t_distribution_p_value: (t: number, df: number) => number;
 //# sourceMappingURL=stats.d.ts.map

package/dist/stats.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stats.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/stats.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,KAAK,CAAC,MAAM,CAAC,KAAG,MAGlD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,KAAK,CAAC,MAAM,CAAC,KAAG,MAKpD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,MAAM,KAAG,MAKpE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,MAAM,KAAG,MAIrE,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,KAAG,MAmBnE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,EAAE,SAAS,MAAM,KAAG,MAGxD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,KAAK,CAAC,MAAM,CAAC,KAAG;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAU9E,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,qCAAqC;IACrC,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACvB,8BAA8B;IAC9B,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAC9B,QAAQ,KAAK,CAAC,MAAM,CAAC,EACrB,UAAU,uBAAuB,KAC/B,kBAgCF,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,WAAW,CAAC,EAAE,uBAAuB,CAAC;CACtC;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAC9B,QAAQ,KAAK,CAAC,MAAM,CAAC,EACrB,UAAU,uBAAuB,KAC/B,kBAqEF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAMtD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,GAAI,OAAO,MAAM,KAAG,MAuB3D,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC9C,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kGAAkG;IAClG,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GACrC,QAAQ,KAAK,CAAC,MAAM,CAAC,EACrB,UAAU,8BAA8B,KACtC,CAAC,MAAM,EAAE,MAAM,CAgBjB,CAAC"}
+{"version":3,"file":"stats.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/stats.ts"],"names":[],"mappings":"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"}

package/dist/stats.js

@@ -204,7 +204,7 @@ export const stats_outliers_mad = (values, options) => {
 /**
  * Common z-scores for confidence intervals.
  */
-export const CONFIDENCE_Z_SCORES = {
+export const STATS_CONFIDENCE_Z_SCORES = {
     0.8: 1.282,
     0.9: 1.645,
     0.95: 1.96,
@@ -217,17 +217,17 @@ export const CONFIDENCE_Z_SCORES = {
  *
  * @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) => {
+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 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
     // This means Φ(z) = (1 + c) / 2, so z = Φ⁻¹((1 + c) / 2)
@@ -248,15 +248,155 @@ export const confidence_level_to_z_score = (level) => {
  * @returns [lower_bound, upper_bound]
  */
 export const stats_confidence_interval = (values, options) => {
-    // 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);
+    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

@@ -56,6 +56,10 @@ 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.

package/dist/time.d.ts.map

@@ -1 +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;;;;;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"}
+{"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"}

package/dist/time.js

@@ -87,6 +87,10 @@ export const time_ns_to_ms = (ns) => ns / TIME_NS_PER_MS;
  * Convert nanoseconds to seconds.
  */
 export const time_ns_to_sec = (ns) => ns / TIME_NS_PER_SEC;
+/**
+ * Display labels for time units (uses proper Unicode μ for microseconds).
+ */
+export const TIME_UNIT_DISPLAY = { ns: 'ns', us: 'μs', ms: 'ms', s: 's' };
 /**
  * Detect the best time unit for a set of nanosecond values.
  * Chooses the unit where most values fall in the range 1-9999.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_util",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "utility belt for JS",
   "glyph": "🦕",
   "logo": "logo.svg",

package/src/lib/benchmark_baseline.ts

@@ -8,12 +8,14 @@ import {join} from 'node:path';
 import {z} from 'zod';
 
 import {fs_exists} from './fs.js';
+import {git_info_get} from './git.js';
 import type {BenchmarkResult} from './benchmark_types.js';
 import {
 	benchmark_stats_compare,
 	type BenchmarkComparison,
 	type BenchmarkStatsComparable,
 } from './benchmark_stats.js';
+import {stats_confidence_interval_from_summary} from './stats.js';
 
 // Version for forward compatibility - increment when schema changes
 const BASELINE_VERSION = 1;
@@ -128,21 +130,6 @@ export interface BenchmarkBaselineTaskComparison {
 const DEFAULT_BASELINE_PATH = '.gro/benchmarks';
 const BASELINE_FILENAME = 'baseline.json';
 
-/** Z-score for 95% confidence interval */
-const Z_95 = 1.96;
-
-/**
- * Calculate 95% confidence interval from mean, std_dev, and sample_size.
- */
-const calculate_confidence_interval = (
-	mean: number,
-	std_dev: number,
-	sample_size: number,
-): [number, number] => {
-	const margin = Z_95 * (std_dev / Math.sqrt(sample_size));
-	return [mean - margin, mean + margin];
-};
-
 /**
  * Convert benchmark results to baseline entries.
  */
@@ -163,28 +150,6 @@ const results_to_entries = (results: Array<BenchmarkResult>): Array<BenchmarkBas
 	}));
 };
 
-/**
- * Try to get git info from the environment or git commands.
- */
-const get_git_info = async (): Promise<{commit: string | null; branch: string | null}> => {
-	try {
-		const {promisify} = await import('node:util');
-		const exec = promisify((await import('node:child_process')).exec);
-
-		const [commit_result, branch_result] = await Promise.all([
-			exec('git rev-parse HEAD').catch(() => ({stdout: ''})),
-			exec('git rev-parse --abbrev-ref HEAD').catch(() => ({stdout: ''})),
-		]);
-
-		return {
-			commit: commit_result.stdout.trim() || null,
-			branch: branch_result.stdout.trim() || null,
-		};
-	} catch {
-		return {commit: null, branch: null};
-	}
-};
-
 /**
  * Save benchmark results as the current baseline.
  *
@@ -209,7 +174,7 @@ export const benchmark_baseline_save = async (
 	let git_commit = options.git_commit;
 	let git_branch = options.git_branch;
 	if (git_commit === undefined || git_branch === undefined) {
-		const git_info = await get_git_info();
+		const git_info = await git_info_get();
 		git_commit ??= git_info.commit;
 		git_branch ??= git_info.branch;
 	}
@@ -360,7 +325,7 @@ export const benchmark_baseline_compare = async (
 			mean_ns: baseline_entry.mean_ns,
 			std_dev_ns: baseline_entry.std_dev_ns,
 			sample_size: baseline_entry.sample_size,
-			confidence_interval_ns: calculate_confidence_interval(
+			confidence_interval_ns: stats_confidence_interval_from_summary(
 				baseline_entry.mean_ns,
 				baseline_entry.std_dev_ns,
 				baseline_entry.sample_size,
@@ -370,7 +335,7 @@ export const benchmark_baseline_compare = async (
 			mean_ns: current.mean_ns,
 			std_dev_ns: current.std_dev_ns,
 			sample_size: current.sample_size,
-			confidence_interval_ns: calculate_confidence_interval(
+			confidence_interval_ns: stats_confidence_interval_from_summary(
 				current.mean_ns,
 				current.std_dev_ns,
 				current.sample_size,