croner

What is croner?

The croner npm package is a high-performance task scheduler for Node.js that allows you to run tasks at specific times or intervals. It is designed to be a drop-in replacement for the 'cron' package with additional features and improvements.

What are croner's main functionalities?

Simple cron job scheduling

This feature allows you to schedule a task to run at intervals defined by the cron syntax. In the provided code sample, a job is scheduled to run every 5 seconds.

const { Cron } = require('croner');

const job = Cron('*/5 * * * * *', () => {
  console.log('This will run every 5 seconds');
});

One-time execution

This feature allows you to schedule a task to run once at a specific time in the future. The code sample schedules a job to run once after 10 seconds.

const { Cron } = require('croner');

const job = Cron(new Date(Date.now() + 10000), () => {
  console.log('This will run once after 10 seconds');
});

Stopping a job

This feature allows you to stop a scheduled job. In the code sample, a job is scheduled to run every 5 seconds but is stopped after 15 seconds.

const { Cron } = require('croner');

const job = Cron('*/5 * * * * *', () => {
  console.log('This job will be stopped.');
});

setTimeout(() => {
  job.stop();
}, 15000);

Timezone support

This feature allows you to schedule jobs according to a specific timezone. The code sample schedules a job to run at 10:30 AM in the 'America/New_York' timezone.

const { Cron } = require('croner');

const job = Cron('0 30 10 * * *', () => {
  console.log('This will run at 10:30 AM in the America/New_York timezone.');
}, { timezone: 'America/New_York' });

Other packages similar to croner

node-schedule

node-schedule is a flexible cron-like and not-cron-like job scheduler for Node.js. It allows you to schedule jobs using both cron-style and human-readable syntax. It is similar to croner but offers a different API and additional scheduling features like scheduling jobs with JavaScript Date objects.

agenda

agenda is a job scheduling library for Node.js that uses MongoDB for persisting job data. It is more suitable for distributed or long-running job tasks. Unlike croner, which focuses on in-memory cron job scheduling, agenda provides persistence and is better suited for applications that require job recovery and failover capabilities.

bull

bull is a Redis-based queue system for Node.js. It is designed for handling distributed jobs and messages in Node.js applications. While croner is used for scheduling tasks, bull is more focused on job queuing, processing, and concurrency, making it suitable for more complex job handling scenarios.

README

Trigger functions in javascript using Cron syntax

Croner

• Trigger functions in javascript using Cron syntax.
• Pause, resume or stop execution efter a task is scheduled.
• Find first date of next month, find date of next tuesday, etc.
• Supports Node.js from 4.0 to current. Both require (commonjs) and import (module).
• Supports browser use (UMD (standalone, requirejs etc.), ES-module)
• Experimental: Schedule in other timezones than default.

Documented with JSDoc for intellisense, and include TypeScript typings.

Quick demo:

// Run a function at the interval set by a cron expression
let job = Cron('* * * * * *', () => {
	console.log('This will run every second');
});

// Control execution
// job.pause();
// job.resume();
// job.stop();

// Get info
let next = job.next();
let previous = job.previous();

// What date is next sunday?
let nextSunday = Cron('0 0 0 * * 7').next();
console.log(nextSunday.toLocaleDateString());

// How many days left to christmas eve?
let msLeft = Cron('59 59 23 24 DEC *').next() - new Date();
console.log(Math.floor(msLeft/1000/3600/24) + " days left to next christmas eve");

More examples...

Installation

Node.js

npm install croner --save

// ESM Import
import Cron from "croner";

// ... or

// CommonJS Require

const Cron = require("croner");

Browser

Manual

• Download latest zipball
• Unpack
• Grab croner.min.js (UMD) or croner.min.mjs (ES-module) from the dist/ folder

CDN

To use as a UMD-module (stand alone, RequireJS etc.)

<script src="https://cdn.jsdelivr.net/npm/croner@4/dist/croner.min.js"></script>

To use as a ES-module

<script type="module">
	import Cron from "https://cdn.jsdelivr.net/npm/croner@4/dist/croner.min.mjs";

	// ... see usage section ...
</script>

... or a ES-module with import-map

<script type="importmap">
	{
		"imports": {
			"croner": "https://cdn.jsdelivr.net/npm/croner@4/dist/croner.min.mjs"
		}
	}
</script>
<script type="module">
	import Cron from 'croner';

	// ... see usage section ...
</script>

Signature

Cron takes three arguments; pattern, options (optional) and a scheduled function (optional).

var scheduler = Cron( <string pattern> [, { ... } ] [, <function toBeRun> ] );

Cron return a scheduler, which can be used in a couple of different ways.

job.next( [ <date previous> ] );	// Get a Date object with next run time according 
					// to pattern relative to previous, or now if omitted

job.msToNext( [ <date previous> ] );    // Get milliseconds left to next execution

job.previous();				// Gets a Date object with previous run time, or null

job.schedule( <fn job> );		// If you didn't pass a function to constructor, you can do it here

job.pause();				// Pause execution
job.resume();				// Resume execution
job.stop();				// Stop execution

Options

Options are optional, and passed as the second parameter of cron.

Example:

Cron( '* * * * * *', { maxRuns: 4 } );

Key	Default value	Data type	Remarks
maxRuns	Infinite	Number
timezone	undefined	String	Timezone in Europe/Stockholm format
startAt	undefined	String	ISO 8601 formatted datetime (2021-10-17T23:43:00) in local or specified timezone
stopAt	undefined	String	ISO 8601 formatted datetime (2021-10-17T23:43:00) in local or specified timezone
paused	false	Boolean	If the job should be paused from start.

Pattern

Pattern is mandatory, and passed as the first argument of Cron.

Example:

Cron( '* * * * * *', () => {} );

Composition:

┌──────────────── (optional) second (0 - 59)
│ ┌────────────── minute (0 - 59)
│ │ ┌──────────── hour (0 - 23)
│ │ │ ┌────────── day of month (1 - 31)
│ │ │ │ ┌──────── month (1 - 12, JAN-DEC)
│ │ │ │ │ ┌────── day of week (0 - 6, SUN-Mon) 
│ │ │ │ │ │       (0 to 6 are Sunday to Saturday; 7 is Sunday, the same as 0)
│ │ │ │ │ │
* * * * * *

Details:

Field	Required	Allowed values	Allowed special characters	Remarks
Seconds	Optional	0-59	* , - /
Minutes	Yes	0-59	* , - /
Hours	Yes	0-23	* , - /
Day of Month	Yes	1-31	* , - /
Month	Yes	1-12 or JAN-DEC	* , - /
Day of Week	Yes	0-7 or SUN-MON	* , - /	0 to 6 are Sunday to Saturday 7 is Sunday, the same as 0

Note: Weekday and month names are case insensitive. Both MON and mon works.

Examples

Minimal

// Run a function each second
Cron('* * * * * *', () => {
	console.log('This will run every second');
});

Expressions

// Run a function the first five seconds of a minute
Cron('0-4 */5 1,2,3 * JAN-MAR SAT', function () {
	console.log('This will run the first five seconds every fifth minute');
	console.log('of hour 1,2 and 3 every saturday in January to March.');
});

Find dates

// Find next month
let nextMonth = Cron('0 0 0 1 * *').next(),
	nextSunday = Cron('0 0 0 * * 7').next(),
	nextSat29feb = Cron("0 0 0 29 2 6").next();

console.log("First day of next month: " +  nextMonth.toLocaleDateString());
console.log("Next sunday: " +  nextSunday.toLocaleDateString());
console.log("Next saturday at 29th of february: " +  nextSat29feb.toLocaleDateString());  // 2048-02-29

With options

var job = Cron(
	'* * * * *', 
	{ 
		maxRuns: Infinity, 
		startAt: "2021-11-01T00:00:00", 
		stopAt: "2021-12-01T00:00:00",
		timezone: "Europe/Stockholm"
	},
	function() {
		console.log('This will run every minute, from 2021-11-01 to 2021-12-01 00:00:00 in Europe/Stockholm.');
	}
);

Job controls

let job = Cron('* * * * * *', () => {
	console.log('This will run every second. Pause on second 10. Resume on second 15. And quit on second 20.');
	console.log('Current second: ', new Date().getSeconds());
	console.log('Previous run: ' + job.previous());
	console.log('Next run: ' + job.next());
});

Cron('10 * * * * *', {maxRuns: 1}, () => job.pause());
Cron('15 * * * * *', {maxRuns: 1}, () => job.resume());
Cron('20 * * * * *', {maxRuns: 1}, () => job.stop());

License

MIT