gamtiq / neva

Simple library to work with custom events

neva

Simple library to work with custom events.

• Simple event emitter API: on, off, emit, hasEventHandler.
• Event emitter API is chainable.
• Events can be emitted with multiple attached parameters.
• Data about emitted event are wrapped into an object with uniform structure that is passed to handlers.
• Ability to add event handler that should be called just once.
• Ability to enhance prototype of constructor function (class) with event emitter API (emitter methods can be mixed in prototype).
• Available as ECMAScript 6/2015 module, CommonJS module or UMD.
• Work in any ECMAScript 3+ environment (browsers, Node.js etc).
• Small.

Table of contents

• Installation
• Usage
• Examples
• API
• Contributing
• License

Installation ↑

Node

npm install neva

Bower

bower install neva

AMD, <script>

Use dist/neva.js or dist/neva.min.js (minified version).

Usage ↑

ECMAScript 6+

import getEmitter from 'neva';

Node

const getEmitter = require('neva').getEmitter;

AMD

define(['path/to/dist/neva.js'], function(neva) {
    const getEmitter = neva.getEmitter;
});

Bower, <script>

<!-- Use bower_components/neva/dist/neva.js if the library was installed by Bower -->
<script type="text/javascript" src="path/to/dist/neva.js"></script>
<script type="text/javascript">
    // neva is available via neva field of window object
    const getEmitter = neva.getEmitter;
</script>

Examples ↑

const emitter = getEmitter();
const eventHandler = (event) => {
    console.log('eventHandler: event type -', event.type, ', data -', event.data);
};
const obj = {
    name: 'obj',
    handler(event) {
        console.log(`${this.name}.handler: event type -`, event.type, ', params -', event.params);
    }
};
function onceHandler(event) {
    console.log('onceHandler: event type -', event.type, ', data -', event.data);
}

emitter.on(['event1', 'event2'], eventHandler)
        .on('event1', obj.handler, obj)
        .on('event2', onceHandler, null, {once: true});

emitter.emit('event1', 1, 2, 3)
        .emit({type: 'event2', data: 'some data', qty: 8});
// The following will be printed into console:
// eventHandler: event type - event1 , data - 1
// obj.handler: event type - event1 , params - Array [ 1, 2, 3 ]
// eventHandler: event type - event2 , data - some data
// onceHandler: event type - event2 , data - some data

emitter.hasEventHandler('event1', eventHandler); // true
emitter.hasEventHandler('event2', onceHandler); // false

emitter.off('event1', eventHandler);
emitter.hasEventHandler('event1', eventHandler); // false
emitter.hasEventHandler('event1'); // true

emitter.off('event1');
emitter.hasEventHandler('event1'); // false
emitter.hasEventHandler(); // true

emitter.off();
emitter.hasEventHandler(); // false

class SomeClass {
    ...
}
// Add event emitter methods to class
getEmitter(SomeClass.prototype);

API ↑

getEmitter([target: Object]): EventEmitter

Create event emitter or add methods to work with events into specified object.

target can be prototype of some constructor function (class).

EventEmitter API

on(type: string | string[], handler: Function, [context: Object], [settings: HandlerSettings]): EventEmitter

Register a handler for the specified event type(s).

off(type: string, handler: Function, [context: Object]): EventEmitter

Remove the specified event handler.

off(type: string): EventEmitter

Remove all handlers for the given event type.

off(): EventEmitter

Remove all registered event handlers.

emit(type: string, [param1: any, param2: any, ...]): EventEmitter

Call all handlers for the specified event type.

An object with the following fields will be passed in each handler:

• type: string - the event type (value of type parameter).
• params: Array - list of additional parameters that are passed besides the event type ([param1, param2, ...]).
• data: any - value of the second function's parameter (value of params[0]).

emit({type: string, ...}): EventEmitter

Call all handlers for the specified event type and pass the given object in each handler.

hasEventHandler(type: string, handler: Function, [context: Object]): boolean

Check whether the specified event handler is registered.

hasEventHandler(type: string): boolean

Check whether any handler for the specified event type is registered.

hasEventHandler(): boolean

Check whether any event handler is registered.

See docs for details.

Contributing ↑

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

License ↑

Copyright (c) 2017-2021 Denis Sikuler
Licensed under the MIT license.