MPP: Promise support in JS

Author: elizarov

integration/kotlinx-coroutines-jdk8/src/main/kotlin/kotlinx/coroutines/experimental/future/Future.kt

@@ -27,14 +27,14 @@ import kotlin.coroutines.experimental.CoroutineContext
 import kotlin.coroutines.experimental.suspendCoroutine
 
 /**
- * Starts new coroutine and returns its results an an implementation of [CompletableFuture].
+ * Starts new coroutine and returns its result as an implementation of [CompletableFuture].
  * This coroutine builder uses [CommonPool] context by default and is conceptually similar to [CompletableFuture.supplyAsync].
  *
  * The running coroutine is cancelled when the resulting future is cancelled or otherwise completed.
  *
  * The [context] for the new coroutine can be explicitly specified.
  * See [CoroutineDispatcher] for the standard context implementations that are provided by `kotlinx.coroutines`.
- * The [context][CoroutineScope.context] of the parent coroutine from its [scope][CoroutineScope] may be used,
+ * The [context][CoroutineScope.coroutineContext] of the parent coroutine from its [scope][CoroutineScope] may be used,
  * in which case the [Job] of the resulting coroutine is a child of the job of the parent coroutine.
  * The parent job may be also explicitly specified using [parent] parameter.
  *

js/kotlinx-coroutines-core-js/src/main/kotlin/kotlinx/coroutines/experimental/CancellableContinuation.kt

@@ -259,6 +259,10 @@ internal class CancellableContinuationImpl<in T>(
 
     override fun toString(): String =
         "CancellableContinuation{${stateString()}}[$delegate]"
+
+    // todo: This workaround for KT-21968, should be removed in the future
+    public override fun cancel(cause: Throwable?): Boolean =
+        super.cancel(cause)
 }
 
 private class CompletedIdempotentResult(

js/kotlinx-coroutines-core-js/src/main/kotlin/kotlinx/coroutines/experimental/CoroutineContext.kt

@@ -16,7 +16,6 @@
 
 package kotlinx.coroutines.experimental
 
-import kotlin.browser.window
 import kotlin.coroutines.experimental.ContinuationInterceptor
 import kotlin.coroutines.experimental.CoroutineContext
 
@@ -46,29 +45,29 @@ public actual val DefaultDispatcher: CoroutineDispatcher = DefaultExecutor
 
 internal object DefaultExecutor : CoroutineDispatcher(), Delay {
     fun enqueue(block: Runnable) {
-        window.setTimeout({ block.run() }, 0)
+        setTimeout({ block.run() }, 0)
     }
 
     fun schedule(time: Double, block: Runnable): Int =
-        window.setTimeout({ block.run() }, time.timeToInt())
+        setTimeout({ block.run() }, time.timeToInt())
 
     fun removeScheduled(handle: Int) {
-        window.clearTimeout(handle)
+        clearTimeout(handle)
     }
 
     override fun dispatch(context: CoroutineContext, block: Runnable) {
-        window.setTimeout({ block.run() }, 0)
+        setTimeout({ block.run() }, 0)
     }
 
     override fun scheduleResumeAfterDelay(time: Int, continuation: CancellableContinuation<Unit>) {
-        window.setTimeout({ with(continuation) { resumeUndispatched(Unit) } }, time.coerceAtLeast(0))
+        setTimeout({ with(continuation) { resumeUndispatched(Unit) } }, time.coerceAtLeast(0))
     }
 
     override fun invokeOnTimeout(time: Int, block: Runnable): DisposableHandle {
-        val handle = window.setTimeout({ block.run() }, time.coerceAtLeast(0))
+        val handle = setTimeout({ block.run() }, time.coerceAtLeast(0))
         return object : DisposableHandle {
             override fun dispose() {
-                window.clearTimeout(handle)
+                clearTimeout(handle)
             }
         }
     }
@@ -85,3 +84,9 @@ public fun newCoroutineContext(context: CoroutineContext, parent: Job? = null):
     return if (context !== DefaultDispatcher && context[ContinuationInterceptor] == null)
         wp + DefaultDispatcher else wp
 }
+
+// We need to reference global setTimeout and clearTimeout so that it works on Node.JS as opposed to
+// using them via "window" (which only works in browser)
+
+private external fun setTimeout(handler: dynamic, timeout: Int = definedExternally): Int
+private external fun clearTimeout(handle: Int = definedExternally): Unit

js/kotlinx-coroutines-core-js/src/main/kotlin/kotlinx/coroutines/experimental/Promise.kt

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2016-2017 JetBrains s.r.o.
+ *
+ * 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.
+ */
+
+package kotlinx.coroutines.experimental
+
+import kotlin.coroutines.experimental.ContinuationInterceptor
+import kotlin.coroutines.experimental.CoroutineContext
+import kotlin.js.Promise
+
+/**
+ * Starts new coroutine and returns its result as an implementation of [Promise].
+ *
+ * The [context] for the new coroutine can be explicitly specified.
+ * See [CoroutineDispatcher] for the standard context implementations that are provided by `kotlinx.coroutines`.
+ * The [context][CoroutineScope.coroutineContext] of the parent coroutine from its [scope][CoroutineScope] may be used,
+ * in which case the [Job] of the resulting coroutine is a child of the job of the parent coroutine.
+ * The parent job may be also explicitly specified using [parent] parameter.
+ *
+ * If the context does not have any dispatcher nor any other [ContinuationInterceptor], then [DefaultDispatcher] is used.
+ *
+ * By default, the coroutine is immediately scheduled for execution.
+ * Other options can be specified via `start` parameter. See [CoroutineStart] for details.
+ *
+ * @param context context of the coroutine. The default value is [DefaultDispatcher].
+ * @param start coroutine start option. The default value is [CoroutineStart.DEFAULT].
+ * @param parent explicitly specifies the parent job, overrides job from the [context] (if any).
+ * @param block the coroutine code.
+ */
+public fun <T> promise(
+    context: CoroutineContext = DefaultDispatcher,
+    start: CoroutineStart = CoroutineStart.DEFAULT,
+    parent: Job? = null,
+    block: suspend CoroutineScope.() -> T
+): Promise<T> =
+    async(context, start, parent, block).asPromise()
+
+/**
+ * Converts this deferred value to the instance of [Promise].
+ */
+public fun <T> Deferred<T>.asPromise(): Promise<T> {
+    val promise = Promise<T> { resolve, reject ->
+        invokeOnCompletion {
+            val e = getCompletionExceptionOrNull()
+            if (e != null) {
+                reject(e)
+            } else {
+                resolve(getCompleted())
+            }
+        }
+    }
+    promise.asDynamic().deferred = this
+    return promise
+}
+
+/**
+ * Converts this promise value to the instance of [Deferred].
+ */
+public fun <T> Promise<T>.asDeferred(): Deferred<T> {
+    val deferred = asDynamic().deferred
+    @Suppress("UnsafeCastFromDynamic")
+    return deferred ?: async { await() }
+}
+
+/**
+ * Awaits for completion of the promise without blocking.
+ *
+ * This suspending function is cancellable.
+ * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
+ * stops waiting for the promise and immediately resumes with [CancellationException].
+ */
+public suspend fun <T> Promise<T>.await(): T = suspendCancellableCoroutine { cont: CancellableContinuation<T> ->
+    this@await.then(
+        onFulfilled = { cont.resume(it) },
+        onRejected = { cont.resumeWithException(it) })
+}

js/kotlinx-coroutines-core-js/src/test/kotlin/kotlinx/coroutines/experimental/PromiseTest.kt

@@ -0,0 +1,90 @@
+/*
+ * Copyright 2016-2017 JetBrains s.r.o.
+ *
+ * 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.
+ */
+
+package kotlinx.coroutines.experimental
+
+import kotlin.js.Promise
+import kotlin.test.*
+
+// :todo: This test does not actually test anything because of KT-21970 JS: Support async tests in Mocha and others
+// One should watch for errors in the console to see if there were any failures (the test would still pass)
+class PromiseTest : TestBase() {
+    @Test
+    fun testPromiseResolvedAsDeferred() = promise {
+        val promise = Promise<String> { resolve, _ ->
+            resolve("OK")
+        }
+        val deferred = promise.asDeferred()
+        assertEquals("OK", deferred.await())
+    }
+    
+    @Test
+    fun testPromiseRejectedAsDeferred() = promise {
+        val promise = Promise<String> { _, reject ->
+            reject(TestException("Rejected"))
+        }
+        val deferred = promise.asDeferred()
+        try {
+            deferred.await()
+            expectUnreached()
+        } catch (e: Throwable) {
+            assertTrue(e is TestException)
+            assertEquals("Rejected", e.message)
+        }
+    }
+
+    @Test
+    fun testCompletedDeferredAsPromise() = promise {
+        val deferred = async(coroutineContext, CoroutineStart.UNDISPATCHED) {
+            // completed right away
+            "OK"
+        }
+        val promise = deferred.asPromise()
+        assertEquals("OK", promise.await())
+    }
+
+    @Test
+    fun testWaitForDeferredAsPromise() = promise {
+        val deferred = async(coroutineContext) {
+            // will complete later
+            "OK"
+        }
+        val promise = deferred.asPromise()
+        assertEquals("OK", promise.await()) // await yields main thread to deferred coroutine
+    }
+
+    @Test
+    fun testCancellableAwaitPromise() = promise {
+        lateinit var r: (String) -> Unit
+        val toAwait = Promise<String> { resolve, _ -> r = resolve }
+        val job = launch(coroutineContext, CoroutineStart.UNDISPATCHED) {
+            toAwait.await() // suspends
+        }
+        job.cancel() // cancel the job
+        r("fail") // too late, the waiting job was already cancelled
+    }
+
+    @Test
+    fun testAsPromiseAsDeferred() = promise {
+        val deferred = async { "OK" }
+        val promise = deferred.asPromise()
+        val d2 = promise.asDeferred()
+        assertTrue(d2 === deferred)
+        assertEquals("OK", d2.await())
+    }
+
+    private class TestException(message: String) : Exception(message)
+}