@philiprehberger/timer

Precise timing utilities — measure, benchmark, countdown

Installation

npm install @philiprehberger/timer

Usage

Timer

import { timer } from '@philiprehberger/timer';

const t = timer();

// Do some work...
t.lap();
// Do more work...
t.lap();

console.log(t.format()); // "245ms"
console.log(t.laps());   // [{ index: 1, split: 120, elapsed: 120 }, ...]

const total = t.stop();

Measure

import { measure, measureAsync } from '@philiprehberger/timer';

const { result, duration } = measure(() => heavyComputation());
console.log(`Result: ${result}, took ${duration}ms`);

const { result: data, duration: ms } = await measureAsync(() => fetch('/api'));
console.log(`Fetched in ${ms}ms`);

Benchmark

import { benchmark } from '@philiprehberger/timer';

const stats = benchmark(() => JSON.parse('{"a":1}'), {
  iterations: 5000,
  warmup: 500,
});

console.log(`Mean: ${stats.mean.toFixed(4)}ms`);
console.log(`Median: ${stats.median.toFixed(4)}ms`);
console.log(`P95: ${stats.p95.toFixed(4)}ms`);
console.log(`P99: ${stats.p99.toFixed(4)}ms`);
console.log(`Min: ${stats.min.toFixed(4)}ms`);
console.log(`Max: ${stats.max.toFixed(4)}ms`);
console.log(`Ops/sec: ${stats.ops.toFixed(0)}`);

Format Duration

import { formatDuration } from '@philiprehberger/timer';

formatDuration(0);         // "0ms"
formatDuration(1500);      // "1s 500ms"
formatDuration(3_661_500); // "1h 1m 1s 500ms"

API

timer(): Timer

Creates a high-resolution timer.

• .elapsed(): number — Current elapsed time in milliseconds.
• .stop(): number — Stops the timer; returns elapsed time.
• .reset(): void — Resets and restarts the timer.
• .lap(): Lap — Records a lap; returns { index, split, elapsed }.
• .laps(): Lap[] — Returns all recorded laps.
• .format(): string — Formats the elapsed time as a human-readable string.

measure<T>(fn: () => T): MeasureResult<T>

Measures execution time of a synchronous function. Returns { result, duration }.

measureAsync<T>(fn: () => Promise<T>): Promise<MeasureResult<T>>

Measures execution time of an asynchronous function. Returns { result, duration }.

benchmark(fn: () => void, options?: BenchmarkOptions): BenchmarkResult

Benchmarks a function over many iterations.

Options:

• iterations — Number of measured iterations (default: 1000).
• warmup — Number of warmup iterations (default: 100).

Result:

• mean — Arithmetic mean in ms.
• median — Median in ms.
• p95 — 95th percentile in ms.
• p99 — 99th percentile in ms.
• min — Minimum duration in ms.
• max — Maximum duration in ms.
• ops — Operations per second.
• iterations — Number of iterations run.

formatDuration(ms: number): string

Formats a millisecond value into a human-readable string (e.g. "1h 2m 3s 45ms").

Development

npm install
npm run build
npm test
npm run typecheck

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT