whenTime: A Simple Package To Do Things On Time In Node.js

Motivation

This package aims to simplify the task of scheduling tasks at specified time with a simple-to-use API. This can be helpful for making your applications restart at specific times in the day or having specific operations occur at a time period with repetitions.

Features

• Simple-to-use API
• Timezones Support
• Human Readable Parameters
• Chainable Syntax
• Memory Efficient
• Lightweight/No Dependencies

Installation

whenTime can be installed using node package manager (npm)

npm i when-time

Examples

Below are some examples making use of whenTime in various situations.

Scheduling multiple tasks at 3:30 AM to occur one-time

const whenTime = require('when-time');

// This is a one-time job which will execute the 2 tasks below once at 3:30 AM
whenTime.isEqualTo('3:30 AM')
.do(() => {
    console.log('This is task 1');
}).do(() => {
    console.log('This is task 2');
});

Scheduling a task to begin at 3:30 AM and repeat every 12 hours

const whenTime = require('when-time');

whenTime.isEqualTo('3:30 AM')
.do(() => {
    console.log('This task will repeat every 12 hours');
})
.repeat()
.every('12 hours');

Scheduling a task to begin at 3:30 AM and repeat every 1 hour for a total of 12 times

const whenTime = require('when-time');

whenTime.isEqualTo('3:30 AM')
.do(() => {
    console.log('This task will repeat every 1 hour for a total of 12 times after 3:30 AM');
})
.repeat(12)
.every('1 hour')
.whenFinished(() => {
    console.log('Successfully trigger above task 12 times');
});

Cancelling a scheduled task before execution

const whenTime = require('when-time');

let task = whenTime.isEqualTo('3:30 AM').do(() => {
    console.log('Some task that will be cancelled');
});

// This will cancel the above task and clean up any underlying setTimeouts/setIntervals
task.cancel();

TimeTask

Below is a breakdown of the TimeTask class generated when calling whenTime.isEqualTo().

Constructor Options

• time_string [String]: Time string representing a target time point.
  • Format: Hours:Minutes:Seconds:Milliseconds AM/PM
  • Examples: 5:30 PM, 10:30:55:850 PM, 18:00, 22:35:50:680
  • Note 12 hour time format will only be used when AM/PM is specified.

TimeTask Properties

| Property | Type | Description | | :-------- | :------- | :------------------------- | | state | String | Possible States: INITIALIZED, PENDING, STARTED, FINISHED, CANCELLED | | next_execution | Number | Timestamp of next execution in milliseconds | | tasks | Array | Returns all scheduled tasks with do(handler) | | remaining | Number | Number of repetitions remaining for task is finished |

TimeTask Methods

• do(Function: operation): Adds an operation to the list of scheduled operations for a TimeTask.
  • Returns TimeTask therefore a chainable method.
  • Note operations will be executed in the order they were scheduled using this method on a TimeTask instance.
• inTimezone(String: timezone): Specifies the timezone for the time_string specified at creation of task.
  • See Timezones for supported timzones.
• repeat(Number: amount): Sets the amount of times the scheduled tasks should repeat.
  • Default: Infinity
  • Returns TimeTask therefore a chainable method.
  • Note: whenFinished() is forbidden once Infinity repetitions have been set on an instance.
  • Note: Calling this method with Infinity amount is forbidden after a whenFinished() handler has been set on an instance.
• every(String: interval): Specifies the interval after which repetitions should occur.
  • Returns TimeTask therefore a chainable method.
  • Format: Amount Metric where Metric = [Day(s), Hour(s), Minute(s), Second(s), Millisecond(s)]
  • Note the default repetition interval for a TimeTask instance is 24 Hours without ever calling this method.
• whenFinished(Function: handler): Binds a handler which is triggered once TimeTask execution is fully complete and all repetitions have been completed.
  • Returns TimeTask therefore a chainable method.
  • Note this method is forbidden when Infinity amount of repetitions have been scheduled for an instance.
• cancel(): Cancels a TimeTask and destroys all underlying timeouts/intervals for a complete cleanup.

License

MIT