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.
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;
}
}
Long
will not produce a number
but a kotlin.Long
behing a any
(doc), but web developers usually use number
to store timestamp.Enum
s are not handled yet (KT-37916) and so exported as any
List
could be used in a majority of cases if it was exported in Arraysdata class
are not really relevant or unusable (copy()
should define all fields in typescript anyway)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.
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.
The current project uses Typescript integration tests, feel free to check what's covered in Samples.
What is supported today:
Long
to number
(by using toLong/toDouble, so be careful with precision issues here!) (doc)List<...>
to Array<...>
and it's ready to support more collections, please open a ticket with your needs. (doc)val rand: Long get() = Random.nextLong()
will be wrapped and called again each time the exposed object is called in Typescript)@JsExport
with @KustomExport
(experimental)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.
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")
}
/*
* 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.
*/