README
Socket Helper
Socket.io helper utilities with events inspired by flux standard actions. This package is targeted towards socket server applications and not client applications.
Why Socket Helper?
SocketIO provides a large set of tools to run websocket servers with ease. What Socket Helper provides is a wrapper for SocketIO with connection
, new connection
, disconnection
and basic message
events preconfigured.
Installation
The package is available in the npm registry. To install, use npm
or yarn
.
$ npm install --save socket-helper
$ yarn add socket-helper
Usage
Once installed, make sure that socket.io
is also installed as this package does not come with it. This will not work without socket.io
.
Basic Usage
To use Socket Helper, pass io
from socket.io
into it.
var io = require('socket.io')(http);
var socketHelper = require('socket-helper');
socketHelper(io);
Custom Listeners
Socket Helper comes with connection and disconnection event listeners by default. We can add our own listeners in addition to the existing ones.
function onConnection(socket, payload) {
console.log('Connected', payload);
}
function onDisconnection(socket, payload) {
console.log('Disconnected', payload);
}
socketHelper(io, onConnection, onDisconnection);
Configs and Overrides
We can customize the default configs used by Socket Helper by providing a custom config.
var config = {
clients: [],
overrides: {
message: true,
connection: true,
disconnection: true,
newConnection: true
}
};
socketHelper(io, onConnection, onDisconnection, config);
clients
The clients key stores the ids of currently active connections.
overrides
Overrides define whether in-built event handlers for message
, connection
, disconnection
and newConnection
are disabled or not.
API
When a new connection is established, the socket server emits two events, one for the new connection and another for all other connected clients.
The data send with the socket event will be FSA compliant, i.e., will have the following format:
{
type: 'TYPE',
payload: {
}
}
The socket event will always emit events of name message
. The data with the event will carry the information about how the event should be handled, similar to Flux actions.
CONNECTION
Event | Type | Payload |
---|---|---|
message |
CONNECTION |
{ clientID, clients } |
message |
NEW_CONNECTION |
{ clientID, clients } |
DISCONNECTION
Event | Type | Payload |
---|---|---|
message |
DISCONNECTION |
{ clientID, clients } |
MESSAGE
The server is configured by default to listen for and respond to events with name message
. So when a client emits a message
event, the server responds to it by broadcasting the message to all the clients including the sender.
Event | Type | Payload |
---|---|---|
message |
MESSAGE |
{clientID, clients, event: data.type, data: data.payload} |
The server expects client to also send the message
event with data in FSA format. The data sent by client, will be mapped as event: type
and data: payload
when it is sent to all connected clients.
Contributing
To contribute, follow one of the two options:
Open an Issue
Open an issue detailing:
- What the issue is
- Steps to reproduce
- Possible solutions
Note: These details are recommended but are entirely optional.
Send a Pull Request
Fork this project and send a pull request to the
master
branch.
LICENSE
MIT