How to define external functions that return type unions in Kotlin/JS?

Question

I'm writing external declarations for LeafletJS 1.8.0, a JavaScript library, using Kotlin 1.6.21.

The Polyline class has a function, getLatLngs() that can return any of these types:

• Array<LatLng>
• Array<Array<LatLng>>
• Array<Array<Array<LatLng>>>

Of course the setter is easy to overload to handle a type-union

open external class Polyline {
  open fun setLatLngs(latlngs: Array<LatLng>): Polyline<T>
  open fun setLatLngs(latlngs: Array<Array<LatLng>>): Polyline<T>
  open fun setLatLngs(latlngs: Array<Array<Array<LatLng>>>): Polyline<T>
}

However it's not possible to overload the getter

open external class Polyline {
  // ERROR: Conflicting overloads
  open fun getLatLngs(): Array<LatLng>
  open fun getLatLngs(): Array<Array<LatLng>>
  open fun getLatLngs(): Array<Array<Array<LatLng>>>
}

As a compromise I can set the return type to dynamic and add a comment so users can see the intention.

open external class Polyline {
  open fun getLatLngs(): dynamic /* Array<LatLng> | Array<Array<LatLng>> | Array<Array<Array<LatLng>>> */
}

There's an open ticket KT-13108, and an update in November 2021 indicates direct Kotlin support for type unions won't be available until after Kotlin 1.7 is released.

Is there a better way of implementing the external function so the return type is type safe, or users can see the available types that might be returned, and handle each appropriately? What's the idiomatic practice?

Answer 1

Problem:

You are looking for an idiomatic way to describe union types for external declarations with:

1. Type safety (to ensure protect against runtime exceptions)
2. Output Type Annotations (for documentation purposes and also IDE code completion)
3. Control flow that handles each type in the union (so the union type can be used in Kotlin)

Long story short, for any general representation of a JS union-type in Kotlin, it's not possible to hit all three of these criteria without having more information about the instances of those types (due to type-erasure which I'll explain). But, In your case and the vast majority of cases, there is a nice trick to do this by using Kotlin's extension functions.

Solution:

There are two cases that I'll explain what to do to hit these criteria as best as possible:

1. Union of types that don't use generics (like Cat | Dog | string)
2. Union of types that do use generics (This is your case as Array<LatLng>, Array<Array<LatLng>>, and Array<Array<Array<LatLng>>> each use Generics for their types)

Union types that don't use Generics:

Say you had the Kotlin external declaration for AnimalOwner that is currently using dynamic as an output for its getPet method:

AnimalOwner.kt (draft)

/*
    pretend right here that the package is declared
     and file:JsModule decorators are present
*/

external class Cat
external class Dog

external class AnimalOwner {
    fun setPet(pet: Cat) // sets the owner's pet to a Cat
    fun setPet(pet: Dog) // sets the owner's pet to a Dog
    fun setPet(pet: String) // sets the owner's pet to a String

    fun getPet(): dynamic // Union of types (Cat, Dog, String)
}

One can specify an external interface to represent the output type. Then, using extension functions, one can define how to cast/morph each instance into each type (or return null if it can't):

Pet.kt

/*
    pretend right here that the package is declared
      However, JsModule decorators are NOT (and cannot be) present here
*/


// created an interface and gave it an arbitrary name that fits
//  what the output to getPet would represent
sealed external interface Pet // we sealed Pet to disallow others from inheriting it

// Create extension functions with fitting names which cast/morph to each type
//  (these are not defined externally, they are defined in Kotlin itself):

inline fun Pet.asCat(): Cat? = this as? Cat
inline fun Pet.asDog(): Dog? = this as? Dog
inline fun Pet.asString(): String? = this as? String
    

Now, we can replace the dynamic keyword in AnimalOwner with Pet (the interface just created):

AnimalOwner.kt (revised)

/*
    pretend right here that the package is declared
     and JsModule decorators are present
*/

external class Cat
external class Dog

external class AnimalOwner {
    fun setPet(pet: Cat)
    fun setPet(pet: Dog)
    fun setPet(pet: String)

    fun getPet(): Pet // <- changed from dynamic to Pet
}

We can now use AnimalOwner by calling each extension function and checking if it is null or not:

fun printPetOf(animalOwner: AnimalOwner) {
    val pet = animalOwner.getPet()
    pet.asCat()?.also { cat -> console.log("I have a Cat") }
    pet.asDog()?.also { dog -> console.log("I have a Dog") }
    pet.asString()?.also { animalStr -> console.log("I have a $animalStr") }
}

fun test() {
    val johnSmith = AnimalOwner()
    johnSmith.setPet(Cat()) // johnSmith has a cat
    printPetOf(johnSmith) // console: "I have a Cat"
    
    johnSmith.setPet(Dog()) // johnSmith now has a dog
    printPetOf(johnSmith) // console: "I have a Dog"

    johnSmith.setPet("Mouse") // johnSmith now has a Mouse
    printPetOf(johnSmith) // console: "I have a Mouse"
}

Union types that do use Generics:

This case is a little more complicated due to type-erasure. Let's use a similar example to AnimalOwner where now the owner is specifying lists of Dogs, Cats, or a String of animals:

AnimalOwner.kt (draft)

/*
    pretend right here that the package is declared
     and JsModule decorators are present
*/


external class Cat
external class Dog

external class AnimalOwner {
    fun setPets(pets: List<Cat>) // sets the owner's pets to be a list of Cats
    fun setPets(pets: List<Dog>) // sets the owner's pets to be a list of Dogs
    fun setPets(pets: String) // sets the owner's pets to a String

    fun getPets(): dynamic // Union of types (List<Cat>, List<Dog>, String)
}

At this point, if we attempt to do the same procedure to create an output type as before, we run into a problem when creating casting/morphing functions:

Pets.kt (ERROR)

/*
    pretend right here that the package is declared
      However, JsModule decorators are NOT (and cannot be) present here
*/


sealed external interface Pets // we sealed Pets to disallow others from inheriting it

inline fun Pets.asCats(): List<Cat>? = this as? List<Cat>  // Possible Bug
inline fun Pets.asDogs(): List<Dog>? = this as? List<Dog>  // Possible Bug
inline fun Pets.asString(): String? = this as? String 

Specifically, we must change the following code this as? List<Cat> and this as? List<Dog> because Generics Types like List<T> lose information on the generic parameter T at runtime. This loss of information is called type-erasure (for more information see here). We must replace this with this as? List<*> for both extension methods because we can't know generics at runtime. This now creates another problem, as of now we cannot delineate between a list of Dogs and a list of Cats. This is where we require some outside knowledge of instances of these lists and how JavaScript getPets() method treats them. This is project specific so for the sake of this example I am going to pretend I have done some research to determine this outside knowledge we speak of.

So let's say we found out that our corresponding JavaScript method for getPets() always represents the returning of an empty list as list of Cats. Now we have enough information to correct our code to delineate List<Cats> and List<Dog> even though we only have access to List<*>:

Pets.kt (revised)

/*
    pretend right here that the package is declared
      However, JsModule decorators are NOT (and cannot be) present here
*/

sealed external interface Pets

inline fun Pets.asCats(): List<Cat>? {
    val listOfSomething = this as? List<*>
    return listOfSomething?.let {
        if (it.isEmpty() || it[0] is Cat) {
            @Suppress("UNCHECKED_CAST")
            it as List<Cat>
        } else {
            null
        }
    }
}

inline fun Pets.asDogs(): List<Dog>? {
    val listOfSomething = this as? List<*>
    return listOfSomething?.let {
        if (it.isNotEmpty() && it[0] is Dog) {
            @Suppress("UNCHECKED_CAST")
            it as List<Dog>
        } else {
            null
        }
    }
}

inline fun Pets.asString(): String? = this as? String

Now, in AnimalOwner, we can change the output type of getPets from dynamic to Pets:

AnimalOwner.kt (revised)

/*
    pretend right here that the package is declared
     and JsModule decorators are present
*/


external class Cat
external class Dog

external class AnimalOwner {
    fun setPets(pets: List<Cat>)
    fun setPets(pets: List<Dog>)
    fun setPets(pets: String)

    fun getPets(): Pets // <- changed from dynamic to Pets
}

We can then use AnimalOwner the same way as the non-Generic case:

fun printPetOf(animalOwner: AnimalOwner) {
    val pets = animalOwner.getPets()
    pets.asCats()?.also { cats -> console.log("I have Cats") }
    pets.asDogs()?.also { dogs -> console.log("I have Dogs") }
    pets.asString()?.also { animalsStr -> console.log("I have $animalsStr") }
}

fun test() {

    val johnSmith = AnimalOwner()
    johnSmith.setPets(listOf(Cat(), Cat())) // johnSmith has two cats
    printPetOf(johnSmith) // console: "I have Cats"

    johnSmith.setPets(listOf<Cat>()) // johnSmith has an empty room of cats (I wonder where they went)
    printPetOf(johnSmith) // console: "I have Cats"

    johnSmith.setPets(listOf<Dog>()) // johnSmith STILL has 0 cats (Schrodinger's cats?)
    printPetOf(johnSmith) // console: "I have Cats"

    johnSmith.setPets(listOf(Dog(), Dog(), Dog())) // johnSmith has 3 dogs
    printPetOf(johnSmith) // console: "I have Dogs"

    johnSmith.setPets("a Mouse, a Horse, and a Sheep") // johnSmith now has "a Mouse, a Horse, and a Sheep"
    printPetOf(johnSmith) // console: "I have a Mouse, a Horse, and a Sheep"
}

Answer 2

I would approach this problem like this.

Step 1: Create an abstract external return type say LatLngResult

external interface LatLngResult

Step 2: Set this return type as the return type to your methods returning unions

open external class Polyline {
  open fun getLatLngs(): LatLngResult
}

Step 3: Add extension functions to cast your return type as desired

inline fun LatLngResult.asArray1() = asDynamic<Array<LatLng>>()

inline fun LatLngResult.asArray2() = asDynamic<Array<Array<LatLng>>>()

inline fun LatLngResult.asArray3() = asDynamic<Array<Array<Array<LatLng>>>>()

Step 4: Use the function

val res: LatLngResult = polyline.getLatLngs()

// case 1
val array1 : Array<LatLng> = res.asArray1()

// case 2
val array2 : Array<Array<LatLng>> = res.asArray2()

// case 3
val array3 : Array<Array<Array<LatLng>>> = res.asArray3()

Note 1: Just like you would approache it in typescript, you still need to know when is it convinient to use array1, array2, array3

Note 2: Specifying types is still optional in kotlin, I just added them here to make this answer easily digestable