@fuzdev/fuz_util 0.42.0 → 0.43.0

package/dist/stats.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Statistical analysis utilities.
+ * Pure functions with zero dependencies - can be used standalone for any data analysis.
+ */
+/**
+ * Calculate the mean (average) of an array of numbers.
+ */
+export declare const stats_mean: (values: Array<number>) => number;
+/**
+ * Calculate the median of an array of numbers.
+ */
+export declare const stats_median: (values: Array<number>) => number;
+/**
+ * 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 declare const stats_std_dev: (values: Array<number>, mean?: number) => number;
+/**
+ * Calculate the variance of an array of numbers.
+ */
+export declare const stats_variance: (values: Array<number>, mean?: number) => number;
+/**
+ * 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 declare const stats_percentile: (values: Array<number>, p: number) => number;
+/**
+ * Calculate the coefficient of variation (CV).
+ * CV = standard deviation / mean, expressed as a ratio.
+ * Useful for comparing relative variability between datasets.
+ */
+export declare const stats_cv: (mean: number, std_dev: number) => number;
+/**
+ * Calculate min and max values.
+ */
+export declare const stats_min_max: (values: Array<number>) => {
+    min: number;
+    max: number;
+};
+/**
+ * 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 declare const stats_outliers_iqr: (values: Array<number>, options?: StatsOutliersIqrOptions) => StatsOutlierResult;
+/**
+ * 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 declare const stats_outliers_mad: (values: Array<number>, options?: StatsOutliersMadOptions) => StatsOutlierResult;
+/**
+ * Common z-scores for confidence intervals.
+ */
+export declare const 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
+ * ```
+ */
+export declare const confidence_level_to_z_score: (level: number) => number;
+/**
+ * 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 declare const stats_confidence_interval: (values: Array<number>, options?: StatsConfidenceIntervalOptions) => [number, number];
+//# sourceMappingURL=stats.d.ts.map

package/dist/stats.d.ts.map

@@ -0,0 +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"}

package/dist/stats.js

@@ -0,0 +1,262 @@
+/**
+ * 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 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
+ * 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) => {
+    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;
+};
+/**
+ * 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) => {
+    // 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/dist/time.d.ts

@@ -0,0 +1,161 @@
+/**
+ * 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';
+/**
+ * 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;;;;;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"}