TimerJobs
TimerJobs is a simple way to create recurring tasks that can react to events.
Installation
npm install timerjobs
or
yarn add timerjobs
Basic Usage
; const timer = interval: 10000 immediate: true // runs immediately upon starting the timer ignoreErrors: true { console; // other important things happen ; }; timerstart;
A Timer that only runs 'n' times and starts upon creation is easy to implement.
const timer = autoStart: true interval: 10000 infinite: false countdown: 10 { console; // other important things happen ; };
Events
The Timer can emit events when job tasks happen. By default it utilizes EventEmitter2,
your own eventemitter may be passed as option emitter: myEventEmitter
to more fully integrate TimerJobs into your application. Optionally, you may also set a default emitter for all timers: TimerJobs.emitter = myDefaultEmitter
. The first argument is (almost) always the instance of the timer.
jobStart
: (instance)
Emitted when the job is started
jobStop
: (instance)
Emitted when the job is stopped, a task may still be executing
jobBegin
: (instance)
Emitted every time a job execution begins
jobEnd
: (instance, ...args)
Emitted every time a job execution completes, i.e when done(null, ...args)
is called.
jobError
: (err, instance, [errors])
Emitted whenever done( err )
is called with an Error
jobComplete
: (instance)
Emitted when infinite
is false and countdown
reaches 0
The above events, with the exception of jobError
, can be silenced by setting
the option emitLevel: 0
.
Emitted events may also be refined with options namespace
and reference
and delimited with delimiter
.
- Emit level
- default: Event
- 0: disabled
- 1: job<task>
- 2: job<task> + <namespace>
- 3: job<task> + <reference>
- 4: job<task> + <namespace> + <reference>
; const timer = interval: 10000 autoStart: true emitLevel: EmitLevelNamespaceAndReference namespace: 'someNamespace' reference: 'mySuperTimer' { console; // other important things happen ; };
Assuming jobStart
emits, the event to listen for would be 'jobStart::someNamespace::mySuperTimer'
React on Events
Your Timer can react to events so that it may automatically start, stop or restart.
Simply set the options startOn
, stopOn
, or restartOn
with the event to listen.
Additionally you may supply callbacks for each listen event, respectively: startCallback
, stopCallback
and restartCallback
.
const timer = interval: 10000 immediate: true emitter: myEventEmitter startOn: 'startEvent' { // do things when your timer starts } stopOn: 'stopEvent' { // do things when your timer stops } restartOn: 'restartEvent' { // do things when your timer restarts // this only runs iff your timer has previously run } { console; // other important things happen ; };
The callback will only execute if the timer action is taken.
TimerJobs Class
const timer = options callback;
Option: Default
autoStart: false
<boolean> - Should the Timer start on creation?
blocking: true
<boolean> - Should we block execution if we're already executing
countdown: 1
<number> - The number of times the timer should execute before stopping, infinite
must be false
delimiter: '::'
<string> - The delimiter used to segment namespaces
emitLevel: 1
<number> - At what level should we emit job events
emitter: EventEmitter2
<EventEmitter> - The eventemitter which emits and listens for events
ignoreErrors: false
<boolean> - Should we ignore errors? Stops execution if false.
immediate: false
<boolean> - Should the timer execute immediately upon starting?
interval: 3000
<number> - The interval in milliseconds which the job should be performed
infinite: true
<boolean> - Should the timer run forever?
namespace: ''
<string> - A way to identify the namespace of this timer
reference: 'timer'
<string> - A reference to this particular timer
restartOn: null
<string> - The event that should restart the timer
restartCallback: null
<function> - The callback which executes when the event restarts the timer
startOn: null
<string> - The event that should start the timer
startCallback: null
<function> - The callback which executes when the event starts the timer
stopOn: null
<string> - The event that should stop the timer
stopCallback: null
<function> - The callback which executes when the event stops the timer'
context: null
<any> - The context in which the timer callback or any event callbacks are invoked
Functions
timer.start(): TimerJobs
Start the Timer
timer.stop(): TimerJobs
Stop the Timer
timer.restart(interval?: number): TimerJobs
Restarts the timer iff it has previously started, optionally set a new interval
timer.started(): boolean
Returns true
if the Timer is started
timer.stopped(): boolean
Returns true
if the Timer is stopped
timer.waitTime(): number
Returns the time in milliseconds until the next job execution
timer.dispose(): void
Stops the timer if running and removes it from the static timers array
Variables
timer.executions
The total number of times the job has executed
timer.busy
A boolean value that indicates if a task is executing
timer.errors
An array of Errors that may have occurred during execution
Static Functionality
const timer = autoStart: true interval: 10000 infinite: false countdown: 10 reference: 'fancyTimer' namespace: 'someNamespace' { console; // other important things happen ; };
Timers Array
An array of all timers that have been created
const timers = TimerJobstimers;
Default Emitter
A default event emitter. An emitter passed with options takes precedence.
TimerJobsemitter = myDefaultEmitter;
Find timers:
const timers = TimerJobs;
Remove one or more timers.
TimerJobs: void;
By default, the Timer being removed will also be stopped. A second argument of false
will keep the timer running (assuming it already is).