# race-event

> Race an event against an AbortSignal

Latest version **1.6.1** (published 2025-07-22) · Apache-2.0 OR MIT license · 0 weekly downloads

## Install

```sh
npm install race-event
pnpm add race-event
yarn add race-event
bun add race-event
```

## Health

**Score 45/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.6.1 |
| Published | 2025-07-22 |
| First published | 2024-01-05 |
| Weekly downloads | 0 |
| License | Apache-2.0 OR MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 1 |
| Unpacked size | 36.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| Author | Alex Potsides |
| Maintainers | achingbrain |

## Links

- npm: https://www.npmjs.com/package/race-event
- Repository: https://github.com/achingbrain/race-event
- Homepage: https://github.com/achingbrain/race-event#readme
- Issues: https://github.com/achingbrain/race-event/issues
- npm.io page: https://npm.io/package/race-event

## Dependencies (1)

- [abort-error](https://npm.io/package/abort-error.md) ^1.0.1

## Recent versions

- 1.6.1 (latest) — 2025-07-22
- 1.6.0 — 2025-07-11
- 1.5.0 — 2025-07-11
- 1.4.0 — 2025-07-11
- 1.3.0 — 2024-04-25
- 1.2.0 — 2024-02-14
- 1.1.0 — 2024-01-05
- 1.0.0 — 2024-01-05
- 0.0.0 — 2024-01-05

## README

# race-event

[![codecov](https://img.shields.io/codecov/c/github/achingbrain/race-event.svg?style=flat-square)](https://codecov.io/gh/achingbrain/race-event)
[![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/race-event/js-test-and-release.yml?branch=main\&style=flat-square)](https://github.com/achingbrain/race-event/actions/workflows/js-test-and-release.yml?query=branch%3Amain)

> Race an event against an AbortSignal

# About

<!--

!IMPORTANT!

Everything in this README between "# About" and "# Install" is automatically
generated and will be overwritten the next time the doc generator is run.

To make changes to this section, please update the @packageDocumentation section
of src/index.js or src/index.ts

To experiment with formatting, please run "npm run docs" from the root of this
repo and examine the changes made.

-->

Race an event against an AbortSignal, taking care to remove any event
listeners that were added.

## Example - Getting started

```TypeScript
import { raceEvent } from 'race-event'

const controller = new AbortController()
const emitter = new EventTarget()

setTimeout(() => {
  controller.abort()
}, 500)

setTimeout(() => {
  // too late
  emitter.dispatchEvent(new CustomEvent('event'))
}, 1000)

// throws an AbortError
const resolve = await raceEvent(emitter, 'event', controller.signal)
```

## Example - Aborting the promise with an error event

```TypeScript
import { raceEvent } from 'race-event'

const emitter = new EventTarget()

setTimeout(() => {
  emitter.dispatchEvent(new CustomEvent('failure', {
    detail: new Error('Oh no!')
  }))
}, 1000)

// throws 'Oh no!' error
const resolve = await raceEvent(emitter, 'success', AbortSignal.timeout(5000), {
  errorEvent: 'failure'
})
```

## Example - Customising the thrown AbortError

The error message and `.code` property of the thrown `AbortError` can be
specified by passing options:

```TypeScript
import { raceEvent } from 'race-event'

const controller = new AbortController()
const emitter = new EventTarget()

setTimeout(() => {
  controller.abort()
}, 500)

// throws a Error: Oh no!
const resolve = await raceEvent(emitter, 'event', controller.signal, {
  errorMessage: 'Oh no!',
  errorCode: 'ERR_OH_NO'
})
```

## Example - Only resolving on specific events

Where multiple events with the same type are emitted, a `filter` function can
be passed to only resolve on one of them:

```TypeScript
import { raceEvent } from 'race-event'

const controller = new AbortController()
const emitter = new EventTarget()

// throws a Error: Oh no!
const resolve = await raceEvent(emitter, 'event', controller.signal, {
  filter: (evt: Event) => {
    return evt.detail.foo === 'bar'
  }
})
```

## Example - Terminating early by throwing from the filter

You can cause listening for the event to cease and all event listeners to be
removed by throwing from the filter:

```TypeScript
import { raceEvent } from 'race-event'

const controller = new AbortController()
const emitter = new EventTarget()

// throws Error: Cannot continue
const resolve = await raceEvent(emitter, 'event', controller.signal, {
  filter: (evt) => {
    if (...reasons) {
      throw new Error('Cannot continue')
    }

    return true
  }
})
```

# Install

```console
$ npm i race-event
```

## Browser `<script>` tag

Loading this module through a script tag will make its exports available as `RaceEvent` in the global namespace.

```html
<script src="https://unpkg.com/race-event/dist/index.min.js"></script>
```

# API Docs

- <https://achingbrain.github.io/race-event>

# License

Licensed under either of

- Apache 2.0, ([LICENSE-APACHE](https://github.com/achingbrain/race-event/LICENSE-APACHE) / <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT ([LICENSE-MIT](https://github.com/achingbrain/race-event/LICENSE-MIT) / <http://opensource.org/licenses/MIT>)

# Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

---
_Source: https://npm.io/package/race-event · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._