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 2030-01-23 00:00:00 according to the time in Asia/Kolkata
new Cron('2030-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

import { Cron } from "jsr:@hexagon/[email protected]";

In a webpage using the UMD-module

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/croner.umd.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.enumerate( /*optional*/ startFromDate ); // Get a stateful CronIterator for use in for...of / destructuring.
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

This is the beginning of the README. Read the rest at the original. Read the full README ↗