Forked from https://github.com/sourceclear/cron-builder

cron-builder

The software utility cron is a time-based scheduler in Unix-like computer operating systems. A user may use cron to schedule jobs (commands or scripts) to run periodically at fixed times, dates, or intervals. A cron statement is composed of 5 fields separated by white space. The * character translates to "every", ie: "every minute" or "every day of the week".

cron-builder will manage the state of a cron expression, allowing a user to manipulate it through a simple API. It is decoupled from the DOM and doesn't have an opinion about where it's being called from. cron-builder considers this article its source of truth.

Install

cron-builder is available on npm and bower:

npm i cron-builder-ts --save

After installing, just require the package as you normally would:

import { CronBuilder } from 'cron-builder-ts';

API

To instantiate the cron builder:

// (default expression is set to "* * * * *")
var cronExp = new CronBuilder();

// optionally, pass in a cron expression to override the default:
var myCronExp = new CronBuilder('5 12 * * 1-5')

To return the cron expression at any given time:

cronExp.build();
// '* * * * *'

// add optional flags to customize build result
cronExp.build(options);

API includes basic getters and setters:

cronExp.get('minute');
// '*'
cronExp.set('minute', '5,35');
// '5,35'
cronExp.get('minute');
// '5,35'
cronExp.build();
// '5,35 * * * *'

Or if you'd prefer to add or remove values one at a time, use addValue and removeValue. These methods build or take away from what is currently set:

cronExp.addValue('hour', '2');
cronExp.addValue('monthOfTheYear', '4');
cronExp.addValue('monthOfTheYear', '10');
cronExp.build();
// '5,35 2 * 4,10 *'

cronExp.removeValue('minute', '5');
cronExp.build();
// '35 2 * 4,10 *'

If you prefer to work with the expression object directly, use getAll and setAll:

var exp = cronExp.getAll();
// {minute: ['35'], hour: ['2'], dayOfTheMonth: ['*'], monthOfTheYear: ['4','10'], ...}
exp.dayOfTheMonth = ['7','14','21','28'];
cronExp.setAll(exp);
cronExp.build();
// '35 2 7,14,21,28 4,10 *'

Build options

outputWeekdayNames and outputMonthNames

Default: false

const myCronExp = new CronBuilder('*/5 9-17/2 * 1-3 1-5')
cronExp.build({ outputWeekdayNames: true, outputMonthNames: true });
// Result: '*/5 *(10-16)/2 * JAN-MAR MON-FRI'

outputHashes

Default: false

const myCronExp = new CronBuilder('*/5 9-17/2 * 1-3 1-5')
cronExp.build({ outputHashes: true });
// Result: 'H/5 H(10-16)/2 H 1-3 1-5'

Notes:

• cron-builder does not currently support using / syntax to indicate values that are repeated. Instead of using */15, use the verbose form 0,15,30,45.
• cron-builder requires using numeric representations of days of the week and months of the year. So instead of using Feb,Mar,Apr just use 2,3,4.

Contribute

Easy!

npm install
npm test

Pull requests and issues appreciated!

TODO

• more validation for things like adding values that are already included in a range, better range validations...
• sorting of values for a given measure of time

License

The MIT License (MIT)