Default Transformers

This guide covers the default transformers provided by the plugin and how to use them effectively.

Overview

Transformers are the core components that define how suspend functions are transformed for different platforms. The plugin provides several built-in transformers that cover the most common use cases.

note

The default transformers depend on the annotation and runtime dependencies provided by the plugin. Make sure you include them in your configuration before using default transformers.

JVM Transformers

JVM Blocking Transformer

The JVM Blocking transformer generates blocking variants of suspend functions using runBlocking.

Configuration

suspendTransformPlugin {
    transformers {
        // Way 1: Simple addition
        addJvmBlocking()

        // Way 2: Using configuration object
        addJvm(SuspendTransformConfigurations.jvmBlockingTransformer)
        
        // Way 3: Using platform-specific addition
        add(
            TargetPlatform.JVM, 
            SuspendTransformConfigurations.jvmBlockingTransformer
        )
    }
}

Usage

Source

class ApiService {
    @JvmBlocking
    suspend fun fetchData(): String {
        delay(1000)
        return "Data fetched"
    }
}

Compiled

class ApiService {
    @JvmSynthetic
    suspend fun fetchData(): String {
        delay(1000)
        return "Data fetched"
    }
    
    @Api4J
    fun fetchDataBlocking(): String = 
        `$runInBlocking$` { fetchData() }
}

Key Features

• Default Generated Function Suffix: Blocking
• Return Type: Same as the original function
• Runtime Function: $runInBlocking$ (based on kotlinx.coroutines.runBlocking)

Mark Annotation

@JvmBlocking provides some properties to change the default values and customize the generated function results.

baseName

baseName represents the base name of the generated function. By default, it is empty (""). If the value is empty, it means using the same value as the original function.

The final function name of the generated function is baseName + suffix.

suffix

suffix represents the suffix of the generated function. By default, it is Blocking.

asProperty

asProperty represents whether to generate a property instead of a function. By default, it is false.

suspend fun foo(): T = ...

// Generated
@Api4J
val fooBlocking: T 
    get() = runInBlocking { foo() }

note

If asProperty is true, the function cannot have parameters.

markName

Refer to Mark Name.

JVM Async Transformer

The JVM Async transformer generates asynchronous variants using CompletableFuture.

Configuration

suspendTransformPlugin {
    transformers {
        // Way 1: Simple addition
        addJvmAsync()

        // Way 2: Using configuration object
        addJvm(SuspendTransformConfigurations.jvmAsyncTransformer)
        
        // Way 3: Using platform-specific addition
        add(
            TargetPlatform.JVM, 
            SuspendTransformConfigurations.jvmAsyncTransformer
        )
    }
}

Usage

Source

class ApiService {
    @JvmAsync
    suspend fun fetchData(): String {
        delay(1000)
        return "Data fetched"
    }
}

Compiled

class ApiService {
    @JvmSynthetic
    suspend fun fetchData(): String {
        delay(1000)
        return "Data fetched"
    }
    
    @Api4J
    fun fetchDataAsync(): CompletableFuture<out String> = 
        `$runInAsync$`(
            block = { fetchData() }, 
            scope = this as? CoroutineScope
        )
}

Key Features

• Default Generated Function Suffix: Async
• Return Type: CompletableFuture<out T> where T is the original return type
• Runtime Function: $runInAsync$
• Scope Handling: Uses the current CoroutineScope if available, otherwise GlobalScope

Mark Annotation

@JvmAsync provides some properties to change the default values and customize the generated function results.

baseName

baseName represents the base name of the generated function. By default, it is empty (""). If the value is empty, it means using the same value as the original function.

The final function name of the generated function is baseName + suffix.

suffix

suffix represents the suffix of the generated function. By default, it is Async.

asProperty

asProperty represents whether to generate a property instead of a function. By default, it is false.

suspend fun foo(): T = ...

// Generated
@Api4J
val fooAsync: CompletableFuture<out T> 
    get() = runInAsync { foo() }

note

If asProperty is true, the function cannot have parameters.

markName

Refer to Mark Name.

JavaScript Transformers

JS Promise Transformer

The JS Promise transformer generates Promise-based variants for JavaScript interoperability.

Configuration

suspendTransformPlugin {
    transformers {
        // Way 1: Simple addition
        addJsPromise()

        // Way 2: Using configuration object
        addJs(SuspendTransformConfigurations.jsPromiseTransformer)
        
        // Way 3: Using platform-specific addition
        add(
            TargetPlatform.JS, 
            SuspendTransformConfigurations.jsPromiseTransformer
        )
    }
}

Usage

Source

class ApiService {
    @JsPromise
    suspend fun fetchData(): String {
        delay(1000)
        return "Data fetched"
    }
}

Compiled

class ApiService {
    
    suspend fun fetchData(): String {
        delay(1000)
        return "Data fetched"
    }
    
    @Api4Js
    fun fetchDataAsync(): Promise<String> = 
        `$runInAsync$`(
            block = { fetchData() }, 
            scope = this as? CoroutineScope
        )
}

Key Features

• Default Generated Function Suffix: Async
• Return Type: Promise<T> where T is the original return type
• Runtime Function: $runInAsync$

Mark Annotation

@JsPromise provides some properties to change the default values and customize the generated function results.

baseName

baseName represents the base name of the generated function. By default, it is empty (""). If the value is empty, it means using the same value as the original function.

The final function name of the generated function is baseName + suffix.

suffix

suffix represents the suffix of the generated function. By default, it is Async.

asProperty

asProperty represents whether to generate a property instead of a function. By default, it is false.

suspend fun foo(): T = ...

// Generated
@Api4Js
val fooAsync: Promise<T> 
    get() = runInAsync { foo() }

note

If asProperty is true, the function cannot have parameters.

markName

Refer to Mark Name.

Convenience Functions

Combined JVM Transformers

suspendTransformPlugin {
    transformers {
        // Includes both addJvmBlocking() and addJvmAsync()
        useJvmDefault()
    }
}

This is equivalent to:

suspendTransformPlugin {
    transformers {
        addJvmBlocking()
        addJvmAsync()
    }
}

Combined JS Transformers

suspendTransformPlugin {
    transformers {
        // Includes addJsPromise()
        useJsDefault()
    }
}

All Default Transformers

suspendTransformPlugin {
    transformers {
        // Includes all default transformers for all platforms
        useDefault()
    }
}

This is equivalent to:

suspendTransformPlugin {
    transformers {
        useJvmDefault()  // JVM Blocking + JVM Async
        useJsDefault()   // JS Promise
    }
}

Combining Multiple Annotations

You can use multiple transformer annotations on the same function:

class ApiService {
    @JvmBlocking
    @JvmAsync
    @JsPromise
    suspend fun fetchData(): String {
        delay(1000)
        return "Data fetched"
    }
}

This will generate:

• fetchDataBlocking(): String (JVM)
• fetchDataAsync(): CompletableFuture<out String> (JVM)
• fetchDataAsync(): Promise<String> (JS)