ConvergenceDomain | Convergence JavaScript Client API Documentation

This represents a single connection to a specific Domain in Convergence. All interactions with the Domain start with this class, through several "services" that provide the following functionality:

ModelService: Manage models (data)
IdentityService: Manage users and groups
ActivityService: Manage activities
PresenceService: Manage presence
ChatService: Create chats and send and receive messages

This object itself is the result of a successful connection and authentication to a Convergence server via one of the Convergence connection methods. Or, to begin working in an offline state, instantiate this class directly.

See the Events section for all the possible events that could be emitted from a domain.

Hierarchy

ConvergenceEventEmitter<IConvergenceDomainEvent>
- ConvergenceDomain

Index

Constructors

constructor

Object literals

Events

Constructors

constructor

new ConvergenceDomain(url: string, options?: IConvergenceOptions): ConvergenceDomain

Overrides ConvergenceEventEmitter.__constructor

Constructs a new ConvergenceDomain using the default options.

Parameters
- url: string
  
  The url of the convergence domain to connect to.
- options: IConvergenceOptions
  
  Options that configure how the convergence domain is configured.
Returns ConvergenceDomain

Methods

activities

activities(): ActivityService

Gets the ActivityService, which is used for interacting with Activities.
```
const activityService = domain.activities();
```
Returns ActivityService

The ActivityService from this ConvergenceDomain.

addListener

addListener(event: string, listener: ConvergenceEventListener<IConvergenceDomainEvent>): ConvergenceEventEmitter<IConvergenceDomainEvent>

Inherited from ConvergenceEventEmitter.addListener

Adds a new event listener for the specified event. The class will ignore duplicate registrations of the same listener to the same event.

Parameters
- event: string
  
  The name of the event to add the listener for.
- listener: ConvergenceEventListener<IConvergenceDomainEvent>
  
  The listener callback to register.
Returns ConvergenceEventEmitter<IConvergenceDomainEvent>

This object, in support of a fluent API.

chat

chat(): ChatService

Gets the ChatService, which is used to send and receive chat messages.
example
```
const chatService = domain.chat();
```
Returns ChatService

The ChatService for this ConvergenceDomain.

connectAnonymously

connectAnonymously(displayName?: string | (() => Promise<string>)): Promise<void>

Connects to a Convergence Domain using anonymous authentication.

Parameters
- displayName: string | (() => Promise<string>)
  
  The optional display name to use for the anonymous user. The display name can be supplied directly or can be supplied as a factory function that will return a promise to obtain it.
Returns Promise<void>

A Promise which will be resolved upon successful connection and authentication.

connectWithJwt

connectWithJwt(jwt: string | (() => Promise<string>)): Promise<void>

Connects to a Convergence Domain using a JSON Web Token (JWT) for authentication.

Parameters
- jwt: string | (() => Promise<string>)
  
  A valid JSON Web Token (JWT) indicating the Domain User to connect as. The JWT can be supplied directly or can be supplied as a factory function that will return a promise to obtain it.
Returns Promise<void>

A Promise which will be resolved upon successful connection and authentication.

connectWithPassword

connectWithPassword(credentials: IUsernameAndPassword | (() => Promise<IUsernameAndPassword>)): Promise<void>

Connects to a Convergence Domain using username / password authentication.

Parameters
- credentials: IUsernameAndPassword | (() => Promise<IUsernameAndPassword>)
  
  The username and password of the Convergence Domain User to connect as. The credentials can be supplied directly or can be supplied as a factory function that will return a promise to obtain them.
Returns Promise<void>

A Promise which will be resolved upon successful connection and authentication.

disconnect

disconnect(): Promise<void>

Disconnects from the server, if connected.

Returns Promise<void>

dispose

dispose(): Promise<void>

Disconnects from the server and releases all resources this domain is using. After calling dispose(), the domain will no longer be usable.
example
```
domain.dispose()
  .then(() => console.log("disposed!"))
  .catch(e => console.error(e));
```
Returns Promise<void>

A promise that is resolved when the ConvergenceDomain is disposed.

events

events(): Observable<IConvergenceDomainEvent>

Inherited from ConvergenceEventEmitter.events
Provides the events emitted by this object as an Observable stream.
example
```
eventEmitter.events()
  .filter(e => e.name === "myevent")
  .subscribe(e => console.log(e));
```
Returns Observable<IConvergenceDomainEvent>

An Observable stream of all events emitted by this object.

id

id(): string

Returns string

The unique ID of this domain.

identity

identity(): IdentityService

Gets the IdentityService, which is used for obtaining information about Users.
```
const identityService = domain.identity();
```
Returns IdentityService

The IdentityService for this ConvergenceDomain.

initializeOffline

initializeOffline(username: string | (() => Promise<string>)): Promise<void>

Initializes the domain without connecting to the server. The method must be provided the username of the normal domain user that will eventually connect as.

experimental

Parameters
- username: string | (() => Promise<string>)
  
  The username of the domain user to connect offline as.
Returns Promise<void>

A Promise that will be completed when the domain is ready to use.

isConnected

isConnected(): boolean

Determines if the domain is connected.

Returns boolean

true if the domain is connected; false otherwise.

isDisconnected

isDisconnected(): boolean

Determines if the domain is disconnected.

Returns boolean

true if the domain is disconnected; false otherwise.

isDisposed

isDisposed(): boolean

Determines if this domain is disposed.

Returns boolean

True if the domain is disposed; false otherwise.

models

models(): ModelService

Gets the ModelService, which is used for interacting with Real Time Models.
```
const modelService = domain.models();
```
Returns ModelService

The ModelService for this ConvergenceDomain.

namespace

namespace(): string

Returns string

The namespace of this domain.

off

off(event: string, listener: ConvergenceEventListener<IConvergenceDomainEvent>): ConvergenceEventEmitter<IConvergenceDomainEvent>

Inherited from ConvergenceEventEmitter.off

Removes a single event listener for a specific event.

Parameters
- event: string
  
  The name of the event to remove the listener for.
- listener: ConvergenceEventListener<IConvergenceDomainEvent>
  
  The listener callback to unregister.
Returns ConvergenceEventEmitter<IConvergenceDomainEvent>

This object, in support of a fluent API.

on

on(event: string, listener: ConvergenceEventListener<IConvergenceDomainEvent>): ConvergenceEventEmitter<IConvergenceDomainEvent>

Inherited from ConvergenceEventEmitter.on

Adds a new event listener for the specified event. The class will ignore duplicate registrations of the same listener to the same event.

Parameters
- event: string
  
  The name of the event to add the listener for.
- listener: ConvergenceEventListener<IConvergenceDomainEvent>
  
  The listener callback to register.
Returns ConvergenceEventEmitter<IConvergenceDomainEvent>

This object, in support of a fluent API.

once

once(event: string, listener: ConvergenceEventListener<IConvergenceDomainEvent>): ConvergenceEventEmitter<IConvergenceDomainEvent>

Inherited from ConvergenceEventEmitter.once

Adds a single shot event listener for the specified event. The listener will be called the first time the specified event is fired after the event registration occurs, after which the registration will be removed and no further events will be passed to the listener.

Parameters
- event: string
  
  The name of the event to add the listener for.
- listener: ConvergenceEventListener<IConvergenceDomainEvent>
  
  The listener callback to register.
Returns ConvergenceEventEmitter<IConvergenceDomainEvent>

This object, in support of a fluent API.

options

options(): IConvergenceOptions

Returns IConvergenceOptions

The resolved options for this domain.

presence

presence(): PresenceService

Gets the PresenceService, which is used to gain insight into the presence of Domain Users.
example
```
const presenceService = domain.presence();
```
Returns PresenceService

The PresenceService for this ConvergenceDomain.

reconnect

reconnect(token?: string | (() => Promise<string>)): Promise<void>

Reconnects to the specified domain using a previously generated reconnect token.

Parameters
- token: string | (() => Promise<string>)
  
  The reconnect token to use for authentication.
Returns Promise<void>

A Promise which will be resolved upon successful connection and authentication.

removeAllListeners

removeAllListeners(): ConvergenceEventEmitter<IConvergenceDomainEvent>

Inherited from ConvergenceEventEmitter.removeAllListeners

Removes all listeners for all events. This is useful for cleanup before disposing of this particular event emitter.

Returns ConvergenceEventEmitter<IConvergenceDomainEvent>

This object, in support of a fluent API.

removeListener

removeListener(event: string, listener: ConvergenceEventListener<IConvergenceDomainEvent>): ConvergenceEventEmitter<IConvergenceDomainEvent>

Inherited from ConvergenceEventEmitter.removeListener

Removes a single event listener for a specific event.

Parameters
- event: string
  
  The name of the event to remove the listener for.
- listener: ConvergenceEventListener<IConvergenceDomainEvent>
  
  The listener callback to unregister.
Returns ConvergenceEventEmitter<IConvergenceDomainEvent>

This object, in support of a fluent API.

removeListeners

removeListeners(event: string): ConvergenceEventEmitter<IConvergenceDomainEvent>

Inherited from ConvergenceEventEmitter.removeListeners

Removes all listeners bound on the given event.

Parameters
- event: string
  
  the name of the event to remove listeners for
Returns ConvergenceEventEmitter<IConvergenceDomainEvent>

This object, in support of a fluent API.

serverTime

serverTime(): Promise<Date>

Gets the server's current time. Callers should not that this will be an approximate time based on network latency between the client and server. A potential way to get a more accurate estimate would be to monitor the round trip time and decrease the response by half the round trip time. For example:
example
```
const requestTime = Date.now();
domain.serverTime().then(serverTime => {
  const responseTime = Date.now();
  const delta = responseTime - requestTime;
  const serverTimeEstimate = new Date(serverTime.getTime() - delta);
  console.log(serverTimeEstimate);
});
```
Returns Promise<Date>

The current server time, at the time the server received the request.

session

session(): ConvergenceSession

Returns ConvergenceSession

The ConvergenceSession attached to this domain.

url

url(): string

Returns string

The url of the domain.

Object literals

Events

Events: object

A list of all the events that could be emitted from a domain.

AUTHENTICATING

AUTHENTICATING: string = AuthenticatingEvent.NAME

Emitted when the domain is actively attempting to authenticate. The actual emitted event is an AuthenticatingEvent.

CONNECTED

CONNECTED: string = ConnectedEvent.NAME

Emitted when the domain successfully (re)connected to the server. The actual emitted event is a ConnectedEvent.

CONNECTING

CONNECTING: string = ConnectingEvent.NAME

Emitted when the domain is actively attempting to connect to the server. The actual emitted event is a ConnectingEvent.

CONNECTION_FAILED

CONNECTION_FAILED: string = ConnectionFailedEvent.NAME

Emitted when a connection attempt failed. The actual emitted event is a ConnectionFailedEvent.

CONNECTION_SCHEDULED

CONNECTION_SCHEDULED: string = ConnectionScheduledEvent.NAME

Emitted when the domain is scheduled to attempt to reconnect. The actual emitted event is a ConnectionScheduledEvent.

DISCONNECTED

DISCONNECTED: string = DisconnectedEvent.NAME

Emitted when the domain is currently disconnected and is not attempting to automatically reconnect. The actual emitted event is a DisconnectedEvent.

ERROR

ERROR: string = ErrorEvent.NAME

Emitted when the domain encountered an unexpected error. The actual emitted event is an ErrorEvent.

INTERRUPTED

INTERRUPTED: string = InterruptedEvent.NAME

Emitted when the domain's connection was interrupted. This indicates that the domain is in a state where it is currently disconnected, but is automatically and continuously attempting to reconnect.

The actual emitted event is an InterruptedEvent.

Hierarchy

Index

Constructors

Methods

Object literals

Constructors

constructor

Parameters

url: string

options: IConvergenceOptions

Returns ConvergenceDomain

Methods

activities

Returns ActivityService

addListener

Parameters

event: string

listener: ConvergenceEventListener<IConvergenceDomainEvent>

Returns ConvergenceEventEmitter<IConvergenceDomainEvent>

chat

Returns ChatService

connectAnonymously

Parameters

displayName: string | (() => Promise<string>)

Returns Promise<void>

connectWithJwt

Parameters

jwt: string | (() => Promise<string>)

Returns Promise<void>

connectWithPassword

Parameters

credentials: IUsernameAndPassword | (() => Promise<IUsernameAndPassword>)

Returns Promise<void>

disconnect

Returns Promise<void>

dispose

Returns Promise<void>

events

Returns Observable<IConvergenceDomainEvent>

id

Returns string

identity

Returns IdentityService

initializeOffline

Parameters

username: string | (() => Promise<string>)

Returns Promise<void>

isConnected

Returns boolean

isDisconnected

Returns boolean

isDisposed

Returns boolean

models

Returns ModelService

namespace

Returns string

off

Parameters

event: string

listener: ConvergenceEventListener<IConvergenceDomainEvent>

Returns ConvergenceEventEmitter<IConvergenceDomainEvent>

on

Parameters

event: string

listener: ConvergenceEventListener<IConvergenceDomainEvent>

Returns ConvergenceEventEmitter<IConvergenceDomainEvent>

once

Parameters

event: string

listener: ConvergenceEventListener<IConvergenceDomainEvent>

Returns ConvergenceEventEmitter<IConvergenceDomainEvent>

options

Returns IConvergenceOptions

presence

Returns PresenceService

reconnect

Parameters

token: string | (() => Promise<string>)

Returns Promise<void>