Universal.Common.Cron 1.0.0

Universal.Common.Cron

A dependency-free cron expression parser and next-occurrence calculator for .NET. Standard 5-field POSIX/vixie-cron syntax (crontab(5)), including the "day-of-month OR day-of-week" rule most alternatives get wrong.

using Universal.Common.Cron;

CronExpression cron = CronExpression.Parse("0 9 * * 1-5"); // weekdays at 9am -- throws FormatException if invalid

if (!CronExpression.TryParse(userInput, out CronExpression? parsed, out string? error))
    Console.WriteLine(error); // e.g. "minute field '60': must be within 0-59."

DateTimeOffset? next = cron.NextAfter(DateTimeOffset.UtcNow);       // next matching instant
bool firesNow        = cron.Matches(DateTimeOffset.UtcNow);         // does it fire right now?
var nextFive         = cron.GetOccurrences(DateTimeOffset.UtcNow)   // lazy sequence -- always bound it
                            .Take(5);

NextAfter/Matches/GetOccurrences take an optional TimeZoneInfo (default TimeZoneInfo.Local), with correct DST handling (spring-forward gap never fires; fall-back overlap fires once).

Equality compares expanded field sets plus day-of-month/day-of-week wildness (the two flags that affect matching — see below), not spelling — "*/30 * * * *" and "0,30 * * * *" are Equal, but "0 0 * * 5" and "0 0 1-31 * 5" are not, despite an identical day-of-month set, because one is wild and the other isn't. ToString() returns the original source text.

Wildness: * vs. an explicit full range

IsMinuteWild/IsHourWild/IsDayOfMonthWild/IsMonthWild/IsDayOfWeekWild report whether a field is a literal */*/N, not whether its expanded set happens to cover every value. This matters because real cron's day-of-month-OR-day-of-week rule keys off the literal token: "0 0 15 * 0-6" fires every day (an explicit 0-6, unlike *, keeps day-of-week "restricted," so the OR rule kicks in and its trivially-always-true condition wins), while "0 0 15 * *" fires only on the 15th.

Supported syntax

*, */N, N-M, N-M/N, comma lists, day/month names (MON-FRI, JAN), Sunday as 0 or 7.

Not supported: seconds field, L/W/#/?, 1-based day-of-week, year field (a different, incompatible Quartz-family dialect) — and, within this dialect, wraparound ranges (11-2 for Nov–Feb) are rejected, matching real cron.

License

CC0-1.0 (public domain).