race-cancellation
v0.5.0 async cancel cancellable cancellation promise race
race-cancellation
This is a library with utils to implement a cancellable async function with a pattern that solves a number of issues with cancellation of promises.
The pattern is a cancellable async function takes a function that will build the cancellation race lazily.
Design Constraints
- Composable
- Cancellation concerns can be composed easily
- Lazy
- Should not create the Promise
until it is raced or it will create meaningless unhandledRejections - Should be able to avoid invoking the raced async function if it is already cancelled
- Should be able to avoid invoking the cancellation task if the outer scope cancellation already won
- Should not create the Promise
- Adaptable
- Should be easy to adapt other promise cancellation patterns
RaceCancellation Interface
export type AsyncFn<T> = () => Promise<T>;
export type RaceCancelFn = <T>(asyncFnOrPromise: AsyncFn<T> | PromiseLike<T>) => Promise<T>;
export type CancellableAsyncFn<T> = (raceCancel: RaceCancelFn) => Promise<T>;
Since race cancellation is a function it can lazily create the Promise
Since it can take a function to invoke to produce the task,
it can avoid starting the task if it is already cancelled and can avoid creating the Promise
This also allows the combined race cancellations to be lazy. For example, if we are already cancelled because we are disconnected we don't need to start a timeout.
Examples of Cancellable Async Functions
import * as fs from "fs";
async function pollFile(path, interval, raceCancel) {
while (!fs.existsSync(path)) {
await sleep(interval, raceCancel);
}
}
async function sleep(ms, raceCancel) {
let id;
try {
const createTimeout = () =>
new Promise<void>(resolve => {
id = setTimeout(resolve, ms);
});
// if cancellation has happened race cancel can return
// a rejected promise without invoking createTimeout
// otherwise createTimeout is called and raced against
// a new Promise<never> created from the cancellation Promise,
// cancellationPromise.then(throwCancellationError)
return await raceCancel(createTimeout);
} finally {
if (id !== undefined) {
// cleanup timeout so node will exit right away if
// our script is done.
clearTimeout(id);
}
}
}
npm i race-cancellation
Metadata
- BSD-2-Clause
- Whatever
- Kris Selden
- released 10/21/2020