Cron-Mbt

Cron-Mbt is a MoonBit cron expression library with a real parser, deterministic matcher, next-trigger calculator, and usable CLI. It is scoped to five-field cron expressions: minute, hour, day-of-month, month, and day-of-week. Time zones, seconds, and year fields are outside the current API boundary.

What It Supports

Standard five-field cron expressions: minute, hour, day-of-month, month, and day-of-week.
Core operators: *, ?, ,, -, /, and L for the last day of month. L is accepted only in the day-of-month field; invalid placements return Err.
Macro aliases: @yearly, @annually, @monthly, @weekly, @daily, @midnight, and @hourly.
Day matching semantics aligned with common cron behavior: when both day-of-month and day-of-week are constrained, either side may satisfy the schedule.
Sunday normalization for both 0 and 7.
Operational APIs for bounded occurrence windows, previous/next batches, business calendars, conflict analysis, diagnostics, registry plans, and execution-policy limits.
A CLI that parses expressions, checks matches, computes next/previous trigger times, explains canonical schedules, validates timestamps, and prints bounded batches.

Why This Revision Matters

The organizer feedback identified concrete gaps in CI, invalid-expression handling, L placement, regression coverage, and release documentation. This revision addresses those items with explicit command stages, parser errors, calendar boundary tests, and a deterministic operations-style corpus.

Project Layout

src/cron/   core parser, matcher, scheduler, tests
src/cli/    command-line interface
benchmarks/ public-API conformance corpus
docs/       architecture, API reference, acceptance notes, source notes
scripts/    validation and baseline helper scripts
.github/    GitHub Actions workflow

Installation

Add the module to your moon.mod import block:

import {
  "cxh04/cron_mbt@0.2.4",
}

Library Usage

Parse and inspect an expression:

let expr = @cron.parse("*/5 8-10 ? * 1-5").unwrap()

Check whether a timestamp matches:

let matched = expr.matches(
  year = 2026,
  minute = 15,
  hour = 9,
  day_of_month = 10,
  month = 6,
  day_of_week = 3,
)

Compute the next trigger time:

let expr = @cron.parse("30 9 * * 1").unwrap()
let current = {
  year: 2026,
  month: 6,
  day: 9,
  hour: 10,
  minute: 0,
}
let next = expr.next_time(current).unwrap()
// 2026-06-15 09:30

CLI Usage

Parse:

moon run src/cli parse "0 9 ? * 1-5"

Next trigger:

moon run src/cli next "30 9 * * 1" 2026 6 9 10 0

Match a timestamp:

moon run src/cli match "15 10 * * *" 2026 6 10 10 15 3

Explain or validate operational input:

moon run src/cli explain "0 0 L * *"
moon run src/cli validate 2026 2 28 9 0
moon run src/cli next-many "0 9 * * 1-5" 2026 8 7 10 0 5

The current repository contains approximately 4,000 lines of effective MoonBit implementation and regression code, including the CLI and acceptance matrix. The source is organized around reusable scheduling operations rather than generated or duplicated filler.

Verification

The local and CI checks are:

moon check --target all --deny-warn
moon build --target all
moon fmt
moon info
moon test --target all --deny-warn
moon test benchmarks
powershell -ExecutionPolicy Bypass -File ./scripts/verify_acceptance.ps1 -SkipMooncakes

The CI workflow uses the official stable MoonBit installer, prints moon version --all, and runs the required moon check, moon build, moon fmt, moon info, and moon test stages on Ubuntu, macOS, and Windows. It also runs the CLI smoke suite on all three platforms. Local acceptance validation is kept compatible with MoonBit 0.10.3; the installer endpoint for that historical binary may return 403, so CI follows the currently available official stable channel.

The deterministic acceptance corpus is under benchmarks/; it covers operations-style schedules, month ends, leap years, calendar transitions, and weekday semantics. scripts/benchmark.ps1 provides a repeatable end-to-end CLI baseline for the current machine. Its timings are regression data, not a portable performance claim.

Mooncakes Status

Module name: cxh04/cron_mbt
Manifest version: 0.2.4
moon publish --dry-run validates packaging before publication
version 0.2.4 contains the acceptance corpus, cross-platform CI, CLI smoke tests, business-calendar scheduling, and documentation fixes

Documents

License

Apache-2.0. See LICENSE.