Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kripod/wsx
Programmatically extensible lightweight WebSocket implementation in JavaScript.
https://github.com/kripod/wsx
Last synced: 7 days ago
JSON representation
Programmatically extensible lightweight WebSocket implementation in JavaScript.
- Host: GitHub
- URL: https://github.com/kripod/wsx
- Owner: kripod
- License: mit
- Created: 2016-08-03T10:14:16.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2016-08-22T10:57:04.000Z (about 8 years ago)
- Last Synced: 2024-05-02T05:05:10.179Z (6 months ago)
- Language: JavaScript
- Homepage:
- Size: 1.17 MB
- Stars: 13
- Watchers: 3
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# wsx
Programmatically extensible lightweight WebSocket implementation in JavaScript.
[](https://npmjs.com/package/wsx)
[](https://travis-ci.org/kripod/wsx)
[](https://codecov.io/gh/kripod/wsx)
[](https://david-dm.org/kripod/wsx)
[](https://gitter.im/kripod/wsx)
## Introduction
WSX provides a lightweight abstraction layer over WebSockets, greatly increasing
developer productivity while aiming to provide blazing fast transmission rates
over the network without sacrificing stability and scalability.
## Getting started
Please refer to the
[API reference](https://kripod.github.io/wsx) and the
[directory of examples](https://github.com/kripod/wsx/tree/master/examples) to
learn more about leveraging the possibilities within the library.
### Initializing communication channels
```js
import Client from 'wsx/client';
import Server from 'wsx/server';
const wsxServer = new Server({ port: 3000 });
const wsxClient = new Client('ws://localhost:3000');
```
_**Pro tip**: WSX tries to detect its environment automatically. This means that
`import Server from 'wsx';` is a valid statement for Node environments, and
`import Client from 'wsx';` is a valid statement for browser environments._
### Sending and receiving messages
WSX features an event-based messaging system with a syntax familiar for
[Socket.IO](http://socket.io) users. Messages are serialized and deserialized
automatically.
#### Example
```js
// Register an event handler on the server side for message type `echo`
wsxServer.on('message:echo', (socket, payload) => {
socket.send('echo', payload);
});
// Register an event handler on the client side for message type `echo`
wsxClient.on('message:echo', (payload) => {
console.log('Received message with type `echo` and the following payload:');
console.log(payload);
});
// Transmit a message with type `echo` to the server
wsxClient.send('echo', 'Hello, World!');
```
#### Multiple recipients
You can broadcast messages or send them to socket groups.
```js
wsxServer.on('message', (socket, data) => {
// Forward the message to everyone else except for the socket that sent it
socket.broadcast(data);
// Forward the message to everyone, including the socket that sent it
wsxServer.sockets.send(data);
// Forward the message to a specific group of sockets
wsxServer.getSocketGroup('socketGroupId').send(data);
});
```
### Socket groups
Socket groups can be established on the server to handle multiple sockets with
ease. Their underlying `Set` of sockets is managed automatically, meaning that
you don't need to care about removing disconnected sockets.
```js
wsxServer.on('message:join', (socket, groupId) => {
// Inexistent socket groups are created automatically
wsxServer.getSocketGroup(groupId).add(socket);
socket.broadcast('join', groupId);
});
wsxServer.on('message:leave', (socket, groupId) => {
// Socket groups with zero sockets are destroyed automatically
wsxServer.getSocketGroup(groupId).remove(socket);
socket.broadcast('leave', groupId);
});
wsxClient.send('join', 'developers');
```
### Error handling
Message transmission errors are handled asynchronously:
```js
wsxServer.on('error', (error, socket) => {
// Server error
if (socket) {
// The error was caused by a socket
}
});
wsxClient.on('error', () => {
// Client error
});
```
### Plugins
Plugins can be used to extend the capability of WSX.
```js
const wsxServerWithPlugins = new Server({
port: 3001,
plugins: [
(wsxServer) => {
// Modify the server instance
},
],
});
const wsxClientWithPlugins = new Client('ws://localhost:3001', {
plugins: [
(wsxClient) => {
// Modify the client instance
},
],
});
```