uEvent

uEvent is a event emitter library which provides the observer pattern to javascript objects. It works on node.js and browser and also supports RequireJS (AMD).

It is a fork of jeromeetienne/microevents.js with the changes of few other forks and custom changes.

Features

• jQuery-like API (on, off, once, trigger`)
• Value modifier support
• prevent default and stop propagation patterns
• handleEvent support

Installation

$ npm install uevent

Usage

Create an emitter

Direct

import { EventEmitter } from 'uevent';

const obj = new EventEmitter();

Class extend

class Manager extends EventEmitter {

}

class obj = new Manager();

Mixin

import { mixin as eventEmitterMixin } from 'uevent';

const obj = {};

eventEmitterMixin(obj);

Callback signature

The first parameter of the callback is always an Event object having the following properties :

• type the name of the event
• target the source object of the event
• args additional parameters

When additional parameters are provided they are passed to the callback :

const callback = function(event, param1, param2) {};

When using the handleEvent feature you only get the event object :

const listener = {
    handleEvent: function(event) {}
};

API

on

Add one or many event handlers.

// bind 'callback' to 'event'
obj.on('event', callback);

// bind 'callback' to 'event1' and 'event2'
obj.on('event1 event2', callback);

// bind 'callback1' to 'event1' and 'callback2' to 'event2'
obj.on({
  event1: callback1,
  event2: callback2
});

off

Remove one or many or all event handlers.

// remove all callbacks for 'event'
obj.off('event');

// remove 'callback' if attached to 'event'
obj.off('event', callback);

// remove all callbacks for 'event1' and 'event2'
obj.off('event1 event2');

// remove 'callback1' if attached to 'event1' and 'callback2' if attached to 'event2'
obj.off({
  event1: callback1,
  event2: callback2
});

// remove all callbacks
obj.off();

once

Same as on but the callbacks will be removed after the first invocation.

The callbacks attached once are only called by trigger and not by change.

trigger

Trigger all handlers for an event. Accept optional arguments transmitted to the callbacks.

// trigger 'event'
obj.trigger('event');

// trigger 'event' with arguments
obj.trigger('event', true, 42);

change

Works like trigger but returns a value. This is used to filter a value before display for example. All callbacks must accept at least on input value and return the modified (or not) value.

// call 'event' filters with 'Hello world' input
var newVal = obj.change('event', 'Hello world')

// call 'event' filters with 'Hello world' input and other arguments
var newVal = obj.change('event', 'Hello world', true, 42)

The Event object has an additional value property which holds the current value.

Advanced

Prevent default

Call preventDefault() on this Event object to "mark" the event. After calling trigger you get a reference to this Event object and can test isDefaultPrevented().

obj.on('event', function(e, id) {
  if (id == 0) {
    e.preventDefault();
  }
});

const e = obj.trigger('event', id);

if (!e.isDefaultPrevented()) {
  // ...
}

Stop propagation

Call stopPropagation() on the Event object to prevent any further callbacks to be called. Works for trigger and change.

obj.on('event', function(e, val) {
  e.stopPropagation();
  return val;
});

obj.on('event', function(e, val) {
  return 'azerty';
});

const newVal = obj.change('event', '1234');
// newVal is still '1234'

License

This library is available under the MIT license.