Home

Awesome

CronosJS

license npm bundle size Build Status Coverage Status

A cron based task scheduler for node and the browser, with extended syntax and timezone support.

Features:

Install / Usage

npm i cronosjs

import { scheduleTask, validate, CronosExpression } from 'cronosjs'

// schedule task every 10 minutes
scheduleTask('*/10 * * * *', (timestamp) => {
  console.log(`Task triggered at ${timestamp}`)
})

// schedule task at 16:10, on the 4th and last day of July, 2035 in the EST timezone
scheduleTask('0 10 16 4,L Jul * 2035', (timestamp) => {
  console.log(`Task triggered at ${timestamp}`)
}, {
  timezone: 'America/New_York'
})

// offset tasks occurring in daylight savings missing hour
scheduleTask('5/20 1 * Mar SunL', (timestamp) => {
  console.log(`Task triggered at ${timestamp}`)
}, {
  timezone: 'Europe/London',
  missingHour: 'offset'
})

// validate cron string
validate('* * 5 smarch *') // false

validate('0 1/120 * * * *', {
  strict: true
}) // false

// get next cron date
CronosExpression.parse('* * 2/5 Jan *').nextDate()

// get next 7 cron dates after 09:17, 12th Mar 2019
CronosExpression.parse('* * 2/5 Jan *').nextNDates(
  new Date('2019-03-12T09:17:00.000Z'), 7)

// advanced usage
const expression = CronosExpression.parse('0 10 16 4,L Jul * 2035', {
  timezone: 'America/New_York'
})
const task = new CronosTask(expression)

task
  .on('run', (timestamp) => {
    console.log(`Task triggered at ${timestamp}`)
  })
  .on('ended', () => {
    console.log(`No more dates matching expression`)
  })
  .start()

// strict mode / warnings
CronosExpression.parse('0 1/120 * * * *', {
  strict: true
}) // Error: Strict mode: Parsing failed with 1 warnings

const strictExpr = CronosExpression.parse('0 1/120 * * * *')

console.log(strictExpr.warnings)
// [{
//   type: 'IncrementLargerThanRange',
//   message: "Increment (120) is larger than range (58) for expression '1/120'"
// }]

// schedule tasks from a list of dates
const taskFromDates = new CronosTask([
  new Date(2020, 7, 23, 9, 45, 0),
  1555847845000,
  '5 Oct 2019 17:32',
])

taskFromDates
  .on('run', (timestamp) => {
    console.log(`Task triggered at ${timestamp}`)
  })
  .on('ended', () => {
    console.log(`No more dates in list`)
  })
  .start()

Supported expression syntax

*  *  *  *  *  *  *    Field              Allowed values    Special symbols
|  |  |  |  |  |  |    -----------------  ---------------   ---------------
`--|--|--|--|--|--|->  Second (optional)  0-59              * / , -
   `--|--|--|--|--|->  Minute             0-59              * / , -
      `--|--|--|--|->  Hour               0-23              * / , -
         `--|--|--|->  Day of Month       1-31              * / , - ? L W
            `--|--|->  Month              1-12 or JAN-DEC   * / , -
               `--|->  Day of Week        0-7 or SUN-SAT    * / , - ? L #
                  `->  Year (optional)    0-275759          * / , -

A cron expression is defined by between 5 and 7 fields separated by whitespace, as detailed above. Each field can contain an integer value in the allowed values range for that field, a three letter abbreviation (case insensitive) for the Day of Week and Month fields, or an expression containing a symbol.

A predefined expression can also be given.

For the Day of Week field, 0 and 7 are equivalent to Sun , 1 = Mon , ... , 5 = Fri , 6 = Sat.

Note If only 5 fields are given, both the optional second and year fields will be given their default values of 0 and * respectively.
If 6 fields are given, the first field is assumed to be the second field, and the year field given its default value.

Why the 0 to 275759 allowed year range?
The JS Date object supports dates 8,640,000,000,000,000 milliseconds either side of the 1st Jan, 1970 UTC (ECMAScript 2019 Specification), giving a maximum valid date of 13th Sep, 275760. Therefore the largest full year representable as a JS Date is 275759.
The year 0 is chosen as the minimum, disallowing negative years, to avoid confusion with the range symbol (-).

The following symbols are valid for any field:

All / Any values (*)

Selects all allowed values in the second, minute, hour, month and year fields. If part of a list of expressions in any of those fields, * will effectively override any other expression in that field.
Can also be used as part of an expression containing the special symbols /, L, W or # as detailed below, where it similarly acts as a range of all valid values for that field, eg. in the hour field acts as 0-23.

In the Day of Month and Day of Week fields, * on its own acts as a placeholder, matching any day (sometimes referred to as "no specific value"), and is overridden by any other expression listed in either "Day of ..." field. Only if both fields are '*', will the symbol have an effect, selecting every day of the month.
If part of another expression, it acts as above.

The ? symbol can be used as an alias for '*' (on its own) in the Day of Month and Day of Week fields.

List (,)

Separates a list of expressions for a field.

The separated expressions can contain any of the allowed values and symbols for that field; however while valid, some lists may not make sense, eg. in 6-14,*, the 6-14 part is made redundant by the * part.

Range (-)

Defines a range of values, inclusive. eg. 16-39 in the seconds field means the 16th second and every second after up to and including the 39th second.

For fields with a cyclic nature (ie. Second, Minute, Hour, Month and Day of Week), wrap-around ranges are supported, eg. Fri-Mon will select Fri, Sat, Sun and Mon. Otherwise for non-cyclic fields (ie. Day of Month and Year) the second value is required to be greater than the first value.

Note Wrap-around ranges are purely 'syntactic sugar' to primarily make day of week and month ranges simpler to write, and do not alter the underlying behaviour of this cron library. The parser effectively translates wrap-around expressions such as Fri-Mon to the standard form, as though it were written as Fri-Sat,Sun-Mon (5-1 and 5-6,0-1 respectively in numerical form), meaning any range expression is still able to be written in a form compatible with other cron implementations.

It is for this reason Day of Month is considered non-cyclic, since the number of days in a month differs between months, leading to possibly unexpected behaviour when a wraparound range is used with an increment.
eg. The Day of Month expression 27-5/2 would select the days 27, 29, 31, 2, 4, regardless of the number of days in the month, so in a month with only 30 days the actual scheduled days would become 27, 29, 2, 4, creating a 3 day increment between the 29th and the 2nd. Correctly handling increments across the wraparound would create behaviour incompatible with other cron implementations, such that simple translation to a non wrap-around form would not be possible.

Increments (/)

Defines increments of a range. Can be used in three ways:

The following symbols are valid only for the Day of Month and/or Day of Week fields, and can be combined with any valid expression above (unless specified otherwise):

No Specific Value (?)

An alias for '*' in the Day of Month and Day of Week fields.

Note Is not valid as part of another expression, eg. ?/2, ?W and ?#3 are invalid.

Last day (L)

When used in the Day of Month field, must be on its own, and means the last day of that month.

When used in the Day of Week field, must be used as a suffix on another expression, and means the last specified day(s) of week of that month.

Examples:

Nearest weekday (W)

The W symbol is only valid as a suffix for the Day of Month field, and will select the nearest weekday(s) (Mon-Fri) to the given day(s) if that day is a Saturday or Sunday, otherwise will select the given day.

Examples:

Note If the given day is the start or end of the month, the nearest weekday will not be selected if it is in another month, instead the next nearest weekday in the same month will be selected.

For example given the expression * * 1W * *, on a month starting on Saturday, the selected day would be the 3rd on the following Monday, not the Friday on the last day of the previous month:

Wed Thu Fri | Sat Sun Mon
29  30  31  |  1   2   3
         x     ^       ✓

Last day and nearest weekday can be combined, ie. LW, to select the last weekday of month.

Nth of month (#)

The # symbol is only valid as a suffix for the Day of Week field expression, and must be followed by a number 1-5

Examples:

Timezone support

The timezone option supports either a string containing an IANA timezone (eg. 'America/New_York'), or a fixed offset from UTC as either a string in the format (+|-)hh[:]mm, or an integer number of minutes.

IANA timezone support is dependent on the Intl.DateTimeFormat api being supported by the browser/Node.js. The Intl api is supported by most modern browsers and versions of Node.js.

If no timezone is specified the system's local timezone is used.

Daylight savings behaviour

If the configured timezone observes daylight savings how the missing hour when the daylight savings starts, and the repeated hour when it ends are handled can be specified by the missingHour and skipRepeatedHour options.

missingHour option

The missingHour option allows three options: 'skip', 'offset' and 'insert'. (Defaults to 'insert')

For example in 'Europe/London' timezone, with the cron expression 5/20 1 * * * :

31st March 2019
GMT(+00:00) -> BST(+01:00)

UTC                 o x     x     x
  |-----------------|-----------------|-----------------|-----------------|
00:00             01:00             02:00             03:00             04:00

GMT(+00:00)           x     x     x
  |-----------------+.................
00:00            (01:00)

                  BST(+01:00)
                    |-----------------|-----------------|-----------------|
                  02:00             03:00             04:00             05:00

Note The task is only run at most once per second, so if multiple times end up occurring at the same time the task is only run once

skipRepeatedHour option

The skipRepeatedHour option is a boolean option, that specifies whether or not a task should be scheduled for a second time in a repeated hour. (Default to true)

For example in 'Europe/London' timezone, with the cron expression */20 1 * * * :

27th October 2019
BST(+01:00) -> GMT(+00:00)

UTC                 o     o     o     x     x     x
  |-----------------|-----------------|-----------------|-----------------|
23:00             00:00             01:00             02:00             03:00

BST(+01:00)         o     o     o
  |-----------------|-----------------+
00:00             01:00            (02:00)

                         GMT(+00:00)  x     x     x
                                      |-----------------|-----------------|
                                    01:00             02:00             03:00

If skipRepeatedHour: true only the times marked o are scheduled, otherwise all times marked o and x are scheduled.

API

import {
  scheduleTask, validate,
  CronosExpression, CronosTask,
  CronosTimezone 
} from 'cronosjs'

scheduleTask

function scheduleTask(cronString, task, options?)

validate

function validate(cronString, options?)

CronosExpression

class CronosExpression

Properties

interface Warning {
  type: WarningType
  message: string
}

type WarningType = 'IncrementLargerThanRange'

Static Methods

Methods

CronosTask

class CronosTask

Constructor (3 overloads)

Properties

Methods

Events

CronosTimezone

class CronosTimezone

Constructor

new CronosTimezone(IANANameOrOffset)

Predefined expressions

ExpressionDescriptionEquivalent to...
@yearly or @annuallyOnce a year at midnight on 1st January0 0 1 1 *
@monthlyOnce a month at midnight on 1st of the month0 0 1 * *
@weeklyOnce a week at midnight on Sunday0 0 * * 0
@daily or @midnightOnce a day at midnight0 0 * * *
@hourlyOnce an hour at the beginning of each hour0 * * * *