cron-parser

What is cron-parser?

The cron-parser npm package is a utility for parsing crontab instructions. It allows users to interpret cron schedule expressions and calculate the next run times for jobs. It is useful for scheduling tasks in Node.js applications.

What are cron-parser's main functionalities?

Parsing Cron Expressions

This feature allows users to parse a cron expression and get the next execution times. The code sample demonstrates how to parse a cron expression that runs every 2 minutes and log the next execution time.

const cronParser = require('cron-parser');

try {
  const interval = cronParser.parseExpression('*/2 * * * *');
  console.log('Date: ', interval.next().toString()); // Get the next date
} catch (err) {
  console.error('Error: ' + err.message);
}

Iterating Over Execution Times

This feature allows users to iterate over the execution times of a cron job. The code sample demonstrates how to get the next 5 execution times for a cron expression that runs at the start of every hour.

const cronParser = require('cron-parser');

try {
  const interval = cronParser.parseExpression('0 * * * *');
  for (let i = 0; i < 5; i++) {
    console.log('Date: ', interval.next().toString()); // Get the next 5 dates
  }
} catch (err) {
  console.error('Error: ' + err.message);
}

Handling Cron Expression with Timezone

This feature allows users to parse a cron expression with a specific timezone. The code sample demonstrates how to parse a cron expression that runs at the start of every hour, considering the timezone of Europe/Amsterdam.

const cronParser = require('cron-parser');

try {
  const options = {
    currentDate: new Date('Wed, 26 Dec 2012 14:38:53 GMT'),
    tz: 'Europe/Amsterdam'
  };
  const interval = cronParser.parseExpression('0 * * * *', options);
  console.log('Date: ', interval.next().toString()); // Get the next date considering timezone
} catch (err) {
  console.error('Error: ' + err.message);
}

Other packages similar to cron-parser

node-cron

node-cron is a task scheduler in pure JavaScript for Node.js based on cron syntax. It allows you to schedule tasks to be executed at specific times or intervals. It is similar to cron-parser but also includes the ability to execute the jobs, not just parse cron expressions.

node-schedule

node-schedule is a flexible cron-like and not-cron-like job scheduler for Node.js. It allows for more complex scheduling than standard cron expressions, offering a higher level of customization. It is similar to cron-parser in parsing cron expressions but also provides an extensive job scheduling system.

bree

bree is a job scheduler for Node.js with cron and human-friendly syntax. It supports cron expressions and allows for scheduling jobs with additional features like job timeouts and concurrency control. Bree is more feature-rich compared to cron-parser, which focuses solely on parsing cron expressions.

agenda

agenda is a light and flexible job scheduling library for Node.js. It uses MongoDB for job storage and offers features like job prioritization, concurrency, and repeating jobs. While cron-parser is focused on parsing cron expressions, agenda provides a full job scheduling system with persistence.

README

cron-parser

Node.js library for parsing crontab instructions

Setup

npm install cron-parser

Supported format

*    *    *    *    *    *
┬    ┬    ┬    ┬    ┬    ┬
│    │    │    │    │    |
│    │    │    │    │    └ day of week (0 - 6)
│    │    │    │    └───── month (1 - 12)
│    │    │    └────────── day of month (1 - 31)
│    │    └─────────────── hour (0 - 23)
│    └──────────────────── minute (0 - 59)
└───────────────────────── second (0 - 59, optional)

Supports mixed use of ranges and range increments (L, W and # characters are not supported currently). See tests for examples.

Usage

Simple expression.

var parser = require('cron-parser');

parser.parseExpression('*/2 * * * *', function(err, interval) {
  if (err) {
    console.log('Error: ' + err.message);
    return;
  }

  console.log('Date: ', interval.next()); // Sat Dec 29 2012 00:42:00 GMT+0200 (EET)
  console.log('Date: ', interval.next()); // Sat Dec 29 2012 00:44:00 GMT+0200 (EET)
});

Alternatively this can be done synchronously.

var parser = require('cron-parser');

var interval = parser.parseExpressionSync('*/2 * * * *');
console.log('Date: ', interval.next()); // Sat Dec 29 2012 00:42:00 GMT+0200 (EET)
console.log('Date: ', interval.next()); // Sat Dec 29 2012 00:44:00 GMT+0200 (EET)

Define start and end date (limited timespan).

var parser = require('cron-parser');

var options = {
  currentDate: new Date('Wed, 26 Dec 2012 12:38:53 UTC'),
  endDate: new Date('Wed, 26 Dec 2012 14:40:00 UTC')
};

parser.parseExpression('*/22 * * * *', options, function(err, interval) {
  if (err) {
    console.log('Error: ' + err.message);
    return;
  }

  while (true) {
    try {
  		console.log(interval.next());
  	} catch (e) {
  		break;
  	}
  }

  // Wed Dec 26 2012 14:44:00 GMT+0200 (EET)
  // Wed Dec 26 2012 15:00:00 GMT+0200 (EET)
  // Wed Dec 26 2012 15:22:00 GMT+0200 (EET)
  // Wed Dec 26 2012 15:44:00 GMT+0200 (EET)
  // Wed Dec 26 2012 16:00:00 GMT+0200 (EET)
  // Wed Dec 26 2012 16:22:00 GMT+0200 (EET)
});