easy-websocket-server
An easy-to-use wrapper around the ws api for an express-like feel.
npm i easy-websocket-server
Examples
const app = ;const server = ;const easySocket = ; const send broadcastAll = easySocketcommands;const socket = ; // Listen for connectionssocket // Listen for someMethod messagessocket; // Listen for otherMethod messagessocket // Send a message to a particular client; // Broadcast to all the clients; server;
Using without express is exactly the same, except you just call:
const server = ;
Instead of this:
const server = ;
Remotes
Using the built in remoteEngine (similar to using express.Router()
);
// index.jsconst app = ;const server = ;const socket = server;const createUser = ; socket; server;
// ./remotes/create-user.jsconst remote = ; remote moduleexports = remote;
There is a more thorough example in the /test
directory.
Sending messages from the client
All must messages from the client are recomended to have this format:
If a client sends up a message without a method
property, you can assign to the message a default
method.
socket
Then you can handle the message like this:
socket
API
const easySocket = ;
easySocket(server)
const socket = ;
The server
should be a http/https server instance.
socket.onServerUpgrade(callback: (next, quit, request, socket, head) => void)
The callback
is called every time when the server upgrades a http(s) request to a websocket.
To keep the request from executing further, call quit()
, otherwise you can call next()
.
Example:
socket
socket.onConnection(callback: id => void)
The callback
is called everytime a new websocket connection is recieved. If quit
or next
are not called in socket.onServerUpgrade
, then this will happen right after onServerUpgrade
.
The id
is the random id assigned to the client.
socket.use(callback: (id, message, next) => void)
Custom middleware, just like express.use()
socket.onMessage(method: String, callback: (id, message) => void)
The callback
is called everytime a message is recieved whose method property equals method
.
socket.onClose(callback: (id, code) => void)
The callback
is called whenever a websocket connection closes. id
will be the id of the connection that closed.
remoteEngine)
socket.useRemote(method: String, remote:The remote
is the remoteEngine to use for the given method
.
Now easySocket will call the onMessage
method on the remote when the message's method property equals method
.
Here is an example.
socket.catchErrors(callback: (error, id, message) => void)
The callback
is called every time an unhandled error or promise rejection occurs in the message processing pipeline. message
and id
are the message that was being processed when the error occured, and the id of the client that sent that message.
easySocket.commands
const commands = easySocket;
commands.send(id, method, data)
The id
is the id of the client to send the message to.
The method
is the method of the message.
The data
is what is to me sent in the message.
commands.broadcastAll(method, data)
Same as commands.send
, except that it broadcasts a message to all the clients.
commands.broadcastExclude()]
The id
is the id of the client to exclude.
Otherwise, id is the same as commands.broadcastAll
.
commands.close(id?)
If and id
is given, easySocket will close only that connection, otherwise, it will close all the connections.
commands.getConnections(): Object
Returns an object of all the connections. Here is an sample of what that might look like:
easySocket.remoteEngine()
const remote = ; // Do something... moduleexports = remote;
See this example.
remote.onMessage(callback: (id, message) => void)
The callback
will be called when a message is recieved with a method that matches the method
paramater in the socket.useRemote
function.
easySocket.hasConnected(id?): Boolean
Checks if a connection exists.
The id
is the id of the connection to check. If no id is given, easySocket will check for at least one connection.
Thanks
Many thanks to @websockets/ws, the backbone of this package.