Schedules

A schedule makes one job on each tick of its timing: a cron rule in a time zone, or a fixed every period. It is stored, so every pod sees the same schedules. This page creates a schedule that ticks every second, lets it fire twice, and previews a cron rule.

Example

import { Queue } from '@sureq/core'

type Digest = { to: string }

const queue = new Queue<Digest>('digests')

// Safe to call on every start-up: the same definition answers 'unchanged'.
const first = await queue.upsertSchedule('team-digest', {
  every: '1s',
  template: { data: { to: 'team@example.com' } },
})
const again = await queue.upsertSchedule('team-digest', {
  every: '1s',
  template: { data: { to: 'team@example.com' } },
})
console.log(first.action, again.action)

// A cron rule in a time zone. previewSchedule stores nothing.
const times = await queue.previewSchedule({ cron: '0 7 * * 1-5', tz: 'Europe/Berlin' }, 2)
console.log(times.map((t) => new Date(t).toISOString()))

let runs = 0
let finish!: () => void
const done = new Promise<void>((resolve) => (finish = resolve))

// A worker on the queue also runs its scheduler, while `scheduler.enabled` is true (the default).
const worker = queue.process(
  async (job) => {
    console.log(job.id, job.schedule?.key)
    if (++runs === 2) finish()
  },
)
worker.on('error', ({ error }) => console.error('worker error', error))

await done
await queue.deleteSchedule('team-digest')
// close() also closes the worker.
await queue.close()

Output (your times differ):

created unchanged
[ '2026-11-16T06:00:00.000Z', '2026-11-17T06:00:00.000Z' ]
sched:team-digest:1794701718162 team-digest
sched:team-digest:1794701719162 team-digest
  • upsertSchedule(key, definition) creates the schedule, or updates it when the definition changed. Its action says which.
  • template is what each job is made of: its data, and optionally a name and add options.
  • Each fired job has the id sched:<key>:<tick time>, and job.schedule tells which schedule and tick made it.
  • The two jobs came one second apart. The second came on the next tick of the same grid.
  • previewSchedule lists the next fire times of a timing without storing anything. The cron rule 0 7 * * 1-5 is 07:00 on weekdays, here in Berlin time.

Common questions

Which pods fire schedules? Every pod that runs a worker on the queue while the queue option scheduler.enabled is true (the default), and every pod that called queue.startScheduler(). See Queue options: scheduler. A producer never fires one. A queue with no running scheduler anywhere fires nothing.

Do several pods make several jobs per tick? No. One job per tick, however many pods run a scheduler.

What if the previous job is still running at the next tick? The overlap option decides: skip the tick, queue it, or fire anyway. See Overlap.

What happens to ticks missed while no pod ran? They collapse into one job for the oldest missed tick. Then the schedule goes on as usual.

Reference

Was this page helpful?