4.6.0 (2026-07-04)

Added

• add cron.shutdown(timeout?) for graceful process teardown (#589) (35f1a61)
• add unref option for heartbeat timers (#588) (35cb140)
• day-of-month: Quartz-style W, L-n and ? modifiers (#570) (cbe379b)
• emit task:failed when a background daemon exits unexpectedly (7bd91d6)
• support cron expression nicknames (@yearly, @daily, etc.) (#579) (6a6e14e)

Fixed

• background task state transition on stop/destroy without fork (#584) (9dbc6de)
• clear jitter timeout on runner stop (#583) (28b8146)
• CommonJS type resolution (#608) (ee9d294)
• correct falied->failed typo in daemon task error log (#594) (66c6961)
• correct shutdown listener typing that broke the build (#595) (7aac3ad)
• correlate execute() by id, isolate event hooks, and stop counting manual runs toward maxExecutions (#607) (0f039a9)
• daemon serialized task state with wrong field name (#587) (688d465)
• expand inverted ranges with wrap-around instead of silently swapping (#602) (a10ae53)
• harden cron.shutdown() teardown (#598) (a0b0d1f)
• kill orphan child process on background task stop/destroy timeout (#582) (8179e10)
• make concurrent background start() await the daemon and time out coordinator lookups (#605) (446f03a)
• make lifecycle calls on a destroyed task safe no-ops (#600) (7fa9795)
• prevent double destroy on registry remove (#585) (8ae9f06)
• release-please: match existing v-prefixed tags (#575) (e43c152)
• runner promise bugs that could hang scheduling or crash process (#581) (0ae62be)
• unref the IPC channel so background tasks let the process exit (#599) (534e593)
• validate the cron expression when scheduling a task (#603) (196e6cd)
• validate() consistency and multi-asterisk expansion (#606) (8cf41c4)
• weekday 7-to-0 conversion corrupting ranges (#580) (c8a3943)

Changed

• replace chai and sinon with native vitest assertions (#590) (d29d07a)

Added

• lastRun() introspection getter on ScheduledTask: returns { date, result } after a successful execution, { date, error } after a failed one, or null before the first run.
• Extended day-of-week tokens: <weekday>#<nth> (nth weekday of the month, e.g. 1#1 for the first Monday) and <weekday>L (last weekday of the month, e.g. 5L for the last Friday).

Performance

• Cache Intl.DateTimeFormat instances per timezone instead of rebuilding on every call.
• Parse the cron expression once per TimeMatcher instead of re-parsing in MatcherWalker.
• Compute the GMT offset lazily (only when formatting ISO strings, not during the next-run search).
• Replace crypto.randomBytes with crypto.randomUUID for internal ID generation.
• Skip setTimeout jitter wrapper when maxRandomDelay is zero.
• Bundle dist into flat files instead of preserving the module tree (reduces import time).

Fixed

• Flaky should schedule a task test: poll for the first execution instead of asserting an exact count after a fixed sleep.

Changed

• Renamed internal functions interprete to interpret and appendSeccondExpression to appendSecondExpression.
• Rewritten README and package metadata to surface scheduling capabilities (overlap prevention, distributed coordination, background tasks).

Patch release.

Changed

• Renamed the distributedTtl task option to distributedLease (same meaning: the safety lease, in ms, for lease-based run coordinators). distributedTtl was the only abbreviation in the options API and shipped just days ago in 4.4.0, so it's removed without an alias. If you adopted distributedTtl from 4.4.0, rename it to distributedLease. (#551)

Full Changelog: v4.4.0...v4.4.1

Features

• Distributed run coordination — opt-in distributed: true runs a task on a single instance per fire across a fleet (the #477 use case). Ships a built-in NODE_CRON_RUN env-var default (one designated runner, no dependencies) and a pluggable RunCoordinator (via setRunCoordinator, or the per-task runCoordinator option) for high-availability, per-fire coordination (e.g. a Redis lock). Adds the distributedTtl option and an execution:skipped event carrying a reason ('not-elected' | 'coordinator-error'). Works for inline and background tasks. (#549, closes #477)
• Task introspection on ScheduledTask: getNextRuns(n) (preview the next N run times), match(date), msToNext(), isBusy(), runsLeft() and getPattern(). (#547)
• cron.parse(expression) and cron.validateDetailed(expression) — decompose an expression into its fields, or get every field-level problem (without throwing) for tooling and richer error messages. (#548)

Fixes

• getNextMatch no longer scans every time of day on a day that matches the day-of-month but not the weekday. A dense expression constrained by both (e.g. * * * 15 * 1) could take minutes to resolve; it is now instant. (#542)

Internal

• Cleanups with no public API change: fixed the milisecond → millisecond spelling and the convertion/ → conversion/ directory name. (#543)

Docs

• New Distributed Coordination guide, plus pages for task introspection and parse/validateDetailed, at nodecron.com.

Full Changelog: v4.3.0...v4.4.0

Features

• L (last day of month) in the day-of-month field — e.g. 0 0 12 L * *, leap-year aware, and combinable with explicit days (15,L). (#396, closes #147 — thanks @antonidasyang)
• missedExecutionTolerance option (ms, default 1000): a heartbeat that wakes a little late still runs its slot instead of being reported as missed. Always capped to the gap to the next slot. (#534, closes #485)
• startTimeout option for background tasks (ms, default 5000). (#535)

Fixes

• Rewrote getNextMatch for correctness around DST: no more ~1-year overshoot when a daily time falls in the spring-forward gap. (#533, closes #518)
• Background task start failures now reject with the real cause (e.g. unsupported TypeScript syntax, missing file) instead of an opaque timeout, and a failed/timed-out start no longer leaves an orphaned daemon running. (#535, closes #484)
• Long-timer drift no longer produces spurious "missed execution" warnings / skipped runs on daily/weekly schedules. (#534, closes #485)

Compatibility

• Supported Node.js is now >= 20 (was >= 20.11), tested on Node 20, 22 and 24. (#538)

Docs

• README refreshed for v4; API reference documents getTasks/getTask. (#536, #537)

Behavior note

• missedExecutionTolerance defaults to 1000ms, so a scheduled run that wakes up to ~1s late now executes instead of emitting execution:missed. This is a bug-fix improvement, not an API break.

Full Changelog: v4.2.1...v4.3.0

What's Changed

• add option recoverMissedExecutions in readme by @theusmoreira in #332
• docs: migrate to es6 and add how to get tasks in node-cron by @linder3hs in #398
• v4 - migrating to typescript by @merencia in #439

New Contributors

• @theusmoreira made their first contribution in #332
• @linder3hs made their first contribution in #398

Full Changelog: v3.0.3...v4.0.0

New Features:

• Added timezone support using tz-offset;
• Provide a function getStatus to retrive the task current status;
• Allows task functions to return a promise, node-cron hanldes that;

Depreciation:

• ImmediateStart: ImmediateStart is removed, and replaced by an options param. The same behavior is allowed by the option scheduled;