timerider

Accurate timers with drift correction, pause/resume, and long delay support.

Features

Timerider improves upon standard timers in three key ways:

1. Time Drift Correction: Automatically corrects time drift for both setInterval and setTimeout, ensuring more accurate timing over long periods.
2. Long Delay Support: Handles delays longer than the 32-bit integer limit (2^31 - 1 ms), which standard timers cannot process correctly.
3. Pause & Resume: Adds the ability to pause a timer and resume it later, perfect for games or interactive applications.

Installation

Deno

deno add jsr:@denostack/timerider

Node.js & Browser

npm install timerider

Usage

Timeout

createTimeout works like setTimeout but returns a Timer object with additional control.

import { createTimeout } from "@denostack/timerider";

// Basic usage
createTimeout(() => {
  console.log("Hello after 1 second");
}, 1000);

// Pause and Resume
const timer = createTimeout(() => {
  console.log("This will run eventually...");
}, 5000);

// Pause the timer
timer.pause();

// Resume after some time
setTimeout(() => {
  timer.resume(); // Will resume waiting for the remaining time
}, 2000);

Interval

createInterval works like setInterval but with built-in drift correction.

import { createInterval } from "@denostack/timerider";

createInterval(() => {
  console.log("Tick every 1 second");
}, 1000);

Long Delays

Standard timers fail with delays larger than ~24.8 days (2^31 - 1 milliseconds). Timerider handles this seamlessly.

import { createTimeout } from "@denostack/timerider";

// Wait for 30 days
const thirtyDays = 1000 * 60 * 60 * 24 * 30;

createTimeout(() => {
  console.log("See you next month!");
}, thirtyDays);

API Reference

createTimeout(callback, delay)

Creates a timer that executes the callback after the specified delay.

• callback: Function to execute.
• delay: Number (ms) or Date object.
• Returns: Timer

createInterval(callback, interval, delay?)

Creates a timer that repeatedly executes the callback at the specified interval.

• callback: Function to execute.
• interval: Number (ms) for the repetition interval.
• delay: (Optional) Number (ms) or Date object for the initial start delay.
• Returns: Timer

Timer Interface

The object returned by createTimeout and createInterval.

interface Timer {
  /**
   * Returns the current state of the timer.
   * "waiting": Timer is running and waiting for the next execution.
   * "paused": Timer is paused.
   * "completed": Timer has finished (for timeouts) or paused permanently.
   */
  state(): "waiting" | "paused" | "completed";

  /**
   * Pauses the timer. The remaining time is preserved.
   */
  pause(): Timer;

  /**
   * Resumes the timer from where it left off.
   */
  resume(): Timer;

  /**
   * Permanently pauses the timer. Similar to clearTimeout/clearInterval.
   */
  clear(): void;
}