Added function PNFuture.await()

as a convenient function for those users that use coroutines.

New module pubnub-kotlin-coroutines has been created.

gradle/libs.versions.toml

@@ -27,6 +27,7 @@ cbor = { module = "co.nstant.in:cbor", version = "0.9" }
 jetbrains-annotations = { module = "org.jetbrains:annotations", version = "24.1.0" }
 kotlinx-atomicfu = { module = "org.jetbrains.kotlinx:atomicfu", version = "0.24.0" }
 kotlinx-datetime = { module = "org.jetbrains.kotlinx:kotlinx-datetime", version.ref = "kotlinx_datetime"}
+coroutines = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "kotlinx_coroutines"}
 
 # tests
 wiremock = { module = "com.github.tomakehurst:wiremock", version = "2.27.2" }

pubnub-kotlin-coroutines/build.gradle.kts

@@ -0,0 +1,14 @@
+plugins {
+    alias(libs.plugins.benmanes.versions)
+    id("pubnub.kotlin-library")
+    id("pubnub.dokka")
+    id("pubnub.shared")
+}
+
+dependencies {
+    api(project(":pubnub-kotlin:pubnub-kotlin-api"))
+    api(libs.coroutines)
+    implementation(kotlin("test"))
+    testImplementation(libs.junit.jupiter.engine)
+    testImplementation(libs.junit.jupiter)
+}

pubnub-kotlin-coroutines/src/main/kotlin/com/pubnub/coroutines/Util.kt

@@ -0,0 +1,19 @@
+package com.pubnub.coroutines
+
+import com.pubnub.kmp.PNFuture
+import kotlinx.coroutines.suspendCancellableCoroutine
+import kotlin.coroutines.resume
+import kotlin.coroutines.resumeWithException
+
+suspend fun <T> PNFuture<T>.await(): T {
+    val t = suspendCancellableCoroutine { cont ->
+        async { result ->
+            result.onSuccess {
+                cont.resume(it)
+            }.onFailure {
+                cont.resumeWithException(it)
+            }
+        }
+    }
+    return t
+}

pubnub-kotlin-coroutines/src/test/kotlin/com/pubnub/coroutines/UtilKtTest.kt

@@ -0,0 +1,43 @@
+package com.pubnub.coroutines
+
+import com.pubnub.api.v2.callbacks.Consumer
+import com.pubnub.kmp.PNFuture
+import kotlinx.coroutines.runBlocking
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Test
+import kotlin.test.assertFailsWith
+
+class FakePNFuture<T>(private val block: (Consumer<com.pubnub.api.v2.callbacks.Result<T>>) -> Unit) : PNFuture<T> {
+    override fun async(callback: Consumer<com.pubnub.api.v2.callbacks.Result<T>>) {
+        block(callback)
+    }
+}
+
+class UtilKtTest {
+    @Test
+    fun `await returns result on success`() = runBlocking {
+        val expected = "Success Result"
+        val future = FakePNFuture<String> { callback ->
+            // Simulate a successful asynchronous result.
+            callback.accept(com.pubnub.api.v2.callbacks.Result.success(expected))
+        }
+        // When await() is called, it should resume with the expected result.
+        val result = future.await()
+        assertEquals(expected, result)
+    }
+
+    @Test
+    fun `await throws exception on failure`() = runBlocking {
+        val exception = Exception("Failure occurred")
+        val future = FakePNFuture<String> { callback ->
+            // Simulate an asynchronous failure.
+            callback.accept(com.pubnub.api.v2.callbacks.Result.failure(exception))
+        }
+        // When await() is called, it should resume with an exception.
+        val thrown = assertFailsWith<Exception> {
+            future.await()
+        }
+        // Optionally verify the exception message.
+        assertEquals(exception.message, thrown.message)
+    }
+}

settings.gradle.kts

@@ -29,3 +29,4 @@ include("examples:kotlin-app")
 include("examples:java-app")
 includeBuild("build-logic/ktlint-custom-rules")
 includeBuild("migration_utils")
+include("pubnub-kotlin-coroutines")