Calling JavaScript from Kotlin

    However, JavaScript is a dynamically typed language, which means it does not check types at compile time. You can freely talk to JavaScript from Kotlin via dynamic types. If you want to use the full power of the Kotlin type system, you can create external declarations for JavaScript libraries which will be understood by the Kotlin compiler and the surrounding tooling.

    An experimental tool to automatically create Kotlin external declarations for npm dependencies which provide type definitions (TypeScript / d.ts) called is also available.

    You can inline some JavaScript code into your Kotlin code using the js("...") function. For example:

    Because the parameter of js is parsed at compile time and translated to JavaScript code “as-is”, it is required to be a string constant. So, the following code is incorrect:

    1. fun jsTypeOf(o: Any): String {
    2.     return js(getTypeof() + " o") // error reported here
    3. }
    4. fun getTypeof() = "typeof"

    Note that invoking js() returns a result of type , which provides no type safety at compile time.

    external modifier

    To tell Kotlin that a certain declaration is written in pure JavaScript, you should mark it with the external modifier. When the compiler sees such a declaration, it assumes that the implementation for the corresponding class, function or property is provided externally (by the developer or via an ), and therefore does not try to generate any JavaScript code from the declaration. This is also why external declarations can’t have a body. For example:

    1. external fun alert(message: Any?): Unit
    3. external class Node {
    4.     val firstChild: Node
    6.     fun append(child: Node): Node
    8.     fun removeChild(child: Node): Node
    10.     // etc
    11. }
    13. external val window: Window

    The external modifier is only allowed on package-level declarations. You can’t declare an external member of a non-external class.

    In JavaScript you can define members either on a prototype or a class itself:

    There is no such syntax in Kotlin. However, in Kotlin we have companion objects. Kotlin treats companion objects of external classes in a special way: instead of expecting an object, it assumes members of companion objects to be members of the class itself. from the example above can be described as follows:

    1. external class MyClass {
    2.     companion object {
    3.         fun sharedMember()
    5.     fun ownMember()
    6. }

    If you are writing an external declaration for a JavaScript function which has an optional parameter, use definedExternally. This delegates the generation of the default values to the JavaScript function itself:

    1. external fun myFunWithOptionalArgs(
    2.     x: Int,
    3.     y: String = definedExternally,
    4.     z: String = definedExternally
    5. )

    With this external declaration, you can call myFunWithOptionalArgs with one required argument and two optional arguments, where the default values are calculated by the JavaScript implementation of myFunWithOptionalArgs.

    You can easily extend JavaScript classes as if they were Kotlin classes. Just define an external open class and extend it by a non-external class. For example:

    • When a function of an external base class is overloaded by signature, you can’t override it in a derived class.
    • You can’t override a function with default arguments.
    • Non-external classes can’t be extended by external classes.

    JavaScript does not have the concept of interfaces. When a function expects its parameter to support two methods foo and bar, you would just pass in an object that actually has these methods.

    You can use interfaces to express this concept in statically typed Kotlin:

    1. external interface HasFooAndBar {
    2.     fun foo()
    4.     fun bar()
    5. }
    7. external fun myFunction(p: HasFooAndBar)

    A typical use case for external interfaces is to describe settings objects. For example:

    1. external interface JQueryAjaxSettings {
    2.     var async: Boolean
    4.     var cache: Boolean
    6.     var complete: (JQueryXHR, String) -> Unit
    9. }
    10. fun JQueryAjaxSettings(): JQueryAjaxSettings = js("{}")
    12. external class JQuery {
    13.     companion object {
    14.         fun get(settings: JQueryAjaxSettings): JQueryXHR
    15.     }
    16. }
    18. fun sendQuery() {
    19.     JQuery.get(JQueryAjaxSettings().apply {
    20.         complete = { (xhr, data) ->
    21.             window.alert("Request complete")
    22.         }
    23.     })
    24. }

    External interfaces have some restrictions:

    • They can’t be used on the right-hand side of is checks.
    • They can’t be passed as reified type arguments.
    • They can’t be used in class literal expressions (such as I::class).

    • as casts to external interfaces always succeed. Casting to external interfaces produces the “Unchecked cast to external interface” compile time warning. The warning can be suppressed with the @Suppress("UNCHECKED_CAST_TO_EXTERNAL_INTERFACE") annotation.

      IntelliJ IDEA can also automatically generate the @Suppress annotation. Open the intentions menu via the light bulb icon or Alt-Enter, and click the small arrow next to the “Unchecked cast to external interface” inspection. Here, you can select the suppression scope, and your IDE will add the annotation to your file accordingly.

    They will be compiled accordingly:

    1. function usingUnsafeCast(s) {
    2.     return s;
    3. }
    5. function usingAsOperator(s) {
    6.     var tmp$;
    7.     return typeof (tmp$ = s) === 'string' ? tmp$ : throwCCE();
    8. }