cron-parser

The library supports a standard cron format with an optional second field. The order of fields is:

second (0-59, optional) | minute (0-59) | hour (0-23) | day of month (1-31) | month (1-12) | day of week (0-7, where 0 or 7 is Sunday).

Special Characters

The library manages date ranges automatically to simplify iteration:

1. startDate as fallback: If currentDate is omitted but startDate is provided, startDate becomes the currentDate.
2. Automatic clamping: If currentDate is outside the range defined by startDate and endDate, it is automatically adjusted (clamped) to the nearest bound.
3. Validation during iteration: Even if currentDate is clamped, the library validates bounds during iteration. If .next() would result in a date exceeding endDate, it throws an error: "Out of the time span range".

const options = {
  currentDate: '2022-01-01T00:00:00Z', // Before startDate
  startDate: '2023-01-01T00:00:00Z',
  endDate: '2024-01-01T00:00:00Z',
};
// currentDate will be clamped to startDate (2023-01-01T00:00:00Z) automatically
const interval = CronExpressionParser.parse('0 0 * * *', options);

To prevent load spikes in job scheduling, the library supports the H special character. When H is used instead of *, it is replaced by a randomized value within the valid range of that field. This is inspired by Jenkins's cron syntax.

Supported patterns:

• H: Random value in the field range.
• H/step: Random offset followed by a step (e.g., H/5).
• H(range): Random value within a specific range (e.g., H(0-10)).
• H#n: Random value at the $n^{th}$ occurrence of a specific day (e.g., * * * * H#3).

Seedable Randomness: You can make the jitter deterministic by providing a hashSeed in the CronExpressionOptions. Using the same seed will always produce the same randomized values.

import { CronExpressionParser } from 'cron-parser';

// At 23:<randomized> on every day-of-week from Monday through Friday.
const interval = CronExpressionParser.parse('H 23 * * 1-5');

// At <randomized>:30 everyday.
const interval = CronExpressionParser.parse('30 H * * *');

// At every minutes of <randomized> second everyday.
const interval = CronExpressionParser.parse('H * H * * *');

// At every 5th minute starting from a random offset.
const interval = CronExpressionParser.parse('H/5 * * * *');

// At a random minute within the range 0-10 everyday.
const interval = CronExpressionParser.parse('H(0-10) * * * *');

// At every 5th minute starting from a random offset within the range 0-4.
const interval = CronExpressionParser.parse('H(0-29)/5 * * * *');

// At every minute of the third <randomized> day of the month
const interval = CronExpressionParser.parse('* * * * H#3');

// Seedable randomness
const options = {
  currentDate: '2023-03-26T01:00:00',
  hashSeed: 'main-backup',
};

const interval = CronExpressionParser.parse('H * * * H', options);
console.log(interval.stringify()); // "12 * * * 4"

const otherInterval = CronExpressionParser.parse('H * * * H', options);
// Using the same seed will always return the same jitter
console.log(otherInterval.stringify()); // "12 * * * 4"

The library supports the L character in the weekday position to represent the "last occurrence of this weekday for the month in progress".

• 0L - 7L: Represents the last occurrence of a specific weekday.
• L in the day of month position: Represents the last day of the month.

Example expressions:

• 0 0 0 * * 1L: Last Monday of every month at midnight.
• 0 0 0 * * 1,3L: Every Monday and the last Wednesday of the month.
• 0 0 L * *: Last day of every month.

import { CronExpressionParser } from 'cron-parser';

// Last Monday of every month at midnight
const lastMonday = CronExpressionParser.parse('0 0 0 * * 1L');

// You can also combine L expressions with other weekday expressions
// This will run every Monday and the last Wednesday of the month
const mixedWeekdays = CronExpressionParser.parse('0 0 0 * * 1,3L');

// Last day of every month
const lastDay = CronExpressionParser.parse('0 0 L * *');

By default, the library allows setting both Day of Month and Day of Week simultaneously, which can lead to ambiguous behavior. Activating strict: true in the options object enforces the following validation rules:

1. Day Of Month and Day Of Week: Prevents setting both fields at the same time.
2. Complete Expression: Requires all 6 fields (second, minute, hour, day of month, month, day of week) to be present.
3. Non-empty Expression: Rejects empty expressions that would otherwise default to '0 * * * * *'.

Use this to ensure your cron expressions are unambiguous and correctly formatted.

import { CronExpressionParser } from 'cron-parser';

const options = {
  currentDate: new Date('Mon, 12 Sep 2022 14:00:00'),
  strict: true,
};

try {
  // This will throw an error in strict mode because it uses both dayOfMonth and dayOfWeek
  CronExpressionParser.parse('0 0 12 1-31 * 1', options);
} catch (err) {
  console.log('Error:', err.message);
  // Error: Cannot use both dayOfMonth and dayOfWeek together in strict mode!
}

Pass an options object to CronExpressionParser.parse() to control timezone, date ranges, and validation.

Options:

• currentDate (Date | string | number): The starting point for iteration. Defaults to current local time in UTC. Supported string formats: ISO8601, HTTP/RFC2822, SQL.
• endDate (Date | string | number): Sets the end point of the iteration range.
• startDate (Date | string | number): Sets the start point of the iteration range. If currentDate is not provided, startDate is used as the fallback.
• tz (string): Timezone (e.g., 'Europe/London').
• hashSeed (string): A seed for the H (randomized) special character.
• strict (boolean): Enable strict mode validation.

import { CronExpressionParser } from 'cron-parser';

const options = {
  currentDate: '2023-01-01T00:00:00Z',
  endDate: '2024-01-01T00:00:00Z',
  tz: 'Europe/London',
};

try {
  const interval = CronExpressionParser.parse('0 0 * * *', options);
  console.log('Next:', interval.next().toString());
} catch (err) {
  console.log('Error:', err.message);
}

You can create a new cron expression by modifying specific fields of an existing one using CronFieldCollection.from. This method accepts either CronField instances or raw values (like arrays of numbers) for the fields you wish to change.

This is useful for keeping most of an expression intact while updating specific parts like the hour or minute.

import { CronExpressionParser, CronFieldCollection, CronHour, CronMinute } from 'cron-parser';

// Parse original expression
const interval = CronExpressionParser.parse('0 7 * * 1-5');

// Create new collection with modified fields using raw values
const modified = CronFieldCollection.from(interval.fields, {
  hour: [8],
  minute: [30],
  dayOfWeek: [1, 3, 5],
});

console.log(modified.stringify()); // "30 8 * * 1,3,5"

// You can also use CronField instances
const modified2 = CronFieldCollection.from(interval.fields, {
  hour: new CronHour([15]),
  minute: new CronMinute([30]),
});

console.log(modified2.stringify()); // "30 15 * * 1-5"

Use CronFileParser to parse standard crontab files. It supports both asynchronous and synchronous parsing.

Result Object Fields:

• variables: Extracted variables from the file.
• expressions: Parsed cron expressions.
• errors: Any errors encountered during parsing.

import { CronFileParser } from 'cron-parser';

// Async file parsing
try {
  const result = await CronFileParser.parseFile('/path/to/crontab');
  console.log('Variables:', result.variables);
  console.log('Expressions:', result.expressions);
  console.log('Errors:', result.errors);
} catch (err) {
  console.log('Error:', err.message);
}

// Sync file parsing
try {
  const result = CronFileParser.parseFileSync('/path/to/crontab');
  console.log('Variables:', result.variables);
  console.log('Expressions:', result.expressions);
  console.log('Errors:', result.errors);
} catch (err) {
  console.log('Error:', err.message);
}