doc: README

Author: wan2land

README.md

@@ -0,0 +1,142 @@
+# timerider <a href="https://github.com/denostack"><img src="https://raw.githubusercontent.com/denostack/images/main/logo.svg" width="160" align="right" /></a>
+
+<p>
+  <a href="https://github.com/denostack/timerider/actions"><img alt="Build" src="https://img.shields.io/github/actions/workflow/status/denostack/timerider/ci.yml?branch=main&logo=github&style=flat-square" /></a>
+  <a href="https://codecov.io/gh/denostack/timerider"><img alt="Coverage" src="https://img.shields.io/codecov/c/gh/denostack/timerider?style=flat-square" /></a>
+  <img alt="License" src="https://img.shields.io/npm/l/timerider.svg?style=flat-square" />
+  <img alt="Language Typescript" src="https://img.shields.io/badge/language-Typescript-007acc.svg?style=flat-square" />
+  <br />
+  <a href="https://jsr.io/@denostack/timerider"><img alt="JSR version" src="https://jsr.io/badges/@denostack/timerider?style=flat-square" /></a>
+</p>
+
+A robust timer library for Deno that solves common issues with standard `setTimeout` and `setInterval`.
+
+## Features
+
+Timerider improves upon standard timers in three key ways:
+
+1. **Time Drift Correction**: Automatically corrects time drift within 250ms 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
+
+```bash
+deno add jsr:@denostack/timerider
+```
+
+### Node.js & Browser
+
+```bash
+npm install timerider
+```
+
+## Usage
+
+### Timeout
+
+`createTimeout` works like `setTimeout` but returns a `Timer` object with additional control.
+
+```ts
+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.
+
+```ts
+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.
+
+```ts
+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`.
+
+```ts
+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;
+}
+```

timer.test.ts

@@ -41,18 +41,18 @@ Deno.test("createTimeout() - executes callback after delay (Date)", async () =>
   assertSpyCalls(spyCallback, 1);
 });
 
-Deno.test("createTimeout() - can be stopped and restarted", async () => {
+Deno.test("createTimeout() - can be paused and restarted", async () => {
   const spyCallback = spy(() => {});
-  // Start with 100ms delay, but stop immediately
-  const timer = createTimeout(spyCallback, 100).stop();
-  assertEquals(timer.state(), "stopped");
+  // Start with 100ms delay, but pause immediately
+  const timer = createTimeout(spyCallback, 100).pause();
+  assertEquals(timer.state(), "paused");
 
   // Wait longer than the delay
   await sleep(150);
   assertSpyCalls(spyCallback, 0);
 
   // Restart
-  timer.start();
+  timer.resume();
   assertEquals(timer.state(), "waiting");
 
   // Wait for the remaining time
@@ -113,31 +113,31 @@ Deno.test("createInterval() - executes with initial delay", async () => {
   timer.clear();
 });
 
-Deno.test("createInterval() - can be stopped and restarted", async () => {
+Deno.test("createInterval() - can be paused and restarted", async () => {
   const spyCallback = spy(() => {});
   const timer = createInterval(spyCallback, 50);
 
   // Allow 2 calls (~100ms)
   await sleep(120);
-  const callsBeforeStop = spyCallback.calls.length;
-  assertEquals(callsBeforeStop >= 2, true);
+  const callsBeforePause = spyCallback.calls.length;
+  assertEquals(callsBeforePause >= 2, true);
 
-  // Stop
-  timer.stop();
-  assertEquals(timer.state(), "stopped");
+  // Pause
+  timer.pause();
+  assertEquals(timer.state(), "paused");
 
   // Wait 200ms (should be no new calls)
   await sleep(200);
-  assertSpyCalls(spyCallback, callsBeforeStop);
+  assertSpyCalls(spyCallback, callsBeforePause);
 
   // Restart
-  timer.start();
+  timer.resume();
 
   // Wait another 100ms (expect more calls)
   await sleep(120);
 
   const callsAfterRestart = spyCallback.calls.length;
-  assertEquals(callsAfterRestart > callsBeforeStop, true);
+  assertEquals(callsAfterRestart > callsBeforePause, true);
 
   timer.clear();
 });

timer.ts

@@ -4,9 +4,9 @@ const MAX_DELAY = 2147483647; // 2 ** 31 - 1
 const ACCURACY = 250;
 
 export interface Timer {
-  state(): "waiting" | "stopped" | "completed";
-  stop(): Timer;
-  start(): Timer;
+  state(): "waiting" | "paused" | "completed";
+  pause(): Timer;
+  resume(): Timer;
   clear(): void;
 }
 
@@ -19,21 +19,21 @@ export function createTimeout(
 ): Timer {
   let waitUntil = parseDelay(delay ?? 0);
   let timer: ReturnType<typeof setTimeout> | null = null;
-  let stopRemains: number | null = null;
+  let pauseRemains: number | null = null;
   let isCompleted = false;
 
   const timeoutInstance = {} as Timer;
-  function stop() {
+  function pause() {
     if (isCompleted) return timeoutInstance;
     timer && clearTimeout(timer);
-    stopRemains = stopRemains ?? waitUntil - Date.now();
+    pauseRemains = pauseRemains ?? waitUntil - Date.now();
     return timeoutInstance;
   }
-  function start() {
+  function resume() {
     if (isCompleted) return timeoutInstance;
-    if (typeof stopRemains === "number") {
-      waitUntil = Date.now() + stopRemains;
-      stopRemains = null;
+    if (typeof pauseRemains === "number") {
+      waitUntil = Date.now() + pauseRemains;
+      pauseRemains = null;
     }
     const remains = Math.max(0, waitUntil - Date.now());
     if (remains <= ACCURACY) {
@@ -42,7 +42,7 @@ export function createTimeout(
         cb();
       }, remains);
     } else {
-      timer = setTimeout(start, Math.min(remains >> 1, MAX_DELAY));
+      timer = setTimeout(resume, Math.min(remains >> 1, MAX_DELAY));
     }
     return timeoutInstance;
   }
@@ -52,16 +52,16 @@ export function createTimeout(
   }
   function state() {
     if (isCompleted) return "completed";
-    if (typeof stopRemains === "number") return "stopped";
+    if (typeof pauseRemains === "number") return "paused";
     return "waiting";
   }
 
   timeoutInstance.state = state;
-  timeoutInstance.start = start;
-  timeoutInstance.stop = stop;
+  timeoutInstance.pause = pause;
+  timeoutInstance.resume = resume;
   timeoutInstance.clear = clear;
 
-  start();
+  resume();
 
   return timeoutInstance;
 }
@@ -77,31 +77,31 @@ export function createInterval(
 ): Timer {
   let waitUntil = parseInterval(parseDelay(delay ?? 0), interval ?? 0);
   let timer: ReturnType<typeof setTimeout> | null = null;
-  let stopRemains: number | null = null;
+  let pauseRemains: number | null = null;
   let isCompleted = false;
 
   const intervalInstance = {} as Timer;
-  function stop() {
+  function pause() {
     if (isCompleted) return intervalInstance;
     timer && clearTimeout(timer);
-    stopRemains = stopRemains ?? waitUntil - Date.now();
+    pauseRemains = pauseRemains ?? waitUntil - Date.now();
     return intervalInstance;
   }
-  function start() {
+  function resume() {
     if (isCompleted) return intervalInstance;
-    if (typeof stopRemains === "number") {
-      waitUntil = Date.now() + stopRemains;
-      stopRemains = null;
+    if (typeof pauseRemains === "number") {
+      waitUntil = Date.now() + pauseRemains;
+      pauseRemains = null;
     }
     const remains = Math.max(0, waitUntil - Date.now());
     if (remains <= ACCURACY) {
       timer = setTimeout(() => {
         cb();
         waitUntil = parseInterval(waitUntil, interval || 0);
-        start();
+        resume();
       }, remains);
     } else {
-      timer = setTimeout(start, Math.min(remains >> 1, MAX_DELAY));
+      timer = setTimeout(resume, Math.min(remains >> 1, MAX_DELAY));
     }
     return intervalInstance;
   }
@@ -111,16 +111,16 @@ export function createInterval(
   }
   function state() {
     if (isCompleted) return "completed";
-    if (typeof stopRemains === "number") return "stopped";
+    if (typeof pauseRemains === "number") return "paused";
     return "waiting";
   }
 
-  intervalInstance.start = start;
-  intervalInstance.stop = stop;
+  intervalInstance.pause = pause;
+  intervalInstance.resume = resume;
   intervalInstance.clear = clear;
   intervalInstance.state = state;
 
-  start();
+  resume();
 
   return intervalInstance;
 }