cron-parser

cron-parser is a mature, dependency-light TypeScript library for parsing and manipulating cron expressions in Node.js. It turns a crontab string into an iterable interval you can step forward and backward through to compute the next and previous scheduled run times, with correct handling of timezones and daylight-saving transitions via Luxon.

Beyond basic five-field crontab syntax, it supports optional seconds, predefined shortcuts like @daily and @weekly, special characters (L for last day, # for nth weekday, H for hash-randomized values), strict validation mode, and reading entire crontab files. It is the parsing engine underneath many popular Node.js job-scheduling tools.

What You Get

• A CronExpressionParser that parses standard and 6-field (with seconds) crontab strings into an iterable interval
• next() / prev() / take() iteration plus for…of support for computing scheduled run times in either direction
• Timezone and daylight-saving-aware date calculation backed by Luxon, configurable per expression
• Support for predefined aliases (@daily, @weekly, @hourly), and special characters L, #, and H
• A CronFileParser for reading crontab files (async and sync), returning variables, expressions, and errors
• Strict validation mode and first-class TypeScript types throughout

Common Use Cases

• Computing the next run time of a scheduled job from a user-supplied cron string
• Validating cron expressions entered in an admin UI or configuration file before saving
• Powering job schedulers, task queues, and reminder systems that accept cron syntax
• Displaying a human-facing list of upcoming run times for a recurring task

Under The Hood

Architecture - Parsing flows through src/CronExpressionParser.ts, which normalizes predefined aliases and splits a raw string into fields, each modeled by a dedicated class in src/fields/ (CronSecond, CronMinute, CronHour, CronDayOfMonth, CronMonth, CronDayOfWeek) extending the abstract CronField base. Parsed fields are held in a CronFieldCollection, and a CronExpression wraps that collection to expose the iterator (next/prev/take), computing candidate dates with an internal CronDate and validating them against optional start/end bounds; CronFileParser layers crontab-file reading on top of the same engine.

Tech Stack - Written in TypeScript (targeting Node.js >= 18) with a single runtime dependency, Luxon, used for timezone-aware and DST-correct date arithmetic. The build compiles to CommonJS via tsc with emitted type declarations; tooling includes Jest for tests, ESLint and Prettier for style, tsd for type tests, Husky/lint-staged for pre-commit hooks, and typedoc for API docs.

Code Quality - The codebase is cleanly decomposed with one class per cron field, private class fields for encapsulation, and thorough JSDoc. It ships an extensive Jest suite in tests/ covering the parser, each field, dates, the file parser, and the random/hash helper, with coverage badges generated in CI, plus dedicated type tests via tsd. Naming is consistent and the public surface is fully typed.

API Design - The entry point is a single CronExpressionParser.parse(expression, options) call returning an iterable interval, which keeps first use minimal while options (currentDate, startDate, endDate, tz, strict, hashSeed) cover advanced needs. Iteration reads naturally through next(), prev(), take(n), and for...of, errors surface as thrown exceptions with clear messages, and the README documents field values, special characters, and edge cases in depth.