EventSignal

EventSignal is a lightweight, browser-safe event messaging controller inspired by js-signals.

Installing

bower

bower install event-signal

npm

npm install event-signal

Examples

function listener(data) {
  console.log(data.message);
}

var resource = {};

// add support for `created` and `updated` events
resource.created = new EventSignal();
resource.updated = new EventSignal();

// add a listener to the `updated` event
resource.updated.addListener(listener);

// emit the `updated` event to all listeners,
// passing an optional `data` object
resource.updated.emit({message: 'foo'});

// remove the listener from the `updated` event-signal
resource.updated.removeListener(listener);

Constructor

var object = {};
object.updated = new EventSignal();

function MyClass() {
  this.updated = new EventSignal();
}

addListener(listener)

Add a listener to the event signal instance.

Returns the EventSignal. Throws TypeError if listener was already previously added.

Param | Type |Description ---------------|---------------|--------------------------------------------------- listener | Function | The listener function

object.saved.addListener(function(){});

// alternatively, use alias `then`
object.saved.then(function(){});

addListener(listener, scope)

Add a listener to the event signal instance, passing a scope object that will be this from inside the listener function. If scope is not provided, listener will use an anonymous {} for scope.

Returns the EventSignal. Throws TypeError if listener was already previously added.

Param | Type | Description ---------------|---------------|--------------------------------------------------- listener | Function | The listener function scope | Object | Optional; scope that will be this inside the listener function

var scope = {
  listener: function(){}
};

object.saved.addListener(scope.listener, scope);

addListener(listener, once)

Add a listener to the event signal instance. Passing true for once will automatically remove the listener after one call.

Returns the EventSignal. Throws TypeError if listener was already previously added.

Param | Type | Description ---------------|---------------|--------------------------------------------------- listener | Function | The listener function
once | boolean | Optional; if true, listener will be removed after one call

object.saved.addListener(function(){}, true);

addListener(listener, scope, once)

The trifecta — add a listener to the event signal instance, passing a scope object that will be this from inside the listener function, and boolean true for once to automatically remove the listener after one call.

Returns the EventSignal. Throws TypeError if listener was already previously added.

Param | Type | Description ---------------|---------------|--------------------------------------------------- listener | Function | The listener function scope | Object | Optional; scope that will be this inside the listener function once | boolean | Optional; if true, listener will be removed after one call

var scope = {
  listener: function(){}
};

object.saved.addListener(scope.listener, scope, true);

emit(data)

Emit the signal to all listeners. Optionally pass data to listeners.

Returns the EventSignal.

Param | Type | Description ---------------|---------------|--------------------------------------------------- data | * | Optional data to be passed to listener

object.saved.emit();

// examples of passing optional data
object.saved.emit({status: 'success'});
object.saved.emit('foo');

removeListener(listener)

Removes the provided listener function.

Returns the EventSignal.

Param | Type |Description ---------------|---------------|--------------------------------------------------- listener | Function | The listener function to be removed

var listener = function(){};
object.saved.addListener(listener);
object.saved.removeListener(listener);

removeAllListeners()

Removes all registered listeners.

Returns the EventSignal.

object.saved.removeAllListeners();

listeners()

Returns a cloned array of registered listeners.

object.saved.listeners();
//-> [{callback:function, scope:Object, once:boolean}]

listenerCount();

Returns the number of registered listeners.

object.saved.listenerCount()
//-> number

Naming Conventions

It's recommended that EventSignal instances be named using the past-tense :

• foo.created
• foo.saved
• foo.updated
• foo.ended

are preferred over :

• foo.create
• foo.onSave
• foo.afterUpdate
• foo.ending
• foo.end

Browser Support

• Chrome
• Firefox
• IE 9+
• IE 8 with es5-shim
• Safari

Module Support

• AMD
• CommonJS
• Browser global

License

EventSignal is free to use under the open-source MIT license.