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


It is also possible to connect with a map of options

    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(reason) {
    // Lost connection to the server!

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

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


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.


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.addStream('topic/foo', diffusion.datatypes.json()).on('value', function(topic, specification, newValue, oldValue) {
    // Do something with the value
    var value = newValue.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.


The JavaScript client provides namespaces, classes, and methods that support the following capabilities:


  • Connect the JavaScript client to Diffusion or Diffusion Cloud by using the diffusion.connect method.

  • To change the security principal that the client is connected with, use the changePrincipal method.

  • The client can log out information by using the diffusion.log method.

  • The client can check its connectivity and roundtrip time to the server by using the pingServer method.

Receive data from topics

  • Subscribe to topics.
    Use the session.select method to subscribe to a topic. The updates to a topic can be interacted with by registering a ValueStream and a provided datatype to start receiving the values of that datatype.

  • Fetch data from topics.
    Use the fetch method to make a fetch request and get a FetchStream object that you can use to receive fetched values.

Create and manage topics

  • Add a topic.
    Use the add method to add a topic. You can create a topic by explicitly defining the topic type, or by providing a TopicSpecification with optional properties.

  • Handle missing topics.
    Use the addMissingTopicHandler method to register a MissingTopicHandler. This handler receives a MissingTopicNotification when a client session subscribes to a topic that does not currently exist. The notified client can then choose to create that topic if appropriate.

  • Remove topics.
    Use the remove method to remove topics. You can also mark topics to be removed automatically with the TopicSpecification property REMOVAL.

Update topics

Manage other clients

Send messages

  • Send a message.
    Use the send method to either send a message to a specific client session or send a message to a path.

  • Receive messages sent to this client session.
    Use the setRequestStream method to receive messages sent to this client session through a RequestStream.

  • Receive messages sent to a path.
    Use the addRequestHandler method to register a RequestHandler that receives messages sent to a path.

Authenticating clients

The server also uses information stored in the system authentication store to authenticate connecting clients.

Updating security roles