spiral/websocket-client

This package is not installable via Composer 1.x, please make sure you upgrade to Composer 2+. Read more about our Composer 1.x deprecation policy.

Websocket JS Client

Installs: 0

Dependents: 0

Suggesters: 0

Security: 0

Stars: 4

Watchers: 11

Forks: 0

Open Issues: 0

Language:TypeScript

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

README

JavaScript WebSockets client library with channel support.

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
Properties
static instances SFSocket[]
Array of all existing sockets
static isReady boolean
false before ready() is called. If is true any new SFSocket will connect upon creation.
Methods
static ready() Marks sockets as ready and launches all connections.
Use if you need to make all sockets to connect automatically on creation
constructor(options: ISFSocketConfig) Create websocket connection
options: ISFSocketConfig - connection options
joinChannel(channel, dontJoin) Creates a named channel and joins it
channel: string name of channel to join. Should NOT be one of system ones: @join, #join, @leave, #leave
dontJoin: boolean default false if true, channel is created, registered inside instance but not joined automatically. Call join method to join later.
return value: Channel returns channel object
getChannel(channel) Gets a previously created named channel
return value: Channel returns channel object
leaveChannel(channel) Removes a named channel and leaves it
channel: string name of channel to join. Should NOT be one of system ones @join, #join, @leave, #leave
return value: Channel returns channel object
subscribe(event, callback, channel) Subscribes to specific event
event: string one of valid event codes. See table below for possible events and their payload
callback: (payload) => void callback to call. Type of payload depends on event type
channel: string (optional) Channel name to follow. If none, subscribes for all. Note that doesn't automatically join channel, just adds listener to existing one.
unsubscribe(event, callback, channel) Unsubscribes from specific event
event: string one of valid event codes. See table below for possible events and their payload
callback: (payload) => void callback to call. Type of payload depends on event type
channel: string (optional) Channel name to unfollow. If none, unsubscribes from all channels. Note that doesn't automatically remove channel, just removes listener from existing one.

SFSocket constructor options

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

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

ISFSocketConfig
host string
Host websocket should connect to
port string or number
(optional) Port websocket should connect to
Default: 80 or 443 if useTSL = true
useTSL boolean
(optional) Use TSL wss instead of regular ws protocol
Default: false
path string
(optional) Server path part
Default: empty
queryParams object of {[key: string]: string} type
(optional) Query params map to append to path
Default: empty
unavailableTimeout number
(optional) A timeout which is considered to be large enough to stop retrying reconnects if server response takes longer
Default: 10000

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

Channel
Properties
status string Channel status, can be closed, joinin, joined, leaving or error
name string Channel name
Methods
constructor(name: string, socket: SFSocket) Creates a channel based on specific SFSocket
name: string - channel name. Can NOT be @join, #join, @leave, #leave
join() Enables channel and sends join command once connection is working
leave() Disables channel and sends leave command if connection is working
subscribe(event, callback) Subscribes to specific event
event: string one of valid event codes. See table below for possible events and their payload
callback: (payload) => void callback to call. Type of payload depends on event type
unsubscribe(event, callback) Unsubscribes from specific event
event: string one of valid event codes. See table below for possible events and their payload
callback: (payload) => void callback to call. Type of payload depends on event type
connect() Starts connection. This method is automatically called after SFSocket.ready() for all existing and new instances
disconnect() Drops connection

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

Events
message ISFSocketEvent
Generic event of message from specific channel or broadcasted Payload depends on channel server implementation
error ISFSocketEvent
Event of error happened in specific channel or broadcasted Payload would contain error details
closed ISFSocketEvent
Connection was closed due some error. Socket might automatically reconnect after that.
channel_joined string[]
Indicates server confirming joining specific channels
channel_left string[]
Indicates server confirming leaving specific channels
channel_join_failed string[]
Indicates server denies joining specific channels

ISFSocketEvent structure

ISFSocketEvent
type string
sfSocket:message, sfSocket:closed or sfSocket:error depending on event tracked.
data any
Any serializable payload depending on implementation that refers to successful flow
error string
Error message
context object
Object with event context details
context.code number
Error code if relevant
context.channel string
Channel name if relevant
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
Windows

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