Merge pull request #3 from turbonetix/modify_how_router_attaches

READY: Modify how router attaches

Author: NathanGRomano

README.md

@@ -21,9 +21,12 @@ 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 `Router` instances to other `Router` instances.
 
 # Examples
 
+The method `on` is an alias to `use`.
+
 ```javascript
 var assert = require('assert');
 var router = require('socket.io-events')();
@@ -111,6 +114,206 @@ router.on(function (socket, args, next) {
 io.use(router);
 ```
 
+You can even attach a `Router' intance to another `Router` intance.
+
+```javascript
+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);
+```
+
+# API
+
+## Router
+
+Get the `Router` class.
+
+```javascript
+var Router = require('socket.io-events');
+```
+
+The `use` and `on` methods are equivalent.  They also can be chained.
+
+```javascript
+var router = Router()
+  .use(function (sock, args, next) { })
+  .use(function (sock, args, next) { })
+  .use(function (sock, args, next) { });
+```
+
+### Router#()
+
+Make a `Router` instance
+
+```javascript
+var router = Router();
+```
+
+### Router#use(fn:Function, ...)
+
+Attach a `function` to the router.
+
+```javascript
+router.use(function (sock, args, next) {
+  //do something!
+  next();
+});
+```
+
+You can pass in multiple `function`s.
+
+```javascript
+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.
+
+```javascript
+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);
+});
+```
+
+### Router#use(event:String, fn:Function, ...)
+
+Bind the `function` to the `event`.
+
+```javascript
+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 `function`s for handling the `event`.
+
+```javascript
+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);
+```
+
+### Router#use(router:Router, ...)
+
+You can attach another `Router` instance to your `Router` instance.
+
+```javascript
+var another = Router();
+another.use(function (sock, args, next) { next(); });
+
+router.use(another);
+```
+
+Attach multiple routers in a single call.
+
+```javascript
+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);
+```
+
+### Router#use(name:String, router:Router, ...)
+
+Just like attaching a `function` to the router given the `event`.  You can attach `Router`
+instance as well to the `event`.
+
+```javascript
+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.
+
+```javascript
+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);
+```
+
+### Router#use(fns:Array, ...)
+
+Attach an `Array` of `Fuction`'s or `Router` instances, or an `Array` or `Array`s .
+
+```javascript
+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);
+```
+
+### Router#use(name:String, fns:Array, ...)
+
+Attach everything to an event.
+
+```javascript
+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);
+```
+
+### Router#on(...)
+
+This is an alias to to the `use` method.  It does the same thing.
+
+```javascript
+router.on(function (sock, args, next) { next() });
+```
+
 # Installation and Environment Setup
 
 Install node.js (See download and install instructions here: http://nodejs.org/).

examples/multiple.js

@@ -0,0 +1,55 @@
+var ok = require('assert').equal;
+var Router = require('./..');
+
+var a = Router();
+a.on('say', function (sock, args, next) {
+  args.push('World');
+  next();
+});
+
+var b = Router();
+b.use('say', function (sock, args, next) { 
+  args.push('Good'); 
+  next();
+});
+
+var c = Router();
+c.use('say', function (sock, args, next) { 
+  args.push('Bye');
+  next();
+});
+
+var d = Router();
+d.use(function (sock, args, next) { 
+  args.push('!!!');
+  next();
+});
+
+a.use(b)
+b.use(c);
+c.use(d);
+
+var io = require('socket.io')(3000);
+io.use(a);
+io.on('connection', function (sock) {
+  sock.on('say', function (hello, world, good, bye, exclamation) {
+    sock.emit('say', hello, world, good, bye, exclamation);
+  });
+});
+
+setTimeout(function () {
+  var sock = require('socket.io-client').connect('ws://localhost:3000');
+  sock.on('connect', function () {
+    sock.emit('say', 'Hello');
+  });
+  sock.on('say', function (hello, world, good, bye, exclamation) {
+    ok(hello, 'Hello');
+    ok(world, 'World');
+    ok(good, 'Good');
+    ok(bye, 'Bye');
+    ok(exclamation, '!!!');
+    console.log('we good');
+    process.exit(0);
+  });
+
+}, 1000);

examples/run.sh

@@ -5,3 +5,5 @@ echo 'testing bau'
 node bau
 echo 'testing recover'
 node recover
+echo 'testing routers attached to routers'
+node multiple