avenir

Lightweight async library based on lazy Futures. Inspired by
folktale's Data.Task

The library provides Tasks for writing asynchronous code with JavaScript in
Node and the Browser.

Unlike Promises, Tasks are _lazy_ and _cancellable_.

avenir Tasks differ also in a few point from folktale Data.Task.

For more details, see comparisaon.

Rationale

Consider the following example using Promises

``js
var promiseA = someAsynFn()
var promiseB = promiseA.then(...)
`

Let's suppose that Promises were given builtin cancellation. And that we invoke
promiseB.cancel(). The question is how do we interpret the effects of this
cancellation ?

1. Should we only cancel promiseB and not touch promiseA ?
2. Or should we also cancel promiseA ?

In case of (1) then what if the code represented an atomic operation ? In this
case a cancellation means cancelling the whole operation and this implies
cancelling also promiseA if it's still pending.

Note that even of we write it inline like this

`js
var promiseB = someAsynFn().then(...)
`

There is no way we can infer the atomicity of the operation because Promises are
immutables and each invocation of then returns a new Promise. The new Promise
itself is not aware of how it was derived.

Now if we choose (2) and cancel the whole chain, then imagine there is another
operation that was attached to promiseA (or that will be attached in some point
of the future[no pun intended] in our code).

`js
var promiseA = someAsynFn()
var promiseB = promiseA.then(...)
var promiseC = promiseA.then(...)
`

Now if promiseB.cancel() triggers cancellation on promiseA then this cancellation
will propagate downward and cancel also promiseC (because it can not be derived
from a cancelled Promise) but we were only aiming at cancelling promiseB
not promiseC.

Here we have 2 separate chains promiseA -> promiseB and promiseA -> promiseC.
Another perspective is to view the operation as a tree with promiseA as root and
with 2 branches whose leafs are promiseB and promiseC. So cancelling one branch
should not affect the other branch (however cancelling the root or cancelling
the whole tree should propagate to the branches as well).

A possible solution is to maintain some ref. couning in promisA. Each time we chain
a then operation we increase the counter if promiseA and once the derived
promise is completed (whatever the outcome) we decrese the counter. If the counter
reaches 0 then we cancel promiseA since all operations that depend on it
have completed.

But ref. couting can have subtle issues. For example what if after promiseB and
and promiseC aer cancelled - cancelling promiseA in the way - we reattach another
then operation in some other part of the code ? And I dont mention here issues
related to race conditions due to async scheduling of chained operations which makes
maintaining the ref. counter error prone. Issues like this one
is a simple illustration. And I'd expect more subtle issues to manifest in real world
applications (I've myself experienced many of those issues when implementing redux-saga
and I couldn't get rid of them until I dropped async scheduling in sequenced
operations and made everything synchronous).

So it's clear how we should propagate cancellation up depends on the
situation. But the problem is precisely how do we infer this situation. A Promise,
once created, lacks the whole context in which it is itself composed with other
Promises to build a control flow. While we can maintain a reference to the parent
promise from which the current promise was derived. We can not know how this
parent promise is used elsewhere and all the other operations that has been or
will be derived from it.
So we can not simply implement a cancel method in the Promise prototype because
we do not have enough information to interpret the meaning of the cancellation.

Another solution is to extract out the cancellation capability into a first
class value. For example we can create some token and then pass it down
to all async operations that construct Promises. The creator of the token can
request the cancellation at any moment. The async operations that have
received the token can then be notified of the cancellation. This is the
solution that was planned to be implemented into the TC39 standard (but was
dropped because of lack of consensus).

We can view the token based solution as an indirect way to describe chained
steps as a whole unit. A created cancel token denote itself the whole operation
and all async functions that receive the token are part of the unit.

Another solution, which IMHO is simpler, more composable and ergonomic is to
make this whole operation - the big picture - itself as a first class value
using Tasks.

$3

A Task can be thought of as a lazy Promise. For example, the following Promise

`js
const promiseA = new Promise((resolve, reject) = {
invokeAsyncFunc((err, res) => {
if(err) reject(err)
else resolve(res)
})
})
`

Can be made lazy like this

`js
const lazyPromiseA = () => new Promise((resolve, reject) = {
invokeAsyncFunc((err, res) => {
if(err) reject(err)
else resolve(res)
})
})
`

The difference is that in the first case the operation is started right after the
Promise creation. While in the second we've only constructed a description of t
he operation.

Now suppose we want to describe a new operation that is the chaining of the above
and another one

`js
const lazySequence = () => lazyPromiseA().then(...)
`

So what's the difference ? one may ask.

Well in the case of normal/hot promises, we've seen that we can not interpret

`js
var hotSequence = promiseA.then(...)
`

as a whole operation that includes promiseA because this one can be used
elsewhere in another sequence.

However in the case of lazy Promises we do have this knowledge. Precisely because
the operation has not started yet. And simply because we will start it ourselves
as a whole operation.

So Tasks are just this and nothing more. The Task
abstraction provided by this library or by
folktale's Data.Task
just wraps this lazy execution and makes it more composable by providing functions to
describe the control flow (like then/chain, all, race ...)

In avenir, you can create a Task with a API similar to Promises using
Task.from. Note the executor
argument takes also a cancel callback. This can be invoked by the executor to
trigger cancellation from the source.

`js
const myTask = Task.from((resolve, reject, cancel) = {
invokeAsyncFunc((err, res) => {
if(err) reject(err)
else resolve(res)
})
})
`

The executor of the Task is not started at the Task creation. It means no side
effect takes place at this moment yet. To effectively start a Task, you must
invoke its run method

`js
// Execution starts from here
myTask.run(onSuccess, onError, onCancel)
`

$3

After a Task has been started, it can be cancelled using the returned Future

`js
// Execution starts from here
const future = myTask.run(onSuccess, onError, onCancel)

// ... after some time
future.cancel('some reason')
`

You can use Task#then
to chain another step

`js
const myWholeTask = myTask.then(...)
`

myWholeTask is a new Task that describes the whole sequence. So when starting it

`js
// Task#fork is the same as Task#run but does not take callbcaks
const future = myWholeTask.fork()
`

Cancelling the returned future will cancel the whole sequence. Due to their lazy
nature, Tasks give an unambiguous meaning to cancellation.

$3

Sometimes a Task needs to join the result of an already started Task (ie a Future).
This can happen if, for example, the 2 Tasks are started from 2 unrelated
contexts (like 2 events handlers in separate UIs).

For example suppose we have a login Task that is started when the user clicks on
a UI button

`js
const loginTask = Task.from((resolve, reject, cancel) => {
api.authorize((err, ok) => {
// attach a cancellation from the source
onCancelLoginClick(() => cancel('Login cancelled'))
if(err) reject(err)
else resolve(ok)
})
})


let loginFuture

function loginClickHandler() {
loginFuture = loginTask.run(onSuccess, onReject, onCancel)
}
`

In another part of the UI, we want to start fetching something but only after the
login succeds. We can use Task.join
to wait for loginFuture to finish

`js
// Task.do allows using Generator syntax
const fetchDataTask = Task.do(function*() {
yield Task.join(loginFuture)
const data = yield myFetchTask
return data
})
`

Above, we used the Generator syntax to describe the operation. We wait for loginFuture
to resolve before continuing. If the login task was cancelled (either by invoking
loginFuture.cancel() or by the loginTask itself if the user clicks on a CancelLogin
button) then the fetchDataTask will be cancelled as well.

Observe that if we cancel fetchDataTask for some other reason while we're
still waiting for loginFuture

`js
const future = fetchDataTask.fork()

// for some reason later
future.cancel('some reason')

`

Then this will only affect fetchDataTask and not loginTask. Cancelling the result
of Task.join(loginFuture)` (which is itself a Task) will only unsubscribe from
the result of loginFuture. The loginTask stays unaffected.

Documentation

API Docs