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.

📖  Full documentation & guides:  onury.io/tasktimer

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 a single timer.

• Precision (on by default): the delay between ticks is auto-adjusted when it drifts due to task/CPU load or clock drift. It uses the monotonic performance.now() (drift-free, in Node and the browser) 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), run on the leading edge (lead), or bind a task to a date window (startDate / stopDate).
• Attach arbitrary data to a task — typed via Task<TData>.
• 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, typed EventEmitter surface (on / once / off / emit …) — listeners get a typed event.
• Coded errors — every throw is a TaskTimerError with a stable err.code; opt out of swallowing task errors with silentErrors.
• ESM-only, zero runtime dependencies, runs in Node and the browser, written in TypeScript.

Event, State, Task, TaskTimerError and ErrorCode are all named exports (there is no TaskTimer.Event namespace).

• 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).

All are named exports: import { State, Event, ErrorCode } from 'tasktimer'.

State — IDLE · RUNNING · PAUSED · STOPPED.

ErrorCode — the code on a thrown TaskTimerError: NO_TASK_PROVIDED · TASK_ID_REQUIRED · CALLBACK_REQUIRED · DUPLICATE_TASK_ID · NO_SUCH_TASK · INVALID_DATE_RANGE · CANNOT_CHANGE_ID · TASK_ERROR.

Event — the events emitted by the timer:

Event listeners receive a typed ITaskTimerEvent: { name, timer, task?, error? }. The related task is event.task and the timer is event.timer — on every event, including taskError.

{ interval?, precision?, stopOnCompleted?, silentErrors? }

{ id?, enabled?, tickDelay?, tickInterval?, totalRuns?, startDate?, stopDate?, defer?, lead?, removeOnCompleted?, data?, callback }

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

{ name, timer, task?, error? }

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

Full reference: onury.io/tasktimer.

See CHANGELOG.md. Migrating from v3? See the migration notes — v4 is ESM-only, drops the TaskTimer.Event namespace for named exports, and reshapes the event payload.

• AccessControl — Role and Attribute based Access Control for Node.js.
• Configuard — Turn flat config rows from a database table into a nested, typed configuration object — with ${...} templating and accessor-based (ABAC) filtering.
• Notation — Read, modify, and filter the contents of objects and arrays via dot/bracket notation strings or glob patterns.

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