simple API for building cron expressions

Downloads in past


0.3.07 years ago8 years agoMinified + gzip package size for cron-builder in KB


Build Status
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.


cron-builder is available on npm and bower:
npm install cron-builder --save
bower install cron-builder --save

After installing, just require the package as you normally would:
var cb = require('/path/to/cron-builder.js');


To instantiate the cron builder:
// (default expression is set to "* * * * *")
var cronExp = new cb();

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

To return the cron expression at any given time:;
// '* * * * *'

API includes basic getters and setters:
// '*'
cronExp.set('minute', '5,35');
// '5,35'
// '5,35';
// '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');;
// '5,35 2 * 4,10 *'

cronExp.removeValue('minute', '5');;
// '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'];
// '35 2 7,14,21,28 4,10 *'
  • 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.


npm install
npm test
Pull requests and issues appreciated!


  • 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


The MIT License (MIT)