$ show kelektiv/node-cron
This repository is the `cron` npm package — a long-standing Node.js library for scheduling callbacks or system commands using cron syntax, with an optional leading seconds field. In production it parses a cron expression into per-field boolean match maps, then drives a setTimeout loop that computes the next matching instant (via Luxon for timezone conversion) and fires registered callbacks. It also supports one-shot Date/Luxon DateTime triggers, execution through child_process spawn, UTC offsets in minutes, presets (@hourly, @daily, etc.), and a threshold option that recovers from missed deadlines caused by event-loop stalls (execute immediately if within threshold, otherwise skip with a warning). Architecture is a compact, clean TypeScript library: src/constants.ts holds field constraints, aliases, and presets; src/time.ts implements CronTime (expression parsing plus next-date search with DST forward/backward ambiguity handling and an 8-year max-match cap for leap-day-only schedules); src/job.ts implements CronJob (timer lifecycle, MAXDELAY chunking for setTimeouts beyond ~24.8 days, waitForCompletion semantics, and threshold-based missed-deadline policy); src/types/cron.types.ts exposes rich parameter/context typing including a recursive IntRange utility that constrains cron field values at compile time. Public entry points exported from src/index.ts are CronJob, CronTime, sendAt, timeout, and validateCronExpression. Maintenance is exemplary: semantic-release automation with trusted npm publishing and provenance, a CI matrix across Node 18/20/22/23/24/25 on Linux/Windows/macOS, enforced coverage thresholds (85% statements/lines/functions, 75% branches), Renovate-driven dependency updates, CodeQL and OpenSSF scorecard checks, and a fast-check property-based fuzz suite (100k randomized runs per tier) complementing the hand-written Jest unit tests. The codebase is current with its ecosystem — TypeScript 5.9, Jest 30, Node 24/25 support — with only a minor lag in ESLint (v8 vs current v9) and typescript-eslint (v7 vs v8), which does not meaningfully impair the project.
The LLM identified 4 files worth highlighting for reuse:
The CronTime class: parses cron syntax (optional seconds field, presets like @daily/@weekends, month/day-name aliases, wildcards, ranges, steps) into per-unit boolean match maps with strict out-of-range and step-zero validation. The getNextDateFrom method walks month → day → hour → minute → second to locate the next match, caps the search at 8 years so leap-day-only expressions (e.g. '* * 29 2 *') terminate correctly, then converts the UTC-evaluated candidate into the target zone with explicit rewinding for DST forward jumps and disambiguation of backward-folded ambiguous times. This is the library's core intellectual asset and could be extracted as a standalone cron-expression engine; the DST/leap-year edge-case reasoning is the non-obvious skill.
A pure TypeScript utility implementing IntRange<F, T> via recursive tuple-length arithmetic: Enumerate builds a tuple one element at a time and returns the union of its indices, giving literal integer unions like 0|1|2|...|59 with zero runtime cost and zero imports. This powers the Ranges interface so every cron field is compile-time constrained to legal values (seconds 0-59, months 1-12, etc.). Fully self-contained and directly copyable into any TypeScript codebase needing numeric range literal types.
Defines a CronError base class, ExclusiveParametersError, and the assertExclusiveTimeZoneAndUtcOffset runtime guard. The insight is that TypeScript discriminates timeZone vs utcOffset cheaply at compile time, but plain JavaScript consumers and @ts-ignore call sites bypass that — so a single centralized assertion makes every constructor path (CronJob constructor, CronJob.from, CronTime) throw the identical validation error for the same bad input. A clean, extractable pattern for library authors exposing mutually exclusive options across multiple construction APIs.
A property-based fuzz harness using fast-check that runs 100,000 randomized inputs in three escalating tiers — regex-constrained cron strings, arbitrary strings, and arbitrary anything — and asserts every thrown error is a typed CronError/TypeError rather than an unexpected crash. Because the scheduler must never hang, infinite loops manifest as Jest timeouts and are caught implicitly. This is a genuinely reusable pattern for calendar/time libraries where hand-written unit tests cannot cover the combinatorial space of cron field interactions, DST transitions, and malformed inputs.