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

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

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).

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.

Tasks are lazy Promises

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

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

Can be made lazy like this

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

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

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.

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

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

Tasks are Cancellable

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

// 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

const myWholeTask = myTask.then(...)

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

// 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.

Tasks are Joinable

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

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

// 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

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