diffusion

##Diffusion JS API

The Diffusion JavaScript API allows interaction with a Diffusion server from both the browser and NodeJS.

Clients use a WebSocket connection to receive and send data, as well as perform other functionality like adding, removing and updating topics.

###Quick start A client session maintains a connection to the server. To create a session, simply do

 diffusion.connect('diffusion.example.com');

It is also possible to connect with a map of options

diffusion.connect({
   host : 'diffusion.example.com',
   port : 8080,
   secure : false,
   principal : 'admin',
   credentials : 'password'
});

Connecting returns a Promise - this will succeed if the session could be connected, or fail if not.

diffuion.connect('diffusion.example.com').then(function(session) {
    // Connected!
}, function(error) {
    // Failed to connect :(
});

Sessions emit events to indicate when they are disconnected or closed. These events are easy to listen to.

session.on('disconnect', function() {
    // Lost connection to the server!
});

session.on('close', function() {
    // Session is closed!
});

Once a session is closed, it can never be re-opened.

####Subscriptions Data in Diffusion is distributed on topics. A topic carries a single value, which can be updated. Each topic is addressed by a unique path.

The way that a session receives data is by using a subscription. These allow the session to select a particular topic, and register a function to handle that topic's data. A session may subscribe to many topics, as well as subscribe to the same topic multiple times.

The simplest way to subscribe is

var subscription = session.subscribe('topic/foo');

The subscription that is returned is a stream of update events when the value of any of the selected topics changes. These events can be listened to like so

subscription.on('update', function(value, topic) {
    // Do something with the value
});

It is possible to register any number of listeners to a subscriptions update events. They will each be called when a new value is received. By default, received values will be provided as buffers. For browsers, a shim is used to provide an equivalent API.

Because clients will most likely wish to consume data in a more specific type, subscriptions can be transformed. Calling the transform method will return a new subscription stream with a bound transformation function. This will be applied to all topic values before being passed to user listeners.

session.subscribe('topic/foo').transform(JSON.parse).on('update', function(update) {
    // Receive the same data, parsed into a JSON object
});