Typescript rewrite

[harrisiirak]

This MR is a long-awaited modernization of this library, converting the existing codebase to TypeScript. Kudos to @MichaelLeeHobbs (most of the changes come from his MR), who started this initiative - without whom this wouldn't have been possible.

There have been some changes to the public API, resulting in a few breaking changes that need to be considered when switching to this version. Additionally, some bugs and minor performance regressions were fixed during the refactor.

Changelog

• BREAKING CHANGE: Bumped the minimum Node.js version to >= 18 and TypeScript to >= 5.
• BREAKING CHANGE: interval.fields (CronExpression.interval) now returns a readonly instance of CronFieldsCollection instead of a regular array. See CronFieldsCollection.from for how to modify the underlying data structure.
• BREAKING CHANGE: Moved crontab file parsing from CronParser to a standalone CronFileParser class (fixes Why not splitting the parser from the expression? #112).
• Refactored the codebase to TypeScript (fixes feature request: native ES module support #190).
• Cleaned up test suites, removed duplicate test cases, and switched from tap to jest.
• Improved documentation and introduced documentation generated by typedoc (fixes Stringify argument not documented. #309, suggestion for iterator example #322, documentation: Document "fields" (Getter) in README #269).
• Added benchmark tooling to help detect future performance regressions.
• Added CronExpression.includesDate to evaluate whether a given date matches the pattern (closes Feature Request: interval.includes #299).
• Fixed issues where certain range and repeat field expressions produced invalid intervals (fixes Some cron expression will build incorrect intervals #156).
• Fixed an issue with day-of-month handling when the range is explicitly set and no wildcard is used (fixes Possible bug: 0 12 1-31 * 1 is parsed incorrectly #284).
• Improved repeat serialization for stringification (fixes 一些数据无法解析正确的表达式 #236).

Performance improvements

While this release won't address the performance issues reported in #287, it will bring some performance improvements of around 20-30% on average, depending on the pattern complexity. The following benchmark results were produced on my 2023 MBP.

┌────────────────────┬────────────┬────────────┬──────────┬─────┐
│ Pattern            │   Old Mean │   New Mean │   Change │     │
├────────────────────┼────────────┼────────────┼──────────┼─────┤
│ * * * * * *        │    73.55ms │    37.43ms │   49.10% │  ↑  │
├────────────────────┼────────────┼────────────┼──────────┼─────┤
│ 0 * * 1,4-10,L * * │  3504.51ms │  2338.42ms │   33.27% │  ↑  │
├────────────────────┼────────────┼────────────┼──────────┼─────┤
│ 10-30/2 2 12 8 0   │  3111.18ms │  2234.32ms │   28.18% │  ↑  │
├────────────────────┼────────────┼────────────┼──────────┼─────┤
│ 0 0 0 * * 4,6L     │  9400.33ms │  6825.61ms │   27.39% │  ↑  │
├────────────────────┼────────────┼────────────┼──────────┼─────┤
│ 0 12 */5 6 *       │  7442.68ms │  5645.95ms │   24.14% │  ↑  │
├────────────────────┼────────────┼────────────┼──────────┼─────┤
│ 0 15 */5 5 *       │  6998.87ms │  5443.22ms │   22.23% │  ↑  │
├────────────────────┼────────────┼────────────┼──────────┼─────┤
│ 0 0 6-20/2,L 2 *   │  8832.87ms │  6947.63ms │   21.34% │  ↑  │
├────────────────────┼────────────┼────────────┼──────────┼─────┤
│ 0 0 0 * * 1L,5L    │ 15416.07ms │ 12474.12ms │   19.08% │  ↑  │
├────────────────────┼────────────┼────────────┼──────────┼─────┤
│ 10 2 12 8 7        │  7105.79ms │  5947.91ms │   16.29% │  ↑  │
└────────────────────┴────────────┴────────────┴──────────┴─────┘

Benchmarks can be run locally by executing the command.:

npm run bench

Individual patterns can be benchmarked by executing bench:pattern command:

npm run bench:pattern "* * * * * *"