<commit_before>[![Build Status](https://travis-ci.org/turbonetix/socket.io-events.svg?branch=master)](https://travis-ci.org/turbonetix/socket.io-events)
[![NPM version](https://badge.fury.io/js/socket.io-events.svg)](http://badge.fury.io/js/socket.io-events)
[![David DM](https://david-dm.org/turbonetix/socket.io-events.png)](https://david-dm.org/turbonetix/socket.io-events.png)

Power your [socket.io](https://github.com/Automattic/socket.io "socket.io") apps with [express](https://github.com/visionmedia/express "express") like `event` routing.

`$ npm install socket.io-events`

```javascript
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);
```

# Features

* 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.
* Support for "wildcard" (*) and Regular Expression matching.

# Examples

The method `on` is an alias to `use`.

```javascript
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.
  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* handling a message and letting [socket.io](https://github.com/Automattic/socket.io "socket.io")
handle things *business as usual*.

```javascript

var router = require('socket.io-events')();
router.on(function (socket, args, next) {
  //do something!
  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.

```javascript
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);
});<commit_msg>doc [ci skip]<commit_after>[![Build Status](https://travis-ci.org/turbonetix/socket.io-events.svg?branch=master)](https://travis-ci.org/turbonetix/socket.io-events)
[![NPM version](https://badge.fury.io/js/socket.io-events.svg)](http://badge.fury.io/js/socket.io-events)
[![David DM](https://david-dm.org/turbonetix/socket.io-events.png)](https://david-dm.org/turbonetix/socket.io-events.png)

Power your [socket.io](https://github.com/Automattic/socket.io "socket.io") apps with [express](https://github.com/visionmedia/express "express") like `event` routing.

`$ npm install socket.io-events`

```javascript
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);
```

# Features

* 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.
* Support for "wildcard" (*) and Regular Expression matching.
* Event consumption and propagation.

# Examples

The method `on` is an alias to `use`.

```javascript
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](https://github.com/Automattic/socket.io "socket.io")
handle things *business as usual*.

```javascript

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.

```javascript
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);
});
{'fraction_non_alphanumeric': 0.18610381077529567, 'fraction_numerical': 0.003942181340341655, 'mean_word_length': 4.412444444444445, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 16, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4241097', 'n_tokens_mistral': 2041, 'n_tokens_neox': 1963, 'n_words': 556}