Cancelable Async Functions (CAF)
CAF (/ˈkahf/) is a wrapper for function*
generators that treats them like async function
s, but with support for external cancelation.
Environment Support
This utility uses ES6 (aka ES2015) features. If you need to support environments prior to ES6, transpile it first (with Babel, etc).
At A Glance
CAF (Cancelable Async Functions) wraps a function*
generator so it behaves like an async function
that can be externally canceled:
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 fake async function, listen to its
// returned promise
main( token.signal, "http://some.tld/other" )
.then( onResponse, onCancelOrError );
// only wait 5 seconds for the request!
setTimeout( function onElapsed(){
token.abort( "Request took too long!" );
}, 5000 );
Create a cancelation 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.
Moreover, the generator itself is provided the cancelation token's signal
, so you can call another function*
generator via CAF and pass along that shared signal
. In this way, a single cancelation signal can cascade across all the CAF-wrapped functions in the 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 cancelation token is used for the 3 generators, if token.abort()
is executed while they're all still paused, they will all immediately abort.
Note: In this example, the cancelation token has no effect on the actual ajax(..)
call itself, since that utility ostensibly doesn't provide cancelation 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 Cancelation Signal Handling below for addressing this concern.
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 function
s inherent to having the syntax and engine make implicit assumptions that you otherwise have to explicitly handle with function*
generators.
One clear example of these limitations 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 cancelation point. This is ugly and error-prone.
function*
generators by contrast can be aborted at any time, using the iterator's return(..)
method. But the downside of using function*
generators is either needing a runner utility or the repetitive boilerplate of handling the iterator manually.
The best solution would be a function*
generator that can be called like a normal async function
, but with a cancelation token to signal it to cancel. That's what CAF provides.
The CAF(..)
function takes a function*
generator, and returns a regular function that expects any arguments, much the same as if it was a normal async function
. Other than minor syntactic aesthetics, the most observable difference is that a CAF-wrapped function should be provided a cancelation token's signal
as its first argument, with any other arguments passed subsequent, as desired.
Overview
These two functions are essentially equivalent; one(..)
is an actual async function
, whereas two(..)
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 cancelation 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 cancelation 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 cancelToken()
instance and a manual call to the environment's setTimeout(..)
. However, there are some subtle but important downsides to doing this kind of thing manually. These downsides are harder to spot in the browser, but are more obvious in Node.js
Consider this code:
function delay(ms) {
return new Promise( function c(res){
setTimeout( res, ms );
} );
}
var token = new CAF.cancelToken();
var main = CAF( function *main(signal,ms){
yield delay( ms );
console.log( "All done!" );
} );
main( token.signal, 100 );
// only wait 5 seconds for the request!
delay( 5000 ).then( function onElapsed(){
token.abort( "Request took too long!" );
} );
The main(..)
function delays for 100
ms and then completes. But there's no logic that clears the timeout set from delay( 5000 )
, so it will continue to hold pending until that amount of time expires.
Of course, the token.abort(..)
call at that point is moot, and is thus silently ignored. But the problem is the timer still running, which keeps a Node.js process alive even if the rest of the program has completed. The symptoms of this would be running a Node.js program from the command line and observing it "hang" for a bit at the end instead of exiting right away. Try the above code to see this in action.
So there's two problems if you want to avoid this downside:
-
If you set up your own timer externally, you need to keep track of the timer's handle so you can call
clearTimeout(..)
if the async task completes successfully before the timeout expires. This is manual and error-prone, as it's far too easy to forget. -
The
delay(..)
helper show, which is a promisified version ofsetTimeout(..)
, is basically what you can produce by using Node.js'sutil.promisify(..)
againstsetTimeout(..)
. However, that timer itself is not cancelable. You can't access the timer handle (return value fromsetTimeout(..)
) to callclearTimeout(..)
on it.
To avoid requiring you to invent solutions to these problems, CAF provides two utilities for managing cancelable delays and timeout cancelations: CAF.delay(..)
and CAF.timeout(..)
.
CAF.delay(..)
Let's look at a scenario that illustrates the CAF.delay(..)
utility:
var token = new CAF.cancelToken();
var discardTimeout = new CAF.cancelToken();
var main = CAF( function *main(signal,ms){
yield CAF.delay( signal, ms );
console.log( "All done!" );
} );
main( token.signal, 100 )
.then( function onComplete(){
discardTimeout.abort();
} );
// only wait 5 seconds for the request!
CAF.delay( discardTimeout.signal, 5000 )
.then(
function onElapsed(msg){
// msg: "delayed: 5000"
token.abort( "Request took too long!" );
},
function onInterrupted(reason){
// reason: "delay (5000) interrupted"
}
);
CAF.delay(..)
is a promisified setTimeout(..)
wrapped, but with support for external cancelation, so you can clear and discard the timeout if you need to. The promise returned from CAF.delay(..)
is fulfilled if the full time amount elapses, with a message such as "delayed: 5000"
. If the timeout is aborted via the cancelation token, the promise is rejected with a reason like "delay (5000) interrupted"
.
Also note that if you don't need a cancelable timeout, CAF.delay(..)
just works normally without creating or passing a token signal:
CAF.delay( 200 ).then( function onElapsed(){
console.log( "Some time went by!" );
} );
CAF.timeout(..)
While CAF.delay(..)
provides a cancelable timeout promise, it's still overly manual to connect the dots between a CAF-wrapped function and the timeout-abort. CAF provides CAF.timeout(..)
to streamline this use-case:
var timeoutToken = CAF.timeout( 5000, "Took too long!" );
var main = CAF( function *main(signal,ms){
yield CAF.delay( signal, ms );
console.log( "All done!" );
} );
main( timeoutToken, 100 ); // NOTE: passing the token and not the .signal !!
CAF.timeout(..)
creates an instance of cancelationToken(..)
that's set to abort()
after the specified amount of time, optionally using the message you provide.
Note that you should pass the full timeoutToken
token to the CAF-wrapped function (main(..)
), instead of normally just passing timeoutToken.signal
. CAF is then able to wire the token and the CAF-wrapped function together, so that each one stops the other, whichever one triggers first. No more hanging timeouts!
Also note that main(..)
receives a normal signal
as always, which is suitable to pass along to other cancelable async functions, such as CAF.delay(..)
as shown.
timeoutToken
is a regular cancelation token as created by CAF.cancelToken()
. As such, you can call abort(..)
on it directly, if necessary. You can also access timeoutToken.signal
to access its signal, and timeoutToken.signal.pr
to access the promise that's rejected when the signal is aborted.
finally { .. }
Canceling a CAF-wrapped function*
generator that is paused causes it to abort right away, but if there's a pending finally {..}
clause, that will still have a chance to run.
Moreover, a return
of any non-undefined
value in that pending finally {..}
clause will override the promise rejection reason:
var token = new CAF.cancelToken();
var main = CAF( function *main(signal,url){
try {
return yield ajax( url );
}
finally {
return 42;
}
} );
main( token.signal, "http://some.tld/other" )
.catch( console.log ); // 42 <-- not "Aborting!"
token.abort( "Aborting!" );
Whatever value is passed to abort(..)
, if any, is normally set as the promise rejection reason. But in this case, return 42
overrides the "Aborting!"
rejection reason.
AbortController(..)
CAF.cancelToken(..)
instantiates AbortController
, the DOM standard for canceling/aborting operations like fetch(..)
calls. As such, a cancelation token's signal
can be passed directly to a DOM method like fetch(..)
, which will respond to it accordingly:
var token = new CAF.cancelToken();
var main = CAF(function *main(signal,url) {
var resp = yield fetch( url, { signal } );
console.log( resp );
return resp;
});
main( token.signal, "http://some.tld/other" )
.catch( console.log ); // "Aborting!"
token.abort( "Aborting!" );
Note: If the standard AbortController
is not defined in the environment, it's polyfilled by CAF. In such a case, fetch(..)
and other such DOM methods will likely not actually respond to the cancelation signal.
Manual Cancelation Signal Handling
Even if you aren't calling a cancelation signal-aware utility (like fetch(..)
), you can still manually respond to the cancelation signal
via its attached promise:
var token = new CAF.cancelToken();
var main = CAF( function *main(signal,url){
// listen to the signal's promise rejection directly
signal.pr.catch( reason => {
// reason == "Aborting!"
} );
var resp = yield ajax( url );
console.log( resp );
return resp;
} );
main( token.signal, "http://some.tld/other" )
.catch( console.log ); // "Aborting!"
token.abort( "Aborting!" );
Note: The catch(..)
handler inside of main(..)
will still run, even though main(..)
itself will be aborted at its waiting yield
statement. If there was a way to manually cancel the ajax(..)
call, that code could run in the catch(..)
handler.
And even if you aren't running a CAF-wrapped function, you can still respond to the cancelation signal
's promise manually to affect flow control:
var token = new CAF.cancelToken();
// normal async function
async function main(signal,url) {
try {
var resp = await Promise.race( [
ajax( url ),
signal.pr
] );
// this won't run if `signal.pr` rejects
console.log( resp );
return resp;
}
catch (err) {
// err == "Aborting!"
}
}
main( token.signal, "http://some.tld/other" )
.catch( console.log ); // "Aborting!"
token.abort( "Aborting!" );
Note: As discussed earlier, the ajax(..)
call itself is not cancelation aware, and is thus not being aborted here. But we are aborting our waiting on the ajax(..)
call. When signal.pr
wins the Promise.race(..)
race and creates an exception from its promise rejection, flow control jumps straight to the catch (err) { .. }
clause.
Beware Of Token Reuse
Beware of creating a single cancelation token that is reused for separate chains of function calls. Unexpected results are likely, and they can be extremely difficult to debug.
As illustrated earlier, it's totally OK and intended that a single cancelation token signal
be shared across all the functions in one chain of calls (A
-> B
-> C
). But reusing the same token across two or more chains of calls (A
-> B
-> C
and D
-> E
-> F
) is asking for trouble.
Imagine a scenario where you make two separate fetch(..)
calls, one after the other, and the second one runs too long so you cancel it via a timeout:
var one = CAF( function *one(signal){
signal.pr.catch( reason => {
console.log( `one: ${reason}` );
} );
return yield fetch( "http://some.tld/", {signal} );
} );
var two = CAF( function *two(signal,v){
signal.pr.catch( reason => {
console.log( `two: ${reason}` );
} );
return yield fetch( `http://other.tld/?v=${v}`, {signal} );
} );
var token = CAF.cancelToken();
one( token.signal )
.then( function(v){
// only wait 3 seconds for this request
setTimeout( function(){
token.abort( "Second response too slow." );
}, 3000 );
return two( token.signal, v );
} )
.then( console.log, console.error );
// one: Second response too slow. <-- Oops!
// two: Second response too slow.
// Second response too slow.
When you call token.abort(..)
to cancel the second fetch(..)
call in two(..)
, the signal.pr.catch(..)
handler in one(..)
still gets called, even though one(..)
is already finished. That's why "one: Second response too slow."
prints unexpectedly.
The underlying gotcha is that a cancelation token's signal
has a single pr
promise associated with it, and there's no way to reset a promise or "unregister" then(..)
/ catch(..)
handlers attached to it once you don't need them anymore. So if you reuse the token, you're reusing the pr
promise, and all registered promise handlers will be fired, even old ones you likely don't intend.
The above snippet illustrates this problem with signal.pr.catch(..)
, but any of the other ways of listening to a promise -- such as yield
/ await
, Promise.all(..)
/ Promise.race(..)
, etc -- are all susceptible to the unexpected behavior.
The safe and proper approach is to always create a new cancelation token for each chain of CAF-wrapped function calls. For good measure, always unset any references to a token once it's no longer needed; thus, you won't accidentally reuse it, and the JS engine can properly garbage collect it.
npm Package
Prior to version 4.0.0, the package name was "async-caf", but starting with version 4.0.0, the name has been simplified to "caf". So, to install this package from npm
:
npm install caf
And to require it in a node script:
var CAF = require("caf");
Builds
The distribution library file (dist/caf.js
) comes pre-built with the npm package distribution, so you shouldn't need to rebuild it under normal circumstances.
However, if you download this repository via Git:
-
The included build utility (
scripts/build-core.js
) builds (andminifies)dist/caf.js
from source. Note: Minification is currently disabled. The build utility expects Node.js version 6+. -
To install the build and test dependencies, run
npm install
from the project root directory.- Note: This
npm install
has the effect of running the build for you, so no further action should be needed on your part.
- Note: This
-
To manually run the build utility with npm:
npm run build
-
To run the build utility directly without npm:
node scripts/build-core.js
Tests
A comprehensive test suite is included in this repository, as well as the npm package distribution. The default test behavior runs the test suite using src/caf.src.js
.
-
You can run the tests in a browser by opening up
tests/index.html
(requires ES6+ browser environment). -
The included Node.js test utility (
scripts/node-tests.js
) runs the test suite. This test utility expects Node.js version 6+. -
Ensure the test dependencies are installed by running
npm install
from the project root directory.- Note: Starting with npm v5, the test utility is not run automatically during this
npm install
. With npm v4, the test utility automatically runs at this point.
- Note: Starting with npm v5, the test utility is not run automatically during this
-
To run the test utility with npm:
npm test
Other npm test scripts:
-
npm run test:dist
will run the test suite againstdist/caf.js
instead of the default ofsrc/caf.src.js
. -
npm run test:package
will run the test suite as if the package had just been installed via npm. This ensurespackage.json
:main
properly referencesdist/caf.js
for inclusion. -
npm run test:all
will run all three modes of the test suite.
-
-
To run the test utility directly without npm:
node scripts/node-tests.js
Test Coverage
If you have Istanbul already installed on your system (requires v1.0+), you can use it to check the test coverage:
npm run coverage
Then open up coverage/lcov-report/index.html
in a browser to view the report.
To run Istanbul directly without npm:
istanbul cover scripts/node-tests.js
Note: The npm script coverage:report
is only intended for use by project maintainers. It sends coverage reports to Coveralls.
License
All code and documentation are (c) 2018 Kyle Simpson and released under the MIT License. A copy of the MIT License is also included.