express-oi

This node.js library seeks to combine express and socket.io into one cohesive library. This project started as a fork of express.oi. This README is a fork too.

Getting started

First install:

npm install express-oi

Then, simply replace this line of code

require('express')

with this line of code

require('express-oi')

Your app should run just the same as before! express-oi is designed to be a superset of express and socket.io.

Usage

Setting up the app

var express = require('express-oi');

var app = express();

app.set('env',process.env.NODE_ENV || 'development');

// Here we create http.Server instance and connect socket.io to our app
// Socket.io DEBUG disabled if app env is not "development"
app.http().io();
// or if socket.io DEBUG no longer needed in app development env
// app.http().io({debug:false});

// Pass in your express-session configuration
// Documentation here: https://github.com/expressjs/session#sessionoptions
// Just config options, dep. "express-session" are included in express-oi
// app.io.session() includes session both to app and app.io
app.io.session({
  secret: 'express-oi makes me happy',
  resave: false,
  saveUninitialized: true
});

app.listen(3000);

express-oi routes

var messages = [];

app.io.route('messages', {
  // socket.io event: messages:list
  list: function(req, res) {
    res.json(messages);
  },

  // socket.io event: messages:add
  add: function(req, res) {
    // data is accessible from req.data (just like req.body, req.query)
    var data = req.data;

    // Or use req.param(key)
    var message = {
      text: req.param('text')
    };

    messages.push(message);

    res.status(200).json(message);
  },

  // socket.io event: messages:remove
  remove: function(req, res) {
    // Or just send a status code
    res.sendStatus(403);
  }
});

Forwarding express routes

Regular express routes can be forwarded to express-oi routes

app.route('/messages')
  .get(function(req, res) {
    // Forward GET /messages to messages:list
    req.io.route('messages:list');
  })
  .post(function(req, res) {
    // Forward POST /messages to messages:add
    req.io.route('messages:add');
  })
  .delete(function(req, res) {
    // Forward DELETE /messages to messages:remove
    req.io.route('messages:remove');
  });

More API Examples

// express-oi routes
app.io.route('examples', {
  example: function(req, res) {

    // Respond to current request
    res.status(200)
       .json({
         message: 'This is my response'
       });

    // You can check if current request is a websocket
    if (req.isSocket) {

      // Emit event to current socket
      req.socket.emit('message', 'this is a test');

      // Emit event to all clients except sender
      req.socket.broadcast.emit('message', 'this is a test');

      // sending to all clients in 'game' room(channel) except sender
      req.socket.broadcast.to('game').emit('message', 'nice game');

      // sending to individual socketid, socketid is like a room
      req.socket.broadcast.to(socketId).emit('message', 'for your eyes only');

    }

    // sending to all clients, including sender
    app.io.emit('message', 'this is a test');

    // sending to all clients in 'game' room/channel, including sender
    app.io.in('game').emit('message', 'cool game');
  }
});

Changelog

0.0.21 - Enable socket.io DEBUG for app development env 0.0.20 - Fix session in io.route middleware 0.0.19 and earlier - See express.oi

Roadmap

sticky-session integration or emulating it.