https://github.com/compulim/respondable-event
Enables event listeners to send response back to the event dispatcher.
https://github.com/compulim/respondable-event
Last synced: about 1 month ago
JSON representation
Enables event listeners to send response back to the event dispatcher.
- Host: GitHub
- URL: https://github.com/compulim/respondable-event
- Owner: compulim
- License: mit
- Created: 2024-12-10T03:17:02.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-02-12T11:26:34.000Z (3 months ago)
- Last Synced: 2025-03-23T11:20:05.335Z (about 2 months ago)
- Language: TypeScript
- Homepage: https://npmjs.com/package/respondable-event
- Size: 318 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# `respondable-event`
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) instead.
## How to use
The code snippet below sends an `"authenticate"` event to the hosting page.
```ts
const event = new RespondableEvent(
'authenticate',
token => {
if (token) {
// Responded.
} else {
// No response.
}
},
{ bubbles: true } // Available to the whole page.
);
element.dispatchEvent(event);
// If `respondWith()` is not called, `checkResponse()`
// function will callback with `undefined`.
event.checkResponse();
```
In the hosting page, the following code snippet responds with a token.
```ts
window.addEventListener('authenticate', event => {
if (event.target === myTrustedElement && event.request === myTrustedRequest) {
event.respondWith('Hello, World!');
event.stopPropagation();
}
});
```
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
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 `respondWith()` was called, `checkResponse()` will return `true`.
- If `respondWith()` was never called, `checkResponse()` will call the `callback` function with `undefined`, and return `false`.
- Subsequent calls to `checkResponse()` will return `true`.
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 observers. It is designed to limit the number of audience who can look at the response.
## Behaviors
### Differences between `RespondableEvent` and `FetchEvent`
- `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
Like us? [Star](https://github.com/compulim/respondable-event/stargazers) us.
Want to make it better? [File](https://github.com/compulim/respondable-event/issues) us an issue.
Don't like something you see? [Submit](https://github.com/compulim/respondable-event/pulls) a pull request.