Schedulers & repeatables
Job Schedulers are the forward-looking way to run recurring work. NextMQ owns the scheduling clock, so repeating jobs fire even while your functions are cold.
Upserting a scheduler#
upsertJobScheduler creates or updates a scheduler by key. Use a cron pattern or a fixed every interval.
import { Queue } from '@nextmq/sdk'
const reports = new Queue('reports')
// Cron: every day at 09:00 in a fixed timezone.
await reports.upsertJobScheduler('daily-report', {
pattern: '0 9 * * *',
tz: 'Europe/Berlin',
}, {
name: 'report',
data: { kind: 'daily' },
})
// Fixed interval: every 15 minutes.
await reports.upsertJobScheduler('healthcheck', {
every: 15 * 60 * 1000,
})Repeat options#
| Option | Description |
|---|---|
pattern | Cron expression for the schedule. |
every | Fixed interval in milliseconds (alternative to pattern). |
limit | Maximum number of times to repeat. |
key | Scheduler identity (the first argument to upsertJobScheduler). |
tz | Timezone for cron evaluation. |
startDate | Don't fire before this time. |
endDate | Don't fire after this time. |
immediately | Produce the first job right away rather than waiting a full interval. |
Reading and removing schedulers#
// All schedulers on the queue
const all = await reports.getJobSchedulers()
// A single scheduler by key
const one = await reports.getJobScheduler('daily-report')
// Remove a scheduler
await reports.removeJobScheduler('daily-report')Note
NextMQ supports the modern Job Scheduler CRUD. Legacy repeatable-job management (
getRepeatableJobs, removeRepeatableByKey) is intentionally omitted — two ways to manage the same thing is worse than one. A limited repeat option on add() still exists for simple cases, but schedulers are preferred.Why this works when functions sleep#
The scheduler clock lives on NextMQ, not in your app. When a scheduled job is due, NextMQ produces it and calls your worker route via webhook — the same path as any other job. Your app doesn't need to be awake for the schedule to advance.