race-event - npm Package Compare versions

Comparing version 1.1.0 to 1.2.0

dist/index.min.js

 (function (root, factory) {(typeof module === 'object' && module.exports) ? module.exports = factory() : root.RaceEvent = factory()}(typeof self !== 'undefined' ? self : this, function () {
-"use strict";var RaceEvent=(()=>{var c=Object.defineProperty;var L=Object.getOwnPropertyDescriptor;var b=Object.getOwnPropertyNames;var u=Object.prototype.hasOwnProperty;var f=(r,e)=>{for(var t in e)c(r,t,{get:e[t],enumerable:!0})},h=(r,e,t,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let o of b(e))!u.call(r,o)&&o!==t&&c(r,o,{get:()=>e[o],enumerable:!(n=L(e,o))||n.enumerable});return r};var p=r=>h(c({},"__esModule",{value:!0}),r);var w={};f(w,{AbortError:()=>s,raceEvent:()=>m});var s=class extends Error{type;code;constructor(e,t){super(e??"The operation was aborted"),this.type="aborted",this.name="AbortError",this.code=t??"ABORT_ERR"}};async function m(r,e,t,n){let o=new s(n?.errorMessage,n?.errorCode);return t?.aborted===!0?Promise.reject(o):new Promise((v,E)=>{let i=d=>{n?.filter?.(d)!==!1&&(r.removeEventListener(e,i),t?.removeEventListener("abort",a),v(d))},a=()=>{r.removeEventListener(e,i),t?.removeEventListener("abort",a),E(o)};r.addEventListener(e,i),t?.addEventListener("abort",a)})}return p(w);})();
+"use strict";var RaceEvent=(()=>{var a=Object.defineProperty;var b=Object.getOwnPropertyDescriptor;var u=Object.getOwnPropertyNames;var f=Object.prototype.hasOwnProperty;var h=(r,e)=>{for(var t in e)a(r,t,{get:e[t],enumerable:!0})},p=(r,e,t,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let o of u(e))!f.call(r,o)&&o!==t&&a(r,o,{get:()=>e[o],enumerable:!(n=b(e,o))||n.enumerable});return r};var y=r=>p(a({},"__esModule",{value:!0}),r);var w={};h(w,{AbortError:()=>i,raceEvent:()=>m});var i=class extends Error{type;code;constructor(e,t){super(e??"The operation was aborted"),this.type="aborted",this.name="AbortError",this.code=t??"ABORT_ERR"}};async function m(r,e,t,n){let o=new i(n?.errorMessage,n?.errorCode);return t?.aborted===!0?Promise.reject(o):new Promise((E,v)=>{let s=d=>{try{if(n?.filter?.(d)===!1)return}catch(L){r.removeEventListener(e,s),t?.removeEventListener("abort",c),v(L);return}r.removeEventListener(e,s),t?.removeEventListener("abort",c),E(d)},c=()=>{r.removeEventListener(e,s),t?.removeEventListener("abort",c),v(o)};r.addEventListener(e,s),t?.addEventListener("abort",c)})}return y(w);})();
 return RaceEvent}));

dist/src/index.d.ts

@@ -7,6 +7,6 @@ /**
  *
- * @example
+ * @example Getting started
  *
  * ```TypeScript
- * const { raceEvent } = require('race-event')
+ * import { raceEvent } from 'race-event'
  *
@@ -28,2 +28,66 @@ * const controller = new AbortController()
  * ```
+ *
+ * @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
+ *   }
+ * })
+ * ```
  */
@@ -30,0 +94,0 @@ /**

dist/src/index.js

@@ -7,6 +7,6 @@ /**
  *
- * @example
+ * @example Getting started
  *
  * ```TypeScript
- * const { raceEvent } = require('race-event')
+ * import { raceEvent } from 'race-event'
  *
@@ -28,2 +28,66 @@ * const controller = new AbortController()
  * ```
+ *
+ * @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
+ *   }
+ * })
+ * ```
  */
@@ -54,3 +118,11 @@ /**
         const eventListener = (evt) => {
-            if (opts?.filter?.(evt) === false) {
+            try {
+                if (opts?.filter?.(evt) === false) {
+                    return;
+                }
+            }
+            catch (err) {
+                emitter.removeEventListener(eventName, eventListener);
+                signal?.removeEventListener('abort', abortListener);
+                reject(err);
                 return;
@@ -57,0 +129,0 @@ }

package.json

 {
   "name": "race-event",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Race an event against an AbortSignal",
@@ -140,4 +140,4 @@ "author": "Alex Potsides <[e-mail]>",
   "devDependencies": {
-    "aegir": "^41.0.0"
+    "aegir": "^42.2.4"
   }
 }

README.md

@@ -1,2 +0,2 @@
-# race-event <!-- omit in toc -->
+# race-event
 
@@ -10,9 +10,24 @@ [![codecov](https://img.shields.io/codecov/c/github/achingbrain/race-event.svg?style=flat-square)](https://codecov.io/gh/achingbrain/race-event)
 
+<!--
+
+!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
+## Example - Getting started
 
 ```TypeScript
-const { raceEvent } = require('race-event')
+import { raceEvent } from 'race-event'
 
@@ -35,2 +50,66 @@ const controller = new AbortController()
 
+## 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
@@ -37,0 +116,0 @@

src/index.ts

@@ -7,6 +7,6 @@ /**
  *
- * @example
+ * @example Getting started
  *
  * ```TypeScript
- * const { raceEvent } = require('race-event')
+ * import { raceEvent } from 'race-event'
  *
@@ -28,2 +28,66 @@ * const controller = new AbortController()
  * ```
+ *
+ * @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
+ *   }
+ * })
+ * ```
  */
@@ -78,3 +142,11 @@
     const eventListener = (evt: any): void => {
-      if (opts?.filter?.(evt) === false) {
+      try {
+        if (opts?.filter?.(evt) === false) {
+          return
+        }
+      } catch (err: any) {
+        emitter.removeEventListener(eventName, eventListener)
+        signal?.removeEventListener('abort', abortListener)
+
+        reject(err)
         return
@@ -81,0 +153,0 @@ }

No alert changes

Improved metrics

Total package byte prevSize

22713

increased by52.19%

Lines of code

426

increased by95.41%

Number of lines in readme file

141

increased by127.42%

No dependency changes