eyas-ranjoustimer-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 stoppedTimer.
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 }
License
This library is licensed under the MIT License. See LICENSE for details.