Getting Started

This guide will walk you through the basic usage of the Kotlin Suspend Transform Compiler Plugin across different platforms.

Configuration

First, enable the default configuration by configuring the Gradle plugin.

note

For more information on configuration, refer to Configuration.

build.gradle.kts

suspendTransformPlugin {
    // `enable = true` is default.
    transformers {
        // Use the standard default transformers.
        useDefault()

        // Or configure individually:
        // addJvmBlocking()
        // addJvmAsync()
        // addJsPromise()

        // Enable Reactive Streams explicitly when needed:
        // addJvmReactive()
    }
}

JVM Platform

The JVM platform supports both blocking and asynchronous transformations of suspend functions.

Basic Usage

Source

class Foo {
    @JvmBlocking
    @JvmAsync
    suspend fun waitAndGet(): String {
        delay(5)
        return "Hello"
    } 
}

Compiled

class Foo {
    // Hide from Java
    @JvmSynthetic
    suspend fun waitAndGet(): String {
        delay(5)
        return "Hello"
    }
    
    @Api4J // RequiresOptIn annotation, provide warnings to Kotlin
    fun waitAndGetBlocking(): String = runInBlocking { waitAndGet() } // 'runInBlocking' from the runtime provided by the plugin

    @Api4J // RequiresOptIn annotation, provide warnings to Kotlin
    fun waitAndGetAsync(): CompletableFuture<out String> = runInAsync { waitAndGet() } // 'runInAsync' from the runtime provided by the plugin
}

Reactive Streams

@JvmReactive generates a Reactive Streams Publisher.

@OptIn(ExperimentalJvmApi::class)
class Foo {
    @JvmReactive
    suspend fun waitAndFind(): String? = null
}

class Foo {
    @Api4J
    fun waitAndFindReactive(): Publisher<String> = runInReactive { waitAndFind() }
}

The publisher emits one non-null value or completes empty when the suspend function returns null. It requires org.reactivestreams.Publisher and org.jetbrains.kotlinx:kotlinx-coroutines-reactive on the JVM classpath. Add these dependencies to the user JVM project or source set manually.

JavaScript Platform

The JavaScript platform supports Promise-based transformations.

Basic Usage

Source

class Foo {
    @JsPromise
    suspend fun waitAndGet(): String {
        delay(5)
        return "Hello"
    } 
}

Compiled

class Foo {
    
    suspend fun waitAndGet(): String {
        delay(5)
        return "Hello"
    }
    
    @Api4Js // RequiresOptIn annotation, provide warnings to Kotlin
    fun waitAndGetAsync(): Promise<String> = runInAsync { waitAndGet() } // 'runInAsync' from the runtime provided by the plugin
}

note

JS platform support was added in version 0.6.0! See the development process at KT-53993, and the final implementation at #39!

WasmJS Platform

Experimental Version 0.6.0

warning

The transformer functions mentioned in the WasmJS example below are assumed to be custom functions defined by YOU.

They are not included in the runtime.

Since there are a lot of restrictions on the use of various types in WasmJS... so I'm not sure how to handle them perfectly yet. Until then, you can customize functions and types to control the behaviour of the compiler plugin yourself. Just like you can customize other platforms.

// Some custom transformer functions by YOU...
fun <T> runInAsync(block: suspend () -> T): AsyncResult<T> = AsyncResult(block)

class AsyncResult<T>(val block: suspend () -> T) {
    @OptIn(DelicateCoroutinesApi::class)
    fun toPromise(): Promise<JsAny?> {
        return GlobalScope.promise { block() }
    }
}

Source

class Foo {
    @JsPromise
    suspend fun waitAndGet(): String {
        delay(5)
        return "Hello"
    }
}

Compiled

class Foo {
    
    suspend fun waitAndGet(): String {
        delay(5)
        return "Hello"
    }
    
    @Api4Js // RequiresOptIn annotation, provide warnings to Kotlin
    fun waitAndGetAsync(): AsyncResult<String> = runInAsync { waitAndGet() } // 'runInAsync' from the runtime provided by the plugin
}