cancellation
Make async function cancellable.
Presentation
@jsenv/cancellation
provides a pattern to make your code cancellable. It is an implementation of cancellation API proposal that does not provide 100% of the proposal.
Installation
npm install @jsenv/cancellation
createCancellationTokenForProcess
createCancellationTokenForProcess
is a function returning a cancellation token cancelled just before process exits. Can be used to close a server before a process exists for instance.
import { createCancellationTokenForProcess } from "@jsenv/util"
import { startServer } from "somewhere"
const cancellationToken = createCancellationTokenForProcess()
const server = await startServer()
cancellationToken.register(() => {
server.stop()
})
— source code at src/createCancellationTokenForProcess.js.
executeAsyncFunction
executeAsyncFunction
receives an async function and calls it immediatly. By default it won't do anything special but you can control what happens during the function execution using catchCancellation
and considerUnhandledRejectionsAsExceptions
.
— source code at src/executeAsyncFunction.js.
catchCancellation
It is a boolean which is false by default. When enabled any cancellation error thrown during the function execution is catched and returned.
By default when a function is cancelled it throws a cancel error. Use catchCancellation
to avoid the cancellation error to terminates Node.js process with exit code 1.
Without catchCancellation
import { createCancellationSource } from "@jsenv/cancellation"
const fn = async ({ cancellationToken }) => {
cancellationToken.throwIfRequested()
}
const cancelSource = createCancellationSource()
cancelSource.cancel()
await fn({
cancellationToken: cancelSource.token,
})
console.log("Hello")
> node --experimental-top-level-await file.js
CANCEL_ERROR: canceled because toto
With catchCancellation
import { createCancellationSource, executeAsyncFunction } from "@jsenv/cancellation"
const fn = async ({ cancellationToken }) => {
cancellationToken.throwIfRequested()
}
const cancelSource = createCancellationSource()
cancelSource.cancel("toto")
await executeAsyncFunction(
() =>
fn({
cancellationToken: cancelSource.token,
}),
{
catchCancellation: true,
},
)
console.log("Hello")
> node --experimental-top-level-await node.js
Hello
As you can see the cancellation error is ignored. You could use isCancelError
to detect the cancellation like this:
import { isCancelError, executeAsyncFunction } from "@jsenv/cancellation"
const result = await executeAsyncFunction(
() =>
fn({
cancellationToken: cancelSource.token,
}),
{
catchCancellation: true,
},
)
if (isCancelError(result)) {
console.log("cancelled")
}
But in practice cancellation means you are no longer interested in the result of the function execution. In my experience I never needed to do that.
considerUnhandledRejectionsAsExceptions
It is a boolean which is false by default. When enabled, any unhandled rejection occuring during the function execution will throw the error and Node.js will exits with 1. This function is usefull in case Node.js was launched with unhandled rejection mode that is not strict
but you want to force a strict behaviour during a function execution.
In other words any unexpected error ocurring during your function execution will throw even if Node.js process is not in strict mod regarding unhandled rejection.
Without considerUnhandledRejectionsAsExceptions
const fn = async () => {
Promise.reject(new Error("toto"))
}
await fn()
> node --experimental-top-level-await file.js
(node:58618) UnhandledPromiseRejectionWarning: Error: toto
With considerUnhandledRejectionsAsExceptions
import { executeAsyncFunction } from "@jsenv/cancellation"
const fn = async () => {
Promise.reject(new Error("toto"))
}
await executeAsyncFunction(fn, { considerUnhandledRejectionsAsExceptions: true })
> node --experimental-top-level-await file.js
Error: toto