Documentation

Common usage

Initialising Sarus

Sarus provides a number of options when initialising an instance:

const sarus = new Sarus({
  url: 'wss://ws.anephenix.com',
  binaryType: 'arraybuffer',
  eventListeners: {
    open: [() => {}],
    message: [event => {}],
    error: [error => {}],
    close: [() => {}],
  },
  reconnectAutomatically: true,
  retryConnectionDelay: true,
  storageType: 'local',
  protocols: 'hybi-00',
  retryProcessTimePeriod: 50,
  storageKey: 'sarus'
});

Below is a table of all of those options:

Attaching event listener functions

If you want to attach event listener functions to the sarus instance, you can do that by using the "on" function call:

// Logs messages to the console for debugging
const logMessage = (event) => {
  console.log(event.data);
};

// Attach the event listener
sarus.on('message', logMessage);

Below is a table of the parameters to pass to the function:

You can add as many event listener functions as you wish.

Removing event listener functions

In case that you want to remove an event listener function, you can do that by calling the 'off' function:

/*
  Remove a function from the Sarus 
  event listener by function variable
*/
sarus.off('message', logMessage);

/*
  You can also remove the event Listener 
  by the name of the function
*/
sarus.off('message', 'parseMessage');

Below is a table of the parameters to pass to the function:

Sending messages

Sending messages in Sarus is identical to how you would send messages with a WebSocket:

sarus.send('Hello world');

Below is a table of the parameters to pass to the function:

Closing the connection

If you want to close the WebSocket connection (for example when the user logs off from an app), then you can do that by calling this:

sarus.disconnect();

Calling that function on the sarus client will do 2 things:

1. Set the reconnectAutomatically flag to false.
2. Close the WebSocket connection.

Event listeners listening on the WebSocket's close event will still trigger, but the client will not attempt to reconnect automatically.

Below is a table of the parameters to pass to the function:

Advanced usage

Here you will get to see some of the advanced features of Sarus in action

Persisting messages with browser storage

Sarus uses a message queue to handle the messages that need to be sent over the WebSocket. When the WebSocket's status is open, the messages are sent. If there isn't an open connection, then the messages are kept in the queue.

In such a case, visitors might try to refresh their web browser, and if that happens, then those messages in the queue would be lost. If there's a case where you want to guarantee messages for delivery (such as pending chat messages to be sent), then you can use Sarus' message storage feature to persist the message queue.

The message queue is persisted with HTML5 browser storage, and there are two options - session storage, and local storage. Below is an example of how to configure Sarus to use session storage for the browser.

const sarus = new Sarus({
  url: 'wss://ws.anephenix.com',
  storageType: 'session',
});

This example above configures Sarus to use HTML5 session storage to persist the message queue. This means that the messages on the queue will persist between web page refreshes. You can inspect your browser's web storage to see the message queue persisted in the browser.

If you need the messages on the queue to be persisted beyond web browser restarts, then you can use HTML5 local storage to persist the message queue, like in the example below:

const sarus = new Sarus({
  url: 'wss://ws.anephenix.com',
  storageType: 'local',
});

The message queue is stored as a JSON array of messages, stringified in order to store in web browser storage.

Note - If you are persisting the message queue alongside messages sent in relation to a user using an app, consider wiping the browser storage when the user logs out of the app.

By default, the key used in HTML5 web storage for storing the messages is 'sarus', but you can customise that by passing the storageKey option as demonstrated in the example below:

const sarus = new Sarus({
  url: 'wss://ws.anephenix.com',
  storageType: 'local',
  storageKey: 'persistedMessages',
});

Delaying reconnection attempts

When a WebSocket connection closes Sarus will attempt to automatically reconnect without any delay. If you want to add a delay before Sarus tries to reconnect the WebSocket, you can do that by passing the 'retryConnectionDelay' option in the configuration for Sarus:

const sarus = new Sarus({
  url: 'wss://ws.anephenix.com',
  retryConnectionDelay: true,
});

The option of passing a boolean will add a delay of 1000ms (1 second) before trying to reconnect. Alternatively, if you want to specify the amount of time to delay the reconnection by, you can pass a number instead (in milliseconds):

const sarus = new Sarus({
  url: 'wss://ws.anephenix.com',
  retryConnectionDelay: 500, // 500ms or 1/2 second
});

Delaying message sending re-attempts

As part of the message queue, Sarus applies a 50ms delay before attempting to resend a message (in the case that the attempt to send a message failed). If you wish to, you can set the time period in milliseconds like this:

const sarus = new Sarus({
  url: 'wss://ws.anephenix.com',
  retryProcessTimePeriod: 25, // 25ms
});