<p align="center"> <img src="https://cdn.jsdelivr.net/gh/hexagon/croner@master/croner.png" alt="Croner" width="150" height="150"><br> Trigger functions or evaluate cron expressions in JavaScript or TypeScript. No dependencies. All features. Node. Deno. Bun. Browser. <br><br>Try it live on <a href="https://jsfiddle.net/hexag0n/hoa8kwsb/">jsfiddle</a>, and check out the full documentation on <a href="https://croner.56k.guru">croner.56k.guru</a>.<br> </p>

Croner - Cron for JavaScript and TypeScript

• Trigger functions in JavaScript using Cron syntax.
• Evaluate cron expressions and get a list of upcoming run times.
• Supports seconds and year fields, L (last), W (weekday), # (nth occurrence), and + (AND logic).
• Works in Node.js >=18.0 (both require and import), Deno >=2.0 and Bun >=1.0.0.
• Works in browsers as standalone, UMD or ES-module.
• Target different time zones.
• Built-in overrun protection
• Built-in error handling
• Includes TypeScript typings.
• Support for asynchronous functions.
• Pause, resume, or stop execution after a task is scheduled.
• Operates in-memory, with no need for a database or configuration files.
• Zero dependencies.

Quick examples:

// Basic: Run a function at the interval defined by a cron expression
const job = new Cron('*/5 * * * * *', () => {
	console.log('This will run every fifth second');
});

// Enumeration: What dates do the next 100 sundays occur on?
const nextSundays = new Cron('0 0 0 * * 7').nextRuns(100);
console.log(nextSundays);

// Days left to a specific date
const msLeft = new Cron('59 59 23 24 DEC *').nextRun() - new Date();
console.log(Math.floor(msLeft/1000/3600/24) + " days left to next christmas eve");

// Run a function at a specific date/time using a non-local timezone (time is ISO 8601 local time)
// This will run 2024-01-23 00:00:00 according to the time in Asia/Kolkata
new Cron('2024-01-23T00:00:00', { timezone: 'Asia/Kolkata' }, () => { console.log('Yay!') });

// Check if a date matches a cron pattern
const mondayCheck = new Cron('0 0 0 * * MON');
console.log(mondayCheck.match('2024-01-01T00:00:00')); // true  (Monday)
console.log(mondayCheck.match('2024-01-02T00:00:00')); // false (Tuesday)

More examples...

Installation

Full documentation on installation and usage is found at https://croner.56k.guru

Note If you are migrating from a different library such as cron or node-cron, or upgrading from a older version of croner, see the migration section of the manual.

Install croner using your favorite package manager or CDN, then include it in you project:

Using Node.js or Bun

// ESM Import ...
import { Cron } from "croner";

// ... or CommonJS Require, destructure to add type hints
const { Cron } = require("croner");

Using Deno

// From deno.land/x
import { Cron } from "https://deno.land/x/croner@10.0.1/dist/croner.js";

// ... or jsr.io
import { Cron } from "jsr:@hexagon/croner@10.0.1";

In a webpage using the UMD-module

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

Documentation

Signature

Cron takes three arguments

• pattern
• options (optional)
• scheduled function (optional)

// Parameters
// - First: Cron pattern, js date object (fire once), or ISO 8601 time string (fire once)
// - Second: Options (optional)
// - Third: Function run trigger (optional)
const job = new Cron("* * * * * *", { maxRuns: 1 }, () => {} );

// If function is omitted in constructor, it can be scheduled later
job.schedule(job, /* optional */ context) => {});

The job will be sceduled to run at next matching time unless you supply option { paused: true }. The new Cron(...) constructor will return a Cron instance, later called job, which have a couple of methods and properties listed below.

Status

job.nextRun( /*optional*/ startFromDate );	// Get a Date object representing the next run.
job.nextRuns(10, /*optional*/ startFromDate ); // Get an array of Dates, containing the next n runs.
job.previousRuns(10, /*optional*/ referenceDate ); // Get an array of Dates, containing previous n scheduled runs.
job.msToNext( /*optional*/ startFromDate ); // Get the milliseconds left until the next execution.
job.currentRun(); 		// Get a Date object showing when the current (or last) run was started.
job.previousRun( ); 		// Get a Date object showing when the previous job was started.

job.match( date ); 		// Check if a Date object or date string matches the cron pattern (true or false).

job.isRunning(); 	// Indicates if the job is scheduled and not paused or killed (true or false).
job.isStopped(); 	// Indicates if the job is permanently stopped using `stop()` (true or false).
job.isBusy(); 		// Indicates if the job is currently busy doing work (true or false).

job.getPattern(); 	// Returns the original pattern string
job.getOnce(); 		// Returns the original run-once date (Date or null)

Control functions

job.trigger();		// Force a trigger instantly
job.pause();		// Pause trigger
job.resume();		// Resume trigger
job.stop();		// Stop the job completely. It is not possible to resume after this.
				// Note that this also removes named jobs from the exported `scheduledJobs` array.

Properties

job.name 			// Optional job name, populated if a name were passed to options

Options

| Key | Default value | Data type | Remarks | |--------------|----------------|----------------|---------------------------------------| | name | undefined | String | If you specify a name for the job, Croner will keep a reference to the job in the exported array scheduledJobs. The reference will be removed on .stop(). | | maxRuns | Infinite | Number | | | catch | false | Boolean|Function | Catch unhandled errors in triggered function. Passing true will silently ignore errors. Passing a callback function will trigger this callback on error. | | timezone | undefined | String | Timezone in Europe/Stockholm format | | startAt | undefined | String | ISO 8601 formatted datetime (2021-10-17T23:43:00)<br>in local time (according to timezone parameter if passed) | | stopAt | undefined | String | ISO 8601 formatted datetime (2021-10-17T23:43:00)<br>in local time (according to timezone parameter if passed) | | interval | 0 | Number | Minimum number of seconds between triggers. | | paused | false | Boolean | If the job should be paused from start. | | context | undefined | Any | Passed as the second parameter to triggered function | | domAndDow | false | boolean | Combine day-of-month and day-of-week using true = AND, false = OR (default) | | legacyMode | (deprecated) | boolean | Deprecated: Use domAndDow instead. Inverse of domAndDow (legacyMode: true = domAndDow: false). | | unref | false | boolean | Setting this to true unrefs the internal timer, which allows the process to exit even if a cron job is running. | | utcOffset | undefined | number | Schedule using a specific utc offset in minutes. This does not take care of daylight savings time, you probably want to use option timezone instead. | | protect | undefined | boolean|Function | Enabled over-run protection. Will block new triggers as long as an old trigger is in progress. Pass either true or a callback function to enable | | alternativeWeekdays | false | boolean | Enable Quartz-style weekday numbering (1=Sunday, 2=Monday, ..., 7=Saturday). When false (default), uses standard cron format (0=Sunday, 1=Monday, ..., 6=Saturday). |

Warning Unreferencing timers (option unref) is only supported by Node.js and Deno. Browsers have not yet implemented this feature, and it does not make sense to use it in a browser environment.

Pattern

Croner uses Vixie Cron based expressions with the following powerful extensions:

// ┌──────────────── (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)
// │ │ │ │ │ │ ┌──── (optional) year (1 - 9999)
// │ │ │ │ │ │ │
// * * * * * * *

• Optional second and year fields for enhanced precision:

  • 6-field format: SECOND MINUTE HOUR DAY-OF-MONTH MONTH DAY-OF-WEEK
  • 7-field format: SECOND MINUTE HOUR DAY-OF-MONTH MONTH DAY-OF-WEEK YEAR
  • Supported year range: 1-9999

• Advanced calendar modifiers:

  • L: Last day of month or last occurrence of a weekday. L in day-of-month = last day of month;