README

mi-cron

const { parseCron } = require('@cheap-glitch/mi-cron');

console.log(parseCron.nextDate('*/5 6-12 3 3 *').toUTCString());
// Wed, 03 Mar 2021 06:00:00

This is a microscopic (~1KB minified & gzipped) zero-dependencies parser for standard cron expressions. It also supports a few non-standard but convenient features, such as @-shorthands (e.g. @daily) and steps (e.g. */10), and can compute the next scheduled date for a given expression.

Installation

npm i @cheap-glitch/mi-cron

API

parseCron(exp: string): CronSchedule

Parses a standard cron expression. Supports:

globs (*)
ranges (0-30, mon-fri)
steps (*/3, 20-31/2, 10/5)
lists (1,15, 0-10,20-30/2)
@-shorthands (@weekly)

Does NOT support:

L, W, #, ?, H
year field
@reboot

Returns an object with all possible values for each field (minutes, hours, days, months and days of the week), or undefined if the expression is invalid (wrong syntax, unsupported instruction, impossible range, etc).

const { parseCron } = require('@cheap-glitch/mi-cron');

console.log(parseCron('*/5 6-10 1,15 * wed'));
// {
// 	minutes:  [0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55],
// 	hours:    [6, 7, 8, 9, 10],
// 	days:     [1, 15],
// 	months:   [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
// 	weekDays: [3],
// }

parseCron.nextDate(exp: string | CronSchedule, from: Date = new Date.now()): Date

Takes a cron schedule or expression and returns the next date that matches the schedule, or undefined if the expression is invalid. If given a datetime as the second argument, it will start the computation from this time (otherwise it will use the current datetime at the moment it's called).

const { parseCron } = require('@cheap-glitch/mi-cron');

console.log(parseCron.nextDate('* * * * *', new Date('01 Jan 2020 00:00:00 GMT')).toUTCString());
// Wed, 01 Jan 2020 00:01:00

// Get the next five scheduled dates
const schedule = parseCron('@weekly');
const nextDate = new Date();
for (let i=0; i<5; i++) {
    console.log(nextDate = parseCron.nextDate(schedule, nextDate));
}

crontab.guru, an interactive cron schedule editor
A description of the crontab format
Best practices for cron

License

Copyright (c) 2020-present, cheap glitch

Permission to use, copy, modify, and/or distribute this software for any purpose
with or without fee is hereby  granted, provided that the above copyright notice
and this permission notice appear in all copies.

THE SOFTWARE  IS PROVIDED "AS IS"  AND THE AUTHOR DISCLAIMS  ALL WARRANTIES WITH
REGARD TO THIS SOFTWARE INCLUDING  ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS.  IN NO  EVENT  SHALL THE  AUTHOR  BE LIABLE  FOR  ANY SPECIAL,  DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
OF USE, DATA OR  PROFITS, WHETHER IN AN ACTION OF  CONTRACT, NEGLIGENCE OR OTHER
TORTIOUS ACTION, ARISING OUT OF OR IN  CONNECTION WITH THE USE OR PERFORMANCE OF
THIS SOFTWARE.

@cheap-glitch/mi-cron

Usage no npm install needed!