respondable-event 0.1.1-main.29f6ea6 → 0.1.1-main.e92dc42

package/README.md

@@ -1,16 +1,16 @@
 # `respondable-event`
 
-Enables event listeners to send at-most-one response back to the dispatching `EventTarget`.
+Enables event listeners to send response back to the event dispatcher.
 
 ## Background
 
 Inspired by the [`FetchEvent`](https://developer.mozilla.org/en-US/docs/Web/API/FetchEvent) which is available to [Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) only, the `RespondableEvent` allows event listeners to send a response back to the dispatching [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget).
 
-This is useful in scenarios where custom elements need to communicate with the host asynchronously or infrequently. For persisted messaging, use `RespondableEvent` to set up [`Channel Messaging`](https://developer.mozilla.org/en-US/docs/Web/API/Channel_Messaging_API/Using_channel_messaging).
+This is useful in scenarios where custom elements need to communicate with the host asynchronously or infrequently. For persisted messaging, use `RespondableEvent` to set up [Channel Messaging](https://developer.mozilla.org/en-US/docs/Web/API/Channel_Messaging_API/Using_channel_messaging) instead.
 
 ## How to use
 
-The code snippet below send an `"authenticate"` event to the hosting page.
+The code snippet below sends an `"authenticate"` event to the hosting page.
 
 ```ts
 const event = new RespondableEvent(
@@ -22,19 +22,19 @@ const event = new RespondableEvent(
       // No response.
     }
   },
-  { bubbles: true } // Make the event available to all ancestors.
+  { bubbles: true } // Available to the whole page.
 );
 
 element.dispatchEvent(event);
 
-// If no response has been made or pending, calling the `checkResponse()` function
-// will call the callback function with undefined.
+// If `respondWith()` is not called, `checkResponse()`
+// function will callback with `undefined`.
 event.checkResponse();
 
 const token = await authenticate.promise;
 ```
 
-In the hosting page, the following code snippet respond with a token.
+In the hosting page, the following code snippet responds with a token.
 
 ```ts
 window.addEventListener('authenticate', event => {
@@ -45,28 +45,30 @@ window.addEventListener('authenticate', event => {
 });
 ```
 
+The callback function passed to the constructor will be called *at most once*. Same as `FetchEvent`, the `respondWith()` function will throw if it is being called for more than once.
+
 ### New `checkResponse` function
 
-The `checkResponse()` function guarantees the `callback` function must be called exactly once. This helps reduce code complexity and its design is similar to the [`HTMLFormElement.checkValidity()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/checkValidity) function:
+To reduce code complexity, the `checkResponse()` function guarantees the `callback` function will be called exactly once. The API design is similar to the [`HTMLFormElement.checkValidity()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/checkValidity) function:
 
-- If a prior response has been made, `checkResponse()` will return `true`.
-- If no prior response is made, `checkResponse()` will call the `callback` function with `undefined`, and return `false`.
+- If `respondWith()` was called, `checkResponse()` will return `true`.
+- If `respondWith()` was never called, `checkResponse()` will call the `callback` function with `undefined`, and return `false`.
 
-It is recommended to call `checkResponse()` after `dispatchEvent()` to guarantee the `callback` function is being called regardless `respondWith()` is called or not.
+It is recommended to put `checkResponse()` immediately after `dispatchEvent()`.
 
 ## Designs
 
 ### Callback function in constructor
 
-The callback function follows the pattern found in [`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/MutationObserver) and other observer classes. It is designed to limit the audience who can receive the response to the creator of the event.
+The callback function follows the pattern found in [`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/MutationObserver) and other observers. It is designed to limit the number of audience who can look at the response.
 
 ## Behaviors
 
-### Differences between `RespondableEvent` and `FetchEvent`?
+### Differences between `RespondableEvent` and `FetchEvent`
 
-- `RespondableEvent` extends from `Event`, where `FetchEvent` extends from `ExtendableEvent` and `Event`
-- `request` property is optional in `RespondableEvent` where it is required in `FetchEvent`
-- [`checkResponse()` function](#new-checkresponse-function) is new in `RespondableEvent`
+- `RespondableEvent` extends from [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event), where [`FetchEvent`](https://developer.mozilla.org/en-US/docs/Web/API/FetchEvent) extends from [`ExtendableEvent`](https://developer.mozilla.org/en-US/docs/Web/API/ExtendableEvent)
+- `request` property is optional in `RespondableEvent` where it is required in [`FetchEvent`](https://developer.mozilla.org/en-US/docs/Web/API/FetchEvent/request)
+- [`checkResponse()`](#new-checkresponse-function) function is new in `RespondableEvent`
 
 ## Contributions
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "respondable-event",
-  "version": "0.1.1-main.29f6ea6",
-  "description": "Enables event listeners to send zero-or-one response back to the dispatching EventTarget.",
+  "version": "0.1.1-main.e92dc42",
+  "description": "Enables event listeners to send zero-or-one response back to the event dispatcher.",
   "files": [
     "./dist/"
   ],
@@ -68,6 +68,6 @@
     "typescript": "^5.6.3"
   },
   "dependencies": {
-    "respondable-event": "^0.1.1-main.29f6ea6"
+    "respondable-event": "^0.1.1-main.e92dc42"
   }
 }