# completion-stage

> A port of Java's CompletionStage using promises

Latest version **1.0.0** (published 2021-12-24) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install completion-stage
pnpm add completion-stage
yarn add completion-stage
bun add completion-stage
```

## Health

**Score 40/100 (D)** — status: abandoned.

Positive: has types; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2021-12-24 |
| First published | 2021-12-24 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 31.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Rob Spoor |
| Maintainers | robtimus |

## Links

- npm: https://www.npmjs.com/package/completion-stage
- Repository: https://github.com/robtimus/completion-stage
- Issues: https://github.com/robtimus/completion-stage/issues
- npm.io page: https://npm.io/package/completion-stage

## Recent versions

- 1.0.0 (latest) — 2021-12-24

## README

# completion-stage

A port of Java's [CompletionStage](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/CompletionStage.html) using [promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). [CompletableFuture](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/CompletableFuture.html) 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])`<sup>1</sup>             |
| `CompletableFuture.anyOf(future1, future2)`                       | `Promise.race([promise1, promise2])`<sup>2</sup>            |
| `CompletableFuture.completedFuture(value)`                        | `Promise.resolve(value)`                                    |
| `CompletableFuture.completedStage(value)`                         | `Promise.resolve(value)`                                    |
| `future.completeOnTimeout(value, timeout, TimeUnit.MILLISECONDS)` | `resolveOnTimeout(promise, value, timeout)`<sup>3</sup>     |
| `CompletableFuture.failedFuture(ex)`                              | `Promise.reject(ex)`                                        |
| `CompletableFuture.failedStage(ex)`                               | `Promise.reject(ex)`                                        |
| `future.orTimeout(timeout, TimeUnit.MILLISECONDS)`                | `rejectOnTimeout(promise, timeout)`<sup>3</sup><sup>4</sup> |
| `CompletableFuture.runAsync(action)`                              | `supply(action)`<sup>5</sup>                                |
| `CompletableFuture.supplyAsync(supplier)`                         | `supply(supplier)`<sup>5</sup>                              |

<sup><sup>1</sup>: 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.</sup>\
<sup><sup>2</sup>: 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.</sup>\
<sup><sup>3</sup>: the timeouts for `resolveOnTimeout` and `rejectOnTimeout` can only be given as milliseconds.</sup>\
<sup><sup>4</sup>: an optional rejection reason can be given as a function. The result of this function is used as rejection reason upon timeout.</sup>\
<sup><sup>5</sup>: an optional delay in milliseconds can be given.</sup>

Note that [promise.then](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then), [promise.catch](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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`.

---
_Source: https://npm.io/package/completion-stage · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._