cron

cron is a Rust crate that parses standard six/seven-field cron expressions (seconds, minutes, hours, day-of-month, month, day-of-week, and an optional year field) into a Schedule type, then lets callers iterate over upcoming or past fire times using chrono’s timezone-aware DateTime. It supports the full cron grammar — ranges, lists, steps, and named months/weekdays — without requiring a running scheduler.

Because it only computes fire times rather than executing jobs itself, it is typically paired with an application’s own timer loop or task runner, making it a building block for job schedulers, monitoring tools that need to know when a cron-defined task is due, and CLIs that validate or explain cron expressions.

What You Get

• A Schedule type parsed via FromStr from six- or seven-field cron expressions
• schedule.upcoming(tz) and schedule.after(&datetime) iterators returning chrono::DateTime values in any timezone
• Support for ranges, comma-separated lists, step values (*/2), and named months/weekdays (Mon, May) in expressions
• An optional serde feature for serializing/deserializing Schedule values
• Structured error types (error module) for invalid expressions

Common Use Cases

• Computing the next N run times for a cron-defined job inside a custom task scheduler or worker loop
• Validating and explaining user-supplied cron expressions in an admin UI or CLI tool
• Driving background job systems that need to check whether a scheduled task’s fire time has passed
• Monitoring/alerting tools that compare a job’s actual run against its expected cron schedule

Under The Hood

Architecture - The crate separates parsing from scheduling: parsing.rs (686 lines) implements the cron-expression grammar using the winnow parser-combinator library, producing intermediate specifier.rs/ordinal.rs representations; schedule.rs (1063 lines) then owns the Schedule type and its upcoming()/after() iterator logic, delegating field-specific range/step semantics to per-unit modules under src/time_unit/ (seconds, minutes, hours, days_of_month, months, days_of_week, years), each implementing a shared trait from time_unit/mod.rs. queries.rs and error.rs round out query helpers and error types.

Tech Stack - Built on chrono for timezone-aware datetime arithmetic, winnow for expression parsing, once_cell for lazy statics, and phf for compile-time perfect-hash maps (used for named month/weekday lookup tables). An optional serde feature (with postcard and serde_test as dev-dependencies) adds serialization support without imposing it on default users.

Code Quality - Testing lives in tests/lib.rs alongside inline unit tests across the time_unit and parsing modules, exercising round-trip parsing and iteration correctness; #![deny(rust_2018_idioms)] and #![deny(rustdoc::broken_intra_doc_links)] are enforced at the crate root. The crate has shipped 11 tagged releases since 2015 with steady, if infrequent, maintenance and 32 contributors, and CI runs via GitHub Actions.

API Design - The primary entry point, Schedule::from_str(expr), mirrors idiomatic Rust parsing conventions, and the resulting iterators (upcoming(tz), after(&dt)) compose naturally with chrono and standard iterator adapters like .take(n). The crate root doc comment demonstrates the full usage flow in a single runnable example, keeping the barrier to a first working schedule low.