SocketCluster JavaScript Client

To maintain compatibility with an existing SocketCluster server, set protocolVersion to 1 and ensure the path matches the old server's path.

let socket = socketClusterClient.create({
  protocolVersion: 1,
  path: '/socketcluster/'
});

To connect to a secure server, set secure: true and specify the appropriate port (usually 443). If using self-signed certificates during development, you may need to set wsOptions: { rejectUnauthorized: false }.

let options = {
  hostname: 'securedomain.com',
  secure: true,
  port: 443,
  wsOptions: { rejectUnauthorized: false }
};
let socket = socketClusterClient.create(options);

To use the SocketCluster client, install it via npm. Note that you will also need socketcluster-server to establish a connection.

npm install socketcluster-client

You can include the client directly in your HTML page. Once embedded, a global socketClusterClient object becomes available. Note that the src path depends on your HTTP server configuration.

<script type="text/javascript" src="/socketcluster-client.js"></script>

Use socket.subscribe(name) to subscribe to a specific channel. You can await the subscribe event via myChannel.listener('subscribe').once() to ensure the channel state is 'subscribed' before proceeding.

(async () => {
  // Subscribe to a channel.
  let myChannel = socket.subscribe('myChannel');

  await myChannel.listener('subscribe').once();
  // myChannel.state is now 'subscribed'.
})();

Use socket.invoke(name, data) to perform a Remote Procedure Call (RPC). This method expects a response from the server and returns a Promise.

(async () => {
  // Invoke an RPC on the server.
  let result = await socket.invoke('myProc', 123);
})();

Use socketClusterClient.create() to initiate a connection. You can provide configuration options such as hostname and port.

let socket = socketClusterClient.create({
  hostname: 'localhost',
  port: 8000
});

Use socket.transmit(name, data) to send data to the server without expecting a response. On the server side, this can be handled using socket.receiver(name).

// Transmit some data to the server.
socket.transmit('foo', 123);

Use socket.channel(name) to obtain a channel object without immediately subscribing to it. You can call myChannel.subscribe() at a later time.

(async () => {
  let myChannel = socket.channel('myChannel');

  // Can subscribe to the channel later as a separate step.
  myChannel.subscribe();
  await myChannel.listener('subscribe').once();
  // myChannel.state is now 'subscribed'.
})();

Channels are asynchronous iterables. You can consume data published to a channel using a for await...of loop.

(async () => {
  for await (let data of myChannel) {
    // ...
  }
})();

The following options are available when calling socketClusterClient.create(options):

let options = {
  path: '/socketcluster/',
  port: 8000,
  hostname: '127.0.0.1',
  autoConnect: true,
  secure: false,
  connectTimeout: 10000, // milliseconds
  ackTimeout: 10000, // milliseconds
  channelPrefix: null,
  autoReconnectOptions: {
    initialDelay: 10000, // milliseconds
    randomness: 10000, // milliseconds
    multiplier: 1.5, // decimal
    maxDelay: 60000 // milliseconds
  },
  authEngine: null,
  codecEngine: null,
  subscriptionRetryOptions: {},
  wsOptions: { rejectUnauthorized: false },
  query: {
    yourparam: 'hello'
  }
};