In most modern async-heavy languages, cancellation is a first-class citizen. It really should be straightforward for a developer, but in JavaScript, gaining that level of control feels a lot like swimming against the current. I've spent a fair amount of time trying to address this gap.
I didn't have a third-party library I could rely on, so I ended up building my own — and I suspect I'm probably not the only one who has traveled down that way. The resulting toolbag served me well in its rougher form and was battle-tested in-house for years before it was finally polished for a public release. Refactoring cleanup logic in our dashboard app to stop resource leaks was a huge win for cancelable promises. It convinced me they were the right tool for the job.
This has been almost a decade-long journey for me to reach the stable release, both in terms of quality and features. It seems to have ended up in a pretty good place.
The problem is the typical promise chain. You have a fetch call that turns into a formatted report:
const reportPromise = fetch('/orders')
.then(res => res.json())
.then(orders => buildReport(orders))
.then(rawReport => render(rawReport))
To halt the process, you usually have to mess with AbortController or manual flag variables. But with canc library, reportPromise.cancel() just stops all involved tasks.
Going from raw then() chains to async..await syntactic sugar requires adding some yield* "salt" to achieve the same result — or, with cancellation, no result at all:
const getReport = canc.async(function* () {
const orders = yield* canc.await(fetch('/orders').then(res => res.json()))
const rawReport = yield* canc.await(buildReport(orders))
return yield* canc.await(render(rawReport))
})
const reportPromise = getReport()
reportPromise.cancel() // Stop all tasks at any point
Need race(), for await..of, and the rest of the bells and whistles? Welcome to the party, then() then: https://github.com/cancjs/canc
The idea of coupling generators with promises has been around since the beginning. Coroutine libraries like the renowned co were a big deal in the pre-async era. That async..await is essentially built with generators and promises under the hood is hardly a coincidence.
I started piecing this together around 2017. Back then, I had already approached a related problem with Angular. Native async functions were fundamentally incompatible with Angular reactivity, backed by Zone.js. The potential solution was to rewire the semantics of async..await with generators to get the control we needed instead of relying on a transpiler. Fortunately for the framework, this eventually resolved with the retirement of Zone.js. Reusing the same foundation for the cancellation mechanism became a reasonable development in my case. Bluebird's cancellation was already around, but it was orthogonal to native promises and async..await. And since async functions make promise-based control flow a breeze, a user can't be expected to give them away for nothing.
The project spent a long time in limbo. Between fixing nasty bugs, unloading a few design footguns, paying off tech debt, and handling some copyright clearances, I had my hands full. That quiet period actually helped shape the library into what it is today. While the JS ecosystem is ever-changing, a few foundational pieces finally settled during that time. Once AbortSignal became a cross-platform primitive, it was integrated deeper into the library for better interop. And as TypeScript became the industry standard, it became clear that the library had to be TS-first for good DX. This pushed me to finally solve the long-standing typing issues with generators, at least as best as the language currently permits.
That's why you have to use yield* instead of yield. It's a necessary trade-off to ensure functional parity with async..await while keeping the type system happy. Using yield* is essentially a known workaround for a typing limitation in generators. It forced us to ditch the eloquent yield promise style of co in favor of the more verbose yield* canc.await(promise). This adds a bit of syntactic overhead, but it's the way to guarantee the strict typing we all rely on today.
It turned out to be the right call, especially since it aligns the yield/yield* distinction with the emitting vs. delegating semantics we deal with in async generator functions — canc coroutines cover this too.
What's next? 1.0 is a big milestone, but work continues. The unhandled rejection package to reduce manual error handling has just been shipped. Beyond that, here are the nearest items on the roadmap:
Web server middleware helpers. Drafting support for Express and Fastify, with more frameworks on the way.
ESLint plugin. Rules to help navigate these new semantics properly.
Async iterators toolbox. Targeting functional parity with the async iterator helpers proposal, but with full cancellation support baked in.
React and Vue packages. Helpers are available for evaluation in React and Vue examples, working on improving them.
Node.js package. A drop-in replacement for built-in Node APIs, with functions both promisified and "cancelified" where it makes sense.
ES5-compatible cancelable promise. Ensuring support for older runtimes and restricted environments.
I hope you find the library useful, or are at least interested in the approach. I'd be very grateful for any feedback or suggestions. I'm currently putting together a few more write-ups with real-world examples and in-depth details.
Just to be sure, the repo is here: https://github.com/cancjs/canc.
Top comments (0)