Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/astoilkov/p-signal
Better way to cancel promises using AbortSignal
https://github.com/astoilkov/p-signal
abortable abortcontroller aborterror abortsignal async await cancelable promise
Last synced: 3 months ago
JSON representation
Better way to cancel promises using AbortSignal
- Host: GitHub
- URL: https://github.com/astoilkov/p-signal
- Owner: astoilkov
- License: mit
- Created: 2022-06-27T16:24:40.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-18T14:44:23.000Z (10 months ago)
- Last Synced: 2024-11-01T00:40:23.658Z (3 months ago)
- Topics: abortable, abortcontroller, aborterror, abortsignal, async, await, cancelable, promise
- Language: TypeScript
- Homepage:
- Size: 34.2 KB
- Stars: 17
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: license
Awesome Lists containing this project
README
# `p-signal`
> Better way to cancel promises using `AbortSignal`
[](https://bundlephobia.com/result?p=p-signal)
[](https://github.com/astoilkov/p-signal/actions/workflows/main.yml)
## Install
```bash
npm install p-signal
```
## Why
In the past few years, async implementations are on the rise. Canceling promises is an important part of working with async code. For example, a very common pattern is for a user task to be canceled or interrupted with the need to compute the latest value. However a good solution for cancelation doesn't exist (see [Alternatives](#alternatives) section for explanation). In this new async world `p-signal` can help.
Also:
- Future-proof — based on [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) and [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal).
- Cancellation as a technique can yield performance improvements because you don't continue executing the canceled task.
- I've researched this topic for months. The solution looks simple, but it's a culmination of a lot of trial and error.
- Supports browsers, React Native, Node 18+, Node 16 (if you [polyfill AbortController](https://github.com/mo/abortcontroller-polyfill)), Deno.
- I aim for high-quality with [my open-source principles](https://astoilkov.com/my-open-source-principles).
## Usage
```ts
import { pSignal, isAbortError } from 'p-signal'
try {
const result = await pSignal(AbortSignal.timeout(200), longRunningTask())
} catch (err) {
if (isAbortError(err)) {
// operation timed out
return
}
throw err
}
async function longRunningTask() {
return await parseText(currentFile.text)
}
```
## API
#### `pSignal(signal: AbortSignal | undefined, value: Promise | () => Promise): T`
Returns: `T` — the value returned by the promise or throws an error if the promise is rejected.
The first parameter accepts: `AbortSignal` or `undefined`. `undefined` as allowed type is useful for methods that accept an optional `signal` parameter:
```ts
function readFiles(files: string[], options: { signal?: AbortSignal }) {
const result = []
for (const file of files) {
result.push(await pSignal(signal, readFile(file)))
}
return result
}
```
The second parameter accepts: a Promise, an asynchronous function, or a synchronous function that returns a Promise.
#### `isAbortError(value: unknown): value is DOMException`
Returns: `boolean`
Sometimes you care about errors but not about aborted actions. For example, you may want to send an error to an error tracking service but skip aborted actions (because they are expected).
```ts
import { pSignal } from 'p-signal'
try {
await pSignal(signal, doHeavyWork())
} catch (err) {
if (!isAbortError(err)) {
sendToErrorTrackingService(err)
}
}
```
The method also works for built-in abort errors. For example, when using `fetch()`:
```ts
import { isAbortError } from 'p-signal'
try {
fetch(url, {
signal
})
} catch (err) {
if (!isAbortError(signal)) {
sendToErrorTrackingService(err)
}
}
```
## Alternatives
For the past years I've experimented with different ways to cancel promises. Unfortunately, a perfect solution doesn't exist because the design of JavaScript asynchronicity has inherent problems. Here are two alternatives I was using before coming up with the idea of `p-signal`:
**Cancelable promises.** [p-cancelable](https://github.com/sindresorhus/p-cancelable) and [Bluebird](https://github.com/petkaantonov/bluebird) are possible repos that you can use to work with the concept of cancelable promises. Note that Bluebird last release was in 2019. I was using cancelable promises before getting the idea about `pSignal`, and it was a nice experience.
**[CAF](https://github.com/getify/CAF).** An elegant way to solve this problem. I recommend it if your codebase is in JavaScript. For TypeScript, it isn't ideal because it can't be correctly typed because it uses generators.
## Related
- [p-cancelable](https://github.com/sindresorhus/p-cancelable) — Create a promise that can be canceled
- [promise-fun](https://github.com/sindresorhus/promise-fun) — Promise packages, patterns, chat, and tutorials
- [CAF](https://github.com/getify/CAF) — Cancelable Async Flows (CAF)
- [Deno async](https://deno.land/[email protected]/async) — Async utilities for Deno