Trigger functions or evaluate cron expressions in JavaScript or TypeScript. No dependencies. All features. Node. Deno. Bun. Browser.

Try it live on jsfiddle, and check out the full documentation on croner.56k.guru.

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

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/[email protected]/dist/croner.js";

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

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

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 br