KMP-NativeCoroutines

KMP-NativeCoroutines is a library designed to bridge Kotlin Coroutines and Swift code in Kotlin Multiplatform (KMP) applications.

It solves two primary limitations of the default Kotlin/Native interoperability:

1. Cancellation Support: Standard Kotlin suspend functions are exposed to Swift as functions with completion handlers, which do not support native Swift cancellation. This library enables proper cancellation support.
2. Generics in Protocols: Because Objective-C does not support generics on protocols, standard Kotlin Flow interfaces lose their generic value types when viewed from Swift. This library restores type safety for flows.

Note: While Swift 5.5+ allows calling completion-handler-based functions as async functions, this is only syntactic sugar and does not provide true cancellation support. KMP-NativeCoroutines provides the actual mechanism for cancellation.

In version 1.0+, the plugin reuses the original property and function names for their native versions. You should remove the Native suffixes from your Swift code calls.

Example Refactoring:

Before:

createPublisher(for: clock.timeNative)
createFuture(for: randomLettersGenerator.getRandomLettersNative())
let value = clock.timeNativeValue
let replayCache = clock.timeNativeReplayCache

After:

createPublisher(for: clock.time)
createFuture(for: randomLettersGenerator.getRandomLetters())
let value = clock.timeValue
let replayCache = clock.timeReplayCache

Note: You can customize or remove the value and replayCache suffixes via configuration (see README).

// Before v1.0
createPublisher(for: clock.timeNative)
createFuture(for: randomLettersGenerator.getRandomLettersNative())
let value = clock.timeNativeValue
let replayCache = clock.timeNativeReplayCache

// After v1.0
createPublisher(for: clock.time)
createFuture(for: randomLettersGenerator.getRandomLetters())
let value = clock.timeValue
let replayCache = clock.timeReplayCache

To expose Kotlin Coroutines to Swift, use the KMP-NativeCoroutines annotations. The plugin automatically generates native wrappers (like AsyncStream, Publisher, or AsyncSequence) based on these annotations.

• Use @NativeCoroutines for general Flow properties or suspend functions.
• Use @NativeCoroutinesState specifically for StateFlow properties to ensure both the value and the flow are exposed.

Generated properties for Flows:

• For Flow: A native version of the flow (e.g., timeNative) and, if it's a StateFlow, a timeValue property.
• For SharedFlow: A timeReplayCache property.

import com.rickclephas.kmp.nativecoroutines.NativeCoroutines
import com.rickclephas.kmp.nativecoroutines.NativeCoroutinesState

class Clock {
    @NativeCoroutines
    val time: StateFlow<Long>

    @NativeCoroutinesState
    val state: StateFlow<Long>
}

class RandomLettersGenerator {
    @NativeCoroutines
    suspend fun getRandomLetters(): String
}

You can install the Swift components via SPM by adding the repository URL to your Package.swift or by using Xcode's File > Add Packages... menu with the URL: https://github.com/rickclephas/KMP-NativeCoroutines.git.

Depending on your needs, you can import specific products for Swift Concurrency, Combine, or RxSwift.

Note: The Swift package version should not include Kotlin version suffixes (e.g., do not use -kotlin-1.6.0). If you only need one implementation, you can use the SPM-specific versions with suffixes like -spm-async, -spm-combine, or -spm-rxswift.

dependencies: [
    .package(url: "https://github.com/rickclephas/KMP-NativeCoroutines.git", exact: "1.0.5")
],
targets: [
    .target(
        name: "MyTargetName",
        dependencies: [
            // Swift Concurrency implementation
            .product(name: "KMPNativeCoroutinesAsync", package: "KMP-NativeCoroutines"),
            // Combine implementation
            .product(name: "KMPNativeCoroutinesCombine", package: "KMP-NativeCoroutines"),
            // RxSwift implementation
            .product(name: "KMPNativeCoroutinesRxSwift", package: "KMP-NativeCoroutines")
        ]
    )
]

You can customize the naming conventions of the generated Kotlin properties and functions by configuring the nativeCoroutines block in your build.gradle.kts file. This allows you to change the suffixes used for native coroutine functions, file names, StateFlow value properties, SharedFlow replay caches, and state properties.

nativeCoroutines {
    // The suffix used to generate the native coroutine function and property names.
    suffix = "Native"
    // The suffix used to generate the native coroutine file names.
    // Note: defaults to the suffix value when `null`.
    fileSuffix = null
    // The suffix used to generate the StateFlow value property names,
    // or `null` to remove the value properties.
    flowValueSuffix = "Value"
    // The suffix used to generate the SharedFlow replayCache property names,
    // or `null` to remove the replayCache properties.
    flowReplayCacheSuffix = "ReplayCache"
    // The suffix used to generate the native state property names.
    stateSuffix = "Value"
    // The suffix used to generate the `StateFlow` flow property names,
    // or `null` to remove the flow properties.
    stateFlowSuffix = "Flow"
}