Schedules
An entry point is a top-level file whose name ends .cron.js and carries a
schedule keyword — .every, .daily or .hourly — followed by a time
token. The name is parsed as:
<base-name> . <keyword> . <time-token> . cron . js
report . hourly . 30 . cron . jsThis page is the definitive grammar. If a top-level filename does not match one of the patterns below it is treated as a supporting file, not a job.
Intervals — .every
Run repeatedly at a fixed spacing. N is any positive integer.
| Pattern | Meaning | Example | Notes |
|---|---|---|---|
<name>.every.<N>ms.cron.js | every N milliseconds | poll.every.500ms.cron.js | Sub-second; use sparingly. |
<name>.every.<N>s.cron.js | every N seconds | ping.every.30s.cron.js | N ≥ 1. |
<name>.every.<N>m.cron.js | every N minutes | digest.every.30m.cron.js | N ≥ 1. |
<name>.every.<N>h.cron.js | every N hours | sync.every.6h.cron.js | N ≥ 1. |
<name>.every.<N>d.cron.js | every N days | prune.every.7d.cron.js | N ≥ 1. Spacing, not a wall-clock time — see .daily for that. |
Interval jobs are spaced from the runner's own clock, not aligned to the wall clock: an
every.6h job fires every six hours from when the runner started tracking it, not at
00:00/06:00/12:00/18:00. Use .daily/.hourly when you need a specific
clock time.
Daily — .daily
Run once a day at a fixed clock time. The token is zero-padded and range-checked.
| Pattern | Meaning | Example | Ranges |
|---|---|---|---|
<name>.daily.<HH>.cron.js | daily at HH:00 | report.daily.09.cron.js | HH 00–23 |
<name>.daily.<HHMM>.cron.js | daily at HH:MM | backup.daily.0300.cron.js | HH 00–23, MM 00–59 |
<name>.daily.<HHMMSS>.cron.js | daily at HH:MM:SS | chime.daily.083000.cron.js | HH 00–23, MM/SS 00–59 |
Hourly — .hourly
Run once an hour at a fixed offset past the hour.
| Pattern | Meaning | Example | Ranges |
|---|---|---|---|
<name>.hourly.<MM>.cron.js | at MM past every hour | sweep.hourly.15.cron.js | MM 00–59 |
<name>.hourly.<MMSS>.cron.js | at MM:SS past every hour | tick.hourly.3000.cron.js | MM/SS 00–59 |
Base-name extraction & the mutex
The base name is everything before the schedule keyword. It is a job's identity and its mutex key.
| Filename | Base name | |
|---|---|---|
report.hourly.30.cron.js | report | |
backup.daily.0300.cron.js | backup | |
daily-summary.every.6h.cron.js | daily-summary |
At most one process per base name runs at a time across the whole runner. A tick that fires while a run with the same base name is still active is skipped — never queued. The Scripts reference states this precisely, and Usage → Server works through what it means at runtime.
The duplicate idiom
There is no multi-time token. To run at several clock times, write one file per time, sharing a base name:
report.hourly.00.cron.js → at :00
report.hourly.30.cron.js → at :30 (base name "report" — same mutex)Because the copies share the base name report, they share the single-instance mutex and
can never overlap. That is what makes the idiom safe: it is one job that fires on two schedules, not two
jobs racing each other. Beware the flip side — two unrelated files that happen to share a base
name will serialise too; see the base-name collision note on
Usage → Client.