Power your socket.io apps with express like event routing.
$ npm install socket.io-events
var io = require('socket.io')(3000);
var router = require('socket.io-events')();
router.on('*', function (sock, args, next) {
var name = args.shift(), msg = args.shift();
sock.emit('received event', name, msg);
});
io.use(router);- Easy to use interface for manipulating socket.io events.
- Express-like routing capabilties for socket.io events.
- Gives you more control over how events are handled.
- Attach
Routerinstances to otherRouterinstances. - Support for "wildcard" (*) and Regular Expression matching.
- Event consumption and propagation.
The method on is an alias to use.
var assert = require('assert');
var router = require('socket.io-events')();
// handles all events
router.on(function (socket, args, next) {
next();
});
// handles all events too
router.on('*', function (socket, args, next) {
next();
});
// handles events matching 'some*'
router.on('some*', function (socket, args, next) {
next();
});
// handles events matching '*events'
router.on('*event', function (socket, args, next) {
next();
});
// handle events matching /^\w+/
router.on(/^\w+/, function (socket, args, next) {
next();
});
// handles all events
router.on(function (socket, args) {
//emits back to the client, and ends the chain.
//Think `res.end()` for express.
//calling `emit()` consumes the event which means no other handlers
//get a chance to process it.
socket.emit(args.shift(), args);
});
router.on(function (socket, args) {
//this wont fire because socket.emit()
//has been called which is like `res.end()` in express.
});
var io = require('socket.io')(3000);
io.use(router);Here is an example of not consuming the event and letting socket.io handle things business as usual.
var router = require('socket.io-events')();
router.on(function (socket, args, next) {
//do something, but don't consume it.
next();
});
var io = require('socket.io')(3000);
io.use(router);
io.on('connection', function (socket) {
socket.on('echo', function (data) {
socket.emit('echo', data);
});
});Here is an example of calling next() with an Error object, and having an error handler capture it.
var router = require('socket.io-events')();
router.on('some event', function (socket, args, next) {
next(new Error('something wrong');
});
router.on(function (err, socket, args, next) {
socket.emit('error', err);
});You can recover from an error too.
var router = require('socket.io-events')();
router.on('some event', function (socket, args, next) {
next(new Error('something wrong');
});
router.on(function (err, socket, args, next) {
//I handled the error so continue to the next middleware.
next();
});
router.on(function (socket, args, next) {
//I recovered from the error.
next();
});
io.use(router);You can even attach a Router' intance to another Router` intance.
var Router = require('socket.io-events')();
var a = Router();
a.use(function (sock, args, next) { next() });
var b = Router();
b.use(function (sock, args, next) { next() });
a.use(b)
var io = require('socket.io')(3000);
io.use(a);Get the Router class.
var Router = require('socket.io-events');The use and on methods are equivalent. They also can be chained.
var router = Router()
.use(function (sock, args, next) { })
.use(function (sock, args, next) { })
.use(function (sock, args, next) { });Make a Router instance
var router = Router();Attach a function to the router.
router.use(function (sock, args, next) {
//do something!
next();
});You can pass in multiple functions.
var a = function (sock, args, next) { next() };
var b = function (sock, args, next) { next() };
var c = function (sock, args, next) { next() };
router.use(a,b,c); You can pass in a function that accepts an Error object.
router.use(function (err, sock, args, next) {
console.error(err);
//calling next(err) will invoke the next error handler.
//to resume operation just call next()
next(err);
});Bind the function to the event.
router.use('chat', function (sock, args, next) {
assert.equal(args[0], 'chat');
args[1] = args[1].length > 128 ? args[1].slice(0, 125) + '...' : args[1];
next();
});You can also pass in multiple functions for handling the event.
var chop = function (sock, args, next) { next() };
var clean = function (sock, args, next) { next() };
var pretty = function (sock, args, next) { next() };
router.use('chat', chop, clean, pretty);Bind the function using a RegExp pattern to match the event.
router.use(/\w+/, function (sock, args, next) {
assert.equal(args[0], 'chat');
args[1] = args[1].length > 128 ? args[1].slice(0, 125) + '...' : args[1];
next();
});You can also pass in multiple functions for handling the event.
var chop = function (sock, args, next) { next() };
var clean = function (sock, args, next) { next() };
var pretty = function (sock, args, next) { next() };
router.use(/\w+/, chop, clean, pretty);You can attach another Router instance to your Router instance.
var another = Router();
another.use(function (sock, args, next) { next(); });
router.use(another);Attach multiple routers in a single call.
var foo = Router();
foo.use(function (sock, args, next) { next(); });
var bar = Router();
bar.use(function (sock, args, next) { next(); });
var baz = Router();
baz.use(function (sock, args, next) { next(); });
router.use(foo, bar, baz);Just like attaching a function to the router given the event. You can attach Router
instance as well to the event.
var foo = Router();
foo.use(function (sock, args, next) { next(); });
router.use('some event', foo);Attach multiple routers in a single call to the event too.
var foo = Router();
foo.use(function (sock, args, next) { next(); });
var bar = Router();
bar.use(function (sock, args, next) { next(); });
var baz = Router();
baz.use(function (sock, args, next) { next(); });
router.use('some event', foo, bar, baz);Attach an Array of Fuction's or Router instances, or an Array or Arrays .
var middleware = [
function (sock, args, next) { next(); },
[
function (sock, args, next) { next(); },
Router().use(function (sock, args, next) { next(); }),
function (sock, args, next) { next(); },
],
Router().use(function (sock, args, next) { next(); })
];
var errHandler = function (err, sock, args, next) { next(err); }
router.use(middleware, errHandler);Attach everything to an event.
var middleware = [
function (sock, args, next) { next(); },
[
function (sock, args, next) { next(); },
Router().use(function (sock, args, next) { next(); }),
function (sock, args, next) { next(); },
],
Router().use(function (sock, args, next) { next(); })
];
var errHandler = function (err, sock, args, next) { next(err); }
router.use('only this event', middleware, errHandler);This is an alias to to the use method. It does the same thing.
router.on(function (sock, args, next) { next() });Install node.js (See download and install instructions here: https://nodejs.org/).
Clone this repository
> git clone [email protected]:turbonetix/socket.io-events.git
cd into the directory and install the dependencies
> cd socket.io-eventst
> npm install && npm shrinkwrap --dev
Install coffee-script
> npm install coffee-script -g
Tests are run using grunt. You must first globally install the grunt-cli with npm.
> sudo npm install -g grunt-cli
To run the tests, just run grunt
> grunt spec