kcron-common

Cron library enables parsing and building complex Cron expressions with intuitive builder functions, supports custom first week days, validates parsing rules, and handles various DateTime libraries.

#date-time

Suggest an edit

JVMKotlin/NativeWasmJS

GitHub stars35

AuthorsScogun

Open issues4

LicenseApache License 2.0

Creation dateover 5 years ago

Last activity2 months ago

Latest release0.31.7 (2 months ago)

GitHub repository Wiki page

KCron

Cron realization for Kotlin Multiplatform

Features

Kotlin Multiplatform library
Parse Cron expressions
- Include L, W, LW, '?' and #
Build Cron expression by smart builder functions:

builder
    .seconds(10 at 0) //Every 10 seconds starting at 0 seconds
    .minutes(5..25) // Every minute between 5 and 25
    .hours(5, 12) // Specific hours: 5 and 12
    .daysOfWeek(7 on 5) // On the 5th Sunday of the month
    .years(2050) // Specific year: 2050

Build Cron expression via Kotlin style function:

cron {
    seconds(10 at 0)//Every 10 seconds starting at 0 seconds
    minutes(5..25) // Every minute between 5 and 25
    hours(5, 12) // Specific hours: 5 and 12
    daysOfWeek(7 on 5) // On the 5th Sunday of the month
    years(2050) // Specific year: 2050
}

Support custom first week day

val builder = Builder(WeekDays.Sunday)
builder
    .daysOfWeek(7 on 5) // On the 5th Saturday of the month

Parsing validation includes combination rules
- 'days' and 'days of week' could not be setup simultaneously
Support
- JVM
- Linux
- Windows (mingwX64)
- macOS
- Javascript
- Wasm
- iOS
Support different DateTime libraries (via DateTime Provider Abstractions)
Provide UI builder for JVM, macOS, JavaScript and iOS on Compose UI multiplatform
- Multilanguage support (English and Russian now)

Usage

KCron-Common library as default implementation uses Kotlinx-DateTime library

Add with Gradle

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation 'com.ucasoft.kcron:kcron-common:0.31.7'
            }
        }
    }
}

Build Cron expression

val builder = Cron.builder()
// By default, builder contains any expression for every part
println(builder.expression) // * * * ? * * *
builder
    .seconds(10 at 0)
    .minutes(5..25)
    .hours(5, 12)
    .daysOfWeek(7 on 5)
    .years(2050)
println(builder.expression) // 0/10 5-25 5,12 ? * 7#5 2050

Parse as Classic as well as Modern Cron expressions

// Auto detect
val builder = Cron.parseAndBuild("0/10 5-25 5,12 ? * 7#5 2050") {
    it.firstDayOfWeek = WeekDays.Sunday
}
@OptIn(DelicateIterableApi::class)
println(builder.asIterable().take(10))
/* Result:
[
    2050-01-29T05:05,
    2050-01-29T05:05:10,
    2050-01-29T05:05:20,
    2050-01-29T05:05:30,
    2050-01-29T05:05:40,
    2050-01-29T05:05:50,
    2050-01-29T05:06,
    2050-01-29T05:06:10,
    2050-01-29T05:06:20,
    2050-01-29T05:06:30
]
*/
// OR Force to parse only Classic expressions
try {
    val builder = Cron.parseAndBuild("0/10 5-25 5,12 ? * 7#5 2050") {
        it.version = Version.Classic
    }
} catch(e: WrongCronExpression) {
    println(e.message) // Expression 0/10 5-25 5,12 ? * 7#5 2050 is not Classic Cron one!
}

Days of week and months can be defined in a parsed expression as numbers as well as short names

builder = Cron.parseAndBuild("15/10 5-25 5 ? JAN,MAR 2,3,4,5 2050")
println(builder.nextRun) // 2050-01-04T05:05:15
// OR
builder = Cron.parseAndBuild("15/10 5-25 5 ? 2-4 MON 2050")
println(builder.nextRun) // 2050-02-07T05:05:15

Easy change any part of expression

val builder = Cron.parseAndBuild("0/10 5-25 5,12 ? * SUN#5 2050")
builder.years(2021..2025)
println(builder.expression) // 0/10 5-25 5,12 ? * SUN#5 2021-2025

Current status

This library is on beta version 0.31.7. It is continuing to develop. Check the news!