@jgarber/radioradio NPM

RadioRadio

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

!NOTE RadioRadio is feature complete and will only be updated to address bugs or security issues.

Key Features

Supports namespaced events (e.g. foo.bar)
Dependency-free
JavaScript module (ESM)

Getting RadioRadio

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

Download a release from Codeberg 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 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: