README

JavaScript WebSockets client library with channel support.

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

Installation

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'});
    </script>

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

https://cdn.jsdelivr.net/gh/spiral/websockets/build/socket.js

API

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
SFSocket.ready();

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

// disconnect from server 
ws.disconnect();

SFSocket

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',
};

Samples

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);

SFSocket.ready();

// 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 
channel1.leave();
channel2.leave();

// disconnect everything
ws.disconnect()

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);

Development

Prerequisites

• nodejs 10.16.3+
• yarn 1.19.1+

Windows

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