A tiny (6 KB) pub sub JS module with added functionality to post messages across iFrame boundaries with window.postMessage.
None. evnt-hub's postMessage features are well supported.
Some features of evnt-hub require Promise support. Be aware that not all browsers support this features
npm install --save evnt-hub<script src="https://unpkg.com/[email protected]/lib/EventHub.min.js" async defer></script>evnt-hub has a number of options, all of which are optional and some of which can be set dynamically depending on your use case.
let hub = new EventHub({
targetOrigin: 'http://your.target-origin.here', // the origin you want to send to
originRegex: /^(https?):\/\/.*(my-domain)(\.com)$/,
targetWindow: window.parent, // the window to postMessage to
hubId: -1,
verbose: true,
});Specify a targetOrigin to be included as the required origin parameter in a window.postMessage command. If no targetOrigin is provided, one will need to be provided in an '_init_' event to the hub. If no targetOrigin is present during a call to emit a postMessage, the postMessage will not send.
The originRegex option allows the hub to accept messages from multiple domains for multi-domain eventing. If not present, the origin checker will not run. WARNING: Dependening on your application, this may pose a security risk. See below for security considerations.
Specify a targetWindow to configure the window to which you will send postMessages. This setting can be overridden by the emit function's 'window' argument. If no targetWindow is provided at postMessage time, no postMessage will be sent.
In order to disambiguate which hub sends which message, hubId, if present, will be tacked on to every outbound postMessage Object payload. A hubId can optionally be set via an '_init_' postMessage. hubId is not added to the
This boolean no longer triggers a debugging mode. See debugFn below.
If passed, debug mode is activated which triggers log messages on every subscribe, publish callback, emit, and postMessage received. The passed function is run for each publish callback allowing the user to hook into the payload data for logging or auditing purposes. Other debugging messages are not configurable.
Subscribes to an event in the hub. When the event is published,
funcwill be executed. Returns a token identifying the subscription.
hub.subscribe('event', func, correlationId)- event the event being listened for
- func the function to execute on publish
- correlationId (optional) a unique token to correlate sent and received events
Publishes an event to the hub. When the event is received in the hub, all subscriptions to that event are processed. Returns true if any relevant subscriptions exist.
hub.publish('event', payload, correlationId)- event the event being published
- payload any data associated with the event
- correlationId (optional) a unique token to correlate sent and received events
Unsubscribes from the hub. Returns the token if successful, otherwise
false.
hub.unsubscribe(token)Subscribes to an event in the hub. When an event with a matching correlationId is published,
funcwill be executed and auto-unsubscribed.
hub.subscribeOnce('event', func, correlationId)- event the event being listened for
- func the function to execute on publish
- correlationId a unique token to correlate sent and received events
Sends a window.postMessage to the targetOrigin to be published on that window's hub.
hub.post('event', payload, window, correlationId)- event the event being published
- payload any data associated with the event
- window (optional) the window to post the message to. Defaults to the targetWindow.
- correlationId (optional) a unique token to correlate sent and received events
Combines publish and post functionality.
hub.emit('event', payload, window, correlationId)- event the event being published
- payload any data associated with the event
- window (optional) the window to post the message to. Defaults to the targetWindow.
- correlationId (optional) a unique token to correlate sent and received events
Returns a promise that resolves whenever the supplied event is received in response. Requests are
emitted - published locally and sent to the targetWindow.
hub.request('requestEvent', 'responseEvent', requestBody)
.then((response) => {
response.value; // response payload
response._meta; // meta information about the published response event
});- reqEvent the event being emitted
- reqEvent the event being subscribed to
- reqBody any data to be sent in the request payload
- correlationId (optional) a unique token to correlate sent and received events
Returns a promise that resolves only when the supplied event is received in response and the correlationIds match. Requests are
emitted - published locally and sent to the targetWindow. LikesubscribeOnce, the subscription is auto-unsubscribed.
hub.request('requestEvent', 'responseEvent', requestBody, correlationId)
.then((response) => {
response.value; // response payload
response._meta; // meta information about the published response event
});- reqEvent the event being emitted
- reqEvent the event being subscribed to
- reqBody any data to be sent in the request payload
- correlationId a unique token to correlate sent and received events
Returns the hub configuration.
hub.about() // {hubId: -1, targetOrigin: http://localhost, ...}evnt-hub is implemented with best practices in mind regarding XSS exposure. For more information on window.postMessage and the security concerns associated with cross origin messaging, check out the MDN documentation.
npm install
npm run dev
# run a dev server at localhost:8100
npm run dev:demo
npm run build
npm run test
npm run test:watchMake sure to run the tests and build the lib folder (dev and build scripts) before committing and submitting a pull request. For your convenience, a prepublish script can be run to accomplish all three tasks.
npm run prepublish