Implements Union Type for JavaScript, JVM, and Native, supporting TypeScript unions and control flow operations like 'map'. Enables external declarations and type-safe computations across platforms.
This library adds Union Types to Kotlin that has multiplatform support; it may be used in Kotlin JVM and Kotlin Native. This library supports representing external typescript unions so kotlin code can easily interface with npm libraries in a type-correct way for KotlinJS.
Kotlin Unions is not a feature not part of the language currently. This library supports creating kotlin unions types to match union types described in typescript (that is, literals, and external JS objects). Although other unions-like structures are very nicely implemented through sealed interfaces and classes, they cannot support unwrapping into JavaScript objects, making them a poor candidate for external declarations in KotlinJS.
The implementation posed here is used to solve externally declared unions while also providing implementations for other multiplatform types (Kotlin JVM and Kotlin Native).
Union types would not be useful if they did not have nice control flow features along with them. That's why this implementation has operators such 'morph' that is a unique but useful control flow that is close to Kotlin's 'when' statement/expression.
Although kotlin-union can be used as general purpose union types for regular JVM project, a big use case is for KotlinJS. For example, say you have an external declaration for a typescript function or type that happens to use a union of types. For example, a function that takes in a color that can be either a number or a string literal:
SomeTypeScriptLibrary.ts:
type Color = number | "red" | "green" | "blue"
function setColor(color: Color) {
// ... code body ...
}
function getColor(): Color {
// ... code body ...
}
At the current moment (1/_/2025), KotlinJS has no better way of express the union type in a type safe manner from an external typescript library than to use dynamic, which is not type safe.
ColorExternal.kt: (without kotlin-union)
// KotlinJS external declaration
external fun setColor(color: dynamic)
external fun getColor(): dynamic
Using kotlin-union, unions types can be created even with external declarations for them:
ColorExternal.kt: (with kotlin-union)
// KotlinJS external declaration
external fun setColor(color: Union<ColorCases>) // FIXED with kotlin-union
external fun getColor(): Union<ColorCases> // FIXED with kotlin-union
One just needs to specify the cases ColorCases within the union:
Color.kt:
// Union cases of typescript type: number | "red" | "green" | "blue"
object ColorCases: MatchCases<ColorCases>() {
val HEX by union(JsNumberCases)
RED obj()
GREEN obj()
BLUE obj()
}
JsNumberCases: MatchCases<JsNumberCases>() {
INT instance<>()
FLOAT instance<>()
}
With union-kotlin unions can be created and protected by type-checking and union values can be appropriately syntax-highlighted by linters (unlike values of dynamic). For control-flow and creating Union types, see the usage section below. Also see the general rules of thumb section for correct usage of this library.
Through gradle (Make sure that you have mavenCentral() in the list of repositories):
repositories {
mavenCentral()
}
val kotlinUnionVersion = "2.0.1"
// this is within commonMain for multiplatform projects
dependencies {
implementation("io.github.mackimaow:kotlin-union:$kotlinUnionVersion")
}
Through maven:
<dependencies>
<dependency>
<groupId>io.github.mackimaow</groupId>
<artifactId>kotlin-union</artifactId>
<version>2.0.1</version>
</>
If the project is platform specific, change the artifact id.
Artifact IDs:
kotlin-union-jskotlin-union-jvmkotlin-union-nativeThen import it into your project:
import io.github.mackimaow.kotlin.union.*
// ... code ...
Creating Union types requires creating a corresponding UCases object (either by creating an object of type MatchingCases or DiscernCases) and then adding cases by calling protected methods obj, instance, instanceWhen, union, and then using to register it to that union-cases object.
Consider the follow example (as laid out in the motivation section):
// Union cases of typescript type: number | "red" | "green" | "blue"
object ColorCases: MatchCases<ColorCases>() {
val HEX by union(JsNumberCases)
RED obj()
GREEN obj()
BLUE obj()
}
JsNumberCases: MatchCases<JsNumberCases>() {
INT instance<>()
FLOAT instance<>()
}
All the possible protected methods that add cases to the union-cases object are as follows:
To create custom cases, create an extension function with UCaseSupplier. For example, say that we want to create that is shorthand for creating a js-number. We can do the following:
// custom case jsNumber():
fun <CS: UCases<CS>> UCaseSupplier<CS>.number() = union(JsNumberCases)
Now, whenever a cases object is created, the number() function is exposed via the case protected property to create a js-number case. For example, we could define ColorCases object alternatively as:
object ColorCases: MatchCases<ColorCases>() {
val HEX by case.number() // using the custom case
val RED by obj("red")
val GREEN by obj("green")
val BLUE by obj("blue")
}
One may also treat the union-cases object as an enumeration. Access cases or nameToCase properties to get all the cases in the union-cases object. For example:
val cases: List<UCase<ColorCases, *>> = ColorCases.cases
val nameToCase: Map<String, UCase<ColorCases, *>> = ColorCases.nameToCase
Each UCase has a name and ordinal:
val redCase: UCase<ColorCases, *> = ColorCases.RED
println(redCase.name) // "RED"
println(redCase.ordinal) // 1
Values are converted into unions by wrapping into a union object, although what actually happens within the library implementation is a little bit more complicated. The underlining data type of Union depends on what platform is being used:
Union. This is needed to support external union declarations.Regardless of the platform, the usage of the library remains the same and the wrapper type is a private implementation detail. To create a union value, use wrap() from either the MatchCases object or from a specific UCase. You may also use the extension function Any?.wrapAs() to create union values. For example, to create a union value of type ColorCases:
// --- Creating unions by wrapping ---
// Wrapping directly on case assures the type of union:
redColor: Union<ColorCases> = ColorCases.RED.wrap()
greenColor: Optional<Union<ColorCases>> = ColorCases.wrap()
blueColor: Optional<Union<ColorCases>> = .wrapAs(ColorCases)
yellowColor: Optional<Union<ColorCases>> = .wrapAs(ColorCases)
intNumber: Union<JsNumberCases> = .wrapAs(JsNumberCases.INT)
intColor: Union<ColorCases> = intNumber.wrapAs(ColorCases.HEX)
floatColor: Optional<Union<ColorCases>> = .wrapAs(ColorCases)
To unwrap a union value in a platform independent way, use Union.unwrap(). This will return a type of Any? regardless of the union type.
// Suppose some function getColor() exists
val myColor: Union<ColorCases> = getColor()
val unwrappedColorValue: Any? = myColor.unwrap()
unwrap() is useful when one would like to perform equality checks on the unwrapped value. If type-correct unwrapping is preferred, one must use the union-specific control-flow functions described in the section below.
To check whether a type of instance obj is part of the union, refrain from using the is keyword because it does not work on all platforms. Rather use MatchCases.canWrap(obj) method:
val colorString = "red"
println(ColorCases.canWrap(colorString)) // true
val notAColorString = "strawberry"
println(ColorCases.canWrap(notAColorString)) // false
Given a Union<ColorCases>, one can use Union.alsoWhen to distinguish between types to perform type-safe computations. Union.alsoWhen is similar to kotlin's extension function Any?.also but with an additional case parameter to run a block specifically if the union is this case:
// for the sake of the example, getColor() returns a Union<ColorCases>
val color: Union<ColorCases> = getColor()
color.alsoWhen(ColorCases.HEX) { hexColor: Union<JsNumberCases> ->
hexColor.alsoWhen(JsNumberCases.INT) { intColor: Int ->
println("I'm an integer color: $intColor")
}.alsoWhen(JsNumberCases.FLOAT) { floatColor: Float ->
println("I'm a float color: $floatColor")
}
}.alsoWhen(ColorCases.RED) { red: String ->
println("I'm a color")
}.alsoWhen(ColorCases.GREEN) { green: String ->
println()
}.alsoWhen(ColorCases.BLUE) { blue: String ->
println()
}
One can write this even more cleanly by using kotlin with statements:
val color: Union<ColorCases> = getColor()
with(ColorCases) {
with(JsNumberCases) {
color.alsoWhen(HEX) { hexColor ->
hexColor.alsoWhen(INT) {
println("I'm an integer color: $it")
}.alsoWhen(FLOAT) {
println("I'm a float color: $it")
}
}.alsoWhen(RED) {
println("I'm a $it color")
}.alsoWhen(GREEN) {
println("I'm a $it color")
}.alsoWhen(BLUE) {
println("I'm a $it color")
}
}
}
You may also use any of the other kotlin control flow extension functions that are fitted into the union type. Here is the table of all of them:
Although the union functions declared above should be able to handle type-safe control flow for any use case, it can become more verbose than necessary. For this reason, the library provides a unique control flow function called morph() (and morphSelf() which returns a different value of the same union). This function's purpose is to translate the corresponding union type into another type in a less verbose way; it takes-in a lambda that has access to the current value of the union (via current), and that lambda allows changes to this current value of the union by calls of , , . Besides these functions, the receiver has access to all the kotlin-inspired control flow functions for union as discussed above. For example:
As said previously, the kotlin inspired functions can be used within morph, but morph has additional values/function to use for control flow. Here is the table of all of them:
Due to type erasure in Kotlin, it's not possible to check whether a given instance is of a type with specific generic parameters at runtime. This needs to be considered when constructing type options for the union using this library. For example, a List<T> has the generic parameter T, which cannot be known at runtime.
There is a way combat this: if one defines a union with a List<T> union case specific with T, a matcher (lambda) must be defined to distinguish this type. Even if a matcher is provided, the empty list of type List<T> is impossible to check the specific type parameter T at runtime. It is strongly encouraged (to avoid bugs) to separate the ambiguous types as their own case and treat them as such:
Every time one of the control-flow functions are used, the matcher lambda is called to check if the union is of that type. As can be seen within the list example above, this call to matcher can be computationally expensive as each check requires checking if all elements of the list are of a certain type. To combat this, one may alternatively create union cases by having the cases object extend DiscernCases instead of MatchCases, where the lambda only needs to differentiate between other cases within union rather than match the type completely:
Although DiscernCases is more efficient than MatchCases, you lose the ability to use canWrap() and wrap() since --if they were allowed-- certain cases would break type-correctness. Therefore, these methods are not implemented for DiscernCases objects. For similar reasons, the union() function (that specifies a union case) cannot take in a DiscernCases object as a parameter.
To make the code more readable, it is recommended to use the following conventions:
For usage only older versions, see the following links:
unionWhen| Case registering function | How the case accepts an object |
|---|
obj() | Checks by equality |
instance() | Checks by type |
instanceWhen() | Checks by type and a specified condition |
union() | Checks by union type |
unionWhen() | Checks by union type and a specified condition |
| Union Function | Inspired Kotlin Function |
|---|
Union.alsoWhen() | Any?.also() |
Union.runWhen() | Any?.run() |
Union.letWhen() | Any?.let() |
Union.applyWhen() | Any?.apply() |
Union.takeIfWhen() | Any?.takeIf() |
Union.takeUnlessWhen() | Any?.takeUnless() |
changeWhen()changeByMorph()changeByMorphingCase()val myColor: Union<ColorCases> = getColor()
// morph color union to boolean
val isFavoriteColor: Boolean = myColor.morph {
// I have access to the current value of the union, which
// --at the moment-- is equal to myColor
println(current == myColor) // true
changeByMorph(ColorCases.HEX) {
changeWhen(JsNumberCases.FLOAT) {
val intHex: Int = (this * 255).toInt()
JsNumberCases.INT.wrap(intHex)
}
runWhen(JsNumberCases.INT) {
if (this < 256)
ColorCases.BLUE.wrap()
else
return@morph false
}.getOrThrow()
}
alsoWhen(ColorCases.GREEN) { green: String ->
println("I don't like $green!")
}
runWhen(ColorCases.BLUE) {
println("I love $this!")
true
}.orElse {
false
}
}
| Morph Function | Description Kotlin Function |
|---|
current | The current union value within the morph block |
changeWhen() | This function changes current given a certain union case |
changeByMorph() | Same as changeWhen() but can change a union case by a nested morph |
changeByMorphingCase() | Same as changeByMorph() but changes a union case into another instance of that same union case |
// Union of List<Float> | List<Int>
object NumbersCases: MatchCases<NumbersCases>() {
// add matcher to distinguish List<Float>
val FLOATS by instance<List<Float>> { obj: Any? ->
val possibleList = obj as? List<*>
if (possibleList != null) {
// make sure to shallow copy the list incase it's mutable
val list = possibleList.toList()
if (list.isNotEmpty() && list.all { item -> item is Float }) {
val floatList = list as List<Float>
return@instance Optional.Some(floatList)
}
}
return@instance Optional.None
}
// add matcher to distinguish List<Int>
val INTS by instance<List<Int>> { obj: Any? ->
val possibleList = obj as? List<*>
if (possibleList != null) {
// make sure to shallow copy the list incase it's mutable
val list = possibleList.toList()
if (list.isNotEmpty() && list.all { item -> item is Int }) {
val intList = list as List<Int>
return@instance Optional.Some(intList)
}
}
return@instance Optional.None
}
// add the ambiguous empty list case with its own matcher
val AMBIGUOUS_LIST by instance<List<*>> { obj: Any? ->
val possibleList = obj as? List<*>
if (possibleList != null) {
// make sure to shallow copy the list incase it's mutable
val list = possibleList.toList()
if (list.isEmpty())
return@instance Optional.Some(list)
}
return@instance Optional.None
}
}
// Union of List<Float> | List<Int>
object NumbersCases: DiscernCases<NumbersCases>() {
// add differentiator to distinguish List<Float>
val FLOATS by instance<List<Float>> { obj: Any? ->
val list = obj as? List<*>
if (list != null) {
// only now have to check if the first element is a float
if (list.isNotEmpty() && list[0] is Float) {
val floatList = list as List<Float>
return@instance Optional.Some(floatList)
}
}
return@instance Optional.None
}
// add differentiator to distinguish List<Int>
val INTS by instance<List<Int>> { obj: Any? ->
val list = obj as? List<*>
if (list != null) {
// only now have to check if the first element is a int
if (list.isNotEmpty() && list[0] is Int) {
val intList = list as List<Int>
return@instance Optional.Some(intList)
}
}
return@instance Optional.None
}
// add the ambiguous empty list case with its own differentiator
val AMBIGUOUS_LIST by instance<List<*>> { obj: Any? ->
val possibleList = obj as? List<*>
if (possibleList != null) {
// make sure to shallow copy the list incase it's mutable
val list = possibleList.toList()
if (list.isEmpty())
return@instance Optional.Some(list)
}
return@instance Optional.None
}
}
instance<T>() and instanceWhen<T>() within either MatchingCases or DiscernCases, if type argument T has generic arguments (e.g. instance<List<String>>(), instance<Map<String, Boolean>>(), etc.), one must supply the matcher/differentiator lambda to distinguish the type to combat type-erasure. Otherwise, it's not type safe! Fortunately, if this is done incorrectly, the library will throw an exception during runtime immediately when that UCases object is created.DiscernCases when the matcher check is expensiveUnion as if they were wrapped in another object. Use Union.unwrap() to get the value that is wrapped in the union. Use canWrap() to check if a value can be wrapped into a union.is to check if a value is a union type.val COLOR by instance<Int>()), not by setting (i.e. DO NOT do this val COLOR = instance<Int>())!MatchingCases or DiscernCases as an object. Other ways are functional, but this is the most readable.MatchingCases or DiscernCases should be prepended by Cases (e.g. ColorCases, NumberCases, etc.).HEX, RED, GREEN, BLUE, etc.).obj, instance, instanceWhen, union, unionWhen or by calling a custom extension function on UCaseSupplier (e.g. case.number() as described in previous sections).Surfaced from shared tags and platforms — no rankings paid for.