
# Cron expressions

A cron expression describes calendar times: "every 15 minutes", "9:00 on working days", "the last Friday of the month". It has six fields, as in Spring, starting with the seconds (Unix cron has five).

## Why

Many jobs follow the calendar, not a period: a report every morning, a cleanup at night, an invoice run on the last working day of the month. A cron expression says it in one line, and the same syntax works in `@Scheduled`, in `CronTrigger` and in properties.

## Example

```dart
@Scheduled(cron: '0 0 9 * * MON-FRI')       // 9:00 on working days, local time
void morningDigest() => mail.sendDigest();

@Scheduled(cron: '0 0 12 LW * *', zone: 'UTC') // noon UTC on the last working day of the month
Future<void> invoices() => billing.run();
```

```text
second minute hour day-of-month month day-of-week
```

## Examples

| Expression | Runs |
|---|---|
| `0 * * * * *` | every minute, at second 0 |
| `*/10 * * * * *` | every 10 seconds |
| `0 */15 * * * *` | every 15 minutes |
| `0 0 * * * *` | every hour |
| `0 0 9-17 * * MON-FRI` | every hour from 9 to 17 on working days |
| `0 30 8 * * *` | 8:30 every day |
| `0 0 0 1 * *` | midnight on the 1st of each month |
| `0 0 18 L * *` | 18:00 on the last day of the month |
| `0 0 12 LW * *` | noon on the last working day of the month |
| `0 0 10 15W * *` | 10:00 on the working day nearest to the 15th |
| `0 0 20 ? * FRIL` | 20:00 on the last Friday of the month |
| `0 0 9 ? * MON#1` | 9:00 on the first Monday of the month |
| `0 0 9 ? * MON#1,MON#3` | 9:00 on the first and the third Monday |
| `0 0 0 1,L * *` | midnight on the first and the last day of the month |
| `0 0 10 * * SAT-SUN` | 10:00 at the weekend |
| `0 0 0 25 DEC *` | midnight on December 25th |
| `@hourly`, `@daily` (`@midnight`), `@weekly`, `@monthly`, `@yearly` (`@annually`) | the usual macros |
| `-` | never: the task is switched off |

## Syntax

- Every field takes `*`, a value (`5`), a list (`1,15,30`), a range (`9-17`) and a step (`*/5`, `0-30/10`, `5/15` = from 5, every 15).
- Months are `JAN`-`DEC`; names are case-insensitive. `?` means "any" in the day fields.
- Days of the week are numbered as in Spring: `MON`-`SUN` are 1-7, and 0 is Sunday too. Sunday at the start of a range counts as 0, so `SAT-SUN`, `MON-SUN` and `SUN-TUE` all work. `*/2` is MON, WED, FRI, SUN.

| Special | Field | Means |
|---|---|---|
| `L` | day of month | the last day |
| `L-n` | day of month | n days before the last |
| `nW` | day of month | the working day nearest to day n |
| `LW` | day of month | the last working day |
| `nL` (`FRIL`) | day of week | the last such day of the month |
| `n#k` (`MON#1`) | day of week | the k-th such day of the month, k from 1 to 5 |

The specials may be combined in lists with each other and with values (`1,L`, `MON-FRI,SATL`).

## Rules that differ from Unix cron

- A day must match **both** day fields (Unix cron matches either), as in Spring.
- Ranges cannot wrap around: `FRI-MON` is an error; write `FRI-SUN,MON`.
- Six fields, starting with seconds.

## Time zones and daylight saving

- `zone` is local time (left out) or UTC (`'UTC'`, `'Z'`, `'GMT'`). Dart has no time zone database, so other zones are an error.
- Local time follows the wall clock, as in Spring. A time inside the hour skipped when clocks go forward does not exist and is skipped (a daily `0 30 2 * * *` does not run that day); a time inside the hour repeated when clocks go back runs twice, before and after the change.

## Checking an expression in code

```dart
final cron = CronExpression.parse('0 0 9 * * MON-FRI');
final next = cron.next(DateTime.now());       // when it runs next
CronExpression.isValid('0 0 25 * * *');       // false: there is no hour 25
```

`CronExpression.parse` throws a `FormatException` naming the wrong field. Use it to check an expression a user typed before scheduling it with a `CronTrigger`.

## In Spring (Java)

```java
CronExpression cron = CronExpression.parse("0 0 9 * * MON-FRI");
LocalDateTime next = cron.next(LocalDateTime.now());
```

The syntax is Spring's `CronExpression`. `#k` takes 1-5 (Spring accepts larger ordinals that never match), and only local time and UTC are offered as zones.

## See also

- [@Scheduled](scheduled.md)
- [TaskScheduler](task-scheduler.md)
