Websocket JS Client

Installs: 3

Dependents: 0

Suggesters: 0

Security: 0

Stars: 7

Watchers: 12

Forks: 0


v0.0.4 2020-10-19 07:05 UTC


JavaScript WebSockets client library with channel support.

Since RoadRunner 2.x, the communication protocol has been changed. Below is a table of version compatibility.


SFSocket available for installing with npm or yarn

    npm install @spiralscout/websockets -D  
    yarn add @spiralscout/websockets 

Next use it like so

    import { SFSocket } from '@spiralscout/websockets';

Or via bundle file

    <script src="/build/socket.js"></script>
    <script type="text/javascript">
        var Socket = SFSocket.SFSocket;
        var connection = new Socket({ host: 'localhost'});

If you prefer CDN usage, use following URL for most recent version



SFSocket proposes easy way to use WebSockets:

import { SFSocket } from '@spiralscout/websockets';

const socketOptions = { host: 'localhost' };

// create an instance of SFSocket
const ws = new SFSocket(socketOptions);

const prepareEvent = event => doSomething(event);

// subscribe to server
ws.subscribe('message', prepareEvent);

// runtime ready for all instances

// unsubscribe from server 
ws.unsubscribe('message', prepareEvent);

// disconnect from server 


SFSocket constructor options

SFSocket supports standard (ws) and secure (wss) protocols.

SFSocket constructor new SFSocket(options: ISFSocketConfig) is expecting options of type ISFSocketConfig

For example to establish connection to ws://some.domain.com/foo?bar=1 use following code

import { SFSocket } from '@spiralscout/websockets';

const socketOptions = {
  host: 'some.domain.com',
  port: '80',
  path: 'foo',
  queryParams: { bar: '1' }

const ws = new SFSocket(socketOptions);

SFSocket channels

Supported events

SFSocket and Channel make it possible to subscribe to connected, message, closed and error events

SFSocket additionally allows to subscribe to channel_joined, channel_join_failed and channel_left events

ISFSocketEvent structure

Message Event
const MessageEvent: ISFSocketEvent = {
  context: {
    channel: 'channel', // optional
    code: 1001, // optional
  data: 'message',
  error: null,
  type: 'sfSocket:message',
Error Event
const ErrorEvent: ISFSocketEvent = {
  context: {
    channel: 'channel', // optional
    code: 1006, // optional
  data: null,
  error: 'message',
  type: 'sfSocket:error',


Working with events

const ws = new SFSocket(socketOptions);

ws.subscribe('connected', () => console.log('connected'));
ws.subscribe('error', (sfSocketEvent) => doSomething(sfSocketEvent));
ws.subscribe('message', (sfSocketEvent) => doSomething(sfSocketEvent));
ws.subscribe('closed', () => console.log('closed'));

const channel = ws.joinChannel('topic1');

channel.subscribe('connected', () => console.log('connected'));
channel.subscribe('error', (sfSocketEvent) => doSomething(sfSocketEvent));
channel.subscribe('message', (sfSocketEvent) => doSomething(sfSocketEvent));
channel.subscribe('closed', () => console.log('closed'));

Multiple channels creation

import { SFSocket } from '@spiralscout/websockets';

const socketOptions = { host: 'localhost' };

const ws = new SFSocket(socketOptions);


// create a channel and it is automatically connected to server
const channel1 = ws.joinChannel('channel_1');
const channel2 = ws.joinChannel('channel_2', true); // This one wont auto-join now

// subscribe the channel to server 
channel1.subscribe('message', (event) => doSomething(event));
channel2.subscribe('message', (event) => doSomething(event));

channel2.join(); // Start receiving messages for channel2 

// disconnect the channel from server 

// disconnect everything

Custom commands

Sending custom commands is supported via sendCommand method. join and leave commands can NOT be used as command name, payload can be any serializable data.

const cmd = 'foo'; // Any string except 'join' or 'leave'
const data = ['bar']; // Serializable data
ws.sendCommand(cmd, data);



On windows execute git config core.autocrlf false to disable automatic line ending conversion.