eternal-timer

A simple and persistent timer library for Node.js. Timers are saved to a file and maintain their state even after process restart.

Features

• Monitor Timers (asynchronous): Start monitoring expired timers asynchronously; the function returns immediately and the callback is invoked when timers expire.
• Persistence: Save timer data to a file that persists across process restarts

Installation

npm install eternal-timer

Usage

Basic Example

import { createTimer, checkTimers, removeTimer, showTimers } from 'eternal-timer';

async function main() {
  // Create a timer (5 seconds)
  const timerId = await createTimer(5000);
  console.log('Timer created:', timerId);

  // Monitor timers (executes when timer expires)
  checkTimers((timer) => {
    console.log('Timer expired:', timer.id);
  });

  // Display all timers
  const timers = await showTimers();
  console.log('Active timers:', timers);

  // Remove a timer
  await removeTimer(timerId);
}

API

createTimer(length: number): Promise<string>

Creates a new timer.

Parameters:

• length (number): Timer duration in milliseconds

Returns: Promise that resolves to the timer ID (UUID)

Throws: If length is invalid(e.g. length < 0) or file operation fails

removeTimer(id: string): Promise<boolean>

Removes a timer by ID.

Parameters:

• id (string): ID of the timer to remove

Returns: void

checkTimers(callback: (timer: Timer) => void, interval?: number): Promise<void>

Starts monitoring expired timers asynchronously and returns immediately. The callback is invoked asynchronously when a timer expires.

Parameters:

• callback: Function invoked when an expired timer is detected (called asynchronously)
• interval (number, optional): Check interval in milliseconds (default: 50ms)

Throws: If file operation fails

showTimers(): Promise<Timer[]>

Retrieves all active timers.

Returns: Array of Timer objects

Throws: If file operation fails

Type Definition

type Timer = {
    id: string;      // Unique timer identifier (UUID)
    start: string;   // Timer start timestamp
    stop: string;    // Timer end timestamp
}

Scripts

• npm run dev: Run in development mode with nodemon
• npm run build: Compile TypeScript
• npm start: Run compiled JavaScript

Storage

Timer data is stored in the .timers file in the project root. Each line follows this format:

{id} {start_timestamp} {stop_timestamp}

License

Apache-2.0

Licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Repository

https://github.com/SUKEsann2000/eternal-timer