✨ New design for factory functions

[LVMVRQUXL]

🤔 The problem

The current stable API provides factory functions encapsulating their result in a Result type.
This is for example the case for the toNonZeroInt factory function.

public fun Number.toNonZeroInt(): Result<NonZeroInt>

But this practice increases the complexity of the API by using a concept that is not widely accepted in the Kotlin community.
Also, the Kotlin team recommends other practices for validating inputs and representing an absence of value using null.

💡 The idea

For all platforms, Kotools Types should provide different types of factory functions for creating types:

• create functions on companion objects that should throw an exception in case of invalid inputs
• createOrNull functions on companion objects that should return null in case of invalid inputs.

For instance, we could add the following factory functions to the PositiveInt type:

fun PositiveInt.Companion.create(number: Number): PositiveInt = TODO()
fun PositiveInt.Companion.createOrNull(number: Number): PositiveInt? = TODO()

Here are examples of calling the PositiveInt.Companion.createOrNull function from Kotlin code:

PositiveInt.createOrNull(23) // 23
PositiveInt.createOrNull(0) // 0
PositiveInt.createOrNull(-7) // null

Here are other examples of calling the same function from Java code:

PositiveInt.Companion.createOrNull(23); // 23
PositiveInt.Companion.createOrNull(0); // 0
PositiveInt.Companion.createOrNull(-7); // null

🙏 Help needed

Please give this post a reaction if you are interested in this change and comment below your thoughts on it.
We would love to have your feedback!

[LVMVRQUXL]

A simpler solution is to provide constructors or constructor-like functions that should throw an exception in case of a failure. They will be easier to use than encapsulating them in companion objects.

Here's an example for the PositiveInt type:

fun PositiveInt(number: Number): PositiveInt

Here's an example of creating a PositiveInt from Kotlin code:

// Before
val number: PositiveInt = 23.toPositiveInt()
    .getOrThrow()
println(number) // 23

// After
val number = PositiveInt(23)
println(number) // 23

Here's an example of creating a PositiveInt from Java code:

// Before
final Object result = PositiveIntKt.toPositiveInt(23);
final PositiveInt number = (PositiveInt) result;
System.out.println(number); // 23

// After
final PositiveInt number = PositiveIntFactory.create(23);
System.out.println(number); // 23

[LVMVRQUXL]

When declared in inline value classes, calling a constructor from Java code produces a compilation error indicating that the constructor can't be found.

The conversion of inline value classes being planed for Kotools Types 5.0, we could introduce create and createOrNull functions like documented in the discussion for first removing the Result type support in 4.* releases (see #587).

After converting inline value classes to regular ones, we could introduce constructors or constructor-like functions for improving the experience of creating types, while deprecating the create and the createOrNull functions for using these constructors instead (see #589).

[LVMVRQUXL]

We've created the topic #587 for implementing this idea.

[lbunschoten]

Hello 👋

I have been following this project a bit on the sidelines lately. I don’t even remember how I found out about it, probably reddit 🤔 Anyway, I like the idea of the project, so I was considering to try it out on a pet project. I also noticed the very structured issues list and documentation. Very nice 👍

Anyway, back to the original discussion.

I have been going through the code a bit and I understand the issues you are having with the java interface. I was wondering if you also considered marking the create and createOrNull methods with the @JvmStatic annotation. If I am not mistaken that would mean we could get rid of the .Companion in java method calls everywhere. That would make it a lot more readable already in my opinion.

One more thing I wanted to add to this discussion. You mentioned that you wanted to convert the value classes back to "normal" classes. I am bit concerned that that might increase the memory overhead quite a bit, which might make the project less suitable for people who want to start using it.

[LVMVRQUXL]

Hello @lbunschoten! 👋

Thank you for commenting your thoughts about Kotools Types. They are valuable to the project and means a lot to us. 🙏

I am glad to read that you like the ideas behind this project and that you are considering trying it out. If you need some help on working with this library, feel free to ask for help in through a Q&A discussion. 🙂

---

We didn't consider marking the create and the createOrNull factory functions with the JvmStatic annotation. Thank you for suggesting, I will include it in the #587 topic! 🙌

---

We want to convert inline value classes back to regular ones for multiple reasons:

1. Inline value classes being replaced by their underlying type at compile-time, they are inexistant in Java, thus incompatible.
2. Due to this inlining mechanism, the validation of these types are ignored during the serialization processes in some environments (like Spring).
3. Using inline value classes exposes consumers of the library to binary compatibility issues, because the Application Binary Interface (ABI) of Kotools Types includes their underlying type (which should be a hidden implementation detail), making the ABI more fragile and incompatible prone.

Now, about the "memory overhead caused by regular classes", you should know that creating an object is not a heavy-memory task for the Java Virtual Machine (JVM). Yes, there is a little bit of memory overhead to do for the JVM when you are creating an object, but this is nothing compared to the reasons listed above. Be careful with these premature optimizations. 😉

[LVMVRQUXL]

We've created the issue #617 for implementing your suggestion @lbunschoten. 🙌