@philiprehberger/timer

Precise timing utilities — measure, benchmark, countdown

Installation

npm install @philiprehberger/timer

Usage

import { timer, measure, benchmark, interval, formatDuration } from '@philiprehberger/timer';

const t = timer();
doSomeWork();
console.log(t.format()); // "245ms"

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"

Drift-Corrected Interval

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

const handle = interval(() => poll(), 1000, { immediate: true });

// later
handle.stop();

Each tick is scheduled relative to the intended next time, so a slow callback does not cause cumulative drift. Async callbacks are awaited before the next tick is scheduled.

API

Function	Description
timer()	Create a high-resolution timer with elapsed/stop/reset/lap/laps/format
measure(fn)	Measure a synchronous function — returns { result, duration }
measureAsync(fn)	Measure an async function — returns a promise of { result, duration }
benchmark(fn, options?)	Benchmark a function over many iterations
interval(fn, ms, options?)	Drift-corrected repeating interval; returns a stoppable handle
formatDuration(ms)	Format milliseconds as "1h 2m 3s 45ms"

IntervalOptions

Option	Type	Default	Description
immediate	boolean	false	Run the callback once on start as well as on the schedule
maxTicks	number	undefined	Stop automatically after N ticks
onError	(err: unknown) => void	undefined	Receive errors thrown by the callback (otherwise rethrown)

BenchmarkResult

Property	Description
mean, median, p95, p99, min, max	Latency stats in ms
ops	Operations per second based on mean
iterations	Number of measured iterations

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