Cron Reference

⏲️ Standard cron expression tools.

Usage

📦 Node

Install @lou.codes/cron as a dependency:

pnpm add @lou.codes/cron
# or
npm install @lou.codes/cron
# or
yarn add @lou.codes/cron

Import it and use it:

import { parse, stringify } from "@lou.codes/cron";

const cron = parse("1-2,3,4 * 2 8,9 1");
/*
	{
		minutes: [{ from: 1, to: 2 }, 3, 4],
		hours: "*",
		dayOfMonth: 2,
		month: [8, 9],
		dayOfWeek: 1
	}
*/

stringify(cron); // "1-2,3,4 * 2 8,9 1"

// Also works with partials:
stringify({ hours: 13 }); // "* 13 * * *"

// Only parses with valid dates:
parse("* * 31 2 *"); // undefined because 2/31 is invalid

🦕 Deno

Import @lou.codes/cron using the npm: prefix, and use it directly:

import { parse, stringify } from "@lou.codes/cron";

const cron = parse("1-2,3,4 * 2 8,9 1");
/*
	{
		minutes: [{ from: 1, to: 2 }, 3, 4],
		hours: "*",
		dayOfMonth: 2,
		month: [8, 9],
		dayOfWeek: 1
	}
*/

stringify(cron); // "1-2,3,4 * 2 8,9 1"

// Also works with partials:
stringify({ hours: 13 }); // "* 13 * * *"

// Only parses with valid dates:
parse("* * 31 2 *"); // undefined because 2/31 is invalid

🌎 Browser

Import @lou.codes/cron using esm.sh, and use it directly:

<script type="module">
	import { parse, stringify } from "https://esm.sh/@lou.codes/cron";

	const cron = parse("1-2,3,4 * 2 8,9 1");
	/*
	{
		minutes: [{ from: 1, to: 2 }, 3, 4],
		hours: "*",
		dayOfMonth: 2,
		month: [8, 9],
		dayOfWeek: 1
	}
*/

	stringify(cron); // "1-2,3,4 * 2 8,9 1"

	// Also works with partials:
	stringify({ hours: 13 }); // "* 13 * * *"

	// Only parses with valid dates:
	parse("* * 31 2 *"); // undefined because 2/31 is invalid
</script>

Useful links

• 📝 Documentation: TypeDoc generated documentation.
• ⏳ Changelog: List of changes between versions.
• ✅ Tests Coverage: Coveralls page with tests coverage.

To do

Soon a human readable parser will be added, so we can do stuff like:

readable("* * * * *"); // "Every minute"
readable("5 * * * *"); // "Minute 5 of every hour"
readable("* 5 * * *"); // "Every minute at 5 AM"
readable("* * 5 * *"); // "Every minute at the 5th day of every month"
readable("* * * 5 *"); // "Every minute in May"
readable("* * * * 5"); // "Every minute on Friday"
readable("5 5 5 5 5"); // "At 5:05 AM, the 5th day of May on Friday"

Cron Object

CronObject

type CronObject: object;

Object that represents the 5 cron expression fields.

See

• Field
• MonthValue

Type declaration

Member	Type
dayOfMonth	Field<DayOfMonth>
dayOfWeek	Field<DayOfWeek>
hour	Field<Hours>
minute	Field<Minutes>
month	Field<MonthValue>

View source

---

Field<Value>

type Field<Value>: AllToken | ListField<Value> | ValueOrRangeField<Value>;

Union of AllToken, ValueOrRangeField and ListField that represents a field in a cron expression.

See

• AllToken
• ValueOrRangeField
• ListField

Type parameters

Type parameter
Value extends number

View source

---

ListField<Value>

type ListField<Value>: ReadOnlyArray<ValueOrRangeField<Value>>;

Type that represents a list of values for a cron object field.

See

ValueOrRangeField

Type parameters

Type parameter
Value extends number

View source

---

MonthValue

type MonthValue: Range<1, 12>;

Type that represents values from 1 to 12 for the month cron field.

View source

---

RangeField<Value>

type RangeField<Value>: object;

Type that represents a range of values for a cron object field.

Type parameters

Type parameter
Value extends number

Type declaration

Member	Type	Description
from	Value	Start of the range, must be lower than to.
to	Value	End of the range, must be higher than from.

View source

---

ValueOrRangeField<Value>

type ValueOrRangeField<Value>: RangeField<Value> | Value;

Union of a set of numbers and a RangeField with that same set of numbers.

Type parameters

Type parameter
Value extends number

View source

---

ALL_TOKEN

const ALL_TOKEN: "*" = "*";

Token that represents “all” in a cron expression.

View source

---

DAY_OF_MONTH_NAME

const DAY_OF_MONTH_NAME: "dayOfMonth" = "dayOfMonth";

Name of a day of month field in the object representation of a cron expression.

View source

---

DAY_OF_WEEK_NAME

const DAY_OF_WEEK_NAME: "dayOfWeek" = "dayOfWeek";

Name of a day of week field in the object representation of a cron expression.

View source

---

FROM_NAME

const FROM_NAME: "from" = "from";

Range field from name.

View source

---

HOUR_NAME

const HOUR_NAME: "hour" = "hour";

Name of a hour field in the object representation of a cron expression.

View source

---

MINUTE_NAME

const MINUTE_NAME: "minute" = "minute";

Name of a minute field in the object representation of a cron expression.

View source

---

MONTH_NAME

const MONTH_NAME: "month" = "month";

Name of a month field in the object representation of a cron expression.

View source

---

TO_NAME

const TO_NAME: "to" = "to";

Range field to name.

View source

---

stringify()

function stringify(
	cron: Partial<CronObject>,
): undefined | `${string} ${string} ${string} ${string} ${string}`;

Takes a cron object and returns a sting expression.

Parameters

Parameter	Type	Description
cron	Partial<CronObject>	Cron object.

Returns

undefined | `${string} ${string} ${string} ${string} ${string}`

Cron string expression.

Example

stringify({}); // "* * * * *"
stringify({ dayOfMonth: 13, month: 10 }); // "* * 13 10 *"
stringify({
	minute: 5,
	dayOfMonth: [10, 11, 13],
	month: { from: 1, to: 10 },
}); // "5 * 10,11,13 1-10 *"
stringify({ month: 2, dayOfMonth: 31 }); // undefined

See

• fieldNamesTuple
• stringifyField
• isValidExpression

View source

---

stringifyField()

function stringifyField(field: Field<number>): FieldString;

Takes a cron object and returns a string expression.

Parameters

Parameter	Type	Description
field	Field<number>	Cron object field.

Returns

FieldString

Cron string field.

Example

stringifyField("*"); // "*"
stringifyField(13); // "13"
stringifyField([10, 11, 13]); // "10,11,13"
stringifyField({ from: 1, to: 10 }); // "1-10"

See

• isAllToken
• stringifyList
• stringifyRange

View source

---

stringifyList()

function stringifyList(
	field: Readonly<Field<number>>,
): Maybe<`${string},${number}` | `${string},${number}-${number}`>;

Turns cron list into a string.

Parameters

Parameter	Type	Description
field	Readonly<Field<number>>	List cron object field

Returns

Maybe<`${string},${number}` | `${string},${number}-${number}`>

String list or undefined if it isn’t a list.

Example

stringifyList([10, 11, 13]); // "10,11,13"

See

• isListField
• stringifyRange

View source

---

stringifyRange()

function stringifyRange<Predicated>(
	field: Readonly<Field<Predicated>>,
): Maybe<`${number}-${number}`>;

Turn a cron range into a string.

Type parameters

Type parameter
Predicated extends number

Parameters

Parameter	Type	Description
field	Readonly<Field<Predicated>>	Cron field to turn into a string.

Returns

Maybe<`${number}-${number}`>

String ranged of undefined if it isn’t a range object.

Example

parseRange({ from: 1, to: 13 }); // "1-13"

See

isRangeField

View source

Cron String

CronString

type CronString: `${string} ${string} ${string} ${string} ${string}`;

String cron expression.

View source

---

FieldString

type FieldString: AllToken | ListString | ValueOrRangeString;

Union of AllToken, ValueOrRangeString and ListString that represents a field in a cron expression.

See

• AllToken
• ValueOrRangeString
• ListString

View source

---

ListString

type ListString: `${string}${ListExpressionSeparatorToken}${ValueOrRangeString}`;

Type that represents a list of values for a cron string field.

See

ValueOrRangeString

View source

---

RangeString

type RangeString: `${number}${RangeExpressionSeparatorToken}${number}`;

Type that represents a range of values for a cron string field.

View source

---

ValueOrRangeString

type ValueOrRangeString: RangeString | `${number}`;

Union of a set any number and a RangeString.

View source

---

ALL_TOKEN

const ALL_TOKEN: "*" = "*";

Token that represents “all” in a cron expression.

View source

---

LIST_EXPRESSION_SEPARATOR_TOKEN

const LIST_EXPRESSION_SEPARATOR_TOKEN: "," = ",";

Token to separate list items in a cron expression.

View source

---

RANGE_EXPRESSION_SEPARATOR_TOKEN

const RANGE_EXPRESSION_SEPARATOR_TOKEN: "-" = "-";

Token to separate range values in a cron expression.

View source

---

normalizeMap

const normalizeMap: object;

Map from 3 letter aliases to their respective number representations.

Type declaration

Member	Type	Value	Description
apr	4	4	April number representation
aug	8	8	August number representation
dec	12	12	December number representation
feb	2	2	February number representation
fri	5	5	Friday number representation
jan	1	1	January number representation
jul	7	7	July number representation
jun	6	6	June number representation
mar	3	3	March number representation
may	5	5	May number representation
mon	1	1	Monday number representation
nov	11	11	November number representation
oct	10	10	October number representation
sat	6	6	Saturday number representation
sep	9	9	September number representation
sun	0	0	Sunday number representation
thu	4	4	Thursday number representation
tue	2	2	Tuesday number representation
wed	3	3	Wednesday number representation

View source

---

isValidExpression()

function isValidExpression(
	string: string,
): string is `${string} ${string} ${string} ${string} ${string}`;

Validates if a string is a cron expression.

Parameters

Parameter	Type
string	string

Returns

string is `${string} ${string} ${string} ${string} ${string}`

See

View source

---

normalizeAliases()

function normalizeAliases(expression: string): FieldString;

Normalizes day and month 3 letter aliases into their number counterparts.

Parameters

Parameter	Type	Description
expression	string	String expression.

Returns

FieldString

Normalized expression

Example

normalizeAliases("* * 13 oct fri"); // "* * 13 10 5"

View source

---

parse()

function parse(
	expression: `${string} ${string} ${string} ${string} ${string}`,
): Maybe<CronObject>;

Parses a cron expression into an object representation.

Parameters

Parameter	Type	Description
expression	`${string} ${string} ${string} ${string} ${string}`	Cron expression to be parsed.

Returns

Maybe<CronObject>

Object representing that expression or undefined if expression is invalid.

Example

parse("* * * * *"); // { minute: "*", hour: "*", dayOfMonth: "*", month: "*", dayOfWeek: "*" }
parse("* * 13 10 *"); // { minute: "*", hour: "*", dayOfMonth: 13, month: 10, dayOfWeek: "*" }
parse("5 * 10,11,13 1-10 *"); // { minute: 5, hour: "*", dayOfMonth: [10, 11, 13], month: { from: 1, to: 10 }, dayOfWeek: "*" }
parse("* * 31 2 *"); // undefined
parse("nope"); // undefined

See

• parseFieldTuplesMap
• normalizeAliases

View source

---

parseField()

function parseField(
	field: string,
): "*" | RangeField<number> | ListField<number> | Maybe<number>;

Parses a cron field.

Parameters

Parameter	Type	Description
field	string	Cron field value (should be validated before this).

Returns

"*" | RangeField<number> | ListField<number> | Maybe<number>

Parsed field.

Example

parseField("*"); // "*"
parseField("13"); // 13
parseField("10,11,13"); // [10, 11, 13]
parseField("1-10"); // { from: 1, to: 10 }

See

• isAllToken
• parseList
• parseRange

View source

---

parseFieldTuplesMap()

function parseFieldTuplesMap(
	iterable: Readonly<Iterable<readonly [keyof CronObject, string], any, any>>,
): Readonly<
	IterableIterator<
		readonly [
			"minute" | "hour" | "dayOfMonth" | "month" | "dayOfWeek",
			"*" | RangeField<number> | ListField<number> | Maybe<number>,
		],
		any,
		any
	>
>;

Given an iterable of tuples with the name of a field and a field value, run each field through parseField.

Parameters

Parameter	Type
iterable	Readonly<Iterable<readonly [keyof CronObject, string], any, any>>

Returns

Readonly<IterableIterator<readonly [ | "minute" | "hour" | "dayOfMonth" | "month" | "dayOfWeek", "*" | RangeField<number> | ListField<number> | Maybe<number>], any, any>>

Example

parseFieldTuplesMap([["minute", "*"]]); // [["minute", "*"]]
parseFieldTuplesMap([["minute", "13"]]); // [["minute", 13]]
parseFieldTuplesMap([["minute", "10,11,13"]]); // [["minute", [10, 11, 13]]]
parseFieldTuplesMap([["minute", "1-10"]]); // [["minute", { from: 1, to: 10 }]]

See

parseField

View source

---

parseList()

function parseList<Predicated>(value: string): Maybe<ListField<Predicated>>;

Parses a cron list into an array.

Type parameters

Type parameter
Predicated extends number

Parameters

Parameter	Type	Description
value	string	String that might be a list.

Returns

Maybe<ListField<Predicated>>

Parsed list of undefined if it isn’t a list string.

Example

parseList("10,11,13"); // [10, 11, 13]

See

• isListString
• parseRange

View source

---

parseListMap()

function parseListMap(
	iterable: Readonly<Iterable<string, any, any>>,
): Readonly<IterableIterator<RangeField<number> | Maybe<number>, any, any>>;

Map to parse cron list items (can be either a range or a number).

Parameters

Parameter	Type
iterable	Readonly<Iterable<string, any, any>>

Returns

Readonly<IterableIterator<RangeField<number> | Maybe<number>, any, any>>

Example

parseListMap(["1", "05", "13", "5-13", "13-13", "13-5", "99"]);
// [1, 5, 13, { from: 5, to: 13 }, 13, undefined, undefined]

See

• parseNumber
• parseRange

View source

---

parseNumber()

function parseNumber<Predicated>(value: string): Maybe<Predicated>;

Parses a cron list into an array.

Type parameters

Type parameter
Predicated extends number

Parameters

Parameter	Type	Description
value	string	String that might be a list.

Returns

Maybe<Predicated>

Parsed list of undefined if it isn’t a list string.

Example

parseNumber("5"); // 5
parseNumber("13"); // 13
parseNumber("59"); // 59
parseNumber("60"); // undefined (60 isn't valid for any cron field)

View source

---

parseNumberMap()

function parseNumberMap<Predicated>(
	iterable: Readonly<Iterable<string, any, any>>,
): Readonly<IterableIterator<Maybe<Predicated>, any, any>>;

Maps given iterable through parseNumber.

Type parameters

Type parameter
Predicated extends number

Parameters

Parameter	Type
iterable	Readonly<Iterable<string, any, any>>

Returns

Readonly<IterableIterator<Maybe<Predicated>, any, any>>

Example

parseNumberMap(["05"]); // [5]
parseNumberMap(["13"]); // [13]
parseNumberMap(["59"]); // [59]
parseNumberMap(["60"]); // [undefined] (60 isn't valid for any cron field)

See

parseNumber

View source

---

parseNumberMatch()

function parseNumberMatch(text: string): boolean;

Matches only valid number values for a cron expression (from 0 or 00 to 59).

Parameters

Parameter	Type
text	string

Returns

boolean

Example

parseNumberMatch("13"); // true
parseNumberMatch("05"); // true
parseNumberMatch("60"); // false
parseNumberMatch("foo"); // false

See

paddedRegExp

View source

---

parseRange()

function parseRange<Predicated>(
	value: string,
): Maybe<Predicated | RangeField<Predicated>>;

Parses a cron range into an object.

Type parameters

Type parameter
Predicated extends number

Parameters

Parameter	Type	Description
value	string	String that might be a range.

Returns

Maybe<Predicated | RangeField<Predicated>>

Parsed ranged of undefined if it isn’t a range string.

Example

parseRange("1-13"); // { from: 1, to: 13 }
parseRange("13-13"); // 13 (normalized)
parseRange("13-1"); // undefined

See

• isRangeString
• zipRangeNames
• parseNumberMap

View source

Internal

fieldNamesTuple

const fieldNamesTuple: readonly [
	"minute",
	"hour",
	"dayOfMonth",
	"month",
	"dayOfWeek",
];

Field names in order.

View source

---

compareField()

function compareField(
	value: number,
	field: ValueOrRangeField<number> | ListField<number>,
): boolean;

Checks if given value is included in given field.

Parameters

Parameter	Type	Description
value	number	Value to compare.
field	ValueOrRangeField<number> | ListField<number>	Field to compare.

Returns

boolean

true if value is included in the given field, false if it isn’t.

Example

compareField(13, 13); // true
compareField(13, 99); // false
compareField(13, { from: 0, to: 99 }); // true
compareField(13, { from: 0, to: 10 }); // false
compareField(13, [10, 13]); // true
compareField(13, [10, 11, 12]); // false
compareField(13, [10, { from: 11, to: 99 }]); // true
compareField(13, [5, { from: 10, to: 12 }]); // false

View source

---

compareRangeOrValue()

function compareRangeOrValue(
	value: number,
): (valueOrRange: ValueOrRangeField<number>) => boolean;

Compares value to a ValueOrRangeField.

Parameters

Parameter	Type	Description
value	number	Value to be compared.

Returns

Function

Curried function expecting a ValueOrRangeField.

Parameters

Parameter	Type
valueOrRange	ValueOrRangeField<number>

Returns

boolean

Example

compareRangeOrValue(13)({ from: 0, to: 99 }); // true
compareRangeOrValue(13)({ from: 0, to: 10 }); // false
compareRangeOrValue(13)(13); // true
compareRangeOrValue(13)(14); // false

View source

---

dateInCron()

function dateInCron(cron: CronObject): (date: Readonly<Date>) => boolean;

Check if given cron expression object includes given date.

Parameters

Parameter	Type	Description
cron	CronObject	Cron object.

Returns

Function

Curried function with cron in context.

Parameters

Parameter	Type
date	Readonly<Date>

Returns

boolean

View source

---

zipRangeNames()

function zipRangeNames<ItemSecond>(
	iterableSecond: Readonly<Iterable<ItemSecond, any, any>>,
): Readonly<IterableIterator<readonly ["from" | "to", ItemSecond], any, any>>;

Zips “from” and “to”.

Type parameters

Type parameter
ItemSecond

Parameters

Parameter	Type
iterableSecond	Readonly<Iterable<ItemSecond, any, any>>

Returns

Readonly<IterableIterator<readonly ["from" | "to", ItemSecond], any, any>>

View source

Other

parseDecimalMap()

function parseDecimalMap<Predicated>(
	iterable: Readonly<Iterable<string, any, any>>,
): Readonly<IterableIterator<Maybe<Predicated>, any, any>>;

Type parameters

Type parameter
Predicated extends number

Parameters

Parameter	Type
iterable	Readonly<Iterable<string, any, any>>

Returns

Readonly<IterableIterator<Maybe<Predicated>, any, any>>

Deprecated

Use parseNumberMap instead.

View source

Predicate

isAllToken()

function isAllToken(actual: unknown): actual is "*";

Predicate to check if the given value is "*".

Parameters

Parameter	Type
actual	unknown

Returns

actual is "*"

View source

---

isListField()

function isListField(value: Field<number>): value is ListField<number>;

Predicate checking if given value is a ListField.

Parameters

Parameter	Type
value	Field<number>

Returns

value is ListField<number>

See

• ListField
• isRangeField

View source

---

isListString()

function isListString(
	value: string,
): value is `${string},${number}` | `${string},${number}-${number}`;

Predicate checking if given value is a ListString.

Parameters

Parameter	Type
value	string

Returns

value is `${string},${number}` | `${string},${number}-${number}`

See

• ListString
• LIST_EXPRESSION_SEPARATOR_TOKEN

View source

---

isNumberString()

function isNumberString<Value>(input: string): input is `${Value}`;

Predicate checking if given value is a number.

Type parameters

Type parameter
Value extends number

Parameters

Parameter	Type
input	string

Returns

input is `${Value}`

View source

---

isRangeField()

function isRangeField(value: unknown): value is RangeField<number>;

Predicate checking if given value is a cron object range (RangeField).

Parameters

Parameter	Type
value	unknown

Returns

value is RangeField<number>

See

RangeField

View source

---

isRangeString()

function isRangeString(value: string): value is `${number}-${number}`;

Predicate checking if given value is a cron string range (RangeString).

Parameters

Parameter	Type
value	string

Returns

value is `${number}-${number}`

See

• RangeString
• rangeStringMatch

View source

Regular Expression

cronRegExp

const cronRegExp: "^\s(?!(?:\S+\s+){2}(?:(?:(?:301?|(?:(?:301?,)+301?))\s+(?:(?:0?2|feb)(?:-(?:0?2|feb))?|(?:(?:(?:0?2|feb)(?:-(?:0?2|feb))?,)+(?:0?2|feb)(?:-(?:0?2|feb))?)))|(?:(?:31(?:-31)?|(?:(?:31(?:-31)?,)+31(?:-31)?))\s+(?:(?:0?[2469]|11|feb|apr|jun|sep|nov)|(?:(?:(?:0?[2469]|11|feb|apr|jun|sep|nov),)+(?:0?[2469]|11|feb|apr|jun|sep|nov)))))\s+\S+)(?<minute>*|(?:(?:0?\d|[1-5]\d)(?:-(?:0?\d|[1-5]\d))?|(?:(?:(?:0?\d|[1-5]\d)(?:-(?:0?\d|[1-5]\d))?,)+(?:0?\d|[1-5]\d)(?:-(?:0?\d|[1-5]\d))?)))\s+(?<hour>*|(?:(?:0?\d|1\d|20-3)(?:-(?:0?\d|1\d|20-3))?|(?:(?:(?:0?\d|1\d|20-3)(?:-(?:0?\d|1\d|20-3))?,)+(?:0?\d|1\d|20-3)(?:-(?:0?\d|1\d|20-3))?)))\s+(?<dayOfMonth>*|(?:(?:0?[1-9]|[12]\d|3[01])(?:-(?:0?[1-9]|[12]\d|3[01]))?|(?:(?:(?:0?[1-9]|[12]\d|3[01])(?:-(?:0?[1-9]|[12]\d|3[01]))?,)+(?:0?[1-9]|[12]\d|3[01])(?:-(?:0?[1-9]|[12]\d|3[01]))?)))\s+(?<month>*|(?:(?:jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec|0?[1-9]|1[0-2])(?:-(?:jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec|0?[1-9]|1[0-2]))?|(?:(?:(?:jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec|0?[1-9]|1[0-2])(?:-(?:jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec|0?[1-9]|1[0-2]))?,)+(?:jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec|0?[1-9]|1[0-2])(?:-(?:jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec|0?[1-9]|1[0-2]))?)))\s+(?<dayOfWeek>*|(?:(?:sun|mon|tue|wed|thu|fri|sat|0?[0-6])(?:-(?:sun|mon|tue|wed|thu|fri|sat|0?[0-6]))?|(?:(?:(?:sun|mon|tue|wed|thu|fri|sat|0?[0-6])(?:-(?:sun|mon|tue|wed|thu|fri|sat|0?[0-6]))?,)+(?:sun|mon|tue|wed|thu|fri|sat|0?[0-6])(?:-(?:sun|mon|tue|wed|thu|fri|sat|0?[0-6]))?)))\s$";

Regular expression to test for valid cron expressions.

Remarks

• We allow 0 or more whitespace before and after the expression.
• Negative lookahead to avoid impossible matches:
  • 30 or 31 of February (Any combination like 30,31; 30-31; 30-30; etc.)
  • 31 of February, April, Jun, September or November (also any combination).
• Then we start capturing each field in a named group (separated with any amount of whitespace): - minute: Digits from 0 to 59 (including padded like 05). - hour: Digits from 0 to 23 (also including padded). - dayOfMonth: Digits from 0 to 31 (also including padded). - month: Digits from 1 to 12 (also including padded, and 3 letter aliases like oct). - dayOfWeek: Digits from 0 to 6 (all padded, and also including 3 letter aliases like fri).

Example

new RegExp(cronRegExp).test("* * * * *"); // true
new RegExp(cronRegExp).test("nope"); // false
new RegExp(cronRegExp).test("* * 31 2 *"); // false
new RegExp(cronRegExp).test("* * 31 feb,4,6 *"); // false
new RegExp(cronRegExp).test("* * 31 feb,mar *"); // true
new RegExp(cronRegExp).test("1 2 3 4 5"); // true

View source

---

fieldRegExp()

function fieldRegExp<Name, Value>(name: Name, value: Value): (?<${Name}>*|(?:${Value}(?:-${Value})?|(?:(?:${Value}(?:-${Value})?,)+${Value}(?:-${Value})?)))

Regular expression to match a cron expression field.

Type parameters

Type parameter
Name extends string
Value extends string

Parameters

Parameter	Type	Description
name	Name	Named group name.
value	Value	Possible values the expression can have.

Returns

(?<${Name}>\*|(?:${Value}(?:-${Value})?|(?:(?:${Value}(?:-${Value})?,)+${Value}(?:-${Value})?)))

Named group capturing the given value by itself, in a list or range.

Example

fieldRegExp("example", 13); // "(?<example>\\*|(?:13(?:-13)?|(?:(?:13(?:-13)?,)+13(?:-13)?)))"

View source

---

paddedRegExp()

function paddedRegExp<Value>(value: Value): `0?${Value}`;

Regular expression to match field with an optional 0 to it’s left.

Type parameters

Type parameter
Value extends string | number

Parameters

Parameter	Type	Description
value	Value	Value to pad.

Returns

`0?${Value}`

RegExp to match value with padded 0.

Example

paddedRegExp(5); // "0?5"

View source

---

rangeStringMatch()

function rangeStringMatch(text: string): boolean;

Regular expression to test if given string is a range.

Parameters

Parameter	Type
text	string

Returns

boolean

View source

---

valueOrListRegExp()

function valueOrListRegExp<Value>(
	value: Value,
): `(?:${Value}|(?:(?:${Value},)+${Value}))`;

Regular expression to match lists.

Type parameters

Type parameter
Value extends string | number

Parameters

Parameter	Type	Description
value	Value	Value to match by itself or as a list.

Returns

`(?:${Value}|(?:(?:${Value},)+${Value}))`

RegExp to match value or list.

Example

valueOrListRegExp(13); // "(?:13|(?:(?:13,)+13))"

View source

---

valueOrRangeRegExp()

function valueOrRangeRegExp<Value>(value: Value): `${Value}(?:-${Value})?`;

Regular expression to match values or ranges.

Type parameters

Type parameter
Value extends string | number

Parameters

Parameter	Type	Description
value	Value	Value to match by itself or as a range.

Returns

`${Value}(?:-${Value})?`

RegExp to match value or range.

Example

valueOrRangeRegExp(13); // "13(?:-13)?"

View source

---

valueRangeOrListRegExp()

function valueRangeOrListRegExp<Value>(
	value: Value,
): `(?:${Value}(?:-${Value})?|(?:(?:${Value}(?:-${Value})?,)+${Value}(?:-${Value})?))`;

Regular expression to match values, ranges or lists.

Type parameters

Type parameter
Value extends string | number

Parameters

Parameter	Type	Description
value	Value	Value to match by itself, as a range or as a list.

Returns

`(?:${Value}(?:-${Value})?|(?:(?:${Value}(?:-${Value})?,)+${Value}(?:-${Value})?))`

RegExp to match value, range or list.

Example

valueRangeOrListRegExp(13); // "(?:13(?:-13)?|(?:(?:13(?:-13)?,)+13(?:-13)?))"

View source

Token

AllToken

type AllToken: typeof ALL_TOKEN;

Type to represent the “all” token ("*").

View source

---

ListExpressionSeparatorToken

type ListExpressionSeparatorToken: typeof LIST_EXPRESSION_SEPARATOR_TOKEN;

Type to represent the “list expression separator” token (",").

View source

---

RangeExpressionSeparatorToken

type RangeExpressionSeparatorToken: typeof RANGE_EXPRESSION_SEPARATOR_TOKEN;

Type to represent the “range expression separator” token ("-").

View source

Util

nextDate()

function nextDate(
	date: Readonly<Date>,
): (
	cron:
		| `${string} ${string} ${string} ${string} ${string}`
		| Partial<CronObject>,
) => Maybe<Date>;

Get next ISO date string for the given date and the given cron expression.

Parameters

Parameter	Type	Description
date	Readonly<Date>	Base date to get the next date from.

Returns

Function

Curried function with date set.

Parameters

Parameter	Type
cron	`${string} ${string} ${string} ${string} ${string}` | Partial<CronObject>

Returns

Maybe<Date>

Example

nextDate(new Date("1989-10-13T10:15:00.000"))("* * * * *"); // Date("1989-10-13T10:16:00.000")

View source

---

nextDates()

function nextDates(
	date: Readonly<Date>,
): (
	cron:
		| `${string} ${string} ${string} ${string} ${string}`
		| Partial<CronObject>,
) => Readonly<IterableIterator<Date, any, any>>;

Get next ISO date iterator for the given date and the given cron expression.

Parameters

Parameter	Type	Description
date	Readonly<Date>	Base date to get the next date from.

Returns

Function

Curried function with date set.

Parameters

Parameter	Type
cron	`${string} ${string} ${string} ${string} ${string}` | Partial<CronObject>

Returns

Readonly<IterableIterator<Date, any, any>>

Example

take(2)(nextDates(new Date("1989-10-13T10:15:00.000Z"))("* * * * *"));
// [Date("1989-10-13T10:16:00.000"), Date("1989-10-13T10:17:00.000Z")]

View source