xcvr

xcvr

xcvr (pronounced Tranz-see-ver) is a simple, asynchronous message bus for your application.

It is intended to be used as a communications channel between various elements of an application. It provides a mechanism for subscribing to and sending messages with a named type and an optional message payload (which can be any type, but is most useful as an object.)

Messages can be sent by one portion of a system without knowing what might be listening for that message. Likewise, messages can be received without advanced knowledge of what the origin of the message is.

This makes xcvr and ideal mechanism for providing loose coupling between application components.

By default xcvr returns a singleton that acts as a message bus for your application.

Usage

    import xcvr from 'xcvr';

    // set up a receiver for a particular message 
    xcvr.receive('greeting_message', function greeting_handler(msg) {
        console.log('received message:' + msg);
    });

    // send a message
    xcvr.send('greeting_message', "Hi there");

    // listen for a particular message type only once:
    xcvr.receive_once('link_terminated', function(msg) {
        console.log('our link was terminated, shutting down');
        do_shutdowny_things();
    });

    // Remove a message receiver we added earlier
    xcvr.remove_receiver('greeting_message', greeting_handler)

The xcvr object acts as a transciever and is used to send and receive messages across the application. Sent messages are delivered automatically to anything that is listening for that type of message.

The messages are delivered asyncronously, so the call to send the message returns immediately, prior to each message recipient being called. Messages are also protected against receivers exceptions, that is to say that if there is an exception in a receiver it will not stop or otherwise prevent delivery to other receivers of the same message type;

By default an instantiated singleton xcvr is created automatically.
This xcvr object can then be used by whatever code needs to send and receive messages throughout your application.

If you need multiple isolated xcvrs, you can create separate instances directly as follows:

    import { xcvr } from 'xcvr';

    const first_xcvr = new xcvr();
    const second_xcvr = new xcvr();

    // set up a receiver for a particular message 
    first_xcvr.receive('greeting_message', function greeting_handler(msg) {
        console.log('first xcvr received message:' + msg);
    });

    // second receiver is separate from first
    second_xcvr.receive('greeting_message', function greeting_handler(msg) {
        console.log('second xcvr received message:' + msg);
    });

When created this way, each xcvr instance is isolated from each other.