README.md

Timer.js

Simple and lightweight library without any dependencies to create and manage, well, timers.

Demo

Installation

The easiest way to install timer.js is via npm:

$ npm install timer.js

or if you prefer good old files, you can manually download dev or min versions.

Examples

Let's cook pizza

var pizzaTimer = new Timer();
var pizzaCookingTime = 15 * 60; // 15 minutes

pizzaTimer.start(pizzaCookingTime).on('end', function () {
  alert('Pizza is ready, bon appetit!');
});

Usage

Timer.js is written in UMD style, so it's compatible with AMD(Require.js), CommonJS(nodejs, browserify, etc.) and direct browser usage as a global.

API

All methods listed below support chaining, so you can write:

myTimer.start(10).on('pause', doSmth).pause(); // and so on

Also you can use this keyword inside of methods as a reference to the instance of Timer

initialization

To create Timer with specific event handlers and options you can pass them as argument to constructor

var myTimer = new Timer(options);

list of available options:

• ontick - what to do on every tick
• tick - set specific tick(e.g. you can set it to 2, then your ontick handler will fire every 2 seconds)
• onstart - start event handler
• onstop - stop event handler
• onpause - pause event handler
• onend - end event handler(when Timer stops without interrupt)

var myTimer = new Timer({
  tick    : 1,
  ontick  : function(ms) { console.log(ms + ' milliseconds left') },
  onstart : function() { console.log('timer started') },
  onstop  : function() { console.log('timer stop') },
  onpause : function() { console.log('timer set on pause') },
  onend   : function() { console.log('timer ended normally') }
});

.start(time)

starts a Timer for a specified time

myTimer.start(10) // start a timer for 10 seconds

.pause()

pause timer

myTimer.pause()

after pause you can continue the job by myTimer.start()

.stop()

to stop timer doing his job

myTimer.stop()

.on(option, function)

set some specific option, support options without 'on' prefix. Available options are : tick, ontick, start, onstart, end, onend, stop, onstop, pause, onpause

myTimer.on('end', function() {
  console.log('woo-hooo! my timer ended normally')
})

.off()

similar to 'on()' but it will remove handler

myTimer.off('pause')

.options()

define multiple specific options at once as an object

myTimer.options({
    onend : function() {
        console.log('onend')
    },
    ontick : function() {
        console.log('every tick');
    }
})

You can use .off('all') to restore all previously defined options to defaults

myTimer.off('all')

.getStatus()

get current status of timer. Available statuses are: 'initialized', 'started', 'paused', 'stopped'

myTimer.getStatus() // 'initialized'
myTimer.start(20).getStatus() // 'started'
myTimer.pause().getStatus() // 'paused'

.getDuration()

get remaining time (in ms)

myTimer.start(20)
// some operation that lasts for 2 seconds
myTimer.getDuration() // 18000

.measureStart(label)

Start a high-performance measurement with an associated label, you need to use the same label to stop measurement, so make sure you've saved it

.measureStop(label)

Stop the measument with the associated label, returns the number of elapsed ms

Example:

myTimer.measureStart('label1');
var a = [];
for (var i = 10000000; i >= 0; i--) {
    a.push(i * Math.random());
};
myTimer.measureStop('label1'); // 276 i.e.

Note! '' (empty string) equals to absence of argument, and it is valid

timer.measureStart();
//some operations
timer.measureStop();

will work

Tests

Running tests is pretty straightforward

$ npm test

Tests are written with Jasmine, you can find all specs in test/specs folder.

Contributing

If you've found a bug, something is not working as it shoud be or you came up with some new cool feature, feel free to create an issue here or send a pull request.

Changelog