pool.socket.io
Clearer, simpler semantics for socket.io.
What is pool.socket.io?
pool.socket.io is a layer that sits on top of socket.io, making the mechanics of communication a whole lot clearer and also a bit easier. It's tiny too – less than 50 lines of ES6 when you subtract the comments.
How does it work?
pool.socket.io is great for the server side whereas traditional socket.io is still fantastic for the client side. On the client side, you won't be managing a pool of incoming connections from the server, so we didn't really need to touch that. It'll work as it always has:
<script src="/socket.io/socket.io.js"></script><script> var connection = ; connection; connection;</script>
On the other hand, your server may be managing a lot of clients at once. As such, we've made it easier to conceptualize how to deal with that. With pool.socket.io, you essentially get access to 3 objects:
- A connection manager which allows you to describe the socket API available to each incoming connection.
- The connection itself which allows you to listen for events on that connection and send messages back through that specific connection.
- A pool object which is the traditional socket.io interface. In other words, it's what you get when you call
io(server)
.
With concerns divided in this way, we can create vastly more comprehensible socket APIs. The following example uses Express to illustrate how pool.socket.io plays nicely with other server frameworks.
// Import the express framework, the native http library,// and the `socketpool` function from pool.socket.io.;;; // Create a server using express and then pass it to `socketpool`// in order to generate our connectionManager. Traditionally,// using socket.io, you would have called `io(server)` instead of// `socketpool(server)`;const app = ;const server = app;const connectionManager = ; // We call `onConnection` and pass it a function in order to// create the API available to each incoming connection from a// client. This function is passed an reference to the connection// and also the full connection pool as arguments.connectionManager;
What can I do with it?
Here is a breakdown of the pool.socket.io API:
The Connection Manager
ConnectionManager#onConnection(apiFn)
When there is a new connection opened, runs the provided function in order to build the API for that connection. The provided function will be handed references to both the single connection as well as the overall pool.
Arguments
apiFn
: Function - Describes the API to be used for a given connection.
Returns
The result of creating a socket.io connection
handler.
ConnectionManager#emit(event, message)
Sends a message to all connections in the pool.
Arguments
event
: String - The name of the event to send.message
: Any - The message associated with the event.
Returns
The result of calling Socket.io's emit
method.
ConnectionManager#emitTo(id, event, message)
Sends a message to a single connection in the pool by ID.
Arguments
id
: String - The ID of the connection to send a message to.event
: String - The name of the event to send.message
: Any - The message associated with the event.
Returns
The result of calling Socket.io's emit
method.
The Connection Object
Connection#on(event, fn)
Creates an event handler for a named event. The handler will be called with a reference to the payload coming in through the connection.
Arguments
event
: String - The name of the incoming event.fn
: Function - The procedure to be executed when the event comes through.
Returns
The result of calling Socket.io's socket.on
method.
Connection#emit(event, message)
Sends a message only through this connection.
Arguments
event
: String - The name of the event to send.message
: Any - The message associated with the event.
Returns
The result of calling Socket.io's emit
method.
The Pool Object
The pool object is the direct result of calling socket.io's io(server)
. As
such, its methods are identical to those described in socket.io's
documentation and won't be repeated here. Suffice it to say, you can use this
object's emit
method to send an event and message to all connections in the
pool at once.