@jgarber/radioradio

RadioRadio

A very small, lightweight, dependency-free JavaScript PubSub library.

Key Features

• Supports namespaced events (e.g. foo.bar)
• Dependency-free
• JavaScript module (ESM), CommonJS, and browser global (window.RadioRadio) support

Getting RadioRadio

You've got a couple options for adding RadioRadio to your project:

• Download a release from GitHub and do it yourself (old school).
• Install using npm: npm install @jgarber/radioradio --save
• Install using Yarn: yarn add @jgarber/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 demo page and the example file.

Browser Support

RadioRadio works in modern browsers. The library makes use of several new(ish) JavaScript methods and, in an effort to remain as lightweight and dependency-free as possible, leaves it up to you to choose whether or not to polyfill features for older browsers.

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:

• CashCash, a very small DOM library inspired by jQuery.
• RouterRouter, a very small routing library extracted from Backbone's Router.
• TemplateTemplate, a very small <template> manipulation library.

License

RadioRadio is freely available under The MIT License. Use it, learn from it, fork it, improve it, change it, tailor it to your needs.