Gathering detailed insights and metrics for cron-parser
Gathering detailed insights and metrics for cron-parser
Gathering detailed insights and metrics for cron-parser
Gathering detailed insights and metrics for cron-parser
cronstrue
Convert cron expressions into human readable descriptions
react-js-cron
A React cron editor with antd inspired by jqCron
croner
Trigger functions and/or evaluate cron expressions in JavaScript. No dependencies. Most features. All environments.
cron-schedule
A zero-dependency cron parser and scheduler for Node.js, Deno and the browser.
npm install cron-parser
Typescript
Module System
Min. Node Version
Node Version
NPM Version
TypeScript (99.35%)
JavaScript (0.65%)
Total Downloads
0
Last Day
0
Last Week
0
Last Month
0
Last Year
0
MIT License
1,406 Stars
384 Commits
163 Forks
14 Watchers
5 Branches
49 Contributors
Updated on Jul 13, 2025
Latest Version
5.3.0
Package Id
cron-parser@5.3.0
Unpacked Size
130.30 kB
Size
27.91 kB
File Count
35
NPM Version
10.9.0
Node Version
22.12.0
Published on
Jun 08, 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
1
A JavaScript library for parsing and manipulating cron expressions. Features timezone support, DST handling, and iterator capabilities.
1npm install cron-parser
* * * * * *
┬ ┬ ┬ ┬ ┬ ┬
│ │ │ │ │ │
│ │ │ │ │ └─ day of week (0-7, 1L-7L) (0 or 7 is Sun)
│ │ │ │ └────── month (1-12, JAN-DEC)
│ │ │ └─────────── day of month (1-31, L)
│ │ └──────────────── hour (0-23)
│ └───────────────────── minute (0-59)
└────────────────────────── second (0-59, optional)
Character | Description | Example |
---|---|---|
* | Any value | * * * * * (every minute) |
? | Any value (alias for * ) | ? * * * * (every minute) |
, | Value list separator | 1,2,3 * * * * (1st, 2nd, and 3rd minute) |
- | Range of values | 1-5 * * * * (every minute from 1 through 5) |
/ | Step values | */5 * * * * (every 5th minute) |
L | Last day of month/week | 0 0 L * * (midnight on last day of month) |
# | Nth day of month | 0 0 * * 1#1 (first Monday of month) |
H | Randomized value | H * * * * (every n minute where n is randomly picked within [0, 59]) |
Expression | Description | Equivalent |
---|---|---|
@yearly | Once a year at midnight of January 1 | 0 0 0 1 1 * |
@monthly | Once a month at midnight of first day | 0 0 0 1 * * |
@weekly | Once a week at midnight on Sunday | 0 0 0 * * 0 |
@daily | Once a day at midnight | 0 0 0 * * * |
@hourly | Once an hour at the beginning of the hour | 0 0 * * * * |
@minutely | Once a minute | 0 * * * * * |
@secondly | Once a second | * * * * * * |
@weekdays | Every weekday at midnight | 0 0 0 * * 1-5 |
@weekends | Every weekend at midnight | 0 0 0 * * 0,6 |
Field | Values | Special Characters | Aliases |
---|---|---|---|
second | 0-59 | * ? , - / H | |
minute | 0-59 | * ? , - / H | |
hour | 0-23 | * ? , - / H | |
day of month | 1-31 | * ? , - / H L | |
month | 1-12 | * ? , - / H | JAN -DEC |
day of week | 0-7 | * ? , - / H L # | SUN -SAT (0 or 7 is Sunday) |
Option | Type | Description |
---|---|---|
currentDate | Date | string | number | Current date. Defaults to current local time in UTC |
endDate | Date | string | number | End date of iteration range. Sets iteration range end point |
startDate | Date | string | number | Start date of iteration range. Set iteration range start point |
tz | string | Timezone (e.g., 'Europe/London') |
hashSeed | string | A seed to be used in conjunction with the H special character |
strict | boolean | Enable strict mode validation |
When using string dates, the following formats are supported:
1import { CronExpressionParser } from 'cron-parser'; 2 3try { 4 const interval = CronExpressionParser.parse('*/2 * * * *'); 5 6 // Get next date 7 console.log('Next:', interval.next().toString()); 8 // Get next 3 dates 9 console.log( 10 'Next 3:', 11 interval.take(3).map((date) => date.toString()), 12 ); 13 14 // Get previous date 15 console.log('Previous:', interval.prev().toString()); 16} catch (err) { 17 console.log('Error:', err.message); 18}
1import { CronExpressionParser } from 'cron-parser'; 2 3const options = { 4 currentDate: '2023-01-01T00:00:00Z', 5 endDate: '2024-01-01T00:00:00Z', 6 tz: 'Europe/London', 7}; 8 9try { 10 const interval = CronExpressionParser.parse('0 0 * * *', options); 11 console.log('Next:', interval.next().toString()); 12} catch (err) { 13 console.log('Error:', err.message); 14}
For working with crontab files, use the CronFileParser:
1import { CronFileParser } from 'cron-parser'; 2 3// Async file parsing 4try { 5 const result = await CronFileParser.parseFile('/path/to/crontab'); 6 console.log('Variables:', result.variables); 7 console.log('Expressions:', result.expressions); 8 console.log('Errors:', result.errors); 9} catch (err) { 10 console.log('Error:', err.message); 11} 12 13// Sync file parsing 14try { 15 const result = CronFileParser.parseFileSync('/path/to/crontab'); 16 console.log('Variables:', result.variables); 17 console.log('Expressions:', result.expressions); 18 console.log('Errors:', result.errors); 19} catch (err) { 20 console.log('Error:', err.message); 21}
In several implementations of CRON, it's ambiguous to specify both the Day Of Month and Day Of Week parameters simultaneously, as it's unclear which one should take precedence. Despite this ambiguity, this library allows both parameters to be set by default, although the resultant behavior might not align with your expectations.
To resolve this ambiguity, you can activate the strict mode of the library. When strict mode is enabled, the library enforces several validation rules:
These validations help ensure that your cron expressions are unambiguous and correctly formatted.
1import { CronExpressionParser } from 'cron-parser'; 2 3// This will throw an error in strict mode because it uses both dayOfMonth and dayOfWeek 4const options = { 5 currentDate: new Date('Mon, 12 Sep 2022 14:00:00'), 6 strict: true, 7}; 8 9try { 10 // This will throw an error in strict mode 11 CronExpressionParser.parse('0 0 12 1-31 * 1', options); 12} catch (err) { 13 console.log('Error:', err.message); 14 // Error: Cannot use both dayOfMonth and dayOfWeek together in strict mode! 15} 16 17// This will also throw an error in strict mode because it has fewer than 6 fields 18try { 19 CronExpressionParser.parse('0 20 15 * *', { strict: true }); 20} catch (err) { 21 console.log('Error:', err.message); 22 // Error: Invalid cron expression, expected 6 fields 23}
The library supports parsing the range 0L - 7L
in the weekday
position of the cron expression, where the L
means "last occurrence of this weekday for the month in progress".
For example, the following expression will run on the last Monday of the month at midnight:
1import { CronExpressionParser } from 'cron-parser'; 2 3// Last Monday of every month at midnight 4const lastMonday = CronExpressionParser.parse('0 0 0 * * 1L'); 5 6// You can also combine L expressions with other weekday expressions 7// This will run every Monday and the last Wednesday of the month 8const mixedWeekdays = CronExpressionParser.parse('0 0 0 * * 1,3L'); 9 10// Last day of every month 11const lastDay = CronExpressionParser.parse('0 0 L * *');
1import { CronExpressionParser } from 'cron-parser'; 2 3const interval = CronExpressionParser.parse('0 */2 * * *'); 4 5// Using for...of 6for (const date of interval) { 7 console.log('Iterator value:', date.toString()); 8 if (someCondition) break; 9} 10 11// Using take() for a specific number of iterations 12const nextFiveDates = interval.take(5); 13console.log( 14 'Next 5 dates:', 15 nextFiveDates.map((date) => date.toString()), 16);
The library provides robust timezone support using Luxon, handling DST transitions correctly:
1import { CronExpressionParser } from 'cron-parser'; 2 3const options = { 4 currentDate: '2023-03-26T01:00:00', 5 tz: 'Europe/London', 6}; 7 8const interval = CronExpressionParser.parse('0 * * * *', options); 9 10// Will correctly handle DST transition 11console.log('Next dates during DST transition:'); 12console.log(interval.next().toString()); 13console.log(interval.next().toString()); 14console.log(interval.next().toString());
You can modify cron fields programmatically using CronFieldCollection.from
and construct a new expression:
1import { CronExpressionParser, CronFieldCollection, CronHour, CronMinute } from 'cron-parser'; 2 3// Parse original expression 4const interval = CronExpressionParser.parse('0 7 * * 1-5'); 5 6// Create new collection with modified fields using raw values 7const modified = CronFieldCollection.from(interval.fields, { 8 hour: [8], 9 minute: [30], 10 dayOfWeek: [1, 3, 5], 11}); 12 13console.log(modified.stringify()); // "30 8 * * 1,3,5" 14 15// You can also use CronField instances 16const modified2 = CronFieldCollection.from(interval.fields, { 17 hour: new CronHour([15]), 18 minute: new CronMinute([30]), 19}); 20 21console.log(modified2.stringify()); // "30 15 * * 1-5"
The CronFieldCollection.from
method accepts either CronField instances or raw values that would be valid for creating new CronField instances. This is particularly useful when you need to modify only specific fields while keeping others unchanged.
The library supports adding jitter to the returned intervals using the H
special character in a field. When H
is specified instead of *
, a random value is used (H
is replaced by 23
, where 23 is picked randomly, within the valid range of the field).
This jitter allows to spread the load when it comes to job scheduling. This feature is inspired by Jenkins's cron syntax.
1import { CronExpressionParser } from 'cron-parser'; 2 3// At 23:<randomized> on every day-of-week from Monday through Friday. 4const interval = CronExpressionParser.parse('H 23 * * 1-5'); 5 6// At <randomized>:30 everyday. 7const interval = CronExpressionParser.parse('30 H * * *'); 8 9// At every minutes of <randomized> hour at <randomized> second everyday. 10const interval = CronExpressionParser.parse('H * H * * *'); 11 12// At every 5th minute starting from a random offset. 13// For example, if the random offset is 3, it will run at minutes 3, 8, 13, 18, etc. 14const interval = CronExpressionParser.parse('H/5 * * * *'); 15 16// At a random minute within the range 0-10 everyday. 17const interval = CronExpressionParser.parse('H(0-10) * * * *'); 18 19// At every 5th minute starting from a random offset within the range 0-4. 20// For example, if the random offset is 2, it will run at minutes 2, 7, 12, 17, etc. 21// The random offset is constrained to be less than the step value. 22const interval = CronExpressionParser.parse('H(0-29)/5 * * * *'); 23 24// At every minute of the third <randomized> day of the month 25const interval = CronExpressionParser.parse('* * * * H#3');
The randomness is seed-able using the hashSeed
option of CronExpressionOptions
:
1import { CronExpressionParser } from 'cron-parser'; 2 3const options = { 4 currentDate: '2023-03-26T01:00:00', 5 hashSeed: 'main-backup', // Generally, hashSeed would be a job name for example 6}; 7 8const interval = CronExpressionParser.parse('H * * * H', options); 9 10console.log(interval.stringify()); // "12 * * * 4" 11 12const otherInterval = CronExpressionParser.parse('H * * * H', options); 13 14// Using the same seed will always return the same jitter 15console.log(otherInterval.stringify()); // "12 * * * 4"
MIT
No vulnerabilities found.
Reason
no binaries found in the repo
Reason
5 commit(s) and 7 issue activity found in the last 90 days -- score normalized to 10
Reason
no dangerous workflow patterns detected
Reason
license file detected
Details
Reason
3 existing vulnerabilities detected
Details
Reason
dependency not pinned by hash detected -- score normalized to 2
Details
Reason
Found 5/30 approved changesets -- score normalized to 1
Reason
detected GitHub workflow tokens with excessive permissions
Details
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
Reason
project is not fuzzed
Details
Reason
branch protection not enabled on development/release branches
Details
Reason
SAST tool is not run on all commits -- score normalized to 0
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