spiral / websocket-client
Websocket JS Client
Installs: 3
Dependents: 0
Suggesters: 0
Security: 0
Stars: 7
Watchers: 12
Forks: 0
Language:TypeScript
This package is auto-updated.
Last update: 2024-10-20 03:47:07 UTC
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
Windows
On windows execute git config core.autocrlf false
to disable automatic line ending conversion.