About

The @h2ml/bettertimeout library provides 2 simple classes for working with the native window.setTimeout() method in a more modern, robust, manner.

Quick Start Guide

The Timeout Class

The Timeout class is the more simple of the two interfaces. After being invoked with new and provided with a callback and duration, this will create a timeout function, which will call the provided callback after the specified duration. Just like the window.setTimeout() method.

The Timeout class contains a single method, Timeout.clear() which works analogously to window.clearTimeout() and will clear the timeout when called.

import { Timeout } from '@h2ml/bettertimeout';
   
// Create a Timeout.
const timeout = new Timeout(() => {
	console.log('Called after 3 seconds.');
}, 3000);

// Clear a Timeout.
timeout.clear(() => {
	console.log('Timeout cleared!');
});

The Timer Class

The Timer class is the more robust of the two interfaces. After being invoked with new and provided with a config object, the Timer instance can be used (and re-used) as a Promise based alternative to both the Timeout class and the window.setTimeout() method.

The config object takes four properties, the required duration property, and the optional startedCallback, successCallback, & failureCallback properties. As with the Timeout class the duration property specifies how long the Timer should wait before resolving, with the relevant callback properties being called throughout the lifecycle of the Timer.

The Timeout class contains a single public property, and 2 methods.

The Timer.done property, once Timer.start() has been called, stores a Promise which will either resolve with the value of calling the successCallback (if one was provided), or upon calling Timer.cancel(), will reject with the value of calling failureCallback (if one was provided).

The Timer.start() method creates a new Promise, accessible through the Timer.done property, this method also calls the startedCallback (if one was provided). The Timer.Start() property can be provided with a config Object as an argument, which can contain the property duration which will override the duration defined by the Timer Instance for this call only.

The Timer.cancel() method cancels the timer, and rejects the Timer.donePromise.

import { Timer } from '@h2ml/bettertimeout';
	
(async () => {try {

	// Timer creation.
	const timer = new Timer({
		duration: 3000, 
		startedCallback: () => console.log('%cTimer started', 'color: #bada55'), 
		successCallback: () => console.log('%cTimer finished', 'color: #00ff00'), 
		failureCallback: () => console.log('%cTimer cancelled', 'color: #ff0f0f')
	});

	// Basic Usage.
	timer.start();
	await timer.done;

	// Chained Usage.
	timer.start().done.then(res => /* Handle success here... */).catch(err => /* Handle cancel here... */);

	// Overriding the duration in the Timer.start() method, 
	// for this call only the Timer will resolve after 1 second.
	await timer.start({
		duration: 1000
	}).done;

	// Updating the Timer instance duration, any subesquent calls 
	// to this Timer instance will now resolve after 5 seconds. 
	timer.duration = 5000;
	await timer.start().done;

	// Cancelling the Timer after 2 seconds.
	timer.start();
	timer.done.then(res => console.log(This will never be called));
	setTimeout(() => {
		timer.cancel();
	}, 2000)
		
} catch(e) {
	// Catch-all for cancelling.
	console.log('A timer was cancelled.');
}})();

@h2ml/bettertimeout

Version: 1.0.0
Author: Jack Notman

• @h2ml/bettertimeout
  • ~Timeout
    • new Timeout(callback, duration)
    • .clear([callback])
  • ~Timer
    • new Timer(config)
    • .done : Undefined | Promise
    • .duration
    • .startedCallback
    • .successCallback
    • .failureCallback
    • .start(config)
    • .cancel()

@h2ml/bettertimeout~Timeout

The Timeout class.

Kind: inner class of @h2ml/bettertimeout

• ~Timeout
  • new Timeout(callback, duration)
  • .clear([callback])

new Timeout(callback, duration)

Creates a new instance of the Timeout class.

| Param | Type | Description | | --- | --- | --- | | callback | function | The callback function to be run once the Timeout finishes. | | duration | Number | The duration, in milliseconds, to wait before the callback function is called. |

timeout.clear([callback])

Clears the Timeout, and calls the callback function if one is provided.

Kind: instance method of Timeout

| Param | Type | Default | Description | | --- | --- | --- | --- | | [callback] | function | false | The callback function to optionally be run once the Timeout finishes. |

@h2ml/bettertimeout~Timer

The Timer class.

Kind: inner class of @h2ml/bettertimeout

• ~Timer
  • new Timer(config)
  • .done : Undefined | Promise
  • .duration
  • .startedCallback
  • .successCallback
  • .failureCallback
  • .start(config)
  • .cancel()

new Timer(config)

Creates a new instance of the Timer class.

| Param | Type | Description | | --- | --- | --- | | config | Object | The default config options for the Timer instance. | | config.duration | Number | The duration, in milliseconds, to wait before the Timer finishes. | | [config.startedCallback] | function | The callback function to be run when the Timer is started. | | [config.successCallback] | function | The callback function to be run once the Timer finishes. | | [config.failureCallback] | function | The callback function to be run if the Timer is cancelled. |

timer.done : Undefined | Promise

Exposes the Timer Promise once the Timer.start method has been called.

Kind: instance property of Timer
Access: public

timer.duration

Sets the duration property.

Kind: instance property of Timer

| Param | Type | Description | | --- | --- | --- | | duration | Number | Sets the duration, in milliseconds, to wait before the Timer finishes. |

timer.startedCallback

Sets the startedCallback property.

Kind: instance property of Timer

| Param | Type | Description | | --- | --- | --- | | startedCallback | function | Sets the callback function to be run when the Timer is started. |

timer.successCallback

Sets the Timer.successCallback property.

Kind: instance property of Timer

| Param | Type | Description | | --- | --- | --- | | successCallback | function | Sets the callback function to be run once the Timer finishes. |

timer.failureCallback

Sets the failureCallback property.

Kind: instance property of Timer

| Param | Type | Description | | --- | --- | --- | | startedCallback | function | Sets the callback function to be run if the Timer is cancelled. |

timer.start(config)

Creates a Promise which resolves after the instance duration or the provided config.duration, and sets the instance Timer.done property equal to the Promise.

Kind: instance method of Timer

| Param | Type | Description | | --- | --- | --- | | config | Object | Config options used to override the defined behaviour of the Timer instance. | | config.duration | Number | Overrides the defined duration of the Timer instance. |

timer.cancel()

Cancels the Timer instance, and if defined calls the failureCallback

Kind: instance method of Timer