Skip to content
An event bus written in JavaScript
JavaScript CoffeeScript Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
lib
sample
src
vendor/assets/javascripts
.gitignore
.rbenv-version
Gemfile
README.markdown
Rakefile
jsbus.gemspec

README.markdown

JsBus 0.1.3

Why Write a JavaScript Message Broker?

Because.

Installing

Copy/Paste

The easiest way to use JsBus is to copy jsbus.js into your project.

Rails Asset Pipeline

JsBus is designed as a gem to work with the Rails asset pipeline. Install the gem and you're ready to go.

$ gem install jsbus

Add to your Gemfile. Run bundler, and you should be ready to go.

gem 'jsbus', '~> 0.1.3'

In application.js, add the following line, and everything should work as expected.

//= require jsbus

Usage

JsBus will add one item to your global namespace: window.eventBus. Everything else is hidden away. The basic operations are

eventBus.subscribe(eventType, callback);    // Subscribe the callback to the event type.
eventBus.publish(eventType, data);          // Publish an event with a type (optionally with data).
eventBus.unsubscribe(eventType);            // Unsubscribe all subscribers with the event type.

Subscribing to events

Subscribing to events is a simple callback pattern. Simply give the event type and what to do when the event is published.

eventBus.subscribe("my.event", function() {
  alert("my.event was raised!");
});

You can subscribe the same callback to multiple events simultaneously.

eventBus.subscribe(["my.event-one", "my.event-two"], function(event) {
  alert(event.eventType + " was raised!");
});

Publishing an event

You can publish one event by calling publish().

eventBus.publish("my.event");

You can publish multiple events simultaneously by sending an array of events.

eventBus.publish(["my.event-one", "my.event-two"]);

You can send data with a publish. You can get to the data by receiving the event in your callback. The data will be stored in event.data.

eventBus.subscribe("my.event", function(event) {
  alert("x: " + event.data.x);
});
eventBus.publish("my.event", { x: 1, y: 3, z: [2, 4, 6] });

Publishing an event can also have a callback. The publisher callback will be invoked after each subscribers.

eventBus.publish("my.event", function() {
  alert("I'm back!");
});

In the example above, if my.event has three subscribers, you can expect three alert popups.

You can even do basic request/response style programming with JsBus. To do this, your subscriber should have a return statement. Whatever is returned from the subscriber will be passed into the publisher's callback.

eventBus.subscribe("my.event", function (event) {
  switch (event.data.op) {
    case 'increment':
      return event.data.value + 1;
    case 'decrement':
      return event.data.value - 1;
    case 'square':
      return event.data.value * event.data.value;
    default:
      return 0;
  }
});
eventBus.publish("my.event", { op: 'square', value: 3 }, function (response) {
  alert("response is: " + response); // response is: 9
});

Unsubscribing

You can unsubscribe from one or more events, too.

eventBus.unsubscribe('my.event');
eventBus.unsubscribe(['my.event.one', 'my.event.two']);

Testing

A Node Express test application is provided in the repository. Unit testing is done with QUnit. You can see a sample usage by browsing to /sample.

$ git clone git@github.com:jarrettmeyer/jsbus.git
$ cd jsbus
$ node ./sample/app

The QUnit tests are at /qunit. A sample page is located at /sample.

Authors

Jarrett Meyer

Something went wrong with that request. Please try again.