#MoonCron

#Features

• Standard 5-field expressions: minute hour day-of-month month day-of-week
• Extended 6-field expressions with seconds
• Values, lists, ranges, steps, and range-with-step syntax
• Seven aliases: @hourly, @daily, @midnight, @weekly, @monthly, @yearly, and @annually
• Detailed validation errors
• Date/time matching with cron day-of-month OR day-of-week semantics
• Previous, next, bounded, and range-based execution-time queries
• English and Chinese descriptions
• Fluent CronBuilder and quick constructors
• Normalization, equivalence checks, field set operations, and frequency analysis
• CLI commands for validation, description, calculation, and matching
• 151 tests across Wasm, Wasm-GC, JavaScript, and Native

#Supported Syntax

# Standard
minute hour day-of-month month day-of-week

# Extended
second minute hour day-of-month month day-of-week

#Installation

import {
  "001-Elsa/mooncron@0.1.4"
}

import {
  "001-Elsa/mooncron" @mooncron,
}

#Library Usage

let cron = @mooncron.CronExpr::parse("*/15 9-17 * * 1-5")

match cron {
  Ok(expr) => {
    let now = @mooncron.DateTime::new(2026, 7, 27, 9, 0)
    println(expr.matches(now).to_string())
    println(expr.describe_en())
    println(expr.describe_cn())

    for time in expr.next_n(now, 5) {
      println(time.to_string())
    }
  }
  Err(err) => println(@mooncron.cron_error_to_string(err))
}

#Common API

pub fn CronExpr::parse(String) -> Result[CronExpr, CronError]
pub fn CronExpr::matches(Self, DateTime) -> Bool
pub fn CronExpr::next_after(Self, DateTime) -> DateTime?
pub fn CronExpr::next_n(Self, DateTime, Int) -> Array[DateTime]
pub fn CronExpr::describe_en(Self) -> String
pub fn CronExpr::describe_cn(Self) -> String

pub fn DateTime::new(Int, Int, Int, Int, Int) -> DateTime
pub fn DateTime::new_with_second(Int, Int, Int, Int, Int, Int) -> DateTime
pub fn DateTime::to_string_with_seconds(Self) -> String
pub fn parse_datetime(String) -> DateTime?

pub fn between(Array[CronField], DateTime, DateTime) -> Array[DateTime]
pub fn count_between(Array[CronField], DateTime, DateTime) -> Int
pub fn prev_before(Array[CronField], DateTime) -> DateTime?
pub fn normalize_expression(String) -> Result[String, CronError]
pub fn are_equivalent(Array[CronField], Array[CronField]) -> Bool

#CLI Usage

# Validate an expression
moon run cmd/main -- check "*/15 9-18 * * 1-5"

# Generate an English description
moon run cmd/main -- explain "0 9 * * 1-5"

# Generate a Chinese description
moon run cmd/main -- describe "0 9 * * 1-5" --cn

# Calculate future execution times
moon run cmd/main -- next "0 9 * * 1-5" --count 5 \
  --time "2026-07-25 12:00"

# Match a specific time
moon run cmd/main -- matches "0 9 * * 1-5" \
  --time "2026-07-27 09:00"

#Validation Errors

61 * * * *          -> invalid minute value 61: expected 0..59
*/0 * * * *         -> step value cannot be 0 in field 'minute'
1--5 * * * *        -> invalid range syntax in field 'minute'
* * * * * * *       -> expected 5 or 6 fields but got 7

#Verification

moon fmt --check
moon check --target all --deny-warn
moon test --target all --deny-warn
moon info
moon package

Total tests: 151, passed: 151, failed: 0.

#Project Structure

mooncron/
├── cmd/main/              # CLI package
├── docs/                  # Design and syntax documentation
├── *.mbt                  # Library source files
├── *_test.mbt             # Tests
├── moon.mod               # Module metadata
├── moon.pkg               # Root package configuration
├── ACCEPTANCE.md          # Acceptance checklist
├── MoonCron项目申报书.md  # Competition application
└── LICENSE

#Project Boundaries

• Actual task execution or a background scheduler
• Distributed scheduling or task persistence
• A web UI or user system
• Timezone or daylight-saving-time support
• Quartz extensions (L, W, #)
• A year field (7-field format)
• Natural-language-to-cron conversion
• AI integration

#Roadmap

• Timezone and daylight-saving-time support
• Quartz extensions (L, W, #)
• Year field support
• Cron expression visualization
• Natural-language-to-cron conversion

#License