time.ts

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

Declarations
#

19 declarations

time_async
#

<T>(fn: () => Promise<T>, timer?: Timer): Promise<{ result: T; timing: TimeResult; }> import {time_async} from '@fuzdev/fuz_util/time.js';

Time an asynchronous function execution.

`fn`

type () => Promise<T>

`timer`

timer to use (defaults to timer_default)

type Timer

default timer_default

returns

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

generics

time_async<T>

`T`

examples

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

time_format
#

time.ts view source

(ns: number, unit: TimeUnit, decimals?: number): string import {time_format} from '@fuzdev/fuz_util/time.js';

Format time with a specific unit.

`ns`

type number

`unit`

type TimeUnit

`decimals`

type number

default 2

returns

string

formatted string like "3.87μs"

time_format_adaptive
#

time.ts view source

(ns: number, decimals?: number): string import {time_format_adaptive} from '@fuzdev/fuz_util/time.js';

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

`ns`

type number

`decimals`

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[]> import {time_measure} from '@fuzdev/fuz_util/time.js';

Measure multiple executions of a function and return all timings.

`fn`

type () => unknown

`iterations`

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.ts';
const stats = new BenchmarkStats(timings_ns);
console.log(`Mean: ${time_format_adaptive(stats.mean_ns)}`);

TIME_NS_PER_MS
#

time.ts view source

1000000 import {TIME_NS_PER_MS} from '@fuzdev/fuz_util/time.js';

TIME_NS_PER_SEC
#

time.ts view source

1000000000 import {TIME_NS_PER_SEC} from '@fuzdev/fuz_util/time.js';

TIME_NS_PER_US
#

time.ts view source

1000 import {TIME_NS_PER_US} from '@fuzdev/fuz_util/time.js';

Time units and conversions.

time_ns_to_ms
#

time.ts view source

(ns: number): number import {time_ns_to_ms} from '@fuzdev/fuz_util/time.js';

Convert nanoseconds to milliseconds.

`ns`

type number

returns

number

time_ns_to_sec
#

time.ts view source

(ns: number): number import {time_ns_to_sec} from '@fuzdev/fuz_util/time.js';

Convert nanoseconds to seconds.

`ns`

type number

returns

number

time_ns_to_us
#

time.ts view source

(ns: number): number import {time_ns_to_us} from '@fuzdev/fuz_util/time.js';

Convert nanoseconds to microseconds.

`ns`

type number

returns

number

time_sync
#

time.ts view source

<T>(fn: () => T, timer?: Timer): { result: T; timing: TimeResult; } import {time_sync} from '@fuzdev/fuz_util/time.js';

Time a synchronous function execution.

`fn`

type () => T

`timer`

timer to use (defaults to timer_default)

type Timer

default timer_default

returns

{ result: T; timing: TimeResult; }

generics

time_sync<T>

`T`

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 import {time_unit_detect_best} from '@fuzdev/fuz_util/time.js';

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`

type number[]

returns

TimeUnit

TIME_UNIT_DISPLAY
#

time.ts view source

Record<TimeUnit, string> import {TIME_UNIT_DISPLAY} from '@fuzdev/fuz_util/time.js';

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

Timer
#

time.ts view source

Timer import type {Timer} from '@fuzdev/fuz_util/time.js';

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 import {timer_browser} from '@fuzdev/fuz_util/time.js';

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 import {timer_default} from '@fuzdev/fuz_util/time.js';

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 import {timer_node} from '@fuzdev/fuz_util/time.js';

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

TimeResult
#

time.ts view source

TimeResult import type {TimeResult} from '@fuzdev/fuz_util/time.js';

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
#

time.ts view source

TimeUnit import type {TimeUnit} from '@fuzdev/fuz_util/time.js';

Time unit for formatting.