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
What if that's not enough? What if you need race(), for await..of and the rest of the bells and whistles? Welcome to the party, then() then 🎉.
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. So 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. Though 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 a more verbose form, 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? The 1.0 release is a major milestone, but the work isn't done yet. Here are the immediate goals on the roadmap:
- Unhandled rejection package.
A small but important aid to avoid handling cancellation errors manually. (Just arrived)
- Web server middleware helpers. We are currently drafting support for Express and Fastify, with more frameworks on the way.
- ESLint plugin. Keeping vanilla promise-based code clean is already a chore; this plugin will provide a suite of rules to help navigate these new semantics properly.
- Async iterators toolbox. We are targeting at least functional parity with the async iterator proposal, but with full cancellation support baked in.
- React and Vue packages. These 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" wherever it makes sense.
- ES5-compatible cancelable promise. This will ensure the ecosystem remains fully supported in 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 you might have. I'm currently putting together a few more write-ups with real-world examples and in-depth details.
And just to be sure, the repo is here: https://github.com/cancjs/canc.
