SocketCluster Client

Common errors

• TypeError: socketCluster.connect is not a function

  cause Using the deprecated `connect` method instead of `create`.
  fix Change `socketClusterClient.connect(...)` to `socketClusterClient.create(...)`. The `connect` method was renamed in v10.0.0.

• ReferenceError: socketClusterClient is not defined

  cause The `socketcluster-client` script tag was not loaded in the HTML, or the module was not correctly imported/required in a module environment.
  fix Ensure `<script type="text/javascript" src="/socketcluster-client.js"></script>` is present and accessible in your HTML, or use `import { create } from 'socketcluster-client';` (ESM) / `const { create } = require('socketcluster-client');` (CJS) at the top of your JavaScript file.

• Error: Cannot read properties of undefined (reading 'connections')

  cause Attempting to access `socketCluster.connections` which was renamed.
  fix Update code to use `socketCluster.clients` instead of `socketCluster.connections`. This rename occurred in v10.0.0.

• UnhandledPromiseRejectionWarning: Error: Socket emitted a reserved event

  cause The client attempted to emit an event name that is reserved by SocketCluster internally.
  fix Rename the custom event you are trying to transmit to avoid conflict with SocketCluster's internal event names. This behavior changed in v13.0.0.

Warnings

• breaking The `SCSocket` class was renamed to `SCClientSocket` for better clarity and consistency with server-side naming conventions.
  Fix: Update all references from `SCSocket` to `SCClientSocket` in your code, including type imports and class instantiations.
• breaking The 'authenticate' event now triggers whenever the `authToken` changes, not just on the initial authentication. This affects scenarios where a new user's token might override a previously logged-in user's token on the same client instance.
  Fix: Review event handlers for 'authenticate' to ensure they correctly handle token changes and potential user session overrides, especially in multi-user or shared device environments.
• breaking The `socketCluster.connect(options)` method was renamed to `socketCluster.create(options)`. The `connect` alias is deprecated but still available.
  Fix: Replace `socketClusterClient.connect(...)` with `socketClusterClient.create(...)` or `create(...)` if using named imports. While `connect` might still work, it is deprecated.
• breaking The `socketCluster.connections` object/map was renamed to `socketCluster.clients`.
  Fix: Update any references to `socketCluster.connections` to `socketCluster.clients`.
• gotcha Passing invalid combinations of `hostname`, `host`, and `port` arguments to `create()` will now throw an error, enforcing stricter configuration validation.
  Fix: Ensure that connection options (hostname, host, port) are correctly configured and mutually exclusive where required. Refer to the official documentation for valid combinations.
• gotcha Attempting to emit a reserved event on the socket will now cause an error to be emitted on the socket itself. This prevents potential conflicts with internal SocketCluster protocols.
  Fix: Avoid using event names that are internally reserved by SocketCluster for custom transmissions. If an error is triggered, rename your custom event.

Install

• npm install socketcluster-client npm
• yarn add socketcluster-client yarn
• pnpm add socketcluster-client pnpm

Imports

• create
  wrong:

  import socketClusterClient from 'socketcluster-client'; const socket = socketClusterClient.create(...);

  correct:

  import { create } from 'socketcluster-client';

  Since v10.0.0, `create` is the preferred named export for initiating a connection. The default export is often used but less precise.
• SCClientSocket
  wrong:

  import { SCSocket } from 'socketcluster-client';

  correct:

  import { SCClientSocket } from 'socketcluster-client';

  The primary socket class was renamed from `SCSocket` to `SCClientSocket` in v13.0.0 for clarity and consistency. Use `SCClientSocket` for type imports or direct instantiation.
• socketClusterClient (global/module object)
  wrong:

  import socketClusterClient from 'socketcluster-client'; // Potentially not the default export, depending on bundler config.

  correct:

  const socketClusterClient = require('socketcluster-client'); // CommonJS
  // Or in browser after script tag:
  const socket = socketClusterClient.create(...);

  The module's main export is often an object containing utility methods like `create`. In browsers, a global `socketClusterClient` object is available after loading the script.

Quickstart

Demonstrates connecting to a SocketCluster server, transmitting data, invoking an RPC, subscribing to a channel, publishing to it, and consuming messages using async iterators.

import { create } from 'socketcluster-client';

const socket = create({
  hostname: 'localhost',
  port: 8000,
  autoConnect: true,
  autoReconnectOptions: {
    initialDelay: 1000,
    randomness: 500,
    multiplier: 1.2,
    maxDelay: 10000
  }
});

(async () => {
  try {
    await socket.listener('connect').once();
    console.log('Socket connected successfully to server.');

    // Transmit data to the server without expecting a response
    socket.transmit('chatMessage', { user: 'developer', text: 'Hello SocketCluster!' });

    // Invoke a remote procedure call (RPC) and await a response
    const serverTime = await socket.invoke('getServerTime');
    console.log('Server time received:', serverTime);

    // Subscribe to a channel and consume messages
    const myChannel = socket.subscribe('myPublicChannel');
    await myChannel.listener('subscribe').once();
    console.log('Successfully subscribed to channel: myPublicChannel');

    // Publish a message to the channel
    await myChannel.invokePublish('This is a message from the client.');
    console.log('Published message to channel.');

    // Consume messages from the channel using an async iterator
    for await (const data of myChannel) {
      console.log('Received channel message:', data);
      // For demonstration, process one message then unsubscribe
      break;
    }
    myChannel.unsubscribe();
    console.log('Unsubscribed from channel.');

  } catch (error) {
    console.error('Socket error or connection failed:', error);
  }

  // Disconnect the socket after a short delay
  setTimeout(() => {
    socket.disconnect();
    console.log('Socket disconnected.');
  }, 5000);
})();