✨ New design for creating types

[LVMVRQUXL]

Our current API providing a heavy usage of the Result type and extension functions for creating types, we would like to improve the design by providing constructors, constructor-like functions for interfaces, and orNull factory functions on companion object instead.

Here's an example of creating a PositiveInt:

// Actual
val first: PositiveInt = 123.toPositiveInt().getOrThrow()
val second: PositiveInt? = 123.toPositiveInt().getOrNull()

// Idea
val first = PositiveInt(123)
val second: PositiveInt? = PositiveInt.orNull(123)

The orNull function being replaceable by using the runCatching function, we are also considering only providing constructors and constructor-like functions.

// These calls produce the same result
val first: PositiveInt? = PositiveInt.orNull(123)
val second: PositiveInt? = runCatching { PositiveInt(123) }.getOrNull()
println(first == second) // true

[LVMVRQUXL]

Another approach would be to provide only factory functions prefixed with from that should explicit describe their behavior in their name. For example, we could define the following functions for the PositiveInt type:

fun PositiveInt.Companion.fromNumber(number: Number): PositiveInt = TODO()
fun PositiveInt.Companion.fromNumberOrNull(number: Number): PositiveInt? = TODO()

fun PositiveInt.Companion.fromString(value: Any): PositiveInt = TODO()
fun PositiveInt.Companion.fromStringOrNull(value: Any): PositiveInt? = TODO()

Here's an example of calling these functions from Kotlin code:

PositiveInt.fromNumber(123)
PositiveInt.fromNumberOrNull(-1.5) // returns null

PositiveInt.fromString("123")
PositiveInt.fromStringOrNull("oops") // returns null

For improving the user experience from Java code, we should also omit the Companion type by using the @JvmStatic annotation. This way, calling these functions from Java code is similar to Kotlin code.

PositiveInt.fromNumber(123);
PositiveInt.fromNumberOrNull(-1.5); // returns null

PositiveInt.fromString("123");
PositiveInt.fromStringOrNull("oops"); // returns null

[LVMVRQUXL]

For improving the design for Kotlin and Java users, we could simply provide constructors for Kotlin and Java and orNull factory functions only for Kotlin users. Here's an example for the PositiveInt type:

fun PositiveInt(number: Int): PositiveInt

@JvmSynthetic // makes it unavailable from Java sources
fun PositiveInt.Companion.orNull(number: Int): PositiveInt?