topic

A simple pub/sub package

npm install topic
4 downloads in the last month

Topic

Topic is a simple, lightweight pub/sub package.

Example:

var topic = require('topic');

//-----------------------------------------------------------------------------
// Configure and start broker.
//-----------------------------------------------------------------------------
new topic.Broker({ port: 8080, pathname: '/broker'})
    .start();

//-----------------------------------------------------------------------------
// Configure and start subscriber.
//-----------------------------------------------------------------------------
var subOptions = { };
subOptions.broker = { url: 'http://localhost:8080/broker' };
subOptions.client = { };
subOptions.client = { port: 8082, hostname: 'localhost', pathname: '/logger/log' };
subOptions.client.topicFilter = null;

new topic.Subscriber(subOptions)
    .on('received', function(topic, message) {
        console.log('topic: ' + topic
            + '\rmessage: ' + JSON.stringify(message) 
            + '\r\r');
    })
    .subscribe(8082, 'localhost');

//-----------------------------------------------------------------------------
// Configure publisher.
//-----------------------------------------------------------------------------
var pubOptions = { };
pubOptions.broker = { url: 'http://localhost:8080/broker' };
var publisher = new topic.Publisher(pubOptions);

//-----------------------------------------------------------------------------
// Publish.
//-----------------------------------------------------------------------------
setTimeout(function () {
    publisher.publish('ping', { description: 'Anybody out there?' });
}, 1000);

setTimeout(function () {
    publisher.publish('ping', { description: 'Anybody out there?' });
}, 4000);

setTimeout(function () {
    publisher.publish('ping', { description: 'Anybody out there?' });
}, 7000);

new topic.Broker(options)

Returns a new Broker object.

Options:

  • port: Port of server.
  • hostname: A domain name or IP address. If the hostname is omitted, the server will accept connections directed to any IPv4 address (INADDR_ANY).
  • pathname: Defaults to '/'.

new topic.Subscriber(options)

Returns a new Subscriber object.

Options:

  • broker:
    • url: The broker URL string.
  • client:
    • port: Port of server.
    • hostname: A domain name or IP address. Defaults to the server's IP address (using dns.lookup()).
    • pathname: Defaults to '/'
  • topicFilter determines which topics the subscriber is interested in. Defaults to null. It can be:
    • a string. The subscriber will receive any message with a topic which exactly matches the string.
    • a regular expression. The subscriber will receive any message with a topic which matches the regular expression. Example (Note, modifiers is optional): { "pattern": "ping", "modifiers": "i" }
    • an array which contains strings and/or regular expressions. The subscriber will receive any message with a topic which matches any element in the array.
    • null. The subscriber will receive all messages.

new topic.Publisher(options)

Returns a new Publisher object.

Options:

  • broker:
    • url: The broker URL string.

Class: topic.Broker

A broker is a server which accepts commands via POSTs with a JSON body. Commands can be of three types: subscribe, unsubscribe and publish.

The following is a sample subscribe command:

    {
        "subscribe": {
            "http://hundred-acre-wood.org/winnie-the-pooh/": [
                { "pattern" : "hunny", "modifiers" : "i" },
                "heffalumpSpotted"
            ]
        }
    }

Its subscriber URL is http://hundred-acre-wood.org/winnie-the-pooh/, and its topic filter is an array with two elements: a regular expression (/hunny/i), and a string ("heffalumpSpotted").

It tells the broker that if it receives a publish command with a topic which contains hunny (case insensitive) or exactly matches heffalumpSpotted, POST the command to http://hundred-acre-wood.org/winnie-the-pooh/.

The following is a sample publish command:

    {
        "publish": {
            "hunnyArrived": { quantity: 10}
        }
    }

It has a topic of hunnyArrived and a message { quantity: 10}. The broker will POST the command to any subscribers who have a topic filter which matches the topic hunnyArrived.

The following is a sample unsubscribe command:

    {
        "unsubscribe": "http://hundred-acre-wood.org/winnie-the-pooh/"
    }

Its subscriber URL is http://hundred-acre-wood.org/winnie-the-pooh/. The broker no longer send topic/message pairs to the subscriber.

This is an EventEmitter with the following events:

Event: 'error'

function(error, context) { }

Emitted when an error occurs.

  • error is the error that has occured.
  • context provides additional information about the error.

Event: 'started'

function(brokerUrl) { }

Emitted when the broker has started, and is ready to accept and process commands.

  • brokerUrl is a formatted URL string which identifies where to POST broker commands.

Event: 'stopped'

function(brokerUrl) { }

Emitted when the broker has stopped, and will no longer accept new commands.

  • brokerUrl is a formatted URL string which identifies where to POST broker commands.

Event: 'subscribed'

function(subscriberUrl, topicFilter) { }

Emitted when the broker accepts a subscribe command.

  • subscriberUrl is a formatted URL string which is used by the broker to uniquely identify the subscriber. The broker will post topic/message pairs to this url based on the topicFilter.
  • topicFilter determines which topics the subscriber is interested in. It can be:
    • a string. The subscriber will receive any message with a topic which exactly matches the string.
    • a regular expression. The subscriber will receive any message with a topic which matches the regular expression. Note, modifiers is optional. Example: { "pattern": "ping", "modifiers": "i" }
    • an array which contains strings and/or regular expressions. The subscriber will receive any message with a topic which matches any element in the array.
    • null. The subscriber will receive all messages.

Event: 'unsubscribed'

function(subscriberUrl) { }

Emitted when the broker accepts an unsubscribe command.

  • subscriberUrl is a formatted URL string which is used by the broker to uniquely identify the subscriber.

Event: 'received'

function(topic, message) { }

Emitted when the broker accepts a publish command.

  • topic is a string which is used to route the message to interested subscribers.
  • message can be null or any type which can be JSON stringified.

Event: 'delivered'

function(topic, message, subscriberUrl) { }

Emitted when a topic/message pair from a publish command has been delivered to an interested subscriber.

  • topic is a string which was used to route the message to the subscriber.
  • message can be null or any type which can be JSON stringified.
  • subscriberUrl is a formatted URL string which identifies which subscriber the topic/message pair was posted to.

broker.start()

Begin accepting and processing commands posted to a url based on the broker's configuration.

broker.stop()

Stop the broker from accepting new commands.

Class: topic.Subscriber

This is an EventEmitter with the following events:

Event: 'error'

function(error, context) { }

Emitted when an error occurs.

  • error is the error that has occured.
  • context provides additional information about the error.

Event: 'subscribed'

function(subscriberUrl, topicFilter, brokerUrl) { }

Emitted when the broker accepts a subscribe command from the subscriber.

  • subscriberUrl is a formatted URL string which is used by the broker to uniquely identify the subscriber. The broker will post topic/message pairs to this url based on the topicFilter.
  • topicFilter determines which topics the subscriber is interested in. It can be:
    • a string. The subscriber will receive any message with a topic which exactly matches the string.
    • a regular expression. The subscriber will receive any message with a topic which matches the regular expression. Example (Note, modifiers is optional): { "pattern": "ping", "modifiers": "i" }
    • an array which contains strings and/or regular expressions. The subscriber will receive any message with a topic which matches any element in the array.
    • null. The subscriber will receive all messages.
  • brokerUrl is a formatted URL string which identifies where the subscribe command was POSTed.

Event: 'unsubscribed'

function(subscriberUrl, brokerUrl) { }

Emitted when the broker accepts an unsubscribe command from the subscriber.

  • subscriberUrl is a formatted URL string which is used by the broker to uniquely identify the subscriber.
  • brokerUrl is a formatted URL string which identifies where the unsubscribe command was POSTed.

Event: 'received'

function(topic, message) { }

Emitted when a topic/message pair has been received from the broker.

  • topic is a string which was used to route the message to the subscriber.
  • message can be null or any type which can be JSON stringified.

subscriber.subscribe()

POSTs a subscribe command to the broker, and listens for any topic/message pairs.

subscriber.unsubscribe()

POSTs an unsubscribe command to the broker, stops listening for any topic/message pairs.

Class: topic.Publisher

This is an EventEmitter with the following events:

Event: 'error'

function(error, context) { }

Emitted when an error occurs.

  • error is the error that has occured.
  • context provides additional information about the error.

Event: 'published'

function(topic, message, brokerUrl) { }

Emitted when the broker accepts a publish command from the publisher.

  • topic is a string which is used to route the message to interested subscribers.
  • message can be null or any type which can be JSON stringified.
  • brokerUrl is a formatted URL string which identifies where the publish command was POSTed.

publisher.publish(topic, [message])

POSTs a publish command to the broker.

  • topic must be a string. It is used to route the message to interested subscribers.
  • message can be any type which can be JSON stringified.

Example:

publisher.publish('ping');

or

publisher.publish('hello', 'world');

or

publisher.publish('hello', { value: 'world' });

npm loves you