Radioradio NPM

RadioRadio

RadioRadio is a very basic, lightweight, dependency-free JavaScript PubSub library.

Key Features

Supports namespaced events (e.g. foo.bar)
Dependency-free
AMD/Node module support

RadioRadio is also really tiny:

Getting RadioRadio

Adding RadioRadio to your project is easy! You've got a couple options:

Download a tagged version from GitHub and do it yourself (old school).
Install via Bower: bower install radioradio
Install via npm: npm install radioradio

Usage

Subscribing

RadioRadio.subscribe(topic, subscriber);

Accepts: topic (String) and subscriber (Function)
Returns: String or false

The `topic` argument

Topics must be strings of any length (e.g. foo) made up of letters, numbers, and underscores. Topics may also be organized into namespaces using a . as a separator (e.g. foo.bar).

Topics within a namespace may themselves act as namespaces. For example, a subscribed topic foo.bar.biz exists in the foo and foo.bar namespaces. Note that this structure will affect publication (see Publishing below).

Wildcard topics within a namespace (e.g. foo.*, foo.bar.*) are also allowed. See Publishing below for more on when these topics are published.

The `subscriber` argument

A function to execute when topic is published. Subscribers accept a single argument (data) passed on from the publish method.

Publishing

RadioRadio.publish(topic, data);

Accepts: topic (String) and data (Object)
Returns: Array or false

The `topic` argument

The topic to which you wish to publish. When using namespaced topics (e.g. foo.bar), you may publish to a single topic:

RadioRadio.publish('foo.bar', data);

…or, to a topic and any topics within its namespace:

RadioRadio.publish('foo', data);

Publishing to the namespace foo will publish to foo and all topics namespaced to foo (e.g. foo.bar, foo.biz, foo.baz). As mentioned above in Subscribing, topics may be deeply nested (e.g. foo.bar.biz) which will affect publishing to namespaces:

RadioRadio.publish('foo', data);     // publishes to `foo`, `foo.bar`, `foo.bar.biz`
RadioRadio.publish('foo.bar', data); // publishes to `foo.bar`, `foo.bar.biz`

Wildcard topics within a namespace (e.g. foo.*) will be published alongside adjacent (e.g. foo.bar, foo.biz) published topics:

RadioRadio.subscribe('foo.bar', subscriber);
RadioRadio.subscribe('foo.*', wildcardSubscriber);

RadioRadio.publish('foo.bar', data); // publishes to `foo.bar` and `foo.*`

Note that topics are published in the order in which they were originally subscribed.

The `data` argument

The data to pass along to subscribers. Most usefully an Object, data could be anything so long as the topic's subscriber functions are prepared to handle it.

Unsubscribing

RadioRadio.unsubscribe(topic);

Accepts: topic (String)
Returns: true

The `topic` argument

The topic from which you wish to unsubscribe. Calling this method removes topic from the stored list of subscribed topics. Subsequent calls to publish to that topic will fail silently, returning false.

Example

For a full-featured RadioRadio demonstration, check out the included example file.

Browser Support

RadioRadio works in all modern browsers. The library makes use of several new(ish) JavaScript methods, including:

Object.keys (MDN)
Array.prototype.forEach() (MDN)

Internet Explorer added native support for these features in version 9, but if you wish to support older versions of IE, check out the polyfills available on the above linked MDN pages. RadioRadio, in an effort to remain as lightweight and dependency-free as possible, leaves it up to you to choose to polyfill older versions of IE.

To avoid throwing JavaScript errors in browsers that don't support these features, you can cut the mustard:

if (Object.keys && Array.forEach) {
    // Your scripts here…
}

Acknowledgments

RadioRadio is inspired by Morgan Roderick's PubSubJS.

RadioRadio is written and maintained by Jason Garber and, yes, it's named after an Elvis Costello & The Attractions song. It's also another in a growing line of small, curiously-named JavaScript utilities: