This module is ESM 🔆. Please read this.

An accurate timer utility for running periodic tasks on the given interval ticks or dates — with a single timer instance, zero runtime dependencies, and full TypeScript types.

Because of the single-threaded, asynchronous nature of JavaScript, each execution takes a slice of CPU time, and the wait before the next one varies with the load. This creates a cumulative latency in naive timers that gradually drifts away from the intended schedule. TaskTimer corrects this drift on every tick, and it lets you run many tasks — each on its own interval, run limit, or date window — from one timer.

• Precision (on by default): the delay between ticks is auto-adjusted when it drifts due to task/CPU load or clock drift. In Node, it uses high-resolution process.hrtime() (immune to clock drift) and auto-recovers via immediate ticks after a blocking task.
• Run or schedule multiple tasks on a single timer instance.
• Sync or async tasks — return a Promise or use the done() callback.
• Limit runs per task (totalRuns), add an initial delay (tickDelay), or bind a task to a date window (startDate / stopDate).
• Add, remove, reset, enable/disable, pause and resume tasks at any time — without recreating the timer.
• Stateful: auto-stop when all tasks complete (stopOnCompleted); free memory when a task finishes (removeOnCompleted).
• A familiar EventEmitter surface (on / once / off / emit …).
• ESM-only, zero runtime dependencies, written in TypeScript.

npm i tasktimer

import { TaskTimer } from 'tasktimer';

const timer = new TaskTimer(1000); // base interval: 1000 ms
timer.add(task => console.log(`Run #${task.currentRuns}`)).start();

const timer = new TaskTimer(5000);
timer.on(TaskTimer.Event.TICK, () => console.log(`Tick #${timer.tickCount}`));
timer.start();

const timer = new TaskTimer(1000); // 1s base resolution

timer.add([
    {
        id: 'task-1',
        tickInterval: 5,  // every 5 ticks → 5s
        totalRuns: 10,    // run 10 times only (0 = unlimited)
        callback(task) {
            console.log(`${task.id} ran ${task.currentRuns} times`);
        }
    },
    {
        id: 'task-2',
        tickDelay: 1,     // wait 1 tick before the first run
        tickInterval: 10, // every 10 ticks → 10s
        totalRuns: 2,
        callback(task) {
            console.log(`${task.id} ran ${task.currentRuns} times`);
        }
    }
]);

timer.on(TaskTimer.Event.TICK, () => {
    console.log(`tick ${timer.tickCount} · elapsed ${timer.time.elapsed} ms`);
});

timer.start();

// return a Promise
timer.add(task => fetch(url).then(handle));

// or call done() when finished
timer.add((task, done) => {
    fs.readFile(path, () => done());
});

const timer = new TaskTimer({ interval: 1000, stopOnCompleted: true });

timer.add({ totalRuns: 3, callback: doWork });
timer.add({ totalRuns: 5, callback: doOtherWork });

timer.on(TaskTimer.Event.COMPLETED, () => console.log('all tasks done'));
timer.start();

timer.start();
timer.pause();   // holds all tasks
timer.resume();  // continues where it left off
timer.stop();    // stops; tasks and counters are retained
timer.reset();   // back to idle; tasks removed silently

• You create a timer with a base interval (e.g. 1000 ms) — the tick resolution shared by all tasks.
• You add tasks that run on tick intervals (e.g. every 5th tick), optionally with a run limit, an initial delay, or a start/stop date.
• Beyond task callbacks, you can listen for lifecycle events (tick, task, completed, …).
• Tasks can be added, removed, reset, enabled or disabled at any time; the timer can be paused and resumed — all without recreating it.

options is either an ITaskTimerOptions object or a number (the base interval in ms).

TaskTimer also exposes the EventEmitter surface: on / addListener, once, off / removeListener, removeAllListeners, emit, listeners, listenerCount, eventNames.

A Task is created implicitly via timer.add(...), or explicitly with the constructor (an ITaskOptions with a required id and callback).

TaskTimer.State — IDLE · RUNNING · PAUSED · STOPPED.

TaskTimer.Event — the events emitted by the timer:

Event listeners receive an ITaskTimerEvent: { name, source, data?, error? }.

{ interval?, precision?, stopOnCompleted? }

{ id?, enabled?, tickDelay?, tickInterval?, totalRuns?, startDate?, stopDate?, immediate?, removeOnCompleted?, callback }

{ started, stopped, elapsed } — timestamps and elapsed time in ms.

{ name, source, data?, error? }

(task: Task, done?: () => void) => void | Promise<unknown>

Full reference: onury.io/tasktimer.

See CHANGELOG.md. Migrating from v3? See the Unreleased notes — v4 is ESM-only.

• AccessControl — Role and Attribute based Access Control for Node.js.
• Notation — Utility for notating and manipulating JS objects via dot-separated keys.

© 2026, Onur Yıldırım. MIT License.