timer-node

A lightweight JavaScript library for measuring elapsed time in Node.js or the browser without using setInterval or setTimeout. It also has type definitions for TypeScript.

Installation

npm install timer-node

API

Import

// JS
const { Timer } = require('timer-node');

// TS
import { Timer, TimerOptions, Time } from 'timer-node';

Timer Class

A timestamp-based timer that can be started, paused, resumed, and stopped. It calculates durations based on system time.

Constructor

new Timer(options?: TimerOptions)

options: An optional configuration object with:
- label?: string – A label for this timer.
- startTimestamp?: number – Start time (if you want to initialize from the past).
- endTimestamp?: number – End time (if already stopped).
- currentStartTimestamp?: number – Most recent resume time.
- pauseCount?: number – Number of times paused.
- accumulatedMs?: number – Accumulated milliseconds from previous runs.

Common Methods

start(): Starts (or restarts) the timer.
pause(): Pauses the timer (if running).
resume(): Resumes the timer (if paused).
stop(): Stops the timer.
clear(): Clears all timer data, resetting it to an unstarted state.
isStarted() / isPaused() / isRunning() / isStopped(): Check the timer state.
ms(): Returns the elapsed time in milliseconds.
time(): Returns an object of time fractions (d, h, m, s, ms).
pauseMs() / pauseTime(): Similar to ms() / time(), but for paused duration.
pauseCount(): Returns how many times the timer has been paused.
format(template?: string): Formats the elapsed time using placeholders (%label, %d, %h, %m, %s, %ms).
serialize(): Returns a JSON string representing the timer state.

Static Methods

Timer.deserialize(serializedTimer: string): Timer
Re-creates a timer from a serialized string generated by .serialize().
Timer.benchmark(fn: () => any): Timer
Measures the synchronous execution time of fn. Returns a stopped Timer.

Time Object

Any method returning an object breakdown of time uses the following shape:

interface Time {
  d: number;  // days
  h: number;  // hours
  m: number;  // minutes
  s: number;  // seconds
  ms: number; // milliseconds
}

Example

const { Timer } = require('timer-node');

const timer = new Timer({ label: 'demo' });
timer.start();

// ... some operations ...

timer.pause();
console.log('Paused at', timer.ms(), 'ms');
timer.resume();

// ... more operations ...

timer.stop();
console.log('Total elapsed:', timer.time());
// e.g. { d: 0, h: 0, m: 1, s: 12, ms: 345 }