concert

Concert.js

![NPM version][npm-badge] ![Build status][travis-badge] [npm-badge]: https://badge.fury.io/js/concert.png [travis-badge]: https://travis-ci.org/moll/js-concert.png?branch=master

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 and trigger.
  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 call on, once or off 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's Object.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 = require("concert")
var music = {}
for (var name in Concert) music[name] = Concert[name]

Then use on and trigger to add listeners and trigger events:

music.on("cowbell", function() { console.log("Cluck!") })
music.trigger("cowbell")

If you're using Underscore.js or Lo-dash, you can use _.extend to mix Concert in:

_.extend(music, Concert)

Enabling Concert on all instances

Mix Concert in to your class's prototype to make each instance observable.

function Music() {}
_.extend(Music.prototype, Concert)

Then you can listen to and trigger events on each instance.

var music = new Music
music.on("cowbell", console.log)

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.

model.trigger("change:name", "John")
model.trigger("change")

### Inheritable Observables Concert.js supports inheriting from your observables without worrying you'll change the prototypes. Set up your event listeners once on your "class's" prototype and then, if need be, add or remove listeners.

function Music(song) { this.song = song }

_.extend(Music.prototype, Concert)

Music.prototype.play = function() { this.trigger("play", this.song) }

Music.prototype.on("play", console.log.bind(null, "Playing %s."))

Once you initialize your object, all of the event listeners will be ready without having to call a bunch of ons and onces 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 = new Music("On Broadway")
music.play() // => 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 = new Music("The Way It Is")
jam.off("play")
jam.on("play", console.log.bind(null, "Jamming %s."))
music.play() // => Will log "Jamming The Way It Is.".

var classic = new Music("Tubular Bells")
classic.play() // => 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 = new Music("The Way It Is")
song.on("play", onPlay, undefined, "play")
song.on("stop", onPlay, undefined, "stop")

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 [e-mail] or create an issue online.

Changelog

2.1.0 (May 27, 2015)

• Allows binding a listener's thisArg to null.

  Using null will mean the event listener will be called in the null context. In [JavaScript's strict mode][strict] that means this === null.

  model.on("change", onChange, null)
  

  As before, using undefined or leaving the context out will mean the event listener will be called in the object's context. This is most useful when setting up listeners on the object's prototype as v2.0.0 featured:

  Model.prototype.on("change", fn)
  

• Allows binding additional arguments:

  model.on("change", onChange, thisArg, 1, 2, 3)