diffusion

Diffusion JavaScript API

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

Clients use a WebSocket or HTTP connection to send and receive, as well as perform other functions such as adding, removing or 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.

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

Sessions emit events to indicate their status such as 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 via topics. A topic has state, which can be updated. The state can be simple - such as a string or an integer - or more complex - such as a JSON document. Each topic has a unique path and is addressed through a topic selector.

The way that a session receives data is by subscribing. Subscriptions allow the session to select one or more topics to receive values from. A session may subscribe to many topics, as well as subscribe to the same topic multiple times.

session.subscribe('topic/foo')

To attach listeners for received values, a ValueStream is used. The stream that is returned will emit events when the value of the selected topic changes.

session.stream('topic/foo').asType(diffusion.datatypes.json()).on('value', function(topic, specification, update) {
    // Do something with the value
    var value = update.get();
});

It is possible to register any number of streams to a subscription's events. They will each be called when a new value is received.