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

import Vue from 'vue';
import VueEventRegistry from 'vue-event-registry';

Vue.use(VueEventRegistry);

new Vue().$mount('#app')

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 names
Vue.use(VueEventRegistry, {
    name: '$userEvents',
    uniqueName: '$achievements',
});

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.

import VueEventRegistry, { createEventRegistry } from 'vue-event-registry';

// Example: Global registries in window object
window.eventRegistry = createEventRegistry();
window.uniqueEventRegistry = createEventRegistry({ uniqueEvents: true });

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.

export default {
    created() {
        // Register handler after async image loading is complete
        this.$events.on('image:loaded', (image, error) => {
            if (error) {
                // Handle error
            } else {
                // Do stuff
            }
        });
    }
}

Emit events

Emit events and optionally pass parameters to event handlers.

export default {
    created() {
        fetch('https://example.com/img').then((image) => {
            this.$events.emit('image:loaded', image);
        }).catch((error) => {
            this.$events.emit('image:loaded', null, error);
        });
    }
}

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.

export default {
    created() {
        this.removeHandler = this.$events.on('user:clicked', () => {});
    },
    destroyed() {
        this.removeHandler();
    }
}

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.

export default {
    created() {
        this.$uniqueEvents.on('user:accepted-cookies', this.createCookies);
    },
    methods: {
        createCookies() {
            // ...
        }
    }
}

<template>
    <button @click="$uniqueEvents.emit('user:accepted-cookies')">
        Accept cookies
    </button>
</template>

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
export default {
    async created() {
        await this.$uniqueEvents.wait('b:created');
        this.$uniqueEvents.emit('a:created');
    }
}

// Component B
export default {
    created() {
        this.$uniqueEvents.emit('b:created');
    }
}

// Component C
export default {
    async created() {
        await Promise.all([
            this.$uniqueEvents.wait('a:created', { timeout: 2000 }),
            this.$uniqueEvents.wait('b:created', { timeout: 2000 }),
        ]);
        this.$uniqueEvents.emit('c:created');
    }
}

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().

export default {
    created() {
        // Listen for general click event
        this.removeClickHandler = this.$events.native('click', () => {});
        // Listen for mouseover on dom element 
        const element = document.getElementById('your-id');
        this.removeMouseoverHandler = this.$events.native('mouseover', () => {}, element);
    },
    destroyed() {
        this.removeClickHandler();
        this.removeMouseoverHandler();
    }
}

Clear all event handlers

The event handlers of a registry can be removed by using clear().

export default {
    destroyed() {
        this.$events.clear(); // Removes all event handlers
        this.$events.clear('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