when-time

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

Usage no npm install needed!

<script type="module">
  import whenTime from 'https://cdn.skypack.dev/when-time';
</script>

README

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

NPM version NPM downloads GitHub issues GitHub stars GitHub license

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.
  • 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