Promise-based simple timer for Node.js

This module provides a simple, promise-based timer for Node.js. It allows the creation of timers that can be awaited asynchronously, making it easier to manage timeouts and delays in your code. The SimpleTimer class supports starting and cancelling the timers, and also provides information about the timer's state.

Table of Contents

• Installation
• Usage
  • Starting a Timer
  • Cancelling a Timer
  • Using Timer States
• Timer States
• The SimpleTimer Class
  • Static Properties
  • Instance Properties
  • Instance Methods
• Contributing
• License

Installation

You can install this module via npm:

npm install @jfabello/simple-timer

Usage

To use the simple-timer module, first import it into your code and then create an instance of the SimpleTimer class.

Here are some examples:

Starting a Timer

const SimpleTimer = require('@jfabello/simple-timer');

async function someAsyncFunction() {
    // Creates a new SimpleTimer instance with a 2000 ms timeout
    let timer = new SimpleTimer(2000);

	// Start the timer and wait for it to finish
    await timer.start();
	console.log("Timer done!");
}

someAsyncFunction();

Cancelling a Timer

const SimpleTimer = require('@jfabello/simple-timer');

async function someAsyncFunction() {
    // Creates a new SimpleTimer instance with a 2000 ms timeout
    let timer = new SimpleTimer(2000);

	// Start the timer and wait for it to finish
    let timerPromise = timer.start();

	// Cancel the timer after 1000 ms
	setTimeout(async () => {
		timer.cancel();
		await timerPromise;
		console.log("Timer cancelled!");
	}, 1000);
}

someAsyncFunction();

Using Timer States

const SimpleTimer = require('@jfabello/simple-timer');

async function someAsyncFunction() {
	// Creates a new SimpleTimer instance with a 2000 ms timeout
	let timer = new SimpleTimer(2000);

	// Start the timer and wait for it to finish
	let timerPromise = timer.start();

	// Report the state of the timer every 500 ms
	let interval = setInterval(() => {
		console.log(`Timer state: ${timer.state.toString()}`);
		if (timer.state === SimpleTimer.DONE || timer.state === SimpleTimer.CANCELLED) {
			clearInterval(interval);
			clearTimeout(timeout);
		}
	}, 500);

	// Cancel the timer after 1000 ms
	let timeout = setTimeout(async () => {
		timer.cancel();
		await timerPromise;
		console.log("Timer cancelled!");
	}, 1500);
}

someAsyncFunction();

The code above should output the following to the console:

Timer state: Symbol(RUNNING)
Timer state: Symbol(RUNNING)
Timer cancelled!
Timer state: Symbol(CANCELLED)

Timer States

The SimpleTimer class provides the following states:

stateDiagram-v2
	[*] --> SET : new SimpleTimer(timeout)
	SET --> RUNNING : start()
	RUNNING --> DONE : "timerup" event
	RUNNING --> CANCELLED : cancel() and then the "timercancelled" event

The SimpleTimer Class

A simple timer class that provides a way to set, start, and cancel a timer with a specified timeout.

Static Properties

• SET: Read-only property representing the SET timer state.
• RUNNING: Read-only property representing the RUNNING timer state.
• DONE: Read-only property representing the DONE timer state.
• CANCELLED: Read-only property representing the CANCELLED timer state.
• errors: Read-only property that contains the simple timer error classes as its properties.

Instance Properties

• state: The timer instance state.

Instance Methods

constructor(timeout)

Creates a new SimpleTimer instance with the specified timeout.

Parameters

• timeout: The timeout duration in milliseconds. Must be an integer greater than 0.

Throws

• ERROR_SIMPLE_TIMER_TIMEOUT_TYPE_INVALID: If the timeout is not an integer.
• ERROR_SIMPLE_TIMER_TIMEOUT_OUT_OF_BOUNDS: If the timeout is less than 1.

start()

Starts the timer if it is in the SET state. If the timer is already running, it returns the existing timer promise. If the timer is not in the SET or RUNNING states, it throws an error.

Returns

A promise that fulfills to SimpleTimer.DONE if the timer times out, or SimpleTimer.CANCELLED if the timer is cancelled before it times out.

Throws

• ERROR_SIMPLE_TIMER_NOT_IN_SET_OR_RUNNING_STATES: If the timer is not in the SET or RUNNING states.

cancel()

Cancels the simple timer. If the timer is not in the RUNNING state, it throws an error.

Returns

• A promise that fulfills to SimpleTimer.CANCELLED once the timer is cancelled.

Throws

• ERROR_SIMPLE_TIMER_NOT_RUNNING: If the timer is not running.

Testing

To run the tests for this module, first clone the repository using the following command:

git clone https://github.com/jfabello/simple-timer.git

Then, navigate to the project directory and install the npm dependencies, this will install the Jest testing framework:

cd simple-timer
npm install

Finally, run the tests using the following command:

npm test

Contributing

Unfortunately, we are not able to accept contributions at this time.

If you find a bug in the code, please open an issue.

Thank you for your understanding.

License

This project is licensed under the MIT License. See the LICENSE file for details.