Delayed & Scheduled Jobs Cheatsheet

One-screen lookup. Cite: Delayed, Job Schedulers, Repeat Strategies, Manage.

Delayed — run one job later

await queue.add('x', data, { delay: 5000 });   // ~5s from now

// aim at a wall-clock time
const delay = Number(new Date('2035-07-03T10:30')) - Number(new Date());
await queue.add('x', data, { delay });

// reschedule while still delayed
const job = await queue.add('x', data, { delay: 2000 });
await job.changeDelay(4000);   // → 4s from now

delay = "at least", not "exactly". changeDelay only works while state is delayed.

Scheduled — the Job Scheduler (factory)

await queue.upsertJobScheduler(
  schedulerId,            // stable id — your key for update/remove
  repeat,                 // { every } | { pattern }  (+ options)
  { name, data, opts },   // job template (optional)
);
// → returns the FIRST job, in 'delayed' state

Repeat strategies — pick ONE

Option	Meaning
`{ every: ms }`	Fixed interval, clock-aligned (not add-aligned).
`{ pattern: 'cron' }`	cron-parser expression (5 or 6 fields).

Never combine every + pattern.

Cron fields

  s   m   h   DOM M   DOW      (s optional → 6-field form)
'0 0 9 * * 1-5'   = 9:00:00 Mon–Fri
'* * * * *'       = every minute
'0 0 0 L * *'     = midnight, last day of month
'0 0 0 * * 0'     = every Sunday midnight

Repeat options (all strategies)

Option	Effect
`startDate`	Nothing produced before this date.
`endDate`	Expiry — stops producing after this.
`limit`	Max repetitions; stops after N.
`immediately`	First job runs now, not on next tick. (v5.19+)

Management

await queue.removeJobScheduler(id);          // true if existed
await queue.upsertJobScheduler(id, repeat);  // re-upsert = update
const all = await queue.getJobSchedulers(0, 100);  // paginated list

Gotchas

Trap	What to do
No custom job id	Scheduler jobs get special ids; use `name` to tell them apart.
Cadence drifts under load	Next job emits only after previous one starts. Add workers / concurrency.
`every` not firing "2s after add"	It's clock-aligned. Use `immediately: true`.
Old code uses `{ repeat }`	Legacy `add(...,{repeat})` + `removeRepeatableByKey`. Use Job Schedulers for new code.

Mental model

Need	API
One job, later	`add(..., { delay })`
Jobs on a schedule	`upsertJobScheduler`