@fuzdev/fuz_util 0.42.0 → 0.43.0

package/dist/benchmark_format.js

@@ -0,0 +1,327 @@
+import { time_unit_detect_best, time_format } 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) => {
+    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, 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;
+    }
+};
+/**
+ * Format results as an ASCII table with percentiles, min/max, and relative performance.
+ * All times use the same unit for easy comparison.
+ * @param results - Array of benchmark results
+ * @returns Formatted table string with enhanced metrics
+ *
+ * @example
+ * ```ts
+ * console.log(benchmark_format_table(results));
+ * // ┌────┬─────────────┬────────────┬────────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┐
+ * // │    │ Task Name   │  ops/sec   │ median(μs) │ p75 (μs) │ p90 (μs) │ p95 (μs) │ p99 (μs) │ min (μs) │ max (μs) │ vs Best  │
+ * // ├────┼─────────────┼────────────┼────────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┤
+ * // │ 🐇 │ slugify v2  │ 1,237,144  │    0.81    │   0.85   │   0.89   │   0.95   │   1.20   │   0.72   │    2.45  │ baseline │
+ * // │ 🐢 │ slugify     │   261,619  │    3.82    │   3.95   │   4.12   │   4.35   │   5.10   │   3.21   │   12.45  │   4.73x  │
+ * // └────┴─────────────┴────────────┴────────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┘
+ * ```
+ *
+ * **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) => {
+    if (results.length === 0)
+        return '(no results)';
+    // Detect best unit for all results
+    const mean_times = results.map((r) => r.stats.mean_ns);
+    const unit = time_unit_detect_best(mean_times);
+    const unit_str = UNIT_LABELS[unit];
+    // Find fastest for relative comparison
+    const fastest_ops = Math.max(...results.map((r) => r.stats.ops_per_second));
+    const rows = [];
+    // Header with unit
+    rows.push([
+        '',
+        'Task Name',
+        'ops/sec',
+        `median (${unit_str})`,
+        `p75 (${unit_str})`,
+        `p90 (${unit_str})`,
+        `p95 (${unit_str})`,
+        `p99 (${unit_str})`,
+        `min (${unit_str})`,
+        `max (${unit_str})`,
+        'vs Best',
+    ]);
+    // Data rows - all use same unit
+    results.forEach((r) => {
+        const 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();
+        const p90 = time_format(r.stats.p90_ns, unit, 2).replace(unit_str, '').trim();
+        const p95 = time_format(r.stats.p95_ns, unit, 2).replace(unit_str, '').trim();
+        const p99 = time_format(r.stats.p99_ns, unit, 2).replace(unit_str, '').trim();
+        const min = time_format(r.stats.min_ns, unit, 2).replace(unit_str, '').trim();
+        const max = time_format(r.stats.max_ns, unit, 2).replace(unit_str, '').trim();
+        // Calculate relative performance
+        const ratio = fastest_ops / r.stats.ops_per_second;
+        const vs_best = ratio === 1.0 ? 'baseline' : `${ratio.toFixed(2)}x`;
+        rows.push([tier, r.name, ops_sec, median, p75, p90, p95, p99, min, max, vs_best]);
+    });
+    // Calculate column widths (using display width for proper emoji handling)
+    const widths = rows[0].map((_, col_i) => {
+        return Math.max(...rows.map((row) => string_display_width(row[col_i])));
+    });
+    // Build table
+    const lines = [];
+    // Top border
+    lines.push('┌' + widths.map((w) => '─'.repeat(w + 2)).join('┬') + '┐');
+    // Header
+    const header = rows[0].map((cell, i) => ' ' + pad_to_width(cell, widths[i]) + ' ').join('│');
+    lines.push('│' + header + '│');
+    // Header separator
+    lines.push('├' + widths.map((w) => '─'.repeat(w + 2)).join('┼') + '┤');
+    // Data rows
+    for (let i = 1; i < rows.length; i++) {
+        const row = rows[i].map((cell, col_i) => {
+            const width = widths[col_i];
+            // Left-align tier emoji and task name, right-align numbers
+            if (col_i === 0 || col_i === 1) {
+                return ' ' + pad_to_width(cell, width, 'left') + ' ';
+            }
+            else {
+                return ' ' + pad_to_width(cell, width, 'right') + ' ';
+            }
+        }).join('│');
+        lines.push('│' + row + '│');
+    }
+    // Bottom border
+    lines.push('└' + widths.map((w) => '─'.repeat(w + 2)).join('┴') + '┘');
+    return lines.join('\n');
+};
+/**
+ * Format results as a Markdown table with key metrics.
+ * All times use the same unit for easy comparison.
+ * @param results - Array of benchmark results
+ * @returns Formatted markdown table string
+ *
+ * @example
+ * ```ts
+ * console.log(benchmark_format_markdown(results));
+ * // | Task Name  | ops/sec    | median (μs) | p75 (μs) | p90 (μs) | p95 (μs) | p99 (μs) | min (μs) | max (μs) | vs Best  |
+ * // |------------|------------|-------------|----------|----------|----------|----------|----------|----------|----------|
+ * // | slugify v2 | 1,237,144  | 0.81        | 0.85     | 0.89     | 0.95     | 1.20     | 0.72     | 2.45     | baseline |
+ * // | slugify    |   261,619  | 3.82        | 3.95     | 4.12     | 4.35     | 5.10     | 3.21     | 12.45    | 4.73x    |
+ * ```
+ */
+export const benchmark_format_markdown = (results) => {
+    if (results.length === 0)
+        return '(no results)';
+    // Detect best unit for all results
+    const mean_times = results.map((r) => r.stats.mean_ns);
+    const unit = time_unit_detect_best(mean_times);
+    const unit_str = UNIT_LABELS[unit];
+    // Find fastest for relative comparison
+    const fastest_ops = Math.max(...results.map((r) => r.stats.ops_per_second));
+    const rows = [];
+    // Header with unit
+    rows.push([
+        'Task Name',
+        'ops/sec',
+        `median (${unit_str})`,
+        `p75 (${unit_str})`,
+        `p90 (${unit_str})`,
+        `p95 (${unit_str})`,
+        `p99 (${unit_str})`,
+        `min (${unit_str})`,
+        `max (${unit_str})`,
+        'vs Best',
+    ]);
+    // Data rows - all use same unit
+    results.forEach((r) => {
+        const ops_sec = benchmark_format_number(r.stats.ops_per_second, 2);
+        const median = time_format(r.stats.median_ns, unit, 2).replace(unit_str, '').trim();
+        const p75 = time_format(r.stats.p75_ns, unit, 2).replace(unit_str, '').trim();
+        const p90 = time_format(r.stats.p90_ns, unit, 2).replace(unit_str, '').trim();
+        const p95 = time_format(r.stats.p95_ns, unit, 2).replace(unit_str, '').trim();
+        const p99 = time_format(r.stats.p99_ns, unit, 2).replace(unit_str, '').trim();
+        const min = time_format(r.stats.min_ns, unit, 2).replace(unit_str, '').trim();
+        const max = time_format(r.stats.max_ns, unit, 2).replace(unit_str, '').trim();
+        // Calculate relative performance
+        const ratio = fastest_ops / r.stats.ops_per_second;
+        const vs_best = ratio === 1.0 ? 'baseline' : `${ratio.toFixed(2)}x`;
+        rows.push([r.name, ops_sec, median, p75, p90, p95, p99, min, max, vs_best]);
+    });
+    // Calculate column widths
+    const widths = rows[0].map((_, col_i) => {
+        return Math.max(...rows.map((row) => row[col_i].length));
+    });
+    // Build table
+    const lines = [];
+    // Header
+    const header = rows[0].map((cell, i) => cell.padEnd(widths[i])).join(' | ');
+    lines.push('| ' + header + ' |');
+    // Separator
+    const separator = widths.map((w) => '-'.repeat(w)).join(' | ');
+    lines.push('| ' + separator + ' |');
+    // Data rows
+    for (let i = 1; i < rows.length; i++) {
+        const row = rows[i].map((cell, col_i) => {
+            const width = widths[col_i];
+            // Right-align numbers, left-align names
+            if (col_i === 0) {
+                return cell.padEnd(width);
+            }
+            else {
+                return cell.padStart(width);
+            }
+        }).join(' | ');
+        lines.push('| ' + row + ' |');
+    }
+    return lines.join('\n');
+};
+/**
+ * Format results as JSON.
+ * @param results - Array of benchmark results
+ * @param options - Formatting options
+ * @returns JSON string
+ *
+ * @example
+ * ```ts
+ * console.log(format_json(results));
+ * console.log(format_json(results, {pretty: false}));
+ * console.log(format_json(results, {include_timings: true}));
+ * ```
+ */
+export const benchmark_format_json = (results, options) => {
+    const pretty = options?.pretty ?? true;
+    const include_timings = options?.include_timings ?? false;
+    // Flatten stats into result object for easier consumption
+    const flattened = results.map((r) => ({
+        name: r.name,
+        iterations: r.iterations,
+        total_time_ms: r.total_time_ms,
+        ops_per_second: r.stats.ops_per_second,
+        mean_ns: r.stats.mean_ns,
+        median_ns: r.stats.median_ns,
+        std_dev_ns: r.stats.std_dev_ns,
+        min_ns: r.stats.min_ns,
+        max_ns: r.stats.max_ns,
+        p75_ns: r.stats.p75_ns,
+        p90_ns: r.stats.p90_ns,
+        p95_ns: r.stats.p95_ns,
+        p99_ns: r.stats.p99_ns,
+        cv: r.stats.cv,
+        confidence_interval_ns: r.stats.confidence_interval_ns,
+        outliers: r.stats.outliers_ns.length,
+        outlier_ratio: r.stats.outlier_ratio,
+        sample_size: r.stats.sample_size,
+        raw_sample_size: r.stats.raw_sample_size,
+        failed_iterations: r.stats.failed_iterations,
+        ...(include_timings ? { timings_ns: r.timings_ns } : {}),
+    }));
+    return pretty ? JSON.stringify(flattened, null, 2) : JSON.stringify(flattened);
+};
+/**
+ * Format results as a grouped table with visual separators between groups.
+ * @param results - Array of benchmark results
+ * @param groups - Array of group definitions
+ * @returns Formatted table string with group separators
+ *
+ * @example
+ * ```ts
+ * const groups = [
+ *   { name: 'FAST PATHS', filter: (r) => r.name.includes('fast') },
+ *   { name: 'SLOW PATHS', filter: (r) => r.name.includes('slow') },
+ * ];
+ * console.log(benchmark_format_table_grouped(results, groups));
+ * // 📦 FAST PATHS
+ * // ┌────┬─────────────┬────────────┬...┐
+ * // │ 🐆 │ fast test 1 │ 1,237,144  │...│
+ * // │ 🐇 │ fast test 2 │   261,619  │...│
+ * // └────┴─────────────┴────────────┴...┘
+ * //
+ * // 📦 SLOW PATHS
+ * // ┌────┬─────────────┬────────────┬...┐
+ * // │ 🐢 │ slow test 1 │    10,123  │...│
+ * // └────┴─────────────┴────────────┴...┘
+ * ```
+ */
+export const benchmark_format_table_grouped = (results, groups) => {
+    if (results.length === 0)
+        return '(no results)';
+    const sections = [];
+    for (const group of groups) {
+        const group_results = results.filter(group.filter);
+        if (group_results.length === 0)
+            continue;
+        // Add group header and table
+        const header = group.description
+            ? `\n📦 ${group.name}\n   ${group.description}`
+            : `\n📦 ${group.name}`;
+        sections.push(header);
+        sections.push(benchmark_format_table(group_results));
+    }
+    // Handle ungrouped results (those that don't match any group)
+    const grouped_names = new Set(groups.flatMap((g) => results.filter(g.filter).map((r) => r.name)));
+    const ungrouped = results.filter((r) => !grouped_names.has(r.name));
+    if (ungrouped.length > 0) {
+        sections.push('\n📦 Other');
+        sections.push(benchmark_format_table(ungrouped));
+    }
+    return sections.join('\n');
+};
+// TODO consider extracting to a general format utility module when more formatters are needed
+/**
+ * Format a number with fixed decimal places and thousands separators.
+ */
+export const benchmark_format_number = (n, decimals = 2) => {
+    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) => {
+    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 = { ns: 'ns', us: 'μs', ms: 'ms', s: 's' };

package/dist/benchmark_stats.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Benchmark-specific statistical analysis.
+ * Uses the general stats utilities from stats.ts for timing/performance analysis.
+ * All timing values are in nanoseconds.
+ */
+/**
+ * Minimal stats interface for comparison.
+ * This allows comparing stats from different sources (e.g., loaded baselines).
+ */
+export interface BenchmarkStatsComparable {
+    mean_ns: number;
+    std_dev_ns: number;
+    sample_size: number;
+    confidence_interval_ns: [number, number];
+}
+/**
+ * Effect size magnitude interpretation (Cohen's d).
+ */
+export type EffectMagnitude = 'negligible' | 'small' | 'medium' | 'large';
+/**
+ * Result from comparing two benchmark stats.
+ */
+export interface BenchmarkComparison {
+    /** Which benchmark is faster ('a', 'b', or 'equal' if difference is negligible) */
+    faster: 'a' | 'b' | 'equal';
+    /** How much faster the winner is (e.g., 1.5 means 1.5x faster) */
+    speedup_ratio: number;
+    /** Whether the difference is statistically significant at the given alpha */
+    significant: boolean;
+    /** P-value from Welch's t-test (lower = more confident the difference is real) */
+    p_value: number;
+    /** Cohen's d effect size (magnitude of difference independent of sample size) */
+    effect_size: number;
+    /** Interpretation of effect size */
+    effect_magnitude: EffectMagnitude;
+    /** Whether the 95% confidence intervals overlap */
+    ci_overlap: boolean;
+    /** Human-readable interpretation of the comparison */
+    recommendation: string;
+}
+/**
+ * Options for benchmark comparison.
+ */
+export interface BenchmarkCompareOptions {
+    /** Significance level for hypothesis testing (default: 0.05) */
+    alpha?: number;
+}
+/**
+ * Complete statistical analysis of timing measurements.
+ * Includes outlier detection, descriptive statistics, and performance metrics.
+ * All timing values are in nanoseconds.
+ */
+export declare class BenchmarkStats {
+    /** Mean (average) time in nanoseconds */
+    readonly mean_ns: number;
+    /** Median time in nanoseconds */
+    readonly median_ns: number;
+    /** Standard deviation in nanoseconds */
+    readonly std_dev_ns: number;
+    /** Minimum time in nanoseconds */
+    readonly min_ns: number;
+    /** Maximum time in nanoseconds */
+    readonly max_ns: number;
+    /** 75th percentile in nanoseconds */
+    readonly p75_ns: number;
+    /** 90th percentile in nanoseconds */
+    readonly p90_ns: number;
+    /** 95th percentile in nanoseconds */
+    readonly p95_ns: number;
+    /** 99th percentile in nanoseconds */
+    readonly p99_ns: number;
+    /** Coefficient of variation (std_dev / mean) */
+    readonly cv: number;
+    /** 95% confidence interval for the mean in nanoseconds */
+    readonly confidence_interval_ns: [number, number];
+    /** Array of detected outlier values in nanoseconds */
+    readonly outliers_ns: Array<number>;
+    /** Ratio of outliers to total samples */
+    readonly outlier_ratio: number;
+    /** Number of samples after outlier removal */
+    readonly sample_size: number;
+    /** Original number of samples (before outlier removal) */
+    readonly raw_sample_size: number;
+    /** Operations per second (NS_PER_SEC / mean_ns) */
+    readonly ops_per_second: number;
+    /** Number of failed iterations (NaN, Infinity, or negative values) */
+    readonly failed_iterations: number;
+    constructor(timings_ns: Array<number>);
+    /**
+     * Format stats as a human-readable string.
+     */
+    toString(): string;
+}
+/**
+ * Compare two benchmark results for statistical significance.
+ * Uses Welch's t-test (handles unequal variances) and Cohen's d effect size.
+ *
+ * @param a - First benchmark stats (or any object with required properties)
+ * @param b - Second benchmark stats (or any object with required properties)
+ * @param options - Comparison options
+ * @returns Comparison result with significance, effect size, and recommendation
+ *
+ * @example
+ * ```ts
+ * const comparison = benchmark_stats_compare(result_a.stats, result_b.stats);
+ * if (comparison.significant) {
+ *   console.log(`${comparison.faster} is ${comparison.speedup_ratio.toFixed(2)}x faster`);
+ * }
+ * ```
+ */
+export declare const benchmark_stats_compare: (a: BenchmarkStatsComparable, b: BenchmarkStatsComparable, options?: BenchmarkCompareOptions) => BenchmarkComparison;
+//# sourceMappingURL=benchmark_stats.d.ts.map

package/dist/benchmark_stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark_stats.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/benchmark_stats.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAcH;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE1E;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,mFAAmF;IACnF,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,OAAO,CAAC;IAC5B,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,WAAW,EAAE,OAAO,CAAC;IACrB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,gBAAgB,EAAE,eAAe,CAAC;IAClC,mDAAmD;IACnD,UAAU,EAAE,OAAO,CAAC;IACpB,sDAAsD;IACtD,cAAc,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,qBAAa,cAAc;IAC1B,yCAAyC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iCAAiC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wCAAwC;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,QAAQ,CAAC,sBAAsB,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD,sDAAsD;IACtD,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACpC,yCAAyC;IACzC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,mDAAmD;IACnD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,sEAAsE;IACtE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;gBAEvB,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC;IAiErC;;OAEG;IACH,QAAQ,IAAI,MAAM;CAGlB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uBAAuB,GACnC,GAAG,wBAAwB,EAC3B,GAAG,wBAAwB,EAC3B,UAAU,uBAAuB,KAC/B,mBA6GF,CAAC"}