Routecraft

cron

← All adapters

cron(expression: string, options?: CronOptions): Source<undefined>

Trigger routes on a cron schedule with timezone support. Produces undefined as the message body. More expressive than timer() for complex recurring schedules.

Supports standard 5-field cron (minute granularity), extended 6-field (second granularity), and nicknames (@daily, @weekly, @hourly, @monthly, @yearly, @annually, @midnight).

// Every 5 minutes
.id('poller')
.from(cron('*/5 * * * *'))

// Weekdays at 9am Eastern
.id('morning-report')
.from(cron('0 9 * * 1-5', { timezone: 'America/New_York' }))

// Daily at midnight (nickname)
.id('nightly-cleanup')
.from(cron('@daily'))

// Every 30 seconds (6-field)
.id('health-check')
.from(cron('*/30 * * * * *'))

// First day of month, limited to 12 fires
.id('monthly-report')
.from(cron('@monthly', { maxFires: 12, name: 'monthly-report' }))

// With jitter to prevent thundering herd
.id('distributed-poll')
.from(cron('*/5 * * * *', { jitterMs: 5000 }))

// Run only during Q1 2026
.id('q1-campaign')
.from(cron('@daily', { startAt: '2026-01-01', stopAt: '2026-04-01' }))

Options:

FieldTypeDefaultRequiredDescription
timezonestringSystem localNoIANA timezone (e.g., "America/New_York", "UTC")
maxFiresnumberInfinityNoMaximum number of fires before stopping (delegated to croner's maxRuns)
jitterMsnumber0NoRandom delay in milliseconds added to each fire
namestring--NoHuman-readable job name for observability
protectbooleantrueNoPrevents overlapping handler execution when the previous run is still in progress
startAtDate | string--NoDate or ISO 8601 string at which the cron job should start running
stopAtDate | string--NoDate or ISO 8601 string at which the cron job should stop running

Cron expression format:

FormatExampleDescription
5-field*/5 * * * *minute, hour, day-of-month, month, day-of-week
6-field*/30 * * * * *second, minute, hour, day-of-month, month, day-of-week
Nickname@dailyPredefined schedule

Supported nicknames: @yearly / @annually, @monthly, @weekly, @daily / @midnight, @hourly

Headers added: Cron metadata including expression, fired time, counter, next run, timezone, and name (via routecraft.cron.* headers)