Stardust

Stardust is a software library containing a lot of powerful features that make the programmer’s life much easier. Stardust is my main project that I’ve been working on for many years. I’m developing the library with Kotlin as a multi-platform project with JVM and JavaScript as target platforms. The library is designed as an extension to Kotlin's standard API.

The Stardust library is open source software. It is licensed under the terms of the Apache License, Version 2.0. You can find the source code on GitLab: https://gitlab.com/jmpersch/stardust.

Stardust consists of different modules that can be included to fit your needs. The following sections provide a brief overview of the modules by showing some selected features.

Main Module

---

Artifact:

cc.persch:stardust

String Building

String formatting was yesterday—with Kotlin’s type-safe builders, we have new capabilities to build things directly with Kotlin code. The Stardust library provides type-safe builders to comfortably create strings especially for the localization of multilingual applications.

fun ShoppingCart.makeString() = rope {

    +"Your shopping cart "

    if(size > 0) {

        +"contains "

        if(size > 1)
            +"$size"
        else
            +"one"

        +" item"
        plural(size, "s")
    }
    else
        +"is empty"

    +"."
}

println("Empty shopping cart:               ${ShoppingCart(0).makeString()}")
println("Shopping cart containing 1 item:   ${ShoppingCart(1).makeString()}")
println("Shopping cart containing 42 items: ${ShoppingCart(42).makeString()}")

Empty shopping cart:               Your shopping cart is empty.
Shopping cart containing 1 item:   Your shopping cart contains one item.
Shopping cart containing 42 items: Your shopping cart contains 42 items.

Extension Modules

---

CEH Computation Utility

Artifact:

cc.persch:stardustx-cehc

Provides utils to implement the equals, hashCode, and compareTo functions in a declarative manner.

Collections

Artifact:

cc.persch:stardustx-collections

Mutable Collections

val mutableList: MutableList<Int> = mutableListOf(1, 2, 3, 4, 5)

// Get an immutable view of the mutable list
val immutableView: ImmutableList<Int> = mutableList.asImmutable()

// Altering the original list …
mutableList.add(6)

println("Mutable list:   $mutableList")

// … also changes the immutable view
println("Immutable view: $immutableView")

Mutable list:   [1, 2, 3, 4, 5, 6]
Immutable view: [1, 2, 3, 4, 5, 6]

Persistent Collections

// Create a persistent list that is guaranteed to be immutable
val persistentList1: PersistentList<Int> = persistentListOf(1, 2, 3, 4, 5)

// Create a mutated persistent copy of the original list
val persistentList2: PersistentList<Int> = persistentList1.mutate { add(6) }

println("Original list: $persistentList1")
println("Mutated copy:  $persistentList2")

Original list: [1, 2, 3, 4, 5]
Mutated copy:  [1, 2, 3, 4, 5, 6]

Date and Time

Artifact:

cc.persch:stardustx-datetime

Stardust provides date and time classes with comfortable handling.

val date = Date.utcCurrent()

val dateTime = DateTime.utcNow()

val timeSpan = dateTime.minus(date.toUtcDateTime())

println("Date:     $date")
println("DateTime: $dateTime")
println("TimeSpan: $timeSpan")

Date:     2023-11-18
DateTime: 2023-11-18 18:03:19.921 UTC
TimeSpan: 0.18:03:19.921

Event Handling

Artifact:

cc.persch:stardustx-events

Stardust provides an easy-to-use event mechanism.

// Subscribe an event
eventSource.subscribe { _, arg -> println("Hello, ${arg.value}!") }

// Raise an event
eventSource.raise(this, EventArgument("Kotlin Notebook"))

Hello, Kotlin Notebook!

Results

Artifact:

cc.persch:stardustx-results

With Conclude and Unsure, Stardust provides two result types. Where Unsure is used to indicate whether there is a result or not, a Conclude additionally contains information about the error.

fun Users.find(username: String): Conclude<User, String> {

    return users.get(username) orFailure { "Username ${username.quote()} not found." }
    //             ↖ User?           ↖ Conclude<User, String>
    //                                      ↖ Either Success<User> or Failure<String>
}

println("""Find "jdoe":   ${users.find("jdoe")}""")
println("""Find "asmith": ${users.find("asmith")}""")

Find "jdoe":   Success(value=John Doe)
Find "asmith": Failure(reason=Username "asmith" not found.)

Text

Artifact:

cc.persch:stardustx-text

UUID

Artifact:

cc.persch:stardustx-uuid

Experimental Module

---

Artifact:

cc.persch:stardusty

This module contains experimental features. The API of this module is unstable and may change anytime.

Documentation

---

Take a look into the documentation of the Stardust library that explains features by showing meaningful sample implementations.

Development History

The development history shows the evolvement of the Stardust library.

---

Use Stardust in Your Software Project

---

The following code sample shows how you can include Stardust in your software project using the Gradle build tool. Select the modules you want use and add them to your build.gradle.kts file.

repositories {

    // The URL to the Maven package registry to retrieve the artifacts of the Stardust library.
    // Find the GitLab repository under: <https://gitlab.com/jmpersch/registry>
    maven("https://gitlab.com/api/v4/projects/41417498/packages/maven")
}

dependencies {

    val stardustVersion = "5.0.0"   

    // Main module
    implementation("cc.persch:stardust:$stardustVersion")

    // Extension modules
    implementation("cc.persch:stardustx-cehc:$stardustVersion")
    implementation("cc.persch:stardustx-collections:$stardustVersion")
    implementation("cc.persch:stardustx-datetime:$stardustVersion")
    implementation("cc.persch:stardustx-events:$stardustVersion")
    implementation("cc.persch:stardustx-results:$stardustVersion")
    implementation("cc.persch:stardustx-text:$stardustVersion")
    implementation("cc.persch:stardustx-uuid:$stardustVersion")

    // Experimental module
    implementation("cc.persch:stardusty:$stardustVersion")
}