ntimer
An event firing, repeatable, cancellable timer for nodejs
.
Installation
Install with npm
npm install ntimer --save
Examples
Just a Timer
ntimer = require 'ntimer' # Creates an manual-start timer which fires after 2000ms ntimer'foo''2s'on "done"-> # do something start
Auto Start
# Creates an auto-start timer which fires after 200ms # Must attach a 'timer' event listener to enable auto start ntimerauto'foo'200on "timer"-> # do something
Cancel Timer
# starts a second timer when the first starts which cancels # the first timer before the first timer ends. ntimerauto'foo''5s'on "start"-> setTimeout => @cancel500on "done"-> # do something on "cancel"-> # why, oh why?
Repeat
# Create an infinitely repeating timer whch fires every 500ms. ntimerrepeat'foo''500ms'on "timer" # do something on "done"-> # never called on "cancel"-> # called if timer is cancelled start
Limited Repeat
# Create a timer which fires every 500ms for five times. ntimerautoRepeat'foo''500ms'5on "timer" # do something on "done"-> # fired after the fifth 'timer' event
API
Create Timer
ntimer(name, timeout)
ntimer.auto(name, timeout)
Creates a single shot, restartable timer. ntimer.auto
creates an auto starting timer.
- name
{String}
is returned as the first argument of events. - timeout can be a
{Number}
inmilliseconds
or a{String}
e.g.'5s'
or'2ms'
. See format.
ntimer'foo'500 # Single shot, manual start, 500ms timer.
Note: An auto-starting timer will start only when it has a event listener for the
trigger
event.
t = ntimerauto'foo'500 # Create an auto start timer, 500ms # The auto-start timer will start only after this listener is attached ton 'trigger'-> # do something
ntimer.repeat(name, timeout[, maxRepeat])
ntimer.autoRepeat(name, timeout[, maxRepeat])
Creates a repeating timer. ntimer.auto
creates an auto starting version.
- name
{String}
is returned as the first argument of events. - timeout can be a
{Number}
inmilliseconds
or a{String}
. See format. - maxRepeat an optional
{Number}
specifies the maximum repeat count.
ntimerrepeat'foo'500 # Single shot, 500ms timer. ntimer'foo''2s' # Single shot, 2 second timer.
Properties
timer.count
The {Number}
of times the repeating timer has already fired.
timer.running
{Boolean}
indicating whether the timer is currently running.
Methods
timer.start()
Start a timer. No-op if already started. Returns the timer object for chaining.
timer.cancel()
Cancels a running timer. No-op if not started or already stopped/cancelled. Returns the timer object for chaining.
Events
on("start", cb(name))
Fired when the timer is started (or restarted) with the name of the timer.
on("cancel", cb(name))
Fired when the timer is cancelled with the name of the timer.
on("done", cb(name))
Fired when the timer is done (not cancelled) with the name of the timer.
on("timer", cb(name, count))
Fired for each timeout
interval, once for single shot timers, or repeatedly for repeating timers, with the name of the timer and the the count of the times the timer has triggered so far.
ntimer.Timer Class
ntimer
exports the Timer class.
String Formats for Time
Uses the millisecond module. The following formats are acceptable:
- x milliseconds
- x millisecond
- x msecs
- x msec
- x ms
- x seconds
- x second
- x secs
- x sec
- x s
- x minutes
- x minute
- x mins
- x min
- x m
- x hours
- x hour
- x hrs
- x hr
- x h
- x days
- x day
- x d
- x weeks
- x week
- x wks
- x wk
- x w
- x years
- x year
- x yrs
- x yr
- x y
The space after the number is optional so you can also write 1ms
instead of 1 ms
.