Vue Event Registry
Simple Vue plugin to easily register, emit and unregister global event handlers inside vue components.
You can also register handlers for unique events, which get called instantly after registration, if the event was already emitted. Unique events only get emitted once. It doesn't matter when a component is loaded, its unique event handlers get fired properly.
Features
- Add and remove event handlers
- Unique events
- Wait for events
- Promises
- Native document events
- Zero dependencies
Why
The main purpose of this plugin is to handle events between independent application modules or components, which get loaded at different times and can cause concurrency problems. This plugin provides a way to handle events from another module, even though they already have been emitted, that's what the unique event registry is for.
Components can also pause execution and wait until some events have been fired or continue without them, making it easy to define module execution orders, if they depend on another.
Another core functionality is the way event handlers get removed by calling the remove function, which gets returned by registering an event handler.
Setup
Install with npm:
npm install --save vue-event-registry
Alternatively install with yarn:
yarn add vue-event-registry
Use plugin in Vue
;; Vue;
Plugin options
The property names of both event registries can be customized.
Registries will not be created and added to vue, if false
is given instead of a string.
// Example with custom event registry namesVue;
Custom event registries
You can create more event registries, by importing the factory function. These registries do not depend on Vue and can be used wherever you want.
; // Example: Global registries in window objectwindoweventRegistry = ;windowuniqueEventRegistry = ;
createEventRegistry([options])
Returns newly created event registry
Parameter | Type | Default | Description |
---|---|---|---|
options | object | Optional event registry config | |
options.debug | boolean | false | Enables debug messages |
options.uniqueEvents | boolean | false | Creates registry for unique events |
Examples
Here are some basic examples on how the event registry can be used:
Listen for events
Register event handlers.
{ // Register handler after async image loading is complete this$events; }
Emit events
Emit events and optionally pass parameters to event handlers.
{ ; }
Remove event handlers
Remove event handlers by calling the function returned by on()
.
If you do not call this function, then event handlers will get executed, even if the component is already destroyed.
{ thisremoveHandler = this$events; } { this; }
Unique events
Unique events can only be emitted once until the page is reloaded and a new vue root instance is created. The code snippets below can be placed in different application modules.
{ this$uniqueEvents; } methods: { // ... }
Accept cookies
Wait for events
The function wait()
will return a promise to wait until the event was emitted.
In this example component A will stop execution until component B was created.
Component C will wait for both A and B, or continue without them if the promise timed out.
// Component A async { await this$uniqueEvents; this$uniqueEvents; }
// Component B { this$uniqueEvents; }
// Component C async { await Promiseall this$uniqueEvents this$uniqueEvents ; this$uniqueEvents; }
Native event handlers
Register native document events with native()
.
These get emitted by document events, not the emit()
function.
If you want to trigger those events yourself, use document.dispatchEvent()
.
{ // Listen for general click event thisremoveClickHandler = this$events; // Listen for mouseover on dom element const element = document; thisremoveMouseoverHandler = this$events; } { this; this; }
Clear all event handlers
The event handlers of a registry can be removed by using clear()
.
{ this$eventsclear; // Removes all event handlers this$eventsclear'event'; // Removes handlers for given event }
Usage
After the setup all vue instances have access to the configured event registries.
With default configuration the registries are accessible from within vue components under
this.$events
and this.$uniqueEvents
.
An Event registry provides following functions:
on(event, handler)
Registers event handler for custom events and returns function to unregister it
Parameter | Type | Default | Description |
---|---|---|---|
event | string | required | Name of event |
handler | function | required | Event handler |
wait(event[, options])
Returns promise to wait for given event registered with on()
Parameter | Type | Default | Description |
---|---|---|---|
event | string | required | Name of event |
options | object | Waiting options | |
options.timeout | number | boolean | false | Time in milliseconds until promise settles, disable with false |
options.resolveOnTimeout | boolean | true | Controls wether promise is resolved or rejected on timeout |
native(event, handler[, target])
Registers event handler for native events and returns function to unregister it
Parameter | Type | Default | Description |
---|---|---|---|
event | string | required | Name of event |
handler | function | required | Event handler |
target | EventTarget | window | Optional event target, needs addEventListener() method |
Note: Use document.dispatchEvent()
to emit registered events.
If the event target should get removed from the DOM, then its event handlers get removed as well.
emit(event[, ...args])
Emits event, executes registered handlers and returns array of executed handlers
Parameter | Type | Default | Description |
---|---|---|---|
event | string | required | Name of event |
args | arguments | Optional arguments which get passed to event handler |
clear([event])
Removes handlers for event if given or all handlers if not
Parameter | Type | Default | Description |
---|---|---|---|
event | string | null | Name of event |
history()
Returns array of all registry interactions
Development
If you want to contribute, then fork and checkout the repository on develop. Navigate to the project and install dev dependencies:
npm install
Jest is used as testing framework. Create tests for each functionality and run them with:
npm run test
Push your changes to a feature branch and create a pull request.
License
MIT