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.
Trigger functions in JavaScript using Cron syntax.
Try it live on jsfiddle.
Croner
- Trigger functions in JavaScript using Cron syntax.
- Pause, resume or stop execution after a task is scheduled.
- Find first date of next month, find date of next tuesday, etc.
- Works in Node.js >=4.0 (both require and import).
- Works in Deno >=1.16.
- Works in browsers as standalone, UMD or ES-module.
- Experimental feature: Schedule in specific target timezones.
- Includes TypeScript typings.
Quick examples:
const job = Cron('* * * * * *', () => {
console.log('This will run every second');
});
const nextSunday = Cron('0 0 0 * * 7').next();
console.log(nextSunday.toLocaleDateString());
const 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...
Why another javascript cron implementation?
Because the existing ones isn't good enough. They have serious bugs, use bloated dependencies, does not work in all environments and/or just doesn't work as expected.
Benchmark at 2021-11-26:
> node cron-implementation-test.js
Test: When is next saturday 29th of february, pattern '0 0 0 29 2 6'
node-schedule: 2022-02-05 00:00:00 in 37.77ms
node-cron: ??? in 6.746ms
cron: 2022-03-05 00:00:00 in 8.282ms
croner: 2048-02-29 00:00:00 in 2.676ms
> node cron-implementation-test.js
Test: When is next 15th of february, pattern '0 0 0 15 2 *'
node-schedule: 2022-02-15 00:00:00 in 91.834ms
node-cron: ??? in 7.69ms
cron: 2022-03-15 00:00:00 in 12.354ms
croner: 2022-02-15 00:00:00 in 4.398ms
Test: When is next monday in october, pattern '0 0 0 * 10 1'
node-schedule: 2022-10-03 00:00:00 in 244.057ms
node-cron: ??? in 12.001ms
cron: 2021-11-29 00:00:00 in 19.322ms
croner: 2022-10-03 00:00:00 in 5.394ms
Test: When is next monday the 1st of any month, pattern '0 0 0 1 * 1'
node-schedule: 2021-11-29 00:00:00 in 39.591ms
node-cron: ??? in 7.078ms
cron: 2021-11-29 00:00:00 in 10.107ms
croner: 2022-08-01 00:00:00 in 9.473ms
Test: When is 23:00 next 31st march, pattern '0 0 23 31 3 *'
node-schedule: 2022-03-31 23:00:00 in 87.661ms
node-cron: ??? in 10.299ms
Month '3' is limited to '30' days.
cron: 2022-04-01 23:00:00 in 25.756ms
croner: 2022-03-31 23:00:00 in 5.569ms
https://gist.github.com/Hexagon/703f85f2dd86443cc17eef8f5cc6cb70
Installation
Node.js
npm install croner --save
JavaScript
import Cron from "croner";
const Cron = require("croner");
TypeScript
Note that only default export is available in Node.js TypeScript, as the commonjs module is used internally.
import Cron from "croner";
const scheduler : Cron = new Cron("* * * * * *", () => {
console.log("This will run every second.");
});
Deno
JavaScript
import Cron from "https://cdn.jsdelivr.net/gh/hexagon/croner@4/src/croner.js";
Cron("* * * * * *", () => {
console.log("This will run every second.");
});
TypeScript
import { Cron } from "https://cdn.jsdelivr.net/gh/hexagon/croner@4/src/croner.js";
const _scheduler : Cron = new Cron("* * * * * *", () => {
console.log("This will run every second.");
});
Browser
Manual
- Download latest zipball
- Unpack
- Grab
croner.min.js
(UMD and standalone) 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";
</script>
Documentation
Full documentation available at hexagon.github.io/croner.
The short version:
Signature
Cron takes three arguments
const job = Cron("* * * * * *" , { maxRuns: 1 } , () => {} );
job.schedule(( job, context) => {});
const nextRun = job.next( previousRun );
const prevRun = job.previous( );
const msToNext = job.msToNext( previousRun );
const isRunning = job.running();
job.pause();
job.resume();
job.stop();
Options
Key | Default value | Data type | Remarks |
---|
maxRuns | Infinite | Number | |
catch | false | Boolean | Catch and ignore unhandled errors in triggered function |
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. |
context | undefined | Any | Passed as the second parameter to triggered function |
Pattern
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
Expressions
Cron('15-45/10 */5 1,2,3 * JAN-MAR SAT', function () {
console.log('This will run every tenth second between second 15-45');
console.log('every fifth minute of hour 1,2 and 3');
console.log('every saturday in January to March.');
});
Find dates
const 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());
With options
const 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
const job = Cron('* * * * * *', (self) => {
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: ' + self.previous());
console.log('Next run: ' + self.next());
});
Cron('10 * * * * *', {maxRuns: 1}, () => job.pause());
Cron('15 * * * * *', {maxRuns: 1}, () => job.resume());
Cron('20 * * * * *', {maxRuns: 1}, () => job.stop());
Passing a context
const data = {
what: "stuff"
};
Cron('* * * * * *', { context: data }, (_self, context) => {
console.log('This will print stuff: ' + context.what);
});
Cron('*/5 * * * * *', { context: data }, (self, context) => {
console.log('After this, other stuff will be printed instead');
context.what = "other stuff";
self.stop();
});
Contributing
See Contribution Guide
License
MIT