@gibme/timer

Event-based Timer/Metronome

A simple, event-driven timer library for Node.js built on EventEmitter. Provides a base Timer for interval-based ticks, plus SyncTimer and AsyncTimer helpers that execute functions on each tick and emit typed results.

Documentation

https://gibme-npm.github.io/timer/

Installation

npm install @gibme/timer

or

yarn add @gibme/timer

Usage

Basic Timer

import Timer from '@gibme/timer';

const timer = new Timer(60_000);

timer.on('tick', () => {
    // runs every 60 seconds
});

timer.start();

Auto-Start with Arguments

const timer = new Timer(5_000, true, 'hello', 42);

timer.on('tick', (greeting: string, value: number) => {
    console.log(greeting, value); // "hello" 42
});

SyncTimer

Wraps a synchronous function, executing it on each interval and emitting the result via the data event.

import { SyncTimer } from '@gibme/timer';

const timer = new SyncTimer(() => Math.random(), 1_000, true);

timer.on('data', (value, timestamp, interval) => {
    console.log(`Got ${value} at ${timestamp}s (every ${interval}ms)`);
});

AsyncTimer

Wraps an asynchronous function, awaiting it on each interval and emitting the resolved value.

import { AsyncTimer } from '@gibme/timer';

const timer = new AsyncTimer(async () => {
    const res = await fetch('https://api.example.com/data');
    return res.json();
}, 30_000, true);

timer.on('data', (payload, timestamp, interval) => {
    console.log(payload);
});

timer.on('error', (error) => {
    console.error('Request failed:', error);
});

sleep

A simple async sleep utility.

import { sleep } from '@gibme/timer';

await sleep(2_000); // wait 2 seconds

API

Timer

new Timer(interval: number, autoStart?: boolean, ...args: any[])

Parameter	Type	Default	Description
interval	number		Milliseconds between ticks
autoStart	boolean	false	Start immediately on construction
...args	any[]		Arguments forwarded to every tick event

Properties

Property	Type	Description
interval	number	The tick interval in milliseconds
paused	boolean	Whether the timer is paused
destroyed	boolean	Whether the timer has been destroyed

Methods

Method	Returns	Description
start()	void	Start the timer
stop()	void	Stop the timer
toggle()	boolean	Toggle on/off; returns true if now running
tick(...args)	void	Force an immediate tick with optional arguments
destroy()	void	Permanently stop and clean up the timer

Events

Event	Listener Signature	Description
tick	(...args: any[]) => void	Emitted on each interval tick
start	() => void	Emitted when the timer starts
stop	() => void	Emitted when the timer stops
error	(error: Error) => void	Emitted on errors

SyncTimer<Type>

Extends Timer. Executes a synchronous function on each tick.

new SyncTimer(func: () => Type, interval: number, autoStart?: boolean)

Emits a data event after each execution:

timer.on('data', (result: Type, timestamp: number, interval: number) => void)

AsyncTimer<Type>

Extends Timer. Executes an asynchronous function on each tick.

new AsyncTimer(func: () => Promise<Type>, interval: number, autoStart?: boolean)

Emits a data event after each execution resolves:

timer.on('data', (result: Type, timestamp: number, interval: number) => void)

Errors thrown or rejected by the function are emitted as error events.

License

MIT