Fork me on GitHub

js-signals

Custom Event/Messaging system for JavaScript

A Signal is similar to an Event Emitter/Dispatcher or a Pub/Sub system, the main difference is that each event type has its own controller and doesn't rely on strings to broadcast/subscribe to events. To know more about the differences and advantages/disadvantages of each approach check the Wiki page.

This implementation is heavily inspired by Robert Penner's AS3-Signals but it is NOT a direct port, it has a different set of features (some extras and some missing) and some methods were renamed to avoid confusions and/or for brevity. It also borrows some ideas from Joa Ebert AS3-Signals fork.

The intention of this library is to be a "small brick" that can be used together with other libraries and frameworks, helping people to develop evented applications easily!

Advantages

Check Comparison between different Obeserver Pattern implementations for more details.

Basic Example

//custom object that dispatch a `started` signal
var myObject = {
  started : new signals.Signal()
};
function onStarted(param1, param2){
  alert(param1 + param2);
}
myObject.started.add(onStarted); //add listener
myObject.started.dispatch('foo', 'bar'); //dispatch signal passing custom parameters
myObject.started.remove(onStarted); //remove a single listener

For more examples check the examples page on the wiki.

Naming convention

It is recommended to always name a signal on the past tense. This convention was based on the AS3-Signals recommendation, the reasoning behind it is to avoid confusions with regular properties and to keep consistency. Try combining multiple words if the event you are trying to describe doesn't have a past tense form or if you have naming collisions.

Good Names:
canceled
clicked
ended
startedAnimation
"Bad" Names:
cancel (action names should be used for methods)
onClick (reminds a DOM1 event handler, you may think the property is a function)
ending (action is still happening, you aren't sure if event is dispatched at begin or end of action)
animationStart (name doesn't represent an event, could be used to store any kind of value like a timestamp of when animation started, number representing the second when animation should start, a cue point, etc...)

Another option is to place all your signals inside an object named on following the DART DOM Events API. That way it will be clear that each member is an event type, it will avoid cluttering your object and make naming easier.

References

More Info

The focus of this library is for custom events, there are no plans to add native DOM events support (AS3-signals has a NativeSignal class that emulates native flash events) specially since most of the JavaScript frameworks already have some kind of facade on top of the native events and also because of the differences between browsers. This feature should be implemented as a plugin or as a separate project.

Contributors and ideas are welcome!

License

MIT License

Author

Miller Medeiros

Bugs / Feature Request

Use github issue tracker to submit bugs and feature requests.

Download

You can download this project in either zip or tar formats. You can also clone the project with Git by running:

$ git clone git://github.com/millermedeiros/js-signals

Or install it on node using npm:

$ npm install signals