time.ts

Time utilities. Provides cross-platform high-resolution timing and measurement helpers.

Declarations
#

19 declarations

view source

time_async
#

time.ts view source

<T>(fn: () => Promise<T>, timer?: Timer): Promise<{ result: T; timing: TimeResult; }>

Time an asynchronous function execution.

fn

async function to time

type () => Promise<T>

timer

timer to use (defaults to timer_default)

type Timer
default timer_default

returns

Promise<{ result: T; timing: TimeResult; }>

object containing the function result and timing information

examples

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)}`);

time_format
#

time.ts view source

(ns: number, unit: TimeUnit, decimals?: number): string

Format time with a specific unit.

ns

time in nanoseconds

type number

unit

unit to use ('ns', 'us', 'ms', 's')

type TimeUnit

decimals

number of decimal places (default: 2)

type number
default 2

returns

string

formatted string like "3.87μs"

time_format_adaptive
#

time.ts view source

(ns: number, decimals?: number): string

Format time with adaptive units (ns/μs/ms/s) based on magnitude.

ns

time in nanoseconds

type number

decimals

number of decimal places (default: 2)

type number
default 2

returns

string

formatted string like "3.87μs" or "1.23ms"

examples

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"

time_measure
#

time.ts view source

(fn: () => unknown, iterations: number, timer?: Timer): Promise<number[]>

Measure multiple executions of a function and return all timings.

fn

function to measure (sync or async)

type () => unknown

iterations

number of times to execute

type number

timer

timer to use (defaults to timer_default)

type Timer
default timer_default

returns

Promise<number[]>

array of elapsed times in nanoseconds

examples

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)}`);

TIME_NS_PER_MS
#

TIME_NS_PER_SEC
#

TIME_NS_PER_US
#

time_ns_to_ms
#

time.ts view source

(ns: number): number

Convert nanoseconds to milliseconds.

ns

type number

returns

number

time_ns_to_sec
#

time.ts view source

(ns: number): number

Convert nanoseconds to seconds.

ns

type number

returns

number

time_ns_to_us
#

time.ts view source

(ns: number): number

Convert nanoseconds to microseconds.

ns

type number

returns

number

time_sync
#

time.ts view source

<T>(fn: () => T, timer?: Timer): { result: T; timing: TimeResult; }

Time a synchronous function execution.

fn

sync function to time

type () => T

timer

timer to use (defaults to timer_default)

type Timer
default timer_default

returns

{ result: T; timing: TimeResult; }

object containing the function result and timing information

examples

const {result, timing} = time_sync(() => { return expensive_computation(); }); console.log(`Result: ${result}, took ${time_format_adaptive(timing.elapsed_ns)}`);

time_unit_detect_best
#

time.ts view source

(values_ns: number[]): TimeUnit

Detect the best time unit for a set of nanosecond values. Chooses the unit where most values fall in the range 1-9999.

values_ns

array of times in nanoseconds

type number[]

returns

TimeUnit

best unit to use for all values

TIME_UNIT_DISPLAY
#

time.ts view source

Record<TimeUnit, string>

Display labels for time units (uses proper Unicode μ for microseconds).

Timer
#

time.ts view source

Timer

Timer interface for measuring elapsed time. Returns time in nanoseconds for maximum precision.

now

Get current time in nanoseconds

type () => number

timer_browser
#

time.ts view source

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.

timer_default
#

time.ts view source

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.

timer_node
#

time.ts view source

Timer

Node.js high-resolution timer using process.hrtime.bigint(). Provides true nanosecond precision.

TimeResult
#

time.ts view source

TimeResult

Result from timing a function execution. All times in nanoseconds for maximum precision.

elapsed_ns

Elapsed time in nanoseconds

type number

elapsed_us

Elapsed time in microseconds (convenience)

type number

elapsed_ms

Elapsed time in milliseconds (convenience)

type number

started_at_ns

Start time in nanoseconds (from timer.now())

type number

ended_at_ns

End time in nanoseconds (from timer.now())

type number

TimeUnit
#

Imported by
#