A previous experimentation has been pushed on Exceptions.

It was practical for our use case at the time but it's leading to more and more subtle issues that we don't want to support. Also it worked only when passing the exception in a method/property, but it cannot be wrapped when a throw is done from Typescript, meaning that a try/catch on the Kotlin will still have to deal with the Typescript Error and not the wrapped exception.

From our learnings, we think it's better to have explicit API with types that don't extends Exception. And if we need to pass it, we'll let KotlinJs deal with it and not trying to interfere here. But for that we need #19 and #17 to be fixed.

As a bonus, it should also reduce the bundle size.

    const abortController = new AbortController();
    const { signal: abortSignal } = abortController;
    var promise = longCompute(abortSignal); // Get a Promise from Kotlin
    abortController.abort(); // Won't work
    
    // Workaround: await just a bit so the promise Kotlin is actually created and listen the `onabort`
    await new Promise((resolve) => {
      setTimeout(resolve, 0);
    });
    abortController.abort(); // Works

The first call to abort() should work.

In some cases, we want to be able to provide companion object methods, for example to build the class. The class itself could have a private constructor, like in this example:

@JvmInline
internal value class DurationMs private constructor(internal val value: Long) {
    init {
        require(value >= 0)
    }

    operator fun plus(t: DurationMs): DurationMs {
        return from(value + t.value)
    }

    fun toSecond(): Int = (value / 1000).toInt()

    companion object {
        fun from(value: Long) = DurationMs(value)
    }
}

Currently we can define an enum like that

enum class Foo(val value: String) {
  ONE("one"), TWO("hey")
}

But once wrapped, there is no way to get the parameters. We don't want to support all super-powers of Kotlin enums right now. Using the given parameter if there is only one string, and returning the value in the facade could be enough.

This results in a compiler error:

@KustomExport
sealed class Foo
@KustomExport
object Bar: Foo()

@SalomonBrys coroutines typescript tests are not running anymore on my side, did not test since Kotlin upgrade, do you know if it's related?

Hi,

Feel free to rename this issue so it is clearer for you 😉 .

With this Kotlin enum:

@KustomExport
public enum class Bar() {
    FIRST, SECOND
}

And this TypeScript code:

const bar = fooInstance.bar // Bar_FIRST
if (bar === Bar_FIRST) {
  console.log('First');
}

The enum instance returned on fooInstance is not guaranteed to be an exported instance of Bar (for example in this case there will be no console.log).

(Hi @glureau 👋 )

Kotlin 1.6.20 brings the support of enum, so using @JsExport on simple enums could be good for performance. Right now the processor expects that all dependencies are also annotated with @KustomExport, but it doesn't check if the classes actually use it or not, leading to project not able to build.

Goal is to scan the dependencies annotations and be able to support JS Export automatically.

Hi! First, just wanted to say thanks for this library. It's made the TypeScript from Kotlin so much nicer to use. :)

I ran into an issue while using with external and have been looking into a fix but I'm fairly new to Kotlin so I could just be doing something wrong. I'm using the latest on the master branch as well as tried with 0.8.0 of KustomExport.

If I have a type exported from Kotlin with @KustomExport (e.g. class Item), create that type in JS (e.g. new Item()), and then send it back through Kotlin, accessing the properties from that object returns undefined.

I have this example Kotlin:

@KustomExport
class Item(
    val id: Long,
    val name: String
)

@KustomExport
class KotlinLibrary(private val js: JsLibrary) {
    fun getItem(): Item {
        return js.getItem()
    }
}

external class JsLibrary {
    fun getItem(): Item = definedExternally
}

and this JS:

export default class JsLibrary {
    getItem(): Item {
        return new Item(1, "Test")
    }
}
// ---
const js = new JsLibrary()
const kt = new KotlinLibrary(js)
const item = kt.getItem()
console.log(item.name) // undefined but should be "Test"

I've been attempting to add support for this use case but thought I'd open an issue just in case you are already familiar with this use case or know a way to support it. I've written a test for the use case here. The first four assertions pass but the others that interface with KustomExport do not pass.

It appears that returning an instance from JS, when it's ran through CommonItem.exportItem(), the getters that proxy to the internal common are no longer connected. I'm new to Kotlin though so that could be incorrect.

Thank you for your time!

A data class that has a map property with type arguments does not get translated correctly. For example:

@KustomExport
data class MapHolder(val map: Map<String, String>) 

Will result in:

2 type arguments expected for interface Map<K, out V>

This project is super cool!

I'm curious if you'd explore a plugin-based architecture.

As an example, we have enums declared like:

enum class MyEnum(val value: String) {
  OPTION_A("option_a"),
  OPTION_B("option_b");
}

We'd love to write a custom rule that lets us export MyEnum as the underlying value (as a lightweight String), rather than a heavier class.

We also have other enum classes that use Ints.

Do you folks think @JsExport will support mapping UInt to numeric as in the future?
https://kotlinlang.slack.com/archives/C0B8L3U69/p1639058809157600

Handling unsigned types should be quite easy to do, if we still go with the rules of mapping to number by default.

@KustomExport
enum class E {
    EnumValue;

    companion object {
        val static = 1
    }
}

generates

@JsExport
public class E internal constructor(
    internal val common: CommonE,
) {
    public val name: String = common.name
}

@JsExport
public fun E_values(): Array<E> = arrayOf(E_EnumValue, E_Companion)

@JsExport
public fun E_valueOf(name: String): E? {
    if (name == E_EnumValue.name)
        return E_EnumValue

    if (name == E_Companion.name)
        return E_Companion

    return null
}

public fun E.importE(): CommonE = common

public fun CommonE.exportE(): E = E_valueOf(this.name)!!

@JsExport
public val E_EnumValue: E = E(CommonE.EnumValue)

@JsExport
public val E_Companion: E = E(CommonE.Companion)

which is an error because Type mismatch: inferred type is E.Companion but E was expected in the last line. The incorrect assumption is made that the companion object is an enum value.

Workaround: Use JsExport instead of KustomExport

Having the following code:

@JsExport
class Tester {
  fun test(f: String = "default value"): String {
    return f
  }
}

Will give this ts output:

class Tester {
    constructor();
    test(f?: string): string;
}

Preserving default value. However, using KustomExport on the same code:

@KustomExport
class Tester {
  fun test(f: String = "default value"): String {
    return f
  }
}

Will generate following kotlin code:

public fun test(f: String): String {
    val result = common.test(
        f = f,
    )
    return result
}

As a result, produced typescript definitions have mandatory parameter f:

class Tester {
    constructor();
    test(f: string): string;
}

For Kotlin data classes, JsExport generates a copy that basically has the same signature as the Kotlin method, i.e. one parameter for each class property. The problem is that JS and TS do not support named arguments, so you always have to specify all parameters. The typical way to simulate this behavior in JS is to use single parameter functions which take in a single object and that object represents a map of parameter names to values.

It seems like a nice feature, if KustomExport could generate alternative copy methods for data classes that are represented by this type of method.

Hi!
I noticed an issue with exporting generic classes. For example, typescript map

@KustomExport
class Foo {
  fun bar(
    map: Map<String>,
  ) {}
}

Will generate following kotlin code:

public fun bar(map: Map): Unit {
    val result = common.bar(
        map = map,
    )
    return result
}

Erasing Map's type

By default Kotlin generate exceptions in the js code but they are not visible in the Typescript code.

By exposing exceptions like CancellationException for Typescript, KustomExport actually generates a duplicated class in the js code. If passing one exception via a method is properly handled, if exception is thrown it's not wrapping the exception. So eventually we ends up with CancellationException and CancellationException_1 in the js code, and the instanceof is failing.

Proposed solution: use external + @JsExport instead of redefining those exception classes.

0.1.1 release actually consider value class as a class:

• if you don't use the annotation on this class, other classes will expect a generated class with the name of the value class, but it doesn't exist
• if you do use the annotation, as it considers it as a class, it'll not work, or generate boilerplate and that's not what we expect from a value class

I think we should generate a typealias for annotated value class, so that it's closer to the expected output of a value class.

JsExport supports @file which is convenient for files with lots of exported classes, to cut down on boilerplate.

Exporting enum to a class to be able to map additional properties and functions is increasing the JS bundle size. An alternative could be to export an enum as a string for example:

@KustomExport(exportMode = ExportMode.Enum.asString)
enum class Direction {
    NORTH, SOUTH, WEST, EAST
}

We could have a default mode to auto that could choose the mode asString or asInt if there is only one String/Int parameter, and choose the full wrapper when there is more than 1 constructor param or a method.

import sample._enum.Direction as CommonDirection // The annotated enum in commonMain

@JsExport
public class Direction internal constructor(
    internal val `value`: CommonDirection
) {
    public val name: String = value.name
}

public fun Direction.importDirection(): CommonDirection = value

public fun CommonDirection.exportDirection(): Direction = Direction(this)

@JsExport
public object Directions {
    public val NORTH: Direction = CommonDirection.NORTH.exportDirection()

    public val SOUTH: Direction = CommonDirection.SOUTH.exportDirection()

    public val WEST: Direction = CommonDirection.WEST.exportDirection()

    public val EAST: Direction = CommonDirection.EAST.exportDirection()
}

import sample._enum.Direction as CommonDirection // The annotated enum in commonMain

typealias Direction = String

public fun Direction.importDirection(): CommonDirection = CommonDirection.valueOf(this)

public fun CommonDirection.exportDirection(): Direction = this.name

@JsExport
public const val Directions_NORTH: Direction = "NORTH"
@JsExport
public const val Directions_SOUTH: Direction = "SOUTH"
@JsExport
public const val Directions_WEST: Direction = "WEST"
@JsExport
public const val Directions_EAST: Direction = "EAST"

Bundle size (js) : 428 chars saved (no compressed) when exporting as strings (vs the full fledged export). A big part of the gain come from removing the object Directions and using (const) val instead, if we keep an object Dimensions the gain is only 14 chars. (So it's probably better to remove the object for the full fledged export, also const as no impact on bundle size.)

Limitations:

• only available when there is no methods/properties (we may be able to use the 1st param instead of name when only one param is defined)
• fun goTo(d: Direction) will be exported as goTo(direction: string); (as expected). It allows passing any string value, but a bad string will generate an IllegalStateException, possibly crashing the app.

Eventually there is an issue today with KSP/KotlinJsIr on multi-modules where external dependencies are not resolvable (WIP). With the current implementation, we expect a class not resolvable to be from another module, and it could be an issue with typealias resolution (not tested yet).

Also a little note about enums, Kotlin 1.6.20 should export enums without an additional layer... https://youtrack.jetbrains.com/issue/KT-37916

If you annotate a sealed class with JsExport, it will export all of the child classes by default. KustomExport does not behave the same way. I found that:

@KustomExport
sealed class Foo {
    data class Bar(val numbers: List<Long>) : Foo()
}

Will fail with a compiler error. It seems the only way to export the child classes is to do:

@KustomExport
sealed class Foo

@KustomExport
data class Bar(val numbers: List<Long>) : Foo()

Exporting sealed class with KotlinJs make the code executable but not compliant with strict typescript rules. (The generated class is not abstract but with abstract fields for example, creating issues on typescript.)

https://youtrack.jetbrains.com/issue/KT-39193

We could generate an abstract class instead: the sealed is important for Kotlin side, but it has no class hierarchy limitation on the JS/TS word, so it's probably nothing more than an abstract class for the facade.

Tools such as Renovate and the gradle-versions-plugin are unable to find version information for KustomExport.

$ ./gradlew dependencyUpdates --info

... 

The exception that is the cause of unresolved state: org.gradle.internal.resolve.ModuleVersionNotFoundException: Could not find any matches for deezer.kustomexport:compiler:+ as no versions of deezer.kustomexport:compiler are available.
Searched in the following locations:
  - https://dl.google.com/dl/android/maven2/deezer/kustomexport/compiler/maven-metadata.xml
  - https://repo.maven.apache.org/maven2/deezer/kustomexport/compiler/maven-metadata.xml
  - https://raw.githubusercontent.com/Deezer/KustomExport/mvn-repo/deezer/kustomexport/compiler/maven-metadata.xml
Required by:
    project :lib

The exception that is the cause of unresolved state: org.gradle.internal.resolve.ModuleVersionNotFoundException: Could not find any matches for deezer.kustomexport:lib:+ as no versions of deezer.kustomexport:lib are available.
Required by:
    project :lib

Normally these tools don't have a problem finding dependencies in custom Maven repos. Is there something missing or unusual about the way KustomExport builds are published?

Currently handled like a normal method, suspend is simply ignored.

A naive/first version could be to wrap it in a Promise with GlobalScope.promise {...}

It seems like references to inner classes are just replaced by references to the outermost class instead, which of course breaks the code.

@KustomExport
data class A(val b: B) {
    data class B(val x: Int)
}

generates

@JsExport
public class A(
    b: CommonA,
) {
    internal lateinit var common: CommonA

    init {
        if (b != dynamicNull) {
            common = CommonA(
                b = b,
            )
        }
    }

    public val b: CommonA
        get() = common.b

    @Suppress("UNNECESSARY_SAFE_CALL")
    internal constructor(common: CommonA) : this(b = dynamicNull.unsafeCast<CommonA>()) {
        this.common = common
    }
}

public fun CommonA.exportA(): A = A(this)

public fun A.importA(): CommonA = this.common

Workaround: Extract the inner classes to top level classes

RC2 is available, after testing it quickly I noticed some weird stuff going on regarding data class wrapping, resulting in Cannot read properties of undefined kind of errors.

(It may be due to our trick with 2nd internal constructor to preserve the first ctor original via tricky use of dynamic.)

package ynab.slik.data.repository

import deezer.kustomexport.KustomExport

@KustomExport
sealed interface InvalidDataError

@KustomExport
class InvalidNumber(val number: Int) : InvalidDataError

@KustomExport
class InvalidName(val name: String) : InvalidDataError

This fails to compile:

> Task :lib:compileKotlinJs FAILED
e: file:///Users/graham/Work/YNAB/slik/lib/build/generated/ksp/js/jsMain/kotlin/ynab/slik/data/repository/js/InvalidDataError.kt:11:5 Inheritance of sealed classes or interfaces from different module is prohibited
e: file:///Users/graham/Work/YNAB/slik/lib/build/generated/ksp/js/jsMain/kotlin/ynab/slik/data/repository/js/InvalidDataError.kt:11:5 Inheritor of sealed class or interface declared in package ynab.slik.data.repository.js but it must be in package ynab.slik.data.repository where base class is declared

FAILURE: Build failed with an exception.

If I change the sealed interface to sealed class, then it works.

package ynab.slik.data.repository

import deezer.kustomexport.KustomExport

@KustomExport
sealed class InvalidDataError

@KustomExport
class InvalidNumber(val number: Int) : InvalidDataError()

@KustomExport
class InvalidName(val name: String) : InvalidDataError()