0.5.2 • Public • Published


SimpleCron is a simple cron runner. I've tried more or less to adhere to the functionality of the traditional unix cron utility. This includes the behaviour during a system time change.

As per the cron man page, in the event of a system time change will do the the following:

  • If the time changes backwards by more than 3 hours, the cron intervals will be reset. This means that jobs will be re-run.
  • If the time changes forwards by more than 3 hours, the cron intervals will be reset. This means that any jobs missed will not get run.
  • If the time changes backwards by less than 3 hours, SimpleCron will continue running normally and those jobs will not get run again.
  • If the time changes forwards by less than 3 hours, SimpleCron will continue running normally and all missed jobs will be run immediately.


npm install --save simple-cron


yarn add simple-cron


Here's a contrived example:

// Instantiate SimpleCron
const SimpleCron = require('simple-cron');
const cron = new SimpleCron(); // Takes an optional parameter to define runInterval

// SimpleCron is also an event emitter so you can
// easily tell when events occur.
// Valid events are run, stop, schedule, cancel, invoke
cron.on('invoke', (jobId) => {
  console.log(`job '${jobId}' just ran!`);

// This is something we want to do every minute
const sendEmails = () => {
  const addresses = getAddresses();
  addresses.forEach((address) => {

// Schedule this job to run every minute
const emailJobId = cron.schedule('* * * * *', sendEmails);

// Start running SimpleCron;

// You can also schedule jobs after SimpleCron is already running if you want
const logJobId = cron.schedule('0 * * * *', () => {
  console.log('Another hour has passed you by...');

// Cancel a running job

// Shutdown SimpleCron. Returns a promise so you know when it's stopped.
cron.stop().then(() => { console.log('Shutdown complete.'); });

SimpleCon uses cron-parser to handle cron expressions.

API Reference


Constructor. Returns reference to cron instance. Take optional options object containing the following keys:

  • runInterval: The frequency in milliseconds for which SimpleCron will check to run jobs. Defaults to 100.

Runs SimpleCron. Starts running any scheduled jobs.


Stops SimpleCron. Returns a promise that resolves when SimpleCron has finished stopping.

cron.schedule(expression, function)

Schedules a function to be called at an interval. Returns an id for this scheduled job.


Cancels a scheduled job so it no longer runs on an interval. Requires you to provide the id returned by cron.schedule().


SimpleCron extends EventEmitter and emits the following events:

  • run
  • stop
  • cancel(id)
  • schedule(id)
  • invoke(id)


SimpleCron has thorough test coverage. To run the tests, clone the repo then do this:

npm i && npm test

SimpleCron uses semistandard for linting.

Package Sidebar


npm i simple-cron

Weekly Downloads






Last publish


  • nbrempel