race-event

Race an event against an AbortSignal

About

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

Example - Getting started

1import { raceEvent } from 'race-event'
2
3const controller = new AbortController()
4const emitter = new EventTarget()
5
6setTimeout(() => {
7  controller.abort()
8}, 500)
9
10setTimeout(() => {
11  // too late
12  emitter.dispatchEvent(new CustomEvent('event'))
13}, 1000)
14
15// throws an AbortError
16const resolve = await raceEvent(emitter, 'event', controller.signal)

Example - Aborting the promise with an error event

1import { raceEvent } from 'race-event'
2
3const emitter = new EventTarget()
4
5setTimeout(() => {
6  emitter.dispatchEvent(new CustomEvent('failure', {
7    detail: new Error('Oh no!')
8  }))
9}, 1000)
10
11// throws 'Oh no!' error
12const resolve = await raceEvent(emitter, 'success', AbortSignal.timeout(5000), {
13  errorEvent: 'failure'
14})

Example - Customising the thrown AbortError

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

1import { raceEvent } from 'race-event'
2
3const controller = new AbortController()
4const emitter = new EventTarget()
5
6setTimeout(() => {
7  controller.abort()
8}, 500)
9
10// throws a Error: Oh no!
11const resolve = await raceEvent(emitter, 'event', controller.signal, {
12  errorMessage: 'Oh no!',
13  errorCode: 'ERR_OH_NO'
14})

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:

1import { raceEvent } from 'race-event'
2
3const controller = new AbortController()
4const emitter = new EventTarget()
5
6// throws a Error: Oh no!
7const resolve = await raceEvent(emitter, 'event', controller.signal, {
8  filter: (evt: Event) => {
9    return evt.detail.foo === 'bar'
10  }
11})

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:

1import { raceEvent } from 'race-event'
2
3const controller = new AbortController()
4const emitter = new EventTarget()
5
6// throws Error: Cannot continue
7const resolve = await raceEvent(emitter, 'event', controller.signal, {
8  filter: (evt) => {
9    if (...reasons) {
10      throw new Error('Cannot continue')
11    }
12
13    return true
14  }
15})

Install

1$ 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.

1<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 / http://www.apache.org/licenses/LICENSE-2.0)
• MIT (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.