Documentation

Class: Stream

Stream

A Sync primitive for pub-sub messaging. Stream Messages are not persisted, exist only in transit, and will be dropped if (due to congestion or network anomalies) they cannot be delivered promptly. Use the Client#stream method to obtain a reference to a Sync Message Stream.
Properties:
Name Type Argument Default Description
sid String The immutable system-assigned identifier of this stream. Never null.
uniqueName String <optional>
 null A unique identifier optionally assigned to the stream on creation.
Fires:

Methods

close()

Conclude work with the stream instance and remove all event listeners attached to it. Any subsequent operation on this object will be rejected with error. Other local copies of this stream will continue operating and receiving events normally.
Example
stream.close();

<async> publishMessage(value)

Publish a Message to the Stream. The system will attempt delivery to all online subscribers.
Parameters:
Name Type Description
value Object The body of the dispatched message. Maximum size in serialized JSON: 4KB. A rate limit applies to this operation, refer to the Sync API documentation for details.
Returns:
A promise which resolves after the message is successfully published to the Sync service. Resolves irrespective of ultimate delivery to any subscribers.
Type
Promise.<StreamMessage>
Example
stream.publishMessage({ x: 42, y: 123 })
  .then(function(message) {
    console.log('Stream publishMessage() successful, message SID:' + message.sid);
  })
  .catch(function(error) {
    console.error('Stream publishMessage() failed', error);
  });

<async> removeStream()

Permanently delete this Stream.
Returns:
A promise which resolves after the Stream is successfully deleted.
Type
Promise.<void>
Example
stream.removeStream()
  .then(function() {
    console.log('Stream removeStream() successful');
  })
  .catch(function(error) {
    console.error('Stream removeStream() failed', error);
  });

<async> setTtl(ttl)

Update the time-to-live of the stream.
Parameters:
Name Type Description
ttl Number Specifies the TTL in seconds after which the stream is subject to automatic deletion. The value 0 means infinity.
Returns:
A promise that resolves after the TTL update was successful.
Type
Promise.<void>
Example
stream.setTtl(3600)
  .then(function() {
    console.log('Stream setTtl() successful');
  })
  .catch(function(error) {
    console.error('Stream setTtl() failed', error);
  });

Events

messagePublished

Fired when a Message is published to the Stream either locally or by a remote actor.
Parameters:
Name Type Description
args Object Arguments provided with the event.
Properties
Name Type Description
message StreamMessage Published message.
isLocal Boolean Equals 'true' if message was published by local code, 'false' otherwise.
Example
stream.on('messagePublished', function(args) {
  console.log('Stream message published');
  console.log('Message SID: ' + args.message.sid);
  console.log('Message value: ', args.message.value);
  console.log('args.isLocal:', args.isLocal);
});

removed

Fired when a stream is removed entirely, whether the remover was local or remote.
Parameters:
Name Type Description
args Object Arguments provided with the event.
Properties
Name Type Description
isLocal Boolean Equals 'true' if stream was removed by local code, 'false' otherwise.
Example
stream.on('removed', function(args) {
  console.log('Stream ' + stream.sid + ' was removed');
  console.log('args.isLocal:', args.isLocal);
});