why deepstreamHub? compare us getting started feature roadmap faq
use cases pricing
developers
company
enterprise blog contact

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

login(authParams, callback)

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. deepstreamHub will always send an object containing the client's user id, but can merge additional information into it. This information can be specified via the add-user dialog on the dashboard or programmatically returned from an http-webhook.

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)