Cancelable Async Flows (CAF)

CAF (/ˈkahf/) is a wrapper for function* generators that treats them like async functions, but with support for external cancellation via tokens. In this way, you can express flows of synchronous-looking asynchronous logic that are still cancelable (Cancelable Async Flows).

Also included is CAG(..), for alternately wrapping function* generators to emulate ES2018 async-generators (async function *).

Environment Support

This library uses ES2018 features. If you need to support environments prior to ES2018, transpile it first (with Babel, etc).

At A Glance

CAF (Cancelable Async Flows) wraps a function* generator so it looks and behaves like an async function, but that can be externally canceled using a cancellation token:

var token = new CAF.cancelToken();

// wrap a generator to make it look like a normal async
// function that when called, returns a promise.
var main = CAF( function *main(signal,url){
    var resp = yield ajax( url );

    // want to be able to cancel so we never get here?!?
    console.log( resp );
    return resp;
} );

// run the wrapped async-looking function, listen to its
// returned promise
main( token.signal, "http://some.tld/other" )
.then( onResponse, onCancelOrError );

// only wait 5 seconds for the ajax request!
setTimeout( function onElapsed(){
    token.abort( "Request took too long!" );
}, 5000 );

Create a cancellation token (via new CAF.cancelToken()) to pass into your wrapped function* generator, and then if you cancel the token, the function* generator will abort itself immediately, even if it's presently waiting on a promise to resolve.

The generator receives the cancellation token's signal, so from inside it you can call another function* generator via CAF and pass along that shared signal. In this way, a single cancellation signal can cascade across and cancel all the CAF-wrapped functions in a chain of execution:

var token = new CAF.cancelToken();

var one = CAF( function *one(signal,v){
    return yield two( signal, v );
} );

var two = CAF( function *two(signal,v){
    return yield three( signal, v );
} );

var three = CAF( function *three(signal,v){
    return yield ajax( `http://some.tld/?v=${v}` );
} );

one( token.signal, 42 );

// only wait 5 seconds for the request!
setTimeout( function onElapsed(){
    token.abort( "Request took too long!" );
}, 5000 );

In this snippet, one(..) calls and waits on two(..), two(..) calls and waits on three(..), and three(..) calls and waits on ajax(..). Because the same cancellation token is used for the 3 generators, if token.abort() is executed while they're all still paused, they will all immediately abort.

Note: The cancellation token has no effect on the actual ajax(..) call itself here, since that utility ostensibly doesn't provide cancellation capability; the Ajax request itself would still run to its completion (or error or whatever). We've only canceled the one(..), two(..), and three(..) functions that were waiting to process its response. See AbortController(..) and Manual Cancellation Signal Handling below for addressing this limitation.

CAG: Cancelable Async ~~Flows~~ Generators

ES2018 added "async generators", which is a pairing of async function and function* -- so you can use await and yield in the same function, await for unwrapping a promise, and yield for pushing a value out. An async-generator (async function * f(..) { .. }), like regular iterators, is designed to be sequentially iterated, but using the "async iteration" protocol.

For example, in ES2018:

async function *stuff(urls) {
    for (let url of urls) {
        let resp = await fetch(url);  // await a promise
        yield resp.json();  // yield a value (even a promise for a value)
    }
}

// async-iteration loop
for await (let v of stuff(assetURLs)) {
    console.log(v);
}

In the same way that CAF(..) emulates an async..await function with a function* generator, the CAG(..) utility emulates an async-generator with a normal function* generator. You can cancel an async-iteration early (even if it's currently waiting internally on a promise) with a cancellation token.

You can also synchronously force-close an async-iterator by calling the return(..) on the iterator. With native async-iterators, return(..) is not actually synchronous, but CAG(..) patches this to allow synchronous closing.

Instead of yielding a promise the way you do with CAF(..), you use a provided pwait(..) function with yield, like yield pwait(somePromise). This allows a yield ..value.. expression for pushing out a value through the iterator, as opposed to yield pwait(..value..) to locally wait for the promise to resolve. To emulate a yield await ..value.. expression (common in async-generators), you use two yields together: yield yield pwait(..value..).

For example:

// NOTE: this is CAG(..), not to be confused with CAF(..)
var stuff = CAG(function *stuff({ signal, pwait },urls){
    for (let url of urls) {
        let resp = yield pwait(fetch(url,{ signal }));  // await a promise
        yield resp.json();  // yield a value (even a promise for a value)
    }
});

var timeout = CAF.timeout(5000,"That's enough results!");
var it = stuff(timeout,assetURLs);

cancelBtn.addEventListener("click",() => it.return("Stop!"),false);

// async-iteration loop
for await (let v of it) {
    console.log(v);
}

In this snippet, the stuff(..) async-iteration can either be canceled if the 5-second timeout expires before iteration is complete, or the click of the cancel button can force-close the iterator early. The difference between them is that token cancellation would result in an exception bubbling out (to the consuming loop), whereas calling return(..) will simply cleanly close the iterator (and halt the loop) with no exception.

Background/Motivation

Generally speaking, an async function and a function* generator (driven with a generator-runner) look very similar. For that reason, most people just prefer the async function form since it's a little nicer syntax and doesn't require a library for the runner.

However, there are limitations to async functions that come from having the syntax and engine make implicit assumptions that otherwise would have been handled by a function* generator runner.

One unfortunate limitation is that an async function cannot be externally canceled once it starts running. If you want to be able to cancel it, you have to intrusively modify its definition to have it consult an external value source -- like a boolean or promise -- at each line that you care about being a potential cancellation point. This is ugly and error-prone.

function* generators by contrast can be aborted at any time, using the iterator's return(..) method and/or by just not resuming the generator iterator instance with next(). But the downside of using function* generators is either needing a runner utility or the repetitive boilerplate of handling the iterator manually.

CAF provides a useful compromise: a function* generator that can be called like a normal async function, but which supports a cancellation token.

The CAF(..) utility wraps a function* generator with a normal promise-returing function, just as if it was an async function. Other than minor syntactic aesthetics, the major observable difference is that a CAF-wrapped function must be provided a cancellation token's signal as its first argument, with any other arguments passed subsequent, as desired.

By contrast, the CAG(..) utility wraps a function* generator as an ES2018 async-generator (async function *) that respects the native async-iteration protocol. Instead of await, you use yield pwait(..) in these emulated async-generators.

Overview

In the following snippet, the two functions are essentially equivalent; one(..) is an actual async function, whereas two(..) is a wrapper around a generator, but will behave like an async function in that it also returns a promise:

async function one(v) {
    await delay( 100 );
    return v * 2;
}

var two = CAF( function *two(signal,v){
    yield delay( 100 );
    return v * 2;
} );

Both one(..) and two(..) can be called directly with argument(s), and both return a promise for their completion:

one( 21 )
.then( console.log, console.error );   // 42

var token = new CAF.cancelToken();

two( token.signal, 21 )
.then( console.log, console.error );   // 42

If token.abort(..) is executed while two(..) is still running, the signal's promise will be rejected. If you pass a cancellation reason (any value, but typically a string) to token.abort(..), that will be the promise rejection reason:

two( token, 21 )
.then( console.log, console.error );    // Took too long!

token.abort( "Took too long!" );

Delays & Timeouts

One of the most common use-cases for cancellation of an async task is because too much time passes and a timeout threshold is passed.

As shown earlier, you can implement that sort of logic with a `cancelTok