message-exchange

integrates redis as a queue and a pubsub by providing an easy mechanism for publishing and handling messages

The goal of this library is to wrap-up kue and [redis] (https://www.npmjs.org/package/redis "Redis") and provide a simple interface for building event driven applications.
At a high-level the library will read messages off of a queue, attempt to handle them, and in some cases publish those events back out onto the pubsub (redis).

Installation and Environment Setup

Install node.js (See download and install instructions here: http://nodejs.org/).

Install redis (See download and install instructions http://redis.io/topics/quickstart)

Install coffee-script

> npm install coffee-script -g

Clone this repository

> git clone git@github.com:NathanGRomano/message-exchange.git

cd into the directory and install the dependencies

> cd message-exchange
> npm install && npm shrinkwrap --dev

Examples

Here is how to create a simple application to handle an event and broadcast it back out.

First we get an exchage instance

 
var events = require('events');
var exchange = require('message-exchange').make();
 

Lets initialize a model and setup a handler for a quit event

 
var employeeModel = {hired: new Date()}:
 
var handler = new events.EventEmitter()
handler.on('quit', function (event) {
 
  // handle the event 
  employeeModel.quit = event.created;
 
  // let Human Resources know the employee quit  
  exchange.channel('human resources').publish(event);
 
});
 
exchange.handler(handler);
 

When we handle a quit event we broadcast the messaage to the human resources channel. So let add a listener on that channel so we can relay the information to say a socket.

 
//presume we have declared sockets elsewhere 
 
exchange.channel('human resources').on('message', function (event) {
  sockets.emit('message', event);
});
 

Now lets publish a quit event the message queue. It will be handled by our handler and then broadcast on our channel and finally broadcast to our sockets.

 
exchange.publish({
  actor:'employee', 
  target:'job', 
  action:'quit', 
  created:new Date(), 
  content:'work performed'
});
 

You can put anything you like into an event. I just like to follow a convention similar to what you saw. Make sure you have the required field "action" in your event.

API Documentation

This is wheere we publish, handle, and propagate messages.

 
var exchange = require('message-exchange').make();
 
 
var messageExchange = require('message-exchange');
 
var queue = messageExchange.Queue.make();
var pubsub = messageExchange.PubSub.make();
var handler = new EventEmitter();
 
var exchange = messageExchange.make(queue, pubsub, handler);
 

Puts the message onto the Queue.

 
var message = {
  actor: 'Me',
  action: 'shout',
  content: 'Hello',
  target: 'You'
};
 
exchange.publish( message );
 

Puts the message onto the PubSub with the channel being "everyone".

 
var message = {
  actor: 'Me',
  action: 'shout',
  content: 'Hello',
  target: 'You'
};
 
exchange.publish( message, 'everyone' );
 

Gets a channel instance, if it doesn't already exist it will subscribe to that channel.

 
var channel = exchange.channel('everyone');
channel.on('message', function (message) {
  //do somethign 
});
 

Gets the Queue instance.

 
var queue = exchange.queue();
queue.send(message);
 

Sets the Queue instance.

 
var kue = require('kue');
var queue = messageExchange.Queue.make(kue.createClient());
 
exchange.queue(queue);
 

Gets the pubsub instance.

 
var pubsub = exchange.pubsub();
pubsub.send(message, 'everyone');
 

Sets the pubsub instance.

 
var redis = require('redis');
 
var pub = redis.createClient();
var sub = redis.createClient();
 
var pubsub = messageExchange.PubSub.make(pub, sub);
 
exchange.pubsub(pubsub);
 

Gets the handler which is an EventEmitter.

 
var handler = exchange.handler();
handler.on('some message', function (messageexchange) {
  // do something 
  exchange.channel(message.target).publish(message);
});
 

Sets the handler.

 
var events = require('events');
 
var handler = new events.EventEmitter;
handler.on('some message', function (messageexchange) {
  // do something 
  exchange.channel(message.target).publish(message);
});
 
exchange.handler(handler);
 

Running Tests

Tests are run using grunt. You must first globally install the grunt-cli with npm.

> sudo npm install -g grunt-cli

To run the tests, just run grunt

> grunt

TODO

  • Support different queues