cancellable-coroutine v1.0.8
Cancellable-Coroutine
Cancellable-coroutine is a wrapper for function generators that runs them as async functions and adds cancellation support.
Usage
// Take a generator function
const myFn = function*(url) {
// Maybe you want some API data
const response = yield fetchSomething(url);
// Maybe you want to delay for some ms
yield delay(500);
console.log(response);
return response;
};
// Wrap the generator in Cancellable.create(...)
const cancellableFn = Cancellable.create(myFn);
// Run the wrapped function, which runs like a function using `async/await`.
// The function returns a promise, which resolves on complete, or rejects on uncaught exception or cancellation.
cancellableFn('https://my-api.com').then(onComplete, onFailureOrCancel);
// Now we can halt the execution of our generator function whenever we want! We use Cancellable.cancel(..) to cancel.
setTimeout(() => {
Cancellable.cancel(cancellableFn);
}, 200);API
create(generatorFn)
Returns a CancellableTask.
When calling this CancellableTask, generatorFn will run like an async/await function (all yield expressions will resolve in sequence).
const task = Cancellable.create(function*(arg: string) {
const result1 = yield doAThing(arg);
const result2 = yield doAnAsyncThing(result1);
return yield doAThirdThing(result2);
};
/*
this task will run like:
async function(arg: string) {
const result1 = await doAThing(arg);
const result2 = await doAnAsyncThing(result1);
return await doAThirdThing(result2);
}
*/
task('hello');cancel(cancellableTask)
Cancels cancellableTask.
If cancellableTask is running, a CancelError will be thrown in the wrapped generator function. If the task is not running, nothing will happen.
const task = Cancellable.create(function*() {
try {
yield doAThingThatTakes5Seconds();
// We want to cancel before this line.
console.log("We did it!");
} catch (error) {
if (Cancellable.isCancelError(error)) {
console.log("We cancelled!");
} else {
console.log("We failed!");
}
}
};
task();
setTimeout(() => {
Cancellable.cancel(task);
}, 1000);
// Only "We cancelled!" will output to the console.CancelError
Extends Error. A CancelError will be thrown into the generator function if it is cancelled while running.
isCancelError(error)
Returns true if the passed error is a CancelError, false otherwise. This can be used in a catch(error) block to check whether error was caused by cancellation or not.
try {
...
} catch (error) {
if (isCancelError(error)) {
// We cancelled!
} else {
// Something else failed!
}
}isCancelled(cancellableTask)
Returns true if the passed task has been cancelled. This can be used in a calling function to check whether a called task ran successfully or was cancelled.
const task = Cancellable.create(function*() {
...
});
task();
Cancellable.cancel(task);
if (Cancellable.isCancelled(task)) {
// task was cancelled!
}