Package detail

schedulator

uka1795MIT2.0.15

Simple and human friendly scheduling tool

javascript, scheduler, json-schema-based, simple-scheduler

readme

schedulator

Build Status npm npm downloads Coverage Status

Simple schedule handling tool. Allows to create JSON schedule scheme and calculate next run based on it. Scheme has clear, readable and human-friendly format.

Table of content

Installation

Node

~$ npm install schedulator

Web

<script src="schedulator-min.js"></script>

Shut up and show me how to use it

Node

let schedulator = require('schedulator');
let scheduleTestObject = 
{
  "startDateTime": "2019-01-01T01:00:00.000Z",
  "eachNWeek": 1,
  "dayOfWeek": ['mon', 'wed', 'fri'],
  "dailyFrequency": { "occursOnceAt": "11:30:00"}
}
console.log(schedulator.nextOccurrence(scheduleTestObject));
//{"result": 2019-01-02T11:30:00.000Z, "error": null}

Web

<!DOCTYPE html>
<html>
<head>
    <script src="schedulator-min.js"></script>
</head>
<body>
<script>
  var scheduleTestObject = 
  {
  "startDateTime": "2019-01-01T01:00:00.000Z",
  "eachNWeek": 1,
  "dayOfWeek": ['mon', 'wed', 'fri'],
  "dailyFrequency": { "occursOnceAt": "11:30:00"}
  }
  alert('Next occurrence: ' + schedulator.nextOccurrence(scheduleTestObject).result);
  //{"result": 2019-01-02T11:30:00.000Z, "error": null}
</script>
</body>
</html>

All examples here and later calculated based on fact that current date time is 2018-12-31T10:00:00.000Z

Schedulator methods

summary(scheduleObject, locale, options)

Parameters

  • scheduleObject
    • Type: Object
    • Description: Object which describes scheduling rule in JSON format (qv Schedule object)
  • locale
  • options
  • Type: string
  • Description: Human readable representation of schedule ```javascript let schedulator = require('schedulator'); let scheduleTestObject = { "oneTime": "2019-01-01T01:00:00.000Z" } console.log(schedulator.summary(scheduleTestObject)); //Once at 1/1/2019, 4:00:00 AM

let scheduleOutdatedTestObject = { "startDateTime": "2018-12-31T01:00:00.000Z", "endDateTime": "2001-12-31T01:00:00.000Z", "month": ["dec", "jul"], "day": [29, 30, 31], "dailyFrequency": { "start": "09:00:00", "occursEvery": { "intervalValue": 90, "intervalType": "minute" } } } console.log(schedulator.summary(scheduleOutdatedTestObject)); //In December and July each 29, 30 and 31 day, every 90 minute(s) between 09:00:00 and 23:59:59, starting 12/31/2018, 4:00:00 AM and till 12/31/2001, 4:00:00 AM

### nextOccurrence(scheduleObject)
#### Parameters
* scheduleObject
  * Type: `Object`
  * Description: Object which describes scheduling rule in JSON format (qv [Schedule object](#schedule-object))
#### Returns
* Type: `Object` 
  * `result` - date-time of next occurence or `null` in case of one of next clauses: 
    * it is not possible to calculate next occurrence 
    * `endDateTime` of `scheduleObject` is in the past 
    * event had `oneTime` schedule which already happened
  * `error` - error message in case if it is not possible to calculate next occurence and `null` in case if calculation was done succesfully
* Description: Object with UTC date and time of nearest next occurrence of [schedule object](#schedule-object) in ISO format (e.g. 2019-01-31T13:00:00.000Z) and error messages if value can not be calculated.

```javascript
let schedulator = require('schedulator');
let scheduleTestObject = 
{
 "oneTime": "2019-01-01T01:00:00.000Z"
}
console.log(schedulator.nextOccurrence(scheduleTestObject));
//{"result": 2019-01-01T01:00:00.000Z, "error": null}

let scheduleOutdatedTestObject = 
{ 
    "startDateTime": "2018-12-31T01:00:00.000Z",
    "endDateTime": "2001-12-31T01:00:00.000Z",
    "month": ["dec", "jul"],
    "day": [29, 30, 31],
    "dailyFrequency": { 
    "start": "09:00:00", 
    "occursEvery": {
        "intervalValue": 90, 
        "intervalType": "minute"
    }
    }
}
console.log(schedulator.nextOccurrence(scheduleOutdatedTestObject));
//{ result: null, error: 'calculated date-time earlier than endDateTime' }

Schedule object

Schedule object describes scheduling rule in JSON format and can be presented by oneTime, daily, weekly or monthly entry. Additionally schedule object contain enabled property which is not mandatory.

All schemas will be validated before run of nextOccurrence method. Error will be returned in result.error in case of any schema mismatch. 

let schedulator = require('schedulator');
let scheduleTestObject = 
{
  "oneTime": 1
}
console.log(schedulator.nextOccurrence(scheduleTestObject));
//{ result: null, error: 'schema is incorrect: data.oneTime should be string, data should NOT have additional properties, data should NOT have additional properties, data should NOT have additional properties, data should match exactly one schema in oneOf' }

enabled (optional)

Next run can be calculate only in case if enabled is true, otherwise error will be returned. 

let schedulator = require('schedulator');
let scheduleTestObject = 
{ 
 "enabled": false,
 "oneTime": "2019-01-01T01:00:00.000Z"
}
console.log(schedulator.nextOccurrence(scheduleTestObject));
//{"result": null, error: "schedule is disabled"}

Property is being considered as true in case if it is not presented in schedule object.

let schedulator = require('schedulator');
let scheduleTestObject = 
{ 
 "oneTime": "2019-01-01T01:00:00.000Z"
}
console.log(schedulator.nextOccurrence(scheduleTestObject));
//{"result": 2019-01-01T01:00:00.000Z, "error": null}

oneTime

Event happens only once and is not going to be repeated.

  • oneTime - string, UTC date and time of event in ISO format (e.g. 2019-01-31T13:00:00.000Z).
let schedulator = require('schedulator');
let scheduleTestObject = 
{ 
 "oneTime": "2019-01-01T01:00:00.000Z"
}
console.log(schedulator.nextOccurrence(scheduleTestObject));
//{"result": 2019-01-01T01:00:00.000Z, "error": null}

daily

Event happens ones per n day(s) according to dailyFrequency field value.

  • startDateTime - string, required. UTC date and time in ISO format (e.g. 2019-01-31T13:00:00.000Z) since when schedule starts to be active. Will be used as a run date-time in case if it fits to run condition.
  • endDateTime - string, optional. UTC date and time in ISO format (e.g. 2019-01-31T13:00:00.000Z) till when schedule is active. nextOccurrence returns null if this date is earlier when current date and time. Schedule without this attribute will always be active.
  • eachNDay - integer, required. Frequency of occurrence in calendar days. Minimum 1.
  • dailyFrequency - object, required. Defines occurrence of event in scope of the day (qv dailyFrequency).
let schedulator = require('schedulator');
let scheduleTestObject = 
{ 
 "startDateTime": "2020-01-31T20:54:23.071Z",
 "endDateTime": "2021-01-31T20:54:23.071Z",
 "eachNDay": 2,
 "dailyFrequency": { "occursOnceAt": "11:11:11"}
}
console.log(schedulator.nextOccurrence(scheduleTestObject));
//{"result": 2020-02-02T11:11:11.000Z, "error": null}

weekly

Event happens ones per n week(s) according to dailyFrequency field value.

  • startDateTime - string, required. UTC date and time in ISO format (e.g. 2019-01-31T13:00:00.000Z) since when schedule starts to be active. Will be used as a run date-time in case if it fits to run condition.
  • endDateTime - string, optional. UTC date and time in ISO format (e.g. 2019-01-31T13:00:00.000Z) till when schedule is active. nextOccurrence returns null if this date-time is earlier when current date-time. Schedule without this attribute will always be active.
  • eachNWeek - integer, required. Frequency of occurrence in weeks. Minimum 1.
  • dayOfWeek - array of string, required. Which days of week event should be triggered. Array should contain unique elements. Reference: ["sun", "mon", "tue", "wed", "thu", "fri", "sat"]
  • dailyFrequency - object, required. Defines occurrence of event in scope of the day (qv dailyFrequency).

Sunday is being considered as a first day of week. Array dayOfWeek can have any order. For example, both ["sun", "mon", "tue"] and ["tue", "sun", "mon"] variants are valid.

let schedulator = require('schedulator');
let scheduleTestObject = {
 "startDateTime": "2020-01-01T00:00:01.000Z",
 "endDateTime": "2020-12-31T23:59:59.000Z",
 "eachNWeek": 3,
 "dayOfWeek": ['mon', 'wed', 'fri'],
 "dailyFrequency": { "occursOnceAt": "11:11:11"}
}    
console.log(schedulator.nextOccurrence(scheduleTestObject));
//{"result": 2020-01-13T11:11:11.000Z, "error": null}

monthly

Event happens ones per each month mentioned and according to dailyFrequency field value.

  • startDateTime - string, required. UTC date and time in ISO format (e.g. 2019-01-31T13:00:00.000Z) since when schedule starts to be active. Will be used as a run date-time in case if it fits to run condition.
  • endDateTime - string, optional. UTC date and time in ISO format (e.g. 2019-01-31T13:00:00.000Z) till when schedule is active. nextOccurrence returns null if this date-time is earlier when current date-time. Schedule without this attribute will always be active.
  • month - array of string, required. Defines during which months event should trigger. Array should contain unique elements. Reference: ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"]
  • day - array of integer, required. Defines days of month event should trigger. Array should contain unique elements. Each and every element should lie between 0 and 32.
  • dailyFrequency - object, required. Defines occurrence of event in scope of the day (qv dailyFrequency).

Arrays month and day can have any order. For example, all variants ["jul", "sep", "may"] and ["may", "jul", "sep"], [1, 2, 3] and [3, 2, 1] are valid.

let schedulator = require('schedulator');
let scheduleTestObject = {
 "startDateTime": "2020-01-01T00:00:01.000Z",
 "endDateTime": "2020-12-31T23:59:59.000Z",
 "month": ["jul", "sep"],
 "day": [11, 2, 8, 1],
 "dailyFrequency": { "occursOnceAt": "11:11:11"}
}
console.log(schedulator.nextOccurrence(scheduleTestObject));
//{"result": 2020-07-01T11:11:11.000Z, "error": null}

dailyFrequency

Daily, weekly and monthly schedule contains dailyFrequency attribute which defines occurrence of event in scope of the day. Can be either once (happens only once per day) or every (happens several times per day based on the clause).

once

Happens only once per day at proper time.

  • occursOnceAt - string, requiered. Time (format hh:mm:ss) when event should be triggered.
let schedulator = require('schedulator');
let scheduleTestObject = 
{ 
 "startDateTime": "2020-01-31T20:54:23.071Z",
 "eachNDay": 1,
 "dailyFrequency": { "occursOnceAt": "11:11:11"}
}
console.log(schedulator.nextOccurrence(scheduleTestObject));
//{"result": 2020-02-01T11:11:11.000Z, "error": null}

every

Event happens starting from start time and repeats either till the end of the day or till time defined by end parameter accordingly to occursEvery condition.

  • start - string, required. Indicates start time (format hh:mm:ss) of the schedule and first occurrence in scope of the day.
  • end - string, required. Indicates end time (format hh:mm:ss) of schedule duration in scope of the day.
  • occursEvery - object, required. Object which defines repetitive condition for event.

nextOccurrence) method returns null as a result in case if start time later or equal to end time.

Repeat condition occursEvery is calculated based on intervalValue and intervalType attibutes.

  • intervalValue - integer, required. Event happens each n minutes or hours presented by this parameter. Minimum 1.
  • intervalType - string, required. Defines type of interval. Reference: ["minute", "hour"]
let schedulator = require('schedulator');
let scheduleTestObject = 
{ 
    "startDateTime": "2018-12-31T01:00:00.000Z",
    "month": ["dec", "jul"],
    "day": [29, 30, 31],
    "dailyFrequency": { 
    "start": "09:00:00", 
    "occursEvery": {
        "intervalValue": 90, 
        "intervalType": "minute"
    }
    }
}
//Considering script runs at 2018-12-31T10:00:00.000Z...
console.log(schedulator.nextOccurrence(scheduleTestObject));
//{"result": 2018-12-31T10:30:00.000Z, "error": null}