timerjobs v2.0.2

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

import { TimerJobs } from 'timerjobs';

const timer = new TimerJobs(
  {
    interval: 10000,
    immediate: true, // runs immediately upon starting the timer
    ignoreErrors: true,
  },
  function (done) {
    console.log('things are happening');

    // other important things happen

    done();
  },
);

timer.start();

A Timer that only runs 'n' times and starts upon creation is easy to implement.

const timer = new TimerJobs(
  {
    autoStart: true,
    interval: 10000,
    infinite: false,
    countdown: 10,
  },
  function (done) {
    console.log('things are happening');

    // other important things happen

    done();
  },
);

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>

import { TimerJobs, EmitLevel } from 'timerjobs';

const timer = new TimerJobs(
  {
    interval: 10000,
    autoStart: true,
    emitLevel: EmitLevel.NamespaceAndReference,
    namespace: 'someNamespace',
    reference: 'mySuperTimer',
  },
  function (done) {
    console.log('things are happening');

    // other important things happen

    done();
  },
);

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 = new TimerJobs(
  {
    interval: 10000,
    immediate: true,
    emitter: myEventEmitter,
    startOn: 'startEvent',
    startCallback: function () {
      // do things when your timer starts
    },
    stopOn: 'stopEvent',
    stopCallback: function () {
      // do things when your timer stops
    },
    restartOn: 'restartEvent',
    restartCallback: function () {
      // do things when your timer restarts
      // this only runs iff your timer has previously run
    },
  },
  function (done) {
    console.log('things are happening');

    // other important things happen

    done();
  },
);

The callback will only execute if the timer action is taken.

TimerJobs Class

const timer = new TimerJobs(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 = new TimerJobs(
  {
    autoStart: true,
    interval: 10000,
    infinite: false,
    countdown: 10,
    reference: 'fancyTimer',
    namespace: 'someNamespace',
  },
  function (done) {
    console.log('things are happening');

    // other important things happen

    done();
  },
);

Timers Array

An array of all timers that have been created

const timers = TimerJobs.timers;

Default Emitter

A default event emitter. An emitter passed with options takes precedence.

TimerJobs.emitter = myDefaultEmitter;

Find timers:

const timers = TimerJobs.findTimers((timer) => timer.infinite);

Remove one or more timers.

TimerJobs.removeTimers((timer) => timer.countdown < 5): 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).