completion-stage

A port of Java's CompletionStage using promises. CompletableFuture is also partially ported.

The following is an overview of how each CompletionStage method is implemented, where future in the left column is replaced by promise in the right.

| CompletionStage | Promise | | ---------------------------------------| --------------------------------------------- | | future.acceptEither(other, action) | Promise.race([promise, other]).then(action) | | future.applyToEither(other, fn) | Promise.race([promise, other]).then(fn) | | future.exceptionally(fn) | promise.catch(fn) | | future.exceptionallyCompose(fn) | promise.catch(fn) | | future.handle(fn) | handle(promise, fn) | | future.runAfterBoth(other, action) | Promise.all([promise, other]).then(action) | | future.runAfterEither(other, action) | Promise.race([promise, other]).then(action) | | future.thenAccept(action) | promise.then(action) | | future.thenAcceptBoth(other, action) | Promise.all([promise, other]).then(action) | | future.thenApply(fn) | promise.then(fn) | | future.thenCombine(other, fn) | combine(promise, other, fn) | | future.thenCompose(fn) | promise.then(fn) | | future.thenRun(action) | promise.then(fn) | | future.toCompletableFuture() | N/A | | future.whenComplete(action) | whenComplete(promise, action) |

In addition, the following is an overview of CompletableFuture methods that are implemented using promises.

| CompletableFuture | Promise | | ----------------------------------------------------------------- | ----------------------------------------------------------- | | CompletableFuture.allOf(future1, future2) | Promise.all([promise1, promise2])1 | | CompletableFuture.anyOf(future1, future2) | Promise.race([promise1, promise2])2 | | CompletableFuture.completedFuture(value) | Promise.resolve(value) | | CompletableFuture.completedStage(value) | Promise.resolve(value) | | future.completeOnTimeout(value, timeout, TimeUnit.MILLISECONDS) | resolveOnTimeout(promise, value, timeout)3 | | CompletableFuture.failedFuture(ex) | Promise.reject(ex) | | CompletableFuture.failedStage(ex) | Promise.reject(ex) | | future.orTimeout(timeout, TimeUnit.MILLISECONDS) | rejectOnTimeout(promise, timeout)34 | | CompletableFuture.runAsync(action) | supply(action)5 | | CompletableFuture.supplyAsync(supplier) | supply(supplier)5 |

1: whereas CompletableFuture.allOf returns a CompletableFuture<Void>, the generic type of the promise returned by Promise.all is a combination of the generic types of each passed promise.
2: whereas CompletableFuture.anyOf returns a CompletableFuture<Object>, the generic type of the promise returned by Promise.race is the union of the generic types of each passed promise.
3: the timeouts for resolveOnTimeout and rejectOnTimeout can only be given as milliseconds.
4: an optional rejection reason can be given as a function. The result of this function is used as rejection reason upon timeout.
5: an optional delay in milliseconds can be given.

Note that promise.then, promise.catch and supply can be used in the same way where CompletionStage and CompletableFuture need multiple methods. Which CompletionStage or CompletableFuture method is implemented depends on the return value of the function passed to promise.then, promise.catch or supply.