Proposal: Make JS promises created via `CoroutineScope.promise` cancellable

[YarnSphere]

Use-case

I'm writing a multiplatform library using coroutines and one of the targets is JS.

It is expected that the JS build of the library will be used from JS; as such, I expose "Async" counterparts of functions of my library that launch coroutines as promises. For example, if I have the following suspend function:

public suspend fun doSomething() { ... }

I also expose, on the JS end, something like:

public fun doSomethingAsync(): Promise<Unit> = myScope.promise { doSomething() }

Calling doSomething from Kotlin must be done within a coroutine that I can cancel, however, calling doSomethingAsync from JS makes it difficult to cancel the coroutine without exposing JS users to coroutines (which I'd like to avoid).

Proposal

Make CoroutineScope.promise return a CancellablePromise (extending Promise) with a cancel method that can be used to cancel the launched coroutine.

[elizarov]

JS promises are not cancellable by their design. How do you expect it to work? What are the best practices in JS ecosystem for cancellation?

[YarnSphere]

Native JS promises aren't, but some 3rd party implementations of promises implement cancellation, e.g. Bluebird. There were some efforts to bring cancellation to native promises a while ago but they didn't come to fruition. I don't know exactly what the best practices are in the JS ecosystem as promise cancellation only exists in 3rd party promise implementations which I've never used but, afaik, these implementations simply expose a cancel method on the promise, or something similarly named, if that's what you're asking.

Either way, different promise implementations can happily coexist in JS. Promise based APIs usually just need objects to be "thenable" i.e., provide a then method, to be seen as promises. It is also perfectly fine to simply extend the native Promise: which is what I expect of CancellablePromise here.

The implementation of CancellablePromise should keep track of the job running "inside" the promise and provide a cancel method that would in turn cancel the job. A CancellationException would be thrown as usual, which could be catched normally via Promise.catch; the semantics here would be similar to those of the coroutines, where a cancellation is seen as a "special" exception.

Something like this would do:

class CancellablePromise<T>(
    private val job: Job,
    executor: (resolve: (T) -> Unit, reject: (Throwable) -> Unit) -> Unit
) : Promise<T>(executor) {
    fun cancel(cause: CancellationException?): Unit = job.cancel(cause)
}

A slight improvement would be to also reimplement then and catch in CancellablePromise to make them return instances of CancellablePromise as well, making a "promise chain" cancellable. These instances of CancellablePromise would all cancel the same job, the one that the initial cancellable promise is keeping track of, since this job is the only thing we can reliably cancel (as it is backed by coroutines).

The improvement isn't super important, it would only make things slightly more ergonomic as we can assign a chain of promises to a variable and then call cancel on said variable; otherwise we need to keep a reference to the initial promise and can only cancel that one reference.

[YarnSphere]

I have a new proposal for this feature, which might be more "JS standards compliant".

I was not aware of this when I first proposed cancellable promises, and in response to @elizarov's question about best practices for cancellation in the JS ecosystem: there exists an AbortController interface, which certain Web APIs support for "aborting requests", the most prominent being the Fetch API.

My new proposal is thus to extend CoroutineScope.promise to optionally receive an AbortSignal. When this signal is notified with an abort (by calling abort on the associated controller), the wrapped coroutine would be cancelled. On cancellation, the promise should fail with an AbortError.

This would allow me to expose something like the following to be used from JS:

public fun doSomethingAsync(signal: AbortSignal? = null): Promise<Unit> =
    myScope.promise(signal = signal) { doSomething() }

And I could now use it from JS as follows:

const controller = new AbortController()
const signal = controller.signal

// Abort if `doSomethingAsync` takes longer than 1 second to complete
const timeoutId = setTimeout(() => controller.abort(), 1000)

doSomethingAsync(signal)
    .then(() => {
        clearTimeout(timeoutId)
        console.log("Finished"))
    })
    .catch((err) => console.error(err.name === 'AbortError' ? 'Aborted' : 'Errored'))

CoroutineScope.promise's implementation would need to contain something like the following (plus a corresponding removeEventListener on job completion):

signal.addEventListener("abort") { job.cancel() }

The AbortController is meant to be used by external APIs (at least this post on "abortable fetch" states so); in my opinion, this makes it a good candidate for being integrated with Kotlinx Coroutines.

Bad news (and this is how I found out about AbortController): it is only supported by Node.js 15 and above. However, it seems to be relatively well supported in browsers, and it is easily polyfillable for those needing it.

What do you think of this proposal? In my opinion it's more "JS standards compliant" than my previous one and effectively solves the same issue: it allows the cancellation of coroutines (exposed as promises) from JS.

[elizarov]

I like the idea. We can actually have both -- a cancel method on a returned Promise instance and an (optional) AbortSignal parameter. Due to the dynamic nature of JS ecosystem, I think the latter can be implemented in a way that is usable on Node.js if available but does not cause any harm when it is not.

We currently don't have time to work on the implementation, but it all looks relatively straightforward, so PR is welcome.

[turansky]

New Disposable interface can be used for this goal (Proposal)

// available since TypeScript 5.2
interface Disposable {
    [Symbol.dispose](): void;
}

Result TS type:

interface JsJob extends Promise, Disposable