Concert.js
Concert.js is an event library for JavaScript and Node.js that implements the observer pattern (a.k.a publish/subscribe). This is a useful pattern for creating decoupled architectures, event driven systems and is one key element in the Model-View-Controller pattern. Concert.js similar to Node's EventEmitter and Backbone.Events, but independent, minimal and light-weight.
Tour
- Simple and minimal — just
on
,once
,off
andtrigger
.
No unnecessary method pollution or large API surface area like with other libraries. No legacy method names either. - Light-weight with little code and no external dependencies.
- Inheritable — You can inherit from you observables and add
listeners later.
All event listeners will initially be inherited and then copied only once you callon
,once
oroff
on the child instances. Eliminate an awful lot of computation by setting your event listeners on your class's prototype. Read more on inheritable observables. - Familiar if you've ever used Backbone.js or Node.js's EventEmitter.
- Comes with a built-in
once
function to listen to an event only once and then remove the listener automatically. - Set a listener's context and optionally extra arguments.
- Rename or alias any function to a name of your choice.
Handy if you need to present a compatible or legacy API:
obj.addEventListener = Concert.on
. - Special
all
event for catching all triggered events.
Useful also for delegating or proxying all events from one object to another. - Add listeners for multiple events at once with object syntax:
obj.on({change: onChange, save: onSave})
- Works well with namespaced event names such as
change:name
.
Because there's no limit to event names, you can easily create faux namespaces. - Supports ECMAScript 6's Symbol in case you need to create events
a little more private.
But really, that's an illusion. There'sObject.getOwnPropertySymbols
. - Thoroughly tested.
Installing
Installing on Node.js
npm install concert
Installing for the browser
Concert.js doesn't yet have a build ready for the browser, but you might be able to use Browserify to have it run there till then.
Using
To add events to any object of your choice, just mix Concert
's functions to
your object:
var Concert = var music = {}for var name in Concert musicname = Concertname
Then use on
and trigger
to add listeners and trigger events:
musicmusic
If you're using Underscore.js or Lo-dash, you can use
_.extend
to mix Concert in:
_
Enabling Concert on all instances
Mix Concert
in to your class's prototype
to make each instance observable.
{}_
Then you can listen to and trigger events on each instance.
var music = music
Faux Namespaces
Because there are no limits to event names, you can create faux namespaces by
adding a separator, e.g :
, to event names. Then trigger both the specific and
general version in your application code and you're good to go. This happens to
be also what Backbone.Model does for its change
events.
modelmodel
{ thissong = song } _ Musicprototype { this } Musicprototype
Once you initialize your object, all of the event listeners will be ready
without having to call a bunch of on
s and once
s in the constructor. This
pattern saves you from an awful lot of unnecessary computation.
Ensure the third argument, the listener's context, remains undefined
when
calling Music.prototype.on
. The listener's context will then be set to
any particular instance on which trigger
was called.
var music = "On Broadway"music // => Will log "Playing On Broadway.".
You can then add listeners without worrying you'll change every instance in the system (as you would when you'd use Node.js's EventEmitter or Backbone's Events).
var jam = "The Way It Is"jamjammusic // => Will log "Jamming The Way It Is.". var classic = "Tubular Bells"classic // => Will still log "Playing Tubular Bells.".
Extra arguments
If you'd like to use a single listener for multiple events, but need a way to still differentiate between events, make use of Concert.js's support for binding arguments:
var song = "The Way It Is"songsong
Your onStartOrStop
function will then be called in the context of song
with
its first argument as either "play"
or "stop"
. Any additional arguments
given to trigger
will come after the bound arguments.
API
For extended documentation on all functions, please see the Concert.js API Documentation.
Concert
- off(event, listener, [thisArg])
- on(event, listener, [thisArg], [arguments...])
- once(event, listener, [thisArg], [arguments...])
- trigger(event, [arguments...])
License
Concert.js is released under a Lesser GNU Affero General Public License, which in summary means:
- You can use this program for no cost.
- You can use this program for both personal and commercial reasons.
- You do not have to share your own program's code which uses this program.
- You have to share modifications (e.g bug-fixes) you've made to this program.
For more convoluted language, see the LICENSE
file.
About
Andri Möll typed this and the code.
Monday Calendar supported the engineering work.
If you find Concert.js needs improving, please don't hesitate to type to me now at andri@dot.ee or create an issue online.