Future

> Cancellable futures for ReScript

Installation

Run the following in your console:

``console
$ yarn add rescript-future
`

Then add rescript-future to your rescript.json's bs-dependencies:

`diff
{
"bs-dependencies": [
+ "rescript-future"
]
}
`

Basics

A Future is a data structure that represents a potential value. It works both synchronously & asynchrously. It consists of 3 possible states:

- Pending: The value is yet to be resolved
- Cancelled: The future has been cancelled before could resolve
- Resolved: The future holds its value

`reason
// Basic synchronous future
Future.value(1)
->Future.map(x => x + 1)
->Future.flatMap(x => Future.value(x + 1))
->Future.get(Console.log)
// Logs: 3
`

API

See the details in the interface file

$3

- value('a) => Future.t<'a>: creates a resolved future
- makePure(('a => unit) => unit) => Future.t<'a>: creates a future
- make(('a => unit) => option unit>) => Future.t<'a>: creates a future with a cancellation effect

$3

- cancel(future): Cancels a future and its dependents

$3

- get(future, cb) => unit: Executes cb with future's resolved value

$3

- map(future, mapper): Returns a new mapped future
- flatMap(future, mapper): Returns a new mapped future with mapper returning a future itself

$3

- isPending(future) => bool
- isCancelled(future) => bool
- isResolved(future) => bool

$3

- mapResult(future, mapper)
- mapOk(future, mapper)
- flatMapOk(future, mapper)
- mapError(future, mapper)
- flatMapError(future, mapper)

$3

- tap(future, cb) => future
- tapOk(resultFuture, cb) => resultFuture
- tapError(resultFuture, cb) => resultFuture

$3

- all2((future, future))
- all3((future, future, future))
- all4((future, future, future, future))
- all5((future, future, future, future, future))
- all6((future, future, future, future, future, future))
- all(array)

$3

- FuturePromise.fromPromise
- FuturePromise.toPromise
- FuturePromise.resultToPromise

Cancellation

In JavaScript, Promises are not cancellable. That can be limiting at times, especially when using React's useEffect, that let's you return a cancellation effect in order to prevent unwanted side-effects.

`reason
let valueFromServer = Future.make(resolve => {
let request = getFromServer((err, data) => {
if err {
resolve(Error(err))
} else {
resolve(Ok(data))
}
})
Some(() => cancelRequest(request))
})

let deserializedValueFromServer =
valueFromServer->Future.map(deserialize)

Future.cancel(valueFromServer)
// valueFromServer & deserializedValueFromServer are cancelled if they were still pending
``

Aknowledgments

Heavily inspired by RationalJS/future's API