Spaced.io - merging socket.io and express

Spaced.io extends socket.IO to make it much more natual when used with Express sessions.

Spaced.io controls handlers by session, and allows listeners to be assigned prior to socket connection.

Spaced.io uses socket.io version 0.9.16

Install

$ npm install spaced.io

Use

//Express must be set up to use sessions. This example will use the Connect cookie session middleware and memoryStore.

//Express session & server stuff. var express = require('express'); var app = express(); var server = require('http').createServer(app);

var sessionStore = new express.session.MemoryStore();

app.use(express.cookieParser('s0meS3cReT')); app.use(express.session({store: sessionStore});

//load Spaced.io and configure it to use the server and sessionStore

var sp = require("spaced.io")(server,sessionStore);

//make sure the app uses the Spaced.io session manager. The session manager encodes the session ID. //The spaced.io saves the encoded session id to the session as socketToken (req.session.socketToken)

app.use(sp.sessionManager);

//the ground work is done. Now you can set up listeners in express routes.

app.get('/test',function(req,res){ sp.uonce(req.sessionID,'foo',function(){ //this will be the current socket. var socket = this;

	socket.emit('bar','output text');
});

res.render('test',{
	// You have to pass the token to the rendered page
	socketToken: req.session.socketToken
});

}

Template/rendered page

Include socket.io as normal

Connect to socket IO using these connect parameters. Filling in the socket token however your template engine requires.

Listeners

sp.on(sessionID,event,listenerFunction,optionalCallbackFunction)

sessionID - string. the session ID. req.sessionID
event - string. the name of the event the listener is for.
listenerFunction - function.  what you want the listener to do. this used in the function will be the current socket.
optionalCallbackFunction - function. this function is called when the listener is applied to a socket, not when it is actually triggered by an event.

.on sets up an event listener for the socket. Note: This can create multiple listeners for the same event, as listeners are transfered between sockets belonging to the same session.

sp.once(sessionID,event,listenerFunction,optionalCallbackFunction)

sessionID - string. the session ID. req.sessionID
event - string. the name of the event the listener is for.
listenerFunction - function.  what you want the listener to do. this used in the function will be the current socket.
optionalCallbackFunction - function. this function is called when the listener is applied to a socket, not when it is actually triggered by an event.

.once sets up an event listener for the socket once.

sp.uon(sessionID,event,listenerFunction,optionalCallbackFunction)

sessionID - string. the session ID. req.sessionID
event - string. the name of the event the listener is for.
listenerFunction - function.  what you want the listener to do. this used in the function will be the current socket.
optionalCallbackFunction - function. this function is called when the listener is applied to a socket, not when it is actually triggered by an event.

.uon sets up an event listner for the socket. The event must be unique. It will not create another event listener if one with the same name already exists.

sp.uonce(sessionID,event,listenerFunction,optionalCallbackFunction)

sessionID - string. the session ID. req.sessionID
event - string. the name of the event the listener is for.
listenerFunction - function.  what you want the listener to do. this used in the function will be the current socket.
optionalCallbackFunction - function. this function is called when the listener is applied to a socket, not when it is actually triggered by an event.

.uonce sets up a listener for the socket one time. The event must be unique. It will not create another event listener if one with the same name already exists.

sp.oncon(sessionID,listenerFunction,optionalCallbackFunction)

sessionID - string. the session ID. req.sessionID
listenerFunction - function. what you want the listener to do. this used in the function will be the current socket.
optionalCallbackFunction - function. this function is called when the listener is applied to a socket, not when it is actually triggered by an event.

.oncon sets up a listener for the socket that fires on connection. This will trigger every time a session socket connects, like on a page refresh. Like .on, this can easily cause duplicate listeners.

sp.oncecon(sessionID,listenerFunction,optionalCallbackFunction)

sessionID - string. the session ID. req.sessionID
listenerFunction - function.  what you want the listener to do. this used in the function will be the current socket.
optionalCallbackFunction - function. this function is called when the listener is applied to a socket, not when it is actually triggered by an event.

.oncecon sets up a listener that fires on socket connection. This event will only fire once. 

sp.emit(sessionID,event,data,optionalCallbackFunction)

sessionID - string. The session ID. req.sessionID
event - string. The event being emitted
data - string, array, boolian, integer, float, or object. The data that is being emitted
optionalCallbackFunction - function. this function is called when the listener is applied to a socket, not when it is actually triggered by an event.

.emit provides the same basic function as the native socket.io emit function.

sp.broadcast(sessionID,event,data,optionalCallbackFunction)

sessionID - string. The session ID. req.sessionID
event - string. The event being emitted
data - string, array, boolian, integer, float, or object. The data that is being emitted
optionalCallbackFunction - function. this function is called when the listener is applied to a socket, not when it is actually triggered by an event.

.broadcast provides the same function as the native socket.io broadcast function. 

sp.off(sessionID,event,optionalCallbackFunction)

sessionID - string. The session ID. req.sessionID
event - string. The event being emitted
optionalCallbackFunction - function. this function is called when the listener is applied to a socket, not when it is actually triggered by an event.

.off removes all listeners for event. If there are multiple listeners for an event, all are discarded.

Rooms

Spaced.io supports grouping sessions into "rooms." This is an express-friendly implementation of socket.io namespaces. **Known Bugs: Room listeners and regular session listeners with the same name. Don't do it. You'll have a bad time.

sp.room.join(sessionID,roomName,optionalCallbackFunction)

sessionID - string. the session ID. req.sessionID
roomName - string. the name of the room the session should be associated with.
optionalCallbackFunction - function. This is called after the room is joined.

.room.join associates the session socket with the room. All existing listeners belonging to the room are transfered to the socket.

sp.room.once(roomName,event,listenerFunction,optionalCallbackFunction)

roomName - string. the name of the room.
event - string. The name of the event the listener is for.
listenerFunction - function.  what you want the listener to do. this used in the function will be the current socket.
optionalCallbackFunction - function. this function is called when the listener is applied to a socket, not when it is actually triggered by an event.

.room.once sets up a one-time listener for the room

sp.room.on(roomName,event,listenerFunction,optionalCallbackFunction)

roomName - string. the name of the room.
event - string. The name of the event the listener is for.
listenerFunction - function.  what you want the listener to do. this used in the function will be the current socket.
optionalCallbackFunction - function. this function is called when the listener is applied to a socket, not when it is actually triggered by an event.

.room.on sets up a listener for the room. 

sp.room.uon(roomName,event,listenerFunction,optionalCallbackFunction)

roomName - string. the name of the room.
event - string. The name of the event the listener is for.
listenerFunction - function.  what you want the listener to do. this used in the function will be the current socket.
optionalCallbackFunction - function. this function is called when the listener is applied to a socket, not when it is actually triggered by an event.

.room.uon sets up a unique listener for the room

sp.room.uonce(roomName,event,listenerFunction,optionalCallbackFunction)

roomName - string. the name of the room.
event - string. The name of the event the listener is for.
listenerFunction - function.  what you want the listener to do. this used in the function will be the current socket.
optionalCallbackFunction - function. this function is called when the listener is applied to a socket, not when it is actually triggered by an event.

.room.uonce sets up a unique one-time listener for the room.

sp.room.emit(roomName,event,data,optionalCallbackFunction)

roomName - string. the name of the room.
event - string. The name of the event the listener is for.
data - string, array, boolian, integer, float, or object. The data that is being emitted
optionalCallbackFunction - function. this function is called when the listener is applied to a socket, not when it is actually triggered by an event.

.room.emit sends data to all sockets in the room as event.

sp.room.broadcast(originatingSessionId,roomName,event,data,optionalCallbackFunction)

roomName - string. the name of the room.
event - string. The name of the event the listener is for.
data - string, array, boolian, integer, float, or object. The data that is being emitted
optionalCallbackFunction - function. this function is called when the listener is applied to a socket, not when it is actually triggered by an event.

sp.room.off(roomName,event,optionalCallbackFunction)

roomName - string. the name of the room.
event - string. The name of the event the listener is for.
optionalCallbackFunction - function. this function is called when the listener is removed.

.room.off removes an event listener from the room

sp.room.leave(sessionID,roomName,optionalCallbackFunction)

sessionID - string. the session ID. req.sessionID
roomName - string. the name of the room the session should no longer be associated with.
optionalCallbackFunction - function. this function is called when the sessionID is no longer "in" the room.

.room.leave uh.. leaves the room.