Lesson 3 — Delayed & Scheduled Jobs

Tied to mission: a queue that only fires "as fast as possible" covers half your needs. The other half — "send the onboarding email 24h after signup", "reconcile invoices at 2am", "poll the API every 90s" — needs time. Builds on Lesson 1 and Lesson 2.

Two mental models — don't mix them up

Delayed = one job, postponed. Scheduled = a Job Scheduler that produces many jobs over time. Everything below follows that split.

1. Delayed jobs — run once, later

A delayed job is dropped into a special delayed set instead of being grabbed by a worker immediately. Once the delay elapses it is promoted to waiting and processed like any other job.

import { Queue } from 'bullmq';
const paint = new Queue('Paint', { connection });

// Run ~5 seconds from now
await paint.add('house', { color: 'white' }, { delay: 5000 });

Aim at a specific clock time

delay is always a duration from now. To hit a wall-clock moment, compute the remaining duration:

const target = new Date('2035-07-03T10:30:00');
const delay = Number(target) - Number(new Date());
await paint.add('house', { color: 'white' }, { delay });

Reschedule a delayed job after it's queued

const job = await paint.add('house', { color: 'blue' }, { delay: 2000 });
// push it out to 4s from now
await job.changeDelay(4000);

2. Scheduled jobs — the Job Scheduler (factory)

A Job Scheduler is a factory that emits jobs on a repeat setting. For historical reasons its output is often still called "repeatable jobs", but the object you manage is the scheduler, not the jobs. You create one with upsertJobScheduler:

const report = new Queue('report', { connection });

// Emit a job every 10 seconds. Returns the FIRST job (in 'delayed' state).
await report.upsertJobScheduler(
  'nightly-recon',        // scheduler id — stable, your key for update/remove
  { every: 10_000 },       // repeat setting
  {
    name: 'recon',
    data: { tenant: 'acme' },
    opts: { attempts: 5, removeOnComplete: 100 },
  },
);

Why "upsert" and not "add"

Calling upsertJobScheduler with an id that already exists updates it instead of creating a duplicate. This is idempotent and exactly what you want in prod: your app can call it on every boot without spawning extra schedules. add would pile up duplicates.

The two built-in repeat strategies

Cron anatomy

field:   (s)   m     h    DOM   M    DOW
         '0 0 9 * * 1-5'  →  9:00:00, Monday–Friday
          │ │ │ │ │ │
          │ │ │ │ │ └── day of week (0-7, 0 or 7 = Sunday; 1L-7L = last weekday)
          │ │ │ │ └─── month (1-12)
          │ │ │ └──── day of month (1-31, L = last day)
          │ │ └────── hour (0-23)
          │ └──────── minute (0-59)
          └────────── second (0-59, optional — 6-field form)

await report.upsertJobScheduler(
  'weekday-standup',
  { pattern: '0 0 9 * * 1-5' },   // 9:00 Mon–Fri
  { name: 'standup-report', data: {} },
);

Common recipes: '* * * * *' every minute · '0 * * * *' top of each hour · '0 0 * * 0' every Sunday midnight · '0 0 0 L * *' last day of month at midnight.

Repeat options (work on every strategy)

Production gotchas you will hit

3. Managing schedulers

// Remove by id → returns true if it existed, false otherwise
await report.removeJobScheduler('nightly-recon');

// Update: just upsert again with the same id and new settings
await report.upsertJobScheduler('nightly-recon', { every: 30_000 }, { name: 'recon' });

// List them all (paginated, start/end offsets)
const schedulers = await report.getJobSchedulers(0, 100);

Because removal is by the stable id, store that id somewhere (config, DB). Lose the id and you'll have to getJobSchedulers and hunt for it.

4. The full picture (TypeScript, typed job)

import { Queue, Worker } from 'bullmq';
import IORedis from 'ioredis';

const connection = new IORedis({ maxRetriesPerRequest: null });

type ReportData = { tenant: string };

const report = new Queue<ReportData>('report', { connection });

// Delayed: one report 1 hour from now
await report.add('ad-hoc', { tenant: 'acme' }, { delay: 3_600_000 });

// Scheduled: every weekday at 9am, capped at 250 runs, starts immediately
await report.upsertJobScheduler(
  'weekday-9am',
  { pattern: '0 0 9 * * 1-5', limit: 250, immediately: true },
  { name: 'daily-summary', data: { tenant: 'acme' }, opts: { attempts: 5 } },
);

new Worker<ReportData>('report', async (job) => {
  console.log(`${job.name} for ${job.data.tenant}`);
}, { connection });

What you just learned

• delay (ms) postpones one job; aim at a clock time by computing the duration.
• job.changeDelay(ms) reschedules, but only while the job is still delayed.
• A Job Scheduler is a factory — upsertJobScheduler(id, repeat, template).
• every (clock-aligned) or pattern (cron) — never both.
• Repeat options: startDate, endDate, limit, immediately.
• Manage with removeJobScheduler(id) and getJobSchedulers(); re-upsert to update.
• Scheduler cadence drifts under load and you can't set custom job ids — don't build on exact timing.

🧠 Quiz — 10 questions

📚 Primary source

📎 Reference

💬 Ask me next

• "How do I make the 9am job skip holidays?"
• "Show me a scheduler that backs off if the downstream API is down."
• "My cron job fires twice — how do I debug it?"
• "How do scheduler ids and job ids relate?"

Or say "next" for Lesson 4: priority queues & rate limiting.