Javascript Client

The deepstream JavaScript client can be used by both browsers and NodeJS. You can install it via NPM, Yarn or Bower package as deepstream.io-client-js or browse the source on Github

Creating the client

deepstream(url, options)

argument	type	optional	description
url	String	false	A url in the format :
options	Object	true	A map of options. Please find a list of available options here

Creates a client instance and initialises the connection to deepstreamHub. The connection will be kept in a quarantine state and won't be fully usable until login() is called.

const deepstream = require('deepstream.io-client-js')
const client = deepstream('wss://123.deepstreamhub.com?apiKey=xxx');
client.login()

Methods

argument	type	optional	description
authParams	Object	false	An object with authentication parameters, e.g `{ type: 'webhook', username: 'peter', password: 'sesame' }`
callback	Function	true	A function that will be called once the response to the authentication request is received.

Authenticates the client against the platform. To learn more about how authentication works, please have a look at the Security Overview.

Callback will be called with: success (Boolean) and clientData (Object).

clientData is data that will be sent to clients upon successful login.

const deepstream = require('deepstream.io-client-js')
const client = deepstream('wss://123.deepstreamhub.com?apiKey=xxx')
// client.getConnectionState() will now return 'AWAITING_AUTHENTICATION'

client.login({
  type: 'email',
  email: 'user@example.com',
  password: 'sesame'
}, (success, data) => {
  if (success) {
    // data will be an object with {id: 'user-id'} plus
    // additional data specified in clientData
    // start application
    // client.getConnectionState() will now return 'OPEN'
  } else {
    // extra data can be returned from the permissionHandler as client data
    // both successful and unsuccesful logins

    // client.getConnectionState() will now return
    // 'AWAITING_AUTHENTICATION' or 'CLOSED'
    // if the maximum number of authentication
    // attempts has been exceeded.
  }
})

// client.getConnectionState() will now return 'AUTHENTICATING'

close()

Ends the connection to the platform.

client.on('connectionStateChanged', connectionState => {
  // will be called with 'CLOSED' once the connection is successfully closed.
})

client.close()

getConnectionState()

Returns the current connectionState. Please find a list of available connectionStates here.

getUid()

Returnes a unique id. The uid starts with a Base64 encoded timestamp to allow for semi-sequentual ordering and ends with a random string.

client.getUid() // 'i9i6db5q-1xak1s2sfzk'

Events

connectionStateChanged

Emitted every time the connectionstate changes. The connectionState is passed to the callback and can also be retrieved using getConnectionState(). A list of possible connection states is available here

error

Aggregates all errors that are encountered. Some errors like CONNECTION_ERROR or MESSAGE_PARSE_ERROR are exlusively emitted by the client. Others like ACK_TIMEOUT or VERSION_EXISTS that relate to a specific Record, Event or RPC are emitted first by the object they relate to and are then forwarded to the client. You can find a list of all errors here.

client.on('error', ( error, event, topic ) => {
  console.log(error, event, topic);
});

Constants

deepstream.CONSTANTS grants access to constants. See constants for a full list
deepstream.MERGE_STRATEGIES grants access to the default merge strategies configurable globally as mergeStrategy client option or per record with record.setMergeStategy( deepstream.MERGE_STRATEGIES.LOCAL_WINS)

deepstream open source

deepstreamHub enterprise