Nonviolent Pigeon Manifestation

    mini-event-emitter

    0.10.2 • Public • Published

    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

    Install

    npm i mini-event-emitter

    DownloadsWeekly Downloads

    92

    Version

    0.10.2

    License

    MIT

    Unpacked Size

    86.1 kB

    Total Files

    17

    Last publish

    Collaborators

    • hawkerboy7