@chloejs/core/timer

export interface Cron {
  /** The minutes it matches, from 0 to 59. */
  minute: number[];
  /** The hours it matches, from 0 to 23. */
  hour: number[];
  /** The days of the month it matches, from 1 to 31. */
  dayOfMonth: number[];
  /** The months it matches, from 1 (January) to 12. */
  month: number[];
  /** The days of the week it matches, from 0 (Sunday) to 6 (Saturday). */
  dayOfWeek: number[];
}

A cron line, read into numbers by parse. Each field lists every value it matches, smallest first.

export function describe(cron: string, timezone = "UTC"): string | undefined

Turns a cron line into words, such as "every 15 minutes" or "weekdays at 09:30 New York". A line with a time of day ends with the city name of timezone. Default timezone: "UTC".

Works for the lines that every makes. Returns undefined for most other lines.

export function due(cron: Cron, at: Date, timezone = "UTC"): boolean

Returns true if the cron line matches the minute of at, read as a clock time in timezone (such as "America/New_York"). Default timezone: "UTC". Daylight saving time is handled for you.

Every field must match. So a line that sets both a day of the month and a day of the week matches only days that are both (most cron programs match days that are either).

export function dueWithin(line: string, minutes: number, timezone = "UTC", from = new Date()): boolean

Whether a cron line is due at any minute from now through minutes from now, in timezone. A line that cannot be read is never due.

export function every(count: number): { readonly minutes: string; readonly hours: string }

Makes a cron line for a job's cron, written the way you would say it. The times are read in the job's timezone.

• every(15).minutes: every 15 minutes, starting on the hour.
• every(4).hours: every 4 hours, on the hour, starting at midnight.
• every.minute: every minute.
• every.hour.at(30): every hour, at 30 minutes past.
• every.day.at("07:00"): every day at 07:00.
• every.weekday.at("9:30"): Monday to Friday. every.weekend is Saturday and Sunday.
• every.monday.at("9:00"): every Monday. Each day of the week works the same way.
• every.month.on(1).at("09:00"): the 1st of every month.

With a number, it must divide an hour (for minutes) or a day (for hours) evenly, so the gaps are all the same: every(7).minutes throws, and the error lists the numbers that work.

export function parse(line: string): Cron

Reads a cron line, such as "30 7 * * 1-5", into numbers.

The line has five fields: minute, hour, day of month, month, day of week. Each field is *, a number, a range (1-5), a list (1,3,5) or a step (0-30/10, or * followed by /15 for every 15th). Sunday is 0, and 7 is not allowed. Names such as MON or JAN are not read.

Throws an error that says what is wrong if the line cannot be read.