Class: Subscription

Subscription

new Subscription()

Provides a stream of topic events, specific to the topic selector that this Subscription was created for. Subscription inherits all functions defined on Stream.


Properties:
Name Type Description
selector String The selector this subscription was created for
Fires:
Examples
// Get a reference to the subscription
session.subscribe('foo').on('open', function(subscription) {
    // Get selector & subscription instance
});
// Subscribe to a single topic
var subscription = session.subscribe('foo');

subscription.on('update', function(value) {
     // Receive updates for the topic 'foo'
});
var subscription = session.subscribe('?foo/.*');

subscription.on('update', function(value, topic) {
     // Receive updates for any topic directly below 'foo'
     // The topic the update is for is provided as the second argument
});
var subscription = session.subscribe('foo');

subscription.on('subscribe', function(details, topic) {
     // Receive notifications when we are subscribed to a topic
});
var subscription = session.subscribe('foo');

subscription.on('unsubscribe', function(reason, topic) {
     // Receive notifications when we are unsubscribed from a topic
});

Extends

Methods

asType(datatype) → {TypedSubscription}

Produce a TypedSubscription from this subscription stream, in order to receive values as a particular DataType. The TypedSubscription will only receive values from topics that are of matching type for the provided data type.

The lifecycle of the produced TypedSubscription is independent of this subscription. If this subscription was created using Session#stream without a selector (i.e as a fallback stream), the TypedSubscription will also be registered as a fallback stream.

Parameters:
Name Type Description
datatype DataType The data type to produce a stream for.
Returns:
A new Typed Subscription stream for the provided data type
Type
TypedSubscription
Example
// Produce a typed subscription for receiving JSON values.
var datatype = diffusion.datatypes.json();

session.subscribe('foo').asType(datatype).on('value', function(topic, value) {
    //...
});

close()

Close the subscription. No further events will be emitted.

off(event, listener) → {Stream}

Remove a listener from a specified event.
Parameters:
Name Type Argument Description
event String The event to remove listeners from
listener function <optional>
The listener to remove. All listeners for the event are removed if this is not specified
Inherited From:
Returns:
This stream.
Type
Stream
Examples
// Bind a single listener to the 'foo' event and then deregister it
var listener = function() {};
stream.on('foo', listener);
stream.off('foo', listener);
// Bind a listener to the 'foo' event and deregister all listeners
var listener = function() {};
stream.on('foo', listener);
stream.off('foo');

on(events, listener) → {Stream}

Register listeners against events.

A single listener may be bound to an event by passing the event name and listener function.

Multiple listeners may be bound by passing in an object, mapping event names to listener functions.

Parameters:
Name Type Argument Description
events String | Object The event name or object mapping event names to listeners
listener function <optional>
The listener to bind to the event, if passed as string.
Inherited From:
Returns:
This stream.
Type
Stream
Examples
// Bind a single listener to the 'foo' event
stream.on('foo', function(arg1, arg2) {
    console.log("Called for 'foo' event", arg1, arg2);
});
// Bind multiple listeners
stream.on({
    foo : function() { ... },
    bar : function() { ... },
    baz : function() { ... }
});

transform(transformer) → {Subscription}

Create a new Subscription instance that is bound with a transformation function.

The transformation function will be applied to any update event values before they are emitted to any listeners.

The transformation function is provided the update value and the topic path and should return a single value.

Parameters:
Name Type Description
transformer function The transformation function to apply to updates
Returns:
The new subscription bound with the transformation
Type
Subscription
Example
// Converts the update from a Buffer to a String
session.subscribe('foo').transform(String).on('update', function(v) { console.log(v); });

Events

close

Emitted when the subscription has been closed using Subscription#close.

error

Emitted when an error occurs in the Stream or in any of its listeners. No further events will be emitted after this.
Properties:
Name Type Description
error Error the error that occurred
Inherited From:

open

Emitted when the subscription is initially opened, passing a reference to the subscription itself. This will only be fired once.

subscribe

Emitted when a topic that is selected by this Subscription's topic selector is subscribed to by this session. Once subscribed, update update events may be received for this topic
Properties:
Name Type Description
details TopicDetails the topic details of the topic to which the subscription applies
topic String the topic to which the subscription applies

unsubscribe

Emitted when a topic that was previously subscribed, has been unsubscribed. No further update events will be received from this topic until subscribed again. Unsubscriptions may occur due to the topic being removed, or through calling Session#unsubscribe - an object containing the reason is provided.
Properties:
Name Type Description
reason String the reason the unsubscription occurred
topic String the topic to which the unsubscription applies

update

Emitted when an update has been received for a topic's value. By default, values are provided as Buffer objects, unless Subscription#transform has been used to convert values to a specific type.
Properties:
Name Type Description
value Buffer the new value of the topic
topic String the topic to which the update applies