Gathering detailed insights and metrics for croner
Gathering detailed insights and metrics for croner
Gathering detailed insights and metrics for croner
Gathering detailed insights and metrics for croner
@edgeros/croner
Trigger functions and/or evaluate cron expressions in JavaScript. No dependencies. Most features. All environments.
@kingsworld/plugin-cron
A simple @sapphire/framework plugin that aims to make use of the croner package and allow users to make cron jobs within their Sapphire discord bot.
@stacksjs/cron
The Stacks cron.
script-timer
Run your scripts at specific intervals, non-stop.
Trigger functions or evaluate cron expressions in JavaScript or TypeScript. No dependencies. Most features. Node. Deno. Bun. Browser.
npm install croner
Typescript
Module System
Min. Node Version
Node Version
NPM Version
TypeScript (100%)
Total Downloads
0
Last Day
0
Last Week
0
Last Month
0
Last Year
0
MIT License
2,289 Stars
632 Commits
64 Forks
11 Watchers
4 Branches
15 Contributors
Updated on Jul 10, 2025
Latest Version
9.1.0
Package Id
croner@9.1.0
Unpacked Size
101.90 kB
Size
25.20 kB
File Count
8
NPM Version
10.8.2
Node Version
18.20.8
Published on
Jun 16, 2025
Cumulative downloads
Total Downloads
Last Day
0%
NaN
Compared to previous day
Last Week
0%
NaN
Compared to previous week
Last Month
0%
NaN
Compared to previous month
Last Year
0%
NaN
Compared to previous year
No dependencies detected.
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.
L
for last day and weekday of month and #
for nth weekday of month.Quick examples:
1// Basic: Run a function at the interval defined by a cron expression 2const job = new Cron('*/5 * * * * *', () => { 3 console.log('This will run every fifth second'); 4}); 5 6// Enumeration: What dates do the next 100 sundays occur on? 7const nextSundays = new Cron('0 0 0 * * 7').nextRuns(100); 8console.log(nextSundays); 9 10// Days left to a specific date 11const msLeft = new Cron('59 59 23 24 DEC *').nextRun() - new Date(); 12console.log(Math.floor(msLeft/1000/3600/24) + " days left to next christmas eve"); 13 14// Run a function at a specific date/time using a non-local timezone (time is ISO 8601 local time) 15// This will run 2024-01-23 00:00:00 according to the time in Asia/Kolkata 16new Cron('2024-01-23T00:00:00', { timezone: 'Asia/Kolkata' }, () => { console.log('Yay!') }); 17
More examples...
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
ornode-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
1// ESM Import ... 2import { Cron } from "croner"; 3 4// ... or CommonJS Require, destructure to add type hints 5const { Cron } = require("croner");
Using Deno
1// From deno.land/x 2import { Cron } from "https://deno.land/x/croner@8.1.2/dist/croner.js"; 3 4// ... or jsr.io 5import { Cron } from "jsr:@hexagon/croner@8.1.2";
In a webpage using the UMD-module
1<script src="https://cdn.jsdelivr.net/npm/croner@8/dist/croner.umd.min.js"></script>
Cron takes three arguments
1// Parameters 2// - First: Cron pattern, js date object (fire once), or ISO 8601 time string (fire once) 3// - Second: Options (optional) 4// - Third: Function run trigger (optional) 5const job = new Cron("* * * * * *", { maxRuns: 1 }, () => {} ); 6 7// If function is omitted in constructor, it can be scheduled later 8job.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.
1job.nextRun( /*optional*/ startFromDate ); // Get a Date object representing the next run. 2job.nextRuns(10, /*optional*/ startFromDate ); // Get an array of Dates, containing the next n runs. 3job.msToNext( /*optional*/ startFromDate ); // Get the milliseconds left until the next execution. 4job.currentRun(); // Get a Date object showing when the current (or last) run was started. 5job.previousRun( ); // Get a Date object showing when the previous job was started. 6 7job.isRunning(); // Indicates if the job is scheduled and not paused or killed (true or false). 8job.isStopped(); // Indicates if the job is permanently stopped using `stop()` (true or false). 9job.isBusy(); // Indicates if the job is currently busy doing work (true or false). 10 11job.getPattern(); // Returns the original pattern string
1job.trigger(); // Force a trigger instantly 2job.pause(); // Pause trigger 3job.resume(); // Resume trigger 4job.stop(); // Stop the job completely. It is not possible to resume after this. 5 // Note that this also removes named jobs from the exported `scheduledJobs` array.
1job.name // Optional job name, populated if a name were passed to 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) in local time (according to timezone parameter if passed) |
stopAt | undefined | String | ISO 8601 formatted datetime (2021-10-17T23:43:00) 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 |
legacyMode | true | boolean | Combine day-of-month and day-of-week using true = OR, false = AND |
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 |
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.
The expressions used by Croner are very similar to those of Vixie Cron, but with a few additions and changes as outlined below:
1// ┌──────────────── (optional) second (0 - 59) 2// │ ┌────────────── minute (0 - 59) 3// │ │ ┌──────────── hour (0 - 23) 4// │ │ │ ┌────────── day of month (1 - 31) 5// │ │ │ │ ┌──────── month (1 - 12, JAN-DEC) 6// │ │ │ │ │ ┌────── day of week (0 - 6, SUN-Mon) 7// │ │ │ │ │ │ (0 to 6 are Sunday to Saturday; 7 is Sunday, the same as 0) 8// │ │ │ │ │ │ 9// * * * * * *
Croner expressions have the following additional modifiers:
5#L
represents the last Friday of the month.5#2
in the day of week field signifies the second Friday of the month. This can be combined with ranges and supports day names. For instance, MON-FRI#2 would match the Monday through Friday of the second week of the month.Croner allows you to pass a JavaScript Date object or an ISO 8601 formatted string as a pattern. The scheduled function will trigger at the specified date/time and only once. If you use a timezone different from the local timezone, you should pass the ISO 8601 local time in the target location and specify the timezone using the options (2nd parameter).
Croner also allows you to change how the day-of-week and day-of-month conditions are combined. By default, Croner (and Vixie cron) will trigger when either the day-of-month OR the day-of-week conditions match. For example, 0 20 1 * MON
will trigger on the first of the month as well as each Monday. If you want to use AND (so that it only triggers on Mondays that are also the first of the month), you can pass { legacyMode: false }
. For more information, see issue #53.
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 | * , - / ? L | |
Month | Yes | 1-12 or JAN-DEC | * , - / ? | |
Day of Week | Yes | 0-7 or SUN-MON | * , - / ? L # | 0 to 6 are Sunday to Saturday 7 is Sunday, the same as 0 # is used to specify nth occurrence of a weekday |
Note Weekday and month names are case-insensitive. Both
MON
andmon
work. When usingL
in the Day of Week field, it affects all specified weekdays. For example,5-6#L
means the last Friday and Saturday in the month." The # character can be used to specify the "nth" weekday of the month. For example, 5#2 represents the second Friday of the month.
It is also possible to use the following "nicknames" as pattern.
Nickname | Description |
---|---|
@yearly | Run once a year, ie. "0 0 1 1 *". |
@annually | Run once a year, ie. "0 0 1 1 *". |
@monthly | Run once a month, ie. "0 0 1 * *". |
@weekly | Run once a week, ie. "0 0 * * 0". |
@daily | Run once a day, ie. "0 0 * * *". |
@hourly | Run once an hour, ie. "0 * * * *". |
Because the existing ones are not good enough. They have serious bugs, use bloated dependencies, do not work in all environments, and/or simply do not work as expected.
croner | cronosjs | node-cron | cron | node-schedule | |
---|---|---|---|---|---|
Platforms | |||||
Node.js (CommonJS) | ✓ | ✓ | ✓ | ✓ | ✓ |
Browser (ESMCommonJS) | ✓ | ✓ | |||
Deno (ESM) | ✓ | ||||
Features | |||||
Over-run protection | ✓ | ||||
Error handling | ✓ | ✓ | |||
Typescript typings | ✓ | ✓ | ✓ | ||
Unref timers (optional) | ✓ | ✓ | |||
dom-OR-dow | ✓ | ✓ | ✓ | ✓ | ✓ |
dom-AND-dow (optional) | ✓ | ||||
Next run | ✓ | ✓ | ✓ | ✓ | |
Next n runs | ✓ | ✓ | ✓ | ||
Timezone | ✓ | ✓ | ✓ | ✓ | ✓ |
Minimum interval | ✓ | ||||
Controls (stop/resume) | ✓ | ✓ | ✓ | ✓ | ✓ |
Range (0-13) | ✓ | ✓ | ✓ | ✓ | ✓ |
Stepping (*/5) | ✓ | ✓ | ✓ | ✓ | ✓ |
Last day of month (L) | ✓ | ✓ | |||
Nth weekday of month (#) | ✓ | ✓ |
croner | cronosjs | node-cron | cron | node-schedule | |
---|---|---|---|---|---|
Size | |||||
Minified size (KB) | 17.0 | 14.9 | 15.2 | 85.4 :warning: | 100.5 :warning: |
Bundlephobia minzip (KB) | 5.0 | 5.1 | 5.7 | 25.8 | 29.2 :warning: |
Dependencies | 0 | 0 | 1 | 1 | 3 :warning: |
Popularity | |||||
Downloads/week 1 | 2019K | 31K | 447K | 1366K | 1046K |
Quality | |||||
Issues 1 | 0 | 2 | 133 :warning: | 13 | 145 :warning: |
Code coverage | 99% | 98% | 100% | 81% | 94% |
Performance | |||||
Ops/s 1 2 3 4 5 6 | 160 651 | 55 593 | N/A :x: | 6 313 :warning: | 2 726 :warning: |
Ops/s 0 0 0 29 2 * | 176 714 | 67 920 | N/A :x: | 3 104 :warning: | 737 :warning: |
Tests | 11/11 | 10/11 | 0/11 2 :question: | 7/11 :warning: | 9/11 |
Note
- Table last updated at 2023-10-10
- node-cron has no interface to predict when the function will run, so tests cannot be carried out.
- All tests and benchmarks were carried out using https://github.com/Hexagon/cron-comparison
This branch contains the latest stable code, released on npm's default channel latest
. You can install the latest stable revision by running the command below.
npm install croner --save
This branch contains code currently being tested, and is released at channel dev
on npm. You can install the latest revision of the development branch by running the command below.
npm install croner@dev
Warning Expect breaking changes if you do not pin to a specific version.
A list of fixes and features currently released in the dev
branch is available here
Croner is founded and actively maintained by Hexagon. If you find value in Croner and want to contribute:
Code Contributions: See our Contribution Guide for details on how to contribute code.
Sponsorship and Donations: See github.com/sponsors/hexagon
Your trust, support, and contributions drive the project. Every bit, irrespective of its size, is deeply appreciated.
MIT License
No vulnerabilities found.
Reason
no binaries found in the repo
Reason
no dangerous workflow patterns detected
Reason
security policy file detected
Details
Reason
license file detected
Details
Reason
0 existing vulnerabilities detected
Reason
packaging workflow detected
Details
Reason
2 commit(s) and 3 issue activity found in the last 90 days -- score normalized to 4
Reason
SAST tool is not run on all commits -- score normalized to 4
Details
Reason
Found 4/15 approved changesets -- score normalized to 2
Reason
dependency not pinned by hash detected -- score normalized to 0
Details
Reason
detected GitHub workflow tokens with excessive permissions
Details
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
project is not fuzzed
Details
Score
Last Scanned on 2025-07-07
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More