MiniEventEmitter

npm install --save mini-event-emitter

What is it?

The MiniEventEmitter is an easy javascript EventEmitter which has no dependencies. You can easily create new instaces of the MiniEventEmitter. This way you can create multiple MiniEventEmitters with isolated events. It also has the ability to show you trace and error messages. This way you can keep track of all events being send and also show you something that does not make sense resulting in an error. This should help you as a developer to debug your code faster and help you check for gost events.

You have the possibility to add a group to an event. This way you can remove events and eventListeners bound to a specific group (e.g. a DOM element). Using .emit() all eventListeners for a specific event will excecute regardless of groups. Also the .trigger() is available which does the exact same thing as .emit(). Some people prefer .trigger() over .emit() so you can use both.

Getting started

Simple example

// Require the MiniEventEmitter
var Events = require("mini-event-emitter");

// Create a new instance of the MiniEventEmitter
var events = new Events();

// Listen for the "test" event and fire an anonymous function
events.on("test", function (a,b) { console.log(a,b); });

// Fire the test event with some example arguments
events.emit("test", "my first argument", "my second argument");

// Response: my first argument my second argument

// Remove all "test" eventListeners
events.off("test");

// Will not fire because all "test" eventListeners have been removed
events.emit("test");

Functions

.on(event[,group],eventListener)

• string event, indicating the event to be listened for.
• string group optional, allows for events to be in a group. Using .off() you can remove (all) events linked to a group.
• function eventListener, the function to be excecuted when the event is emitted or triggered.

.off([event][,group][,eventListener])

• string event optional
• string group optional
• function eventListener optional All possible ways to use .off() are explained below.

.off()

Remove all events, groups and eventListeners

.off(event)

Remove all eventListener's for this event without a group.

.off(event,group)

Remove all eventListener's for this event in this group.

.off(event,eventListener)

Remove a specific eventListener for this event without a group.

.off(event,group,eventListener)

Remove a specific eventListener for this event in this group.

.off(null)

Remove all events and eventListeners without a group. (the first argument event must be null)

.off(null,group)

Remove all events and eventListeners in this group. (the first argument event must be null)

.emit(event[, ...])

• string event, identifies which eventListeners are to be excecuted.
• ... optional, any amount of aditional arguments may be added

.trigger(event[, ...])

Same as .emit()

.emitIf(event[, ...])

Same as .emit() but the event will only be send if it is being listened for

.triggerIf(event[, ...])

Same as .emitIf()

Aditional examples

Removing specific listener functions

// Require the MiniEventEmitter
var Events = require("mini-event-emitter");

// Create a new instance of the MiniEventEmitter
var events = new Events();

// Create some test functions and let all of them be triggerd on the test event
events.on("test", test1 = function () { console.log("test1"); });
events.on("test", test2 = function () { console.log("test2"); });
events.on("test", test3 = function () { console.log("test3"); });
events.on("test", test4 = function () { console.log("test4"); });

// Fire the test event
events.emit("test");

// Response: "test1", "test2", "test3", "test4"

// Remove specific "test" eventListeners by providing the references to the functions
events.off("test",test2);
events.off("test",test3);

// Fire the test event
events.emit("test");

// Response: "test1", "test4"

Using groups

// Require the MiniEventEmitter
var Events = require("mini-event-emitter");

// Create a new instance of the MiniEventEmitter
var events = new Events();

// Create some test functions and let all of them be triggerd on the test event
events.on("test", test1 = function () { console.log("test1"); });
events.on("test", test2 = function () { console.log("test2"); });
events.on("test", "group1", test3 = function () { console.log("test3"); });
events.on("test", "group1", test4 = function () { console.log("test4"); });
events.on("test", "group2", test5 = function () { console.log("test5"); });
events.on("test", "group2", test6 = function () { console.log("test6"); });

// Fire the test event
events.emit("test");

// Response: "test1", "test2", "test3", "test4", "test5", "test6"

// Remove a complete group
events.off("test","group1");

// Fire the test event
events.emit("test");

// Response: "test1", "test2", "test5", "test6"

// Remove a specific function within a group
events.off("test","group2", test5);

// Fire the test event
events.emit("test");

// Response: "test1", "test2", "test6"

// Pay attention: This will remove all test events WITHOUT a group (or group "").
// In this case that means "group2" function "test6" will still fire with the test event
events.off("test");

// Fire the test event
events.emit("test");

// Response: "test6"

// Remove all functions in "group2" (which at this point only is function test 6)
events.off("test", "group2");

// Fire the test event
events.emit("test");

// No Response

Clear a group

// Require the MiniEventEmitter
var Events = require("mini-event-emitter");

// Create a new instance of the MiniEventEmitter
var events = new Events();

// Create some test functions and and group them to group testGroup
events.on("test1", "testGroup1", test1 = function () { console.log("test1"); });
events.on("test2", "testGroup1", test2 = function () { console.log("test2"); });
events.on("test3", "testGroup1", test3 = function () { console.log("test3"); });
events.on("test3", "testGroup2", test4 = function () { console.log("test4"); });
events.on("test3", "testGroup2", test5 = function () { console.log("test5"); });

// Fire the events
events.emit("test1").emit("test2").emit("test3");

// Response: "test1", "test2", "test3", "test4", "test5"

// Remove a complete group
events.off(null,"testGroup1");

// Fire the test event
events.emit("test1").emit("test2").emit("test3");

// Response: "test4", "test5"

Extra's

Logging

new Events([options])

• options object, contains the options for this MiniEventEmitter instance

options.error = [boolean]

Defaults to false. If true is provided actions which do not make sense and probably are mistakes are logged.

options.trace = [boolean]

Defaults to false. If true is provided succesfull events and their arguments, if available, will be logged.

options.name = [string]

Defaults to MiniEventEmitter. If [string] is provided error and trace messages will contain the provided name. While running the application you could toggle the trace and error. events.settings.[error/trace] = true/false. Pay attention though! Due to asynchrony toggling between on/off could be more confusing than helpfull, however you are free to choose.

Error example

// Require the MiniEventEmitter
var Events = require("mini-event-emitter");

// Create a new instance of the MiniEventEmitter
var events = new Events({error: true});

// Any possible mistake will now be shown in the console

// Trigger the emit function without event name
events.emit();

// Response: MiniEventEmitter ~ emit ~ Event was not provided

// Turn error-logging off again
events.settings.error = false

// Trigger the emit function without event name
events.emit();

// No Response

Trace example

// Require the MiniEventEmitter
var Events = require("mini-event-emitter");

// Create a new instance of the MiniEventEmitter
var events = new Events({trace: true});

// All traces of succesfull "event emits" will be shown in the console

// Create an example test event with eventListener
events.on("test", function () {console.log("test message");});

// Fire the "test" event
events.emit("test");

// Response: "MiniEventEmitter ~ trace ~ test", "test message"

// Turn trace-logging off again
events.settings.trace = false

// Fire the "test" event
events.emit("test");

// Response: "test message"

Name example

// Require the MiniEventEmitter
var Events = require("mini-event-emitter");

// Create a new instance of the MiniEventEmitter
var events = new Events({trace: true, error: true, name: "My Name"});

// Any possible mistake will now be shown in the console
// All traces of succesfull "event emits" will be shown in the console

// Create an example test event with eventListener
events.on("test", function () {console.log("test message");});

// Fire the "test" event
events.emit("test");

// Response: "My Name ~ trace ~ test"
// Response: "test message"

// Trigger the emit function without event name
events.emit();

// Response: "My Name ~ emit ~ Event was not provided"

Cases MiniEventEmitter can warn you about

The following cases can be recognized by the MiniEventEmitter and can be shown to you in the console:

• .emit an event which has no eventListener for it
• Using .emit without an event.
• Using .off for an event that does not exist (in the specified group)
• Using .off for a group that does not exist
• Using .off and providing an eventListener that does not exist with the provided event name (and group)
• Providing anything other than a string as event or group
• Providing anything other than a function as an eventListener

Chaining

It is also possible to chain MiniEventEmitter methodes.

// Require the MiniEventEmitter
var Events = require("mini-event-emitter");

// Create a new instance of the MiniEventEmitter
var events = new Events();

// Chained: add eventListener "test", trigger the event and remove the event
events.on("test",function(){console.log("test");}).emit("test");

// Response: "test"

Used attributes

If you want to extend MiniEventEmitter which you can, you do need to make sure you do not override existing attributes as that will break MiniEventEmitter. Below you find all attributes used.

var events = new Events = require("mini-event-emitter");

// MiniEventEmitter Functions
events.on()
events.off()
events.emit()
events.emitIf()
events.trigger()
events.triggerIf()

// MiniEventEmitter references and storage objects
events.events
events.groups
events.settings