Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build Status Coverage Status Known Vulnerabilities Downloads License
npm Release TypeScript Documentation
© 2021, Onur Yıldırım (@onury).

An accurate timer utility for running periodic tasks on the given interval ticks or dates.

Why TaskTimer?

Because of the single-threaded, asynchronous nature of JavaScript, each execution takes a piece of CPU time, and the time they have to wait will vary, depending on the load. This creates a latency and cumulative difference in asynchronous timers; that gradually increase the inacuraccy. TaskTimer claims to be the best timer that overcomes this problem as much as possible.

Secondly, I needed a task manager that can handle multiple tasks on different intervals, with a single timer instance.


  • Precission & Accuracy: With the precision option (enabled by default);
    • The delay between each tick is auto-adjusted when it's off due to task/CPU loads or clock drifts.
    • In Node.js, TaskTimer also makes use of process.hrtime() high-resolution real-time. The time is relative to an arbitrary time in the past (not related to the time of day) and therefore not subject to clock drifts.
    • The timer may hit a synchronous / blocking task; or detect significant time drift (longer than the base interval) due to JS event queue, which cannot be recovered by simply adjusting the next delay. In this case, right from the next tick onward; it will auto-recover as much as possible by running "immediate" tasks until it reaches the proper time vs tick/run balance.
  • Run or schedule multiple tasks (on a single timer instance).
  • Ability to run sync or async tasks that return a promise (or use callbacks).
  • Ability to balance task-loads via distributing executions by tick intervals.
  • Ability to limit total runs of a task.
  • Stateful tasks: i.e. ability to auto-stop when all tasks complete.
  • TaskTimer is also an EventEmitter.
  • Universal module. Works in both Node and Browser.
  • Small size (4.5kB minified, gzipped).
  • Completely re-written in TypeScript. (version 2.0.0+)


npm i tasktimer


In Node/CommonJS environments:

const { TaskTimer } = require('tasktimer');

With transpilers (TypeScript, Babel):

import { TaskTimer } from 'tasktimer';

In (Modern) Browsers:

<script src="js/tasktimer.min.js"></script>
    const { TaskTimer } = tasktimer;

Simplest Example

const timer = new TaskTimer(1000);
timer.add(task => console.log(`Current runs: ${task.currentRuns}`)).start();

Regular Timer (without Task Management)

const timer = new TaskTimer(5000);
timer.on('tick', () => console.log(`Tick count: ${timer.tickCount}`));

Detailed Example

// Timer with 1000ms (1 second) base interval resolution.
const timer = new TaskTimer(1000);
// interval can be updated anytime by setting the `timer.interval` property.

// Add multiple tasks (at once) based on tick intervals.
        id: 'task-1',       // unique ID of the task
        tickInterval: 5,    // run every 5 ticks (5 x interval = 5000 ms)
        totalRuns: 10,      // run 10 times only. (set to 0 for unlimited times)
        callback(task) {
            // code to be executed on each run
            console.log(`${} task has run ${task.currentRuns} times.`);
        id: 'task-2',       // unique ID of the task
        tickDelay: 1,       // 1 tick delay before first run
        tickInterval: 10,   // run every 10 ticks (10 x interval = 10000 ms)
        totalRuns: 2,       // run 2 times only. (set to 0 for unlimited times)
        callback(task) {
            // code to be executed on each run
            console.log(`${} task has run ${task.currentRuns} times.`);

// You can also execute some code on each tick... (every 1000 ms)
timer.on('tick', () => {
    console.log('tick count: ' + timer.tickCount);
    console.log('elapsed time: ' + timer.time.elapsed + ' ms.');
    // stop timer (and all tasks) after 1 hour
    if (timer.tickCount >= 3600000) timer.stop();

// Start the timer

How it works

  • When you create a timer; you set a time-interval (e.g. 1000 milliseconds), to be used as base resolution (tick) for the tasks.
  • Then add task(s) to be executed on tick-intervals.
    (e.g. task1 runs on every 10th tick, task2 runs on every 30th)
  • You can optionally define:
    • The number of total runs,
    • An initial delay,
    • Start/end dates for each task...
  • In addition to task callbacks; event listeners can be added to execute some other code on each tick (base interval) or task run, etc...
  • You can add, remove, reset, disable individual tasks at any time, without having to stop or re-create the timer.
  • Pause and resume the timer at any time; which effects all current tasks.


See API reference and examples here.


If you're migrating from TaskTimer v1 to v2+, there are various breaking changes!..


Clone original project:

git clone

Install dependencies:

npm install

Add tests into test/node and test/browser and run:

npm run test!   # builds and runs tests
npm test        # runs tests without building

Use included tslint.json and editorconfig for style and linting.
Travis build should pass, coverage should not degrade.




An accurate timer utility for running periodic tasks on the given interval ticks or dates. (Node and Browser)







No packages published