Skip to content
Tutorials Center
My learning

Topics

Lesson 126 of 133 ยท Projects

Project: Cron-Style Task Scheduler

Build a cron-style scheduler in Node.js. Parse five-field cron expressions, compute the next run, chain timers past the 24-day limit, prevent overlap and recover missed runs after a restart.

"Send the report every weekday at 8:30." "Clean up temporary files at 3 a.m." "Check for expired subscriptions every 15 minutes." Almost every application has jobs like these, and Unix solved the way to describe them fifty years ago with cron expressions: five fields that say minute, hour, day of month, month, day of week. Libraries such as node-cron and cron implement them for Node.js; in this project you build the core yourself, so you understand what those libraries do and where their sharp edges are.

You will write a cron parser, a function that finds the next run time, a scheduler that fires tasks using timers (and survives the awkward limits of setTimeout), a policy for overlapping runs, and persistence so that a restart does not forget or double-run tasks. As in the other projects, the clock and the timers are injected, so the demo can simulate a month of schedule in a few milliseconds.

Plan

  1. parseCron(expression) turns "*/15 8-17 * * 1-5" into sets of allowed values per field.
  2. nextRun(cron, after) finds the first matching minute after a given time.
  3. Scheduler keeps tasks, arms one timer per task and runs the callbacks.
  4. A small JSON state file remembers when each task last ran, for restarts.

All times are UTC here. Local-time schedules have daylight-saving traps (an hour that does not exist, an hour that happens twice), which is why servers usually run in UTC and why we state the time zone of every schedule.

Stage 1: parsing cron expressions

The five fields, in order, and their ranges:

Field Range Notes
minute 0-59
hour 0-23
day of month 1-31
month 1-12
day of week 0-6 0 is Sunday; many implementations also accept 7 for Sunday

Each field can be * (every value), a number, a list 1,15,30, a range 8-17, or a step: */15 (every 15th value) or 10-40/10. We implement all of that with one small function per field. A field that cannot be parsed throws a clear error naming the field, because a scheduler that silently ignores a typo will simply never run your job.

Node.js parseCron: fields, ranges, steps and errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Look at 5/20 * * * *: a number with a step means "start at 5 and step by 20", giving minutes 5, 25 and 45. The Sunday 7 in 30 9 * 1,7 7 became 0. The quirk noted in the code is real and surprising: if both day of month and day of week are restricted, standard cron runs on days that match either one (0 0 13 * 5 means "on the 13th, and also every Friday", not "Friday the 13th").

Stage 2: finding the next run

Given the time of the last run, what is the next one? The simple method is to try every minute until one matches: at most 366 x 24 x 60, about half a million checks for a yearly job, which takes a few milliseconds. We speed it up with obvious skips: if the month does not match, jump to the first minute of the next month; if the day does not match, jump to the next midnight; if the hour does not match, jump to the next full hour. Those jumps are cheap and still correct, because nothing between can match either.

Node.js nextRun: skip ahead through non-matching months, days and hours

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check a few answers by hand. The time is Friday 2026-01-30 10:07:45, so the next quarter hour is 10:15. The next weekday 08:30 is Monday, 2 February. 2026 is not a leap year, so 0 12 29 2 * waits until 2028. 0 9 31 4,6,9,11 * can never match (April, June, September and November have 30 days), and the function gives up after five years with an error instead of looping forever: validate user-supplied schedules by calling nextRun once when you register them.

Stage 3: the scheduler and its timers

The scheduler arms one timer per task, for the delay until that task's next run. When the timer fires, it runs the callback, computes the next run and arms again. Three details decide whether it is reliable:

  1. setTimeout has a maximum delay of 2,147,483,647 ms (about 24.8 days). A longer delay fires immediately and prints a TimeoutOverflowWarning. So the scheduler sleeps in chunks of at most that size and re-checks the time.
  2. Timers drift and can fire a little early or late. After the timer fires, compare the real clock with the planned time and compute the next run from the planned time, not from now, or each run slips by a few milliseconds and eventually a minute can be skipped or repeated.
  3. A run can take longer than the interval. If "every minute" takes 90 seconds, you must choose: skip the overlapping run (the safe default), queue it, or run in parallel. We implement skip with a running flag per task.

Errors in a task callback must never crash the scheduler or kill its timer. We catch them and report them through an onError hook.

To make all this testable, Scheduler receives a clock object with now(), setTimeout and clearTimeout. In production it is { now: Date.now, setTimeout, clearTimeout }. The demo uses a virtual clock that jumps from timer to timer instantly.

Node.js Scheduler on a virtual clock: runs, overlap and errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Read the log (each line is written when a run finishes or is skipped, with its planned time in parentheses). ping ran every 30 minutes during hours 0 and 1. slow is due every 10 minutes but takes 25 minutes, so some of its runs were skipped instead of piling up. flaky failed once at 01:15, was reported through onError, and did not stop the other tasks or its own next run. The summer task is due 92 days away; no single timer can wait that long, so #arm sleeps in chunks of at most about 24.8 days and re-checks. (The virtual clock refuses longer delays, just as real Node warns and fires immediately.)

On a real clock, replace VirtualClock with { now: () => Date.now(), setTimeout, clearTimeout }. Also call timer.unref() if the scheduler should not keep the process alive on its own, or leave the timers referenced when the scheduler is the program. Real timers cannot be sped up, which is why our tests never use them.

Stage 4: persistence and missed runs

If the process restarts at 08:29:50 and comes back at 08:31, the 08:30 run was missed. What should happen? There is no universal answer, so make it a per-task policy:

  • skip (the default for most jobs): ignore the missed run and wait for the next one. Right for "refresh a cache" or "send a reminder", where late is worse than never.
  • catch-up-once: run one time immediately, however many runs were missed. Right for "sync data" or "build the report", where the work matters but doing it ten times is pointless.

To know what was missed, the scheduler stores each task's lastRun time on disk. Write the file atomically: write to a temporary file and rename it over the real one, so a crash in the middle of a write cannot leave half a JSON file (File System Promises). We also count missed runs by walking nextRun from the last run to now.

Node.js State file with atomic writes and catch-up after a restart

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

After the outage, the hourly sync missed the 09:00, 10:00 and 11:00 runs, and the policy catch-up-once runs it once, not three times. The daily report missed nothing (its next slot is tomorrow 06:30), and the cache warmer missed fourteen slots, but a stale cache refresh is pointless, so it just waits. The rename trick is the standard way to update a file safely; for a scheduler with more state or several workers, use a database table instead and take a lock per task, so two instances do not run the same job (Job Queue project).

Production notes

  • One instance runs the schedule. If you deploy three copies of your app, all three fire "every day at 3:00". Use a leader election, a database lock row per task, or run the scheduler in a single dedicated process.
  • Time zones. Store schedules with an explicit zone and convert with Intl.DateTimeFormat or a library such as luxon, or use UTC. Test the days when clocks change.
  • Long jobs belong in a queue. The scheduler should only enqueue "run the report", and workers do the heavy lifting with retries (Job Queue project). A scheduler callback that blocks the event loop delays every other timer (Timers).
  • Observability. Log each run with its planned time, start, duration and outcome, and alert when a task has not run for longer than its interval allows.
  • Graceful shutdown. On SIGTERM stop arming timers and wait for running tasks (Graceful Shutdown).
  • Libraries. For real projects node-cron, croner, bree or a queue-backed scheduler such as BullMQ's repeatable jobs are well-tested; you now know what they do under the hood.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does the cron expression */15 8-17 * * 1-5 mean?

    Fields are minute, hour, day of month, month, day of week. */15 is every 15th minute, 8-17 the hours 8 to 17, and 1-5 is Monday to Friday.
  2. 2. What happens if you pass a delay larger than about 24.8 days to setTimeout?

    The delay is stored in a 32-bit signed integer. A scheduler must sleep in chunks and re-check the time.
  3. 3. Why is the next run computed from the planned time and not from the time the callback finished?

    Using the planned time keeps the schedule aligned with the cron expression regardless of delays.
  4. 4. A job that runs every minute sometimes takes 90 seconds. Which overlap policy is the safest default?

    Skipping prevents piles of concurrent runs that make the slowness worse. Other policies, such as queueing, are choices you make per job.
  5. 5. Why write the state file to a temporary name and then rename it?

    Rename within one file system is atomic: readers see either the old complete file or the new complete file.

Summary

  • Cron expressions have five fields (minute, hour, day of month, month, day of week) with lists, ranges and steps; if both day fields are restricted, either may match.
  • nextRun finds the next matching minute and skips non-matching months, days and hours; reject schedules that never match.
  • Use one timer per task, chunk long delays below 2^31 - 1 ms, compute the next run from the planned time, arm the next timer before running the callback and never let a task error stop the scheduler.
  • Decide the overlap policy (skip is the safe default) and the missed-run policy (skip or catch up once) for each task.
  • Persist last-run times with atomic writes; inject the clock so a month of schedule can be tested instantly. In production run the schedule from a single instance and hand heavy work to a queue.

Next: Project: File Sharing Platform