Timer

ExecutionTimer measures elapsed time without creating a trace. The tracing APIs use the same timer internally.

Timings come from performance.now(), so they are monotonic and unaffected by system clock changes.

Usage

Basic

import { ExecutionTimer } from 'execution-engine';

const timer = new ExecutionTimer();

timer.start();
for (let i = 0; i < 1_000_000; i++) {
  // work to measure
}
timer.stop();

console.log(timer.getDuration());    // 4.213829994201660
console.log(timer.getElapsedTime()); // "4.213 ms"

Multiple timers

One instance can hold many independent timers, each identified by a string. Anything without an explicit id uses 'default':

const timer = new ExecutionTimer();

timer.start('fetch');
await fetchUsers();
timer.stop('fetch');

timer.start('render');
renderUsers();
timer.stop('render');

console.log(timer.getElapsedTime('fetch'));  // "128.442 ms"
console.log(timer.getElapsedTime('render')); // "3.118 ms"

Timer details

getInfo() returns all the details for one timer as a single object:

console.log(timer.getInfo('fetch', 2, 2));
// {
//   executionId: 'fetch',
//   startTime: 2025-08-08T15:14:50.118Z,
//   endTime:   2025-08-08T15:14:50.246Z,
//   duration: 128.44,
//   elapsedTime: '128.44 ms'
// }

Human-readable output

getElapsedTime() breaks longer durations into readable units:

Pass fractionDigits to control the millisecond precision: timer.getElapsedTime('default', 3) "4.214 ms".

API

constructor(executionId?)

Creates a timer identified by executionId, defaulting to 'default'. Construction does not start it.

start(executionId?)

Starts, or restarts, the named timer. Restarting resets both timestamps.

stop(executionId?)

Stops the named timer. Does nothing if that timer was never started.

getDuration(executionId?, fractionDigits?)

Returns the elapsed milliseconds as a number, or undefined if the timer was never started.

• fractionDigits decimal places from 0 to 100. Omit it for full precision.

getElapsedTime(executionId?, fractionDigits?)

Returns the duration as a human-readable string, or undefined if the timer was never started.

getStartDate(executionId?)

Returns the wall-clock Date at which the timer started, or undefined. Derived from performance.timeOrigin plus the recorded offset.

getEndDate(executionId?)

Returns the wall-clock Date at which the timer stopped, or undefined if it has not been stopped.

getInfo(executionId?, durationFractionDigits?, elapsedTimeFractionDigits?)

Returns a TimerDetailsModel for one timer:

interface TimerDetailsModel {
  executionId: string;
  startTime: Date | undefined;
  endTime: Date | undefined;
  duration: number | undefined;
  elapsedTime: string | undefined;
}

The two precision arguments round duration and the millisecond portion of elapsedTime independently.

Stop a running timer before calling getInfo() when you need endTime in that result. getInfo() reads endTime before getDuration() performs its implicit stop.

Remarks

• The individual value getters return undefined when the requested timer was never started. getInfo() still returns an object, with its unavailable fields set to undefined.
• getEndDate() returns undefined while a timer is running. After stop() or getDuration(), it returns the recorded end date.

See also

• trace automatic timing as part of a full execution trace.
• Trace where duration and elapsedTime land on a trace node.