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

Croner

• Trigger functions in javascript using cron syntax.
• Pause, resume or stop exection efter a task is scheduled.
• Find first date of next month, find date of next tuesday, etc.
• Schedule in an other timezone than default.
• Support Node.js >4 to current. Both require (commonjs) and import (module)
• Supports browser (standalone, requirejs, udm, es-module, etc)

Documented with JSDoc for intellisense, and include TypeScript typings.

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

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

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

Installation

Manual

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

Node.js

npm install croner --save

// ESM Import
import Cron from "croner";

// ... or

// CommonJS Require

const Cron = require("croner");

CDN

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

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

To use as a ES-module

<script type="module">
	import Cron from "https://cdn.jsdelivr.net/npm/croner@3/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@3/dist/croner.min.mjs"
		}
	}
</script>
<script type="module">
	import Cron from 'croner';

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

Examples

Minimalist scheduling

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

Find dates

// Find next month
let nextMonth = Cron('0 0 0 1 * *').next(),
	nextSunday = Cron('0 0 0 * * 7').next();

console.log("First day of next month: " +  nextMonth.toLocaleDateString());
console.log("Next sunday: " +  nextSunday.toLocaleDateString());

Minimalist scheduling with stepping and custom timezone

// Run a function every fifth second
Cron('*/5 * * * * *', { timezone: 'Europe/Stockholm' } function () {
	console.log('This will run every fifth second');
});

Minimalist scheduling with range

// Run a function the first five seconds of a minute
Cron('0-4 * * * * *', function () {
	console.log('This will run the first five seconds every minute');
});

Minimalist scheduling with options

// Run a function each second, limit to five runs
Cron('* * * * * *', { maxRuns: 5 }, function () {
	console.log('This will run each second, but only five times.');
});

Minimalist scheduling with job controls

// Run a function each second, get reference to job
var job = Cron('* * * * * *', function () {
	console.log('This will run each second.');
});

// Pause job
job.pause();

// Resume job
job.resume();

// Stop job
job.stop();

Basic scheduling

// Run every minute
var scheduler = Cron('0 * * * * *');

scheduler.schedule(function() {
	console.log('This will run every minute');
});

Scheduling with options

// Run every minute
var scheduler = Cron('0 * * * * *');

// Schedule with options (all options are optional)
scheduler.schedule({ maxRuns: 5 }, function() {
	console.log('This will run every minute.');
});

Scheduling with job controls controlled by croner

let scheduler = Cron('* * * * * *')

let job = scheduler.schedule(function () {
	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: ' + scheduler.next());
	console.log('Next run: ' + scheduler.next());
});

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

Full API

var o = Cron( <string pattern> [, <object options>] [, <function callback> ] );

// If Cron is initialized without a scheduled function, cron itself is returned
// and the following member functions is available.
o.next( [ <date previous> ] );
o.msToNext();
o.previous();

// If Cron is initialized _with_ a scheduled function, the job is retured instead.
// Otherwise you get a reference to the job when scheduling a new job.
var job = o.schedule( [ { startAt: <date|string>, stopAt: <date|string>, maxRuns: <integer>, timezone: <string> } ,] callback);

// These self-explanatory functions is available to control the job
job.pause();
job.resume();
job.stop();

Pattern

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

License

MIT