node-schedule

What is node-schedule?

The node-schedule npm package is a flexible cron-like and not-cron-like job scheduler for Node.js. It allows you to schedule jobs (arbitrary functions) for execution at specific dates, with optional recurrence rules. It is suitable for building job schedulers, task reminders, or any other automation based on time events.

What are node-schedule's main functionalities?

One-time jobs

Schedule a job to be executed once at a specific date and time.

const schedule = require('node-schedule');
const date = new Date(2023, 3, 21, 5, 30, 0);

const job = schedule.scheduleJob(date, function() {
  console.log('This job is run once at the specified date.');
});

Recurring jobs using cron-style scheduling

Schedule a job to be executed on a recurring basis using a cron string to specify the frequency.

const schedule = require('node-schedule');

const job = schedule.scheduleJob('*/5 * * * *', function() {
  console.log('This job runs every 5 minutes.');
});

Recurring jobs using object literal syntax

Schedule a job using a more human-readable object literal syntax for setting the schedule.

const schedule = require('node-schedule');

const job = schedule.scheduleJob({hour: 14, minute: 30, dayOfWeek: 1}, function() {
  console.log('This job runs at 2:30pm every Monday.');
});

Canceling jobs

Cancel a scheduled job before it is executed.

const schedule = require('node-schedule');
const job = schedule.scheduleJob('*/5 * * * *', function() {
  console.log('This job will be canceled.');
});

job.cancel();

Other packages similar to node-schedule

cron

The 'cron' package is similar to node-schedule and is used for scheduling jobs to run at specific times or intervals. It uses the Unix cron string format to define schedules and is widely used for its simplicity and familiarity to those with Unix/Linux experience.

agenda

Agenda is a more feature-rich job scheduling library for Node.js. It supports persistence with MongoDB, which allows scheduled jobs to be stored and run across server restarts. It also offers more control over job queuing and locking, making it suitable for more complex scheduling needs.

bull

Bull is a Redis-based queue system for Node.js. It is often used for job scheduling as well as for processing distributed jobs in the background. It offers advanced features like repeatable jobs, rate limiting, and job prioritization, making it a good choice for high-performance job processing.

bree

Bree is a job scheduler for Node.js that supports cron, dates, ms (milliseconds), later, and human-friendly strings for job scheduling. It uses workers for parallel job processing and includes support for job timeouts and graceful cancellation. It's a modern alternative with a focus on reliability and concurrency.

README

Node Schedule

Node Schedule is a flexible cron-like and not-cron-like job scheduler for Node.js. It allows you to schedule jobs (arbitrary functions) for execution at specific dates, with optional recurrence rules. It only uses a single timer at any given time (rather than reevaluating upcoming jobs every second/minute).

Usage

Installation

You can install using npm.

npm install node-schedule

Overview

Node Schedule is for time-based scheduling, not interval-based scheduling. While you can easily bend it to your will, if you only want to do something like "run this function every 5 minutes", you'll find setInterval much easier to use, and far more appropriate. But if you want to, say, "run this function at the :20 and :50 of every hour on the third Tuesday of every month," you'll find that Node Schedule suits your needs better. Additionally, Node Schedule has Windows support unlike true cron since the node runtime is now fully supported.

Note that Node Schedule is designed for in-process scheduling, i.e. scheduled jobs will only fire as long as your script is running, and the schedule will disappear when execution completes. If you need to schedule jobs that will persist even when your script isn't running, consider using actual cron.

Jobs and Scheduling

Every scheduled job in Node Schedule is represented by a Job object. You can create jobs manually, then execute the schedule() method to apply a schedule, or use the convenience function scheduleJob() as demonstrated below.

Job objects are EventEmitter's, and emit a run event after each execution. They also emit a scheduled event each time they're scheduled to run, and a canceled event when an invocation is canceled before it's executed (both events receive a JavaScript date object as a parameter). Note that jobs are scheduled the first time immediately, so if you create a job using the scheduleJob() convenience method, you'll miss the first scheduled event. Also note that canceled is the single-L American spelling.

Cron-style Scheduling

The cron format consists of:

*    *    *    *    *    *
┬    ┬    ┬    ┬    ┬    ┬
│    │    │    │    │    |
│    │    │    │    │    └ day of week (0 - 7) (0 or 7 is Sun)
│    │    │    │    └───── month (1 - 12)
│    │    │    └────────── day of month (1 - 31)
│    │    └─────────────── hour (0 - 23)
│    └──────────────────── minute (0 - 59)
└───────────────────────── second (0 - 59, OPTIONAL)

Examples with the cron format:

var schedule = require('node-schedule');

var j = schedule.scheduleJob('42 * * * *', function(){
  console.log('The answer to life, the universe, and everything!');
});

Execute a cron job when the minute is 42 (e.g. 19:42, 20:42, etc.).

And:

var j = schedule.scheduleJob('0 17 ? * 0,4-6', function(){
  console.log('Today is recognized by Rebecca Black!');
});

Execute a cron job every 5 Minutes = */5 * * * *

Unsupported Cron Features

Currently, W (nearest weekday), L (last day of month/week), and # (nth weekday of the month) are not supported. Most other features supported by popular cron implementations should work just fine.

cron-parser is used to parse crontab instructions.

Date-based Scheduling

Say you very specifically want a function to execute at 5:30am on December 21, 2012. Remember - in JavaScript - 0 - January, 11 - December.

var schedule = require('node-schedule');
var date = new Date(2012, 11, 21, 5, 30, 0);

var j = schedule.scheduleJob(date, function(){
  console.log('The world is going to end today.');
});

You can invalidate the job with the cancel() method:

j.cancel();

To use current data in the future you can use binding:

var schedule = require('node-schedule');
var date = new Date(2012, 11, 21, 5, 30, 0);
var x = 'Tada!';
var j = schedule.scheduleJob(date, function(y){
  console.log(y);
}.bind(null,x));
x = 'Changing Data';

This will log 'Tada!' when the scheduled Job runs, rather than 'Changing Data', which x changes to immediately after scheduling.

Recurrence Rule Scheduling

You can build recurrence rules to specify when a job should recur. For instance, consider this rule, which executes the function every hour at 42 minutes after the hour:

var schedule = require('node-schedule');

var rule = new schedule.RecurrenceRule();
rule.minute = 42;

var j = schedule.scheduleJob(rule, function(){
  console.log('The answer to life, the universe, and everything!');
});

You can also use arrays to specify a list of acceptable values, and the Range object to specify a range of start and end values, with an optional step parameter. For instance, this will print a message on Thursday, Friday, Saturday, and Sunday at 5pm:

var rule = new schedule.RecurrenceRule();
rule.dayOfWeek = [0, new schedule.Range(4, 6)];
rule.hour = 17;
rule.minute = 0;

var j = schedule.scheduleJob(rule, function(){
  console.log('Today is recognized by Rebecca Black!');
});

RecurrenceRule properties

• second
• minute
• hour
• date
• month
• year
• dayOfWeek

Note: It's worth noting that the default value of a component of a recurrence rule is null (except for second, which is 0 for familiarity with cron). If we did not explicitly set minute to 0 above, the message would have instead been logged at 5:00pm, 5:01pm, 5:02pm, ..., 5:59pm. Probably not what you want.

Object Literal Syntax

To make things a little easier, an object literal syntax is also supported, like in this example which will log a message every Sunday at 2:30pm:

var j = schedule.scheduleJob({hour: 14, minute: 30, dayOfWeek: 0}, function(){
  console.log('Time for tea!');
});

Set StartTime and EndTime

It will run after 5 seconds and stop after 10 seconds in this example. The ruledat supports the above.

let startTime = new Date(Date.now() + 5000);
let endTime = new Date(startTime.getTime() + 5000);
var j = schedule.scheduleJob({ start: startTime, end: endTime, rule: '*/1 * * * * *' }, function(){
  console.log('Time for tea!');
});

Contributing

This module was originally developed by Matt Patenaude, and is now maintained by Tejas Manohar and other wonderful contributors.

We'd love to get your contributions. Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit.

Before jumping in, check out our Contributing page guide!

Copyright and license

Copyright 2015 Matt Patenaude.

Licensed under the [MIT License] license.