/**
 * Time utilities.
 * Provides cross-platform high-resolution timing and measurement helpers.
 *
 * @module
 */
/**
 * 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.
 */
export declare const time_unit_detect_best: (values_ns: Array<number>) => TimeUnit;
/**
 * Format time with a specific unit.
 * @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.
 * @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 timer - timer to use (defaults to `timer_default`)
 *
 * @example
 * ```ts
 * const {result, timing} = await time_async(async () => {
 *   await fetch('https://api.fuz.dev/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 timer - timer to use (defaults to `timer_default`)
 *
 * @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 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