Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/gamtiq/neva

Simple library to work with custom events
https://github.com/gamtiq/neva

dispatch emitter event event-handler eventbus eventemitter listener pub-sub subscription

Last synced: about 1 month ago
JSON representation

Simple library to work with custom events

Awesome Lists containing this project

README 

        
# neva 



Simple library to work with custom events.



[![NPM version](https://badge.fury.io/js/neva.png)](http://badge.fury.io/js/neva)

[![Build Status](https://secure.travis-ci.org/gamtiq/neva.png?branch=master)](http://travis-ci.org/gamtiq/neva)

[![Built with Grunt](https://cdn.gruntjs.com/builtwith.png)](http://gruntjs.com/)



* 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](#install)

* [Usage](#usage)

* [Examples](#examples)

* [API](#api)

* [Contributing](#contributing)

* [License](#license)



## Installation  [↑](#start)



### Node



    npm install neva



### [Bower](https://bower.io)



    bower install neva



### AMD, <script>



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



## Usage  [↑](#start)



### ECMAScript 6+



```js

import getEmitter from 'neva';

```



### Node



```js

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

```



### AMD



```js

define(['path/to/dist/neva.js'], function(neva) {

    const getEmitter = neva.getEmitter;

});

```



### Bower, <script>



```html



    // neva is available via neva field of window object

    const getEmitter = neva.getEmitter;



```



### Examples  [↑](#start)



```js

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  [↑](#start)



### 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`](https://gamtiq.github.io/neva/) for details.



## Contributing  [↑](#start)

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](http://gruntjs.com/).



## License  [↑](#start)

Copyright (c) 2017-2021 Denis Sikuler  

Licensed under the MIT license.