npm.io
3.0.0 • Published 1 year ago

@georapbox/timer

Licence
MIT
Version
3.0.0
Deps
0
Size
26 kB
Vulns
0
Weekly
0
Stars
4

npm version npm license

Timer

A lightweight, drift-free timer library built for the browser — precise, pause-resumable, and easy to use.

API documentation • Demo

Installation

npm install --save @georapbox/timer

The library is exported in ESM format. You can import it the following way:

import { Timer } from '@georapbox/timer';

API

Constructor
new Timer({ elapsed, duration })

Options

Name Type Description
elapsed number Initial elapsed time in milliseconds. Default: 0. Must be ≥ 0.
duration number Total duration in milliseconds. Default: Infinity. Must be ≥ 0 or Infinity.

Throws

  • TypeError if either elapsed or duration is not a number.

Notes

  • The timer is paused after construction; call .start() to begin.
  • Internally drift-free: time is computed from absolute timestamps, not accumulated deltas.
Instance Methods

All methods (except getters) return the instance for chaining.

start()

Starts or resumes the timer. Has no effect if the timer is already running or has reached its full duration (elapsed >= duration).

stop()

Pauses the timer. The elapsed time is preserved for resuming later.

reset()

Stops and resets the timer to its initial elapsed time (the value passed at construction).

time()

Returns a snapshot of the timer's current time state:

const { elapsed, remaining } = timer.time();
  • elapsed — elapsed time in ms
  • remaining — remaining time in ms (Infinity if duration is Infinity)
on(type, listener, options), off(type, listener, options)

Attach, detach, event listeners for timer events.
(See Events below for details.)

Static Methods
Timer.now()

Returns a high-resolution, monotonic timestamp in milliseconds. Uses performance.now() when available, otherwise falls back to Date.now().

Properties
elapsed

Returns the current elapsed time in milliseconds.

remaining

Returns the remaining time in milliseconds (Infinity if duration is Infinity).

running

Returns true if the timer is currently running; otherwise false.

Events

The Timer instance emits standard Event objects using the DOM EventTarget API to signal state changes during its lifecycle. You can subscribe using .on() and unsubscribe using .off() methods.

Event Name Fired When Notes
start The timer starts or resumes after being stopped. Fired once per start.
tick On each animation frame while running. Frequency depends on the browser's requestAnimationFrame (≈60fps).
stop The timer is paused manually. Elapsed time is preserved for resuming.
reset The timer is reset to its initial elapsed time. Stops the timer if running.
finish The timer reaches its total duration. Fired once automatically at completion.

Events are standard Event objects (not CustomEvents) emitted through the DOM EventTarget interface. They don't bubble through the document — they're scoped to the Timer instance itself.
To access timing data, call .time() or read .elapsed / .remaining from the event's currentTarget.

When removing listeners with .off(), you must pass the same function reference you used with .on().
Creating a new anonymous function won't remove the previous listener — this mirrors native addEventListener / removeEventListener behavior in the DOM.

const timer = new Timer({ duration: 5000 });

const onStart = () => console.log('Timer started');
const onTick = evt => {
  const { elapsed, remaining } = evt.currentTarget.time();
  console.log(`Elapsed: ${elapsed}ms, Remaining: ${remaining}ms`);
};
const onFinish = () => console.log('Timer finished');

timer
  .on('start', onStart)
  .on('tick', onTick)
  .on('finish', onFinish)
  .start();

  // Later...
  timer.
    off('start', onStart)
    .off('tick', onTick)
    .off('finish', onFinish);
Usage Examples
Basic Countdown
const timer = new Timer({ duration: 10_000 })
  .on('tick', evt => {
    const { remaining } = evt.currentTarget;
    label.textContent = `${Math.ceil(remaining / 1000)}s`;
  })
  .on('finish', () => {
    label.textContent = 'Done!';
  });

timer.start();
Pause and Resume
timer.stop(); // Pause
// ...later
timer.start(); // Resume
Reset
const t = new Timer({ elapsed: 2000, duration: 10_000 }); // start "2s in"
t.start();
// ...
t.reset(); // back to 2000ms elapsed
Infinite timer
const infiniteTimer = new Timer({ duration: Infinity })
  .on('tick', () => console.log('Timer is running indefinitely'))
  .start();

Changelog

For API updates and breaking changes, check the CHANGELOG.

License

The MIT License (MIT)

Keywords