deezer / KustomExport

EXPERIMENTAL : A JS facade generator for KotlinJS / KMP
Apache License 2.0
69 stars 9 forks source link

KustomExport: a KSP generator of JS facade

Status: Experimental

At Deezer, we develop KMP libraries, this tool help us provide nicer API for Typescript since November 2021.

The generated code will change to support more features and/or stop supporting features provided by KotlinJS directly, so you may expect breaking changes when upgrading.

Motivation

Providing a nice Typescript API can sometimes be complex/verbose from a Kotlin Multiplatform Project.

A simple example:

// @JsExport // Cannot be annotated in Kotlin 1.6.10 and before
enum class StateEnum { IDLE, RUNNING }
@JsExport
data class SomeDataObject(
    val timestamp: Long,
    val state: StateEnum,
    val idList: List<String>
)

Results in Typescript:

export namespace sample.doc_examples {
    class SomeDataObject {
        constructor(timestamp: any/* kotlin.Long */, state: any/* sample.doc_examples.StateEnum */, idList: any/* kotlin.collections.List<string> */);
        get timestamp(): any/* kotlin.Long */;
        get state(): any/* sample.doc_examples.StateEnum */;
        get idList(): any/* kotlin.collections.List<string> */;
        component1(): any/* kotlin.Long */;
        component2(): any/* sample.doc_examples.StateEnum */;
        component3(): any/* kotlin.collections.List<string> */;
        copy(timestamp: any/* kotlin.Long */, state: any/* sample.doc_examples.StateEnum */, idList: any/* kotlin.collections.List<string> */): sample.doc_examples.SomeDataObject;
        toString(): string;
        hashCode(): number;
        equals(other: Nullable<any>): boolean;
    }
}

There are some good reasons why it's not supported by KotlinJs right now, but it's not practical to provide a clean Typescript API.

KustomExport wants to be the bridge to provide a nice Typescript API until KotlinJS produces an equivalent export.

Technical approach

A manual way to approach this problem is to write a facade in Kotlin and only @JsExport the facade.

// jsMain/StateEnumJs.kt
// Export the enum in a class, so it's providing a real class in JS instead of 'any'
@JsExport
class StateEnumJs internal constructor(internal val stateEnum: StateEnum) {
    val name: String = stateEnum.name
}
fun StateEnumJs.import(): StateEnum = value
fun StateEnum.export(): StateEnumJs = Encoding(this)
// Object that exposes all possible values of the enum (note the 's')
@JsExport
object StateEnumsJs {
    val IDLE: StateEnumJs = StateEnumJs(StateEnum.IDLE)
    val RUNNING: StateEnumJs = StateEnumJs(StateEnum.RUNNING)
}
// And more methods like values(), valueOf()...

If you write similar facades yourself, this generator could help you avoid writing them manually. Please open issues with your needs!

Note that it's adding code to your existing codebase, so it will increase your JS bundle size.

Current status

The current project uses Typescript integration tests, feel free to check what's covered in Samples.

What is supported today:

What is not supported yet:

Feel free to open issues for more features!

You can have a look to the Samples to have a feel of how it can be used.

Setup

KustomExport use KSP (Kotlin Symbol Processor), and you need to install it in your build.gradle.kts

plugins {
    kotlin("multiplatform")
    id("com.google.devtools.ksp") version "1.6.21-1.0.5"
}

Then you need to define the dependency to the library

repositories {
    mavenCentral()
    maven(url = "https://raw.githubusercontent.com/Deezer/KustomExport/mvn-repo")
}

kotlin {
    // jvm(), js() and other platforms...
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("deezer.kustomexport:lib:<version>")
                implementation("deezer.kustomexport:lib-coroutines:<version>")
            }
        }
    }
}

And finally enable the compiler with

kotlin { 
    // KMP configuration
}
dependencies {
    add("kspJs", "deezer.kustomexport:compiler:0.6.1")
}

Licence

/*
 * Copyright 2021 Deezer.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */