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 plain 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 on 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 using a subscription. Subscriptions allow the session to select a particular topic, and register a function to handle notifications that a topic's data has been changed. 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 containing values encoded as binary Buffer objects that can be transformed as appropriate. 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
});

For anything other than simple topic types it is more convenient to type the stream of values so that they can be accessed without requiring decoding. These values are then delivered as value events. So, for instance, to subscribe to a stream of JSON updates:

  subscription.asType(diffusion.datatypes.json()).on('value', function(topic, specification, value) {
      var jsonvalue = value.get(); // Do something with the new JSON value
  });

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

Because clients will most likely consume data in a more specific type, subscriptions to update events 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(String).on('update', function(update) {
    // Receive the same data, parsed into a String object
});