Class: Cron

A cron expression, as @Schedule uses it: second minute hour day-of-month month day-of-week, the second optional (0 when omitted). Each field accepts * (or ?), values, ranges (1-5), steps (*/15, 10/5, 1-30/2) and lists (1,15); the months and the days of the week also accept their English three-letter names (jan, mon), and the day of the week 7 is Sunday like 0. The macros @yearly, @annually, @monthly, @weekly, @daily, @midnight and @hourly are accepted. When both the day of the month and the day of the week are restricted, a day matching either of them matches.

Example

import {Cron} from 'lakutata/com/entrypoint'

//At 09:30 on the weekdays, in Shanghai
const cron: Cron = new Cron('30 9 * * mon-fri', 'Asia/Shanghai')
const next: Date | undefined = cron.next(new Date('2026-01-02T12:00:00Z'))
console.log(next?.toISOString()) //2026-01-05T01:30:00.000Z
console.log(new Cron('0 0 30 2 *').next()) //undefined: February has no 30th

Constructors

Constructor

new Cron(expression, timezone?): Cron

Parse a cron expression.

Parameters

expression

string

The expression, 5 or 6 fields separated by spaces, or a macro (case-insensitive).

timezone?

string

The IANA time zone the expression's times are in (Asia/Shanghai); the local time zone when omitted.

Returns

Cron

Throws

When the expression does not have 5 or 6 fields, or a field has a value out of its range, a reversed range or an invalid step.

Throws

When the time zone is unknown.

Properties

expression

readonly expression: string

---

timezone?

readonly optional timezone?: string

Methods

next()

next(after?): Date | undefined

Find the next time matching the expression, strictly after a time, to the second. When the clocks go back, the times of the repeated hour match once; the times skipped when the clocks go forward never match.

Parameters

after?

number | Date

The time to search from, a date or milliseconds since the epoch; now by default.

Returns

Date | undefined

The next matching time, undefined when none matches within eight years (such as February 30th).