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 asmergeStrategy
client option or per record withrecord.setMergeStategy( deepstream.MERGE_STRATEGIES.LOCAL_WINS)