node package manager

simpl

Highly pluggable WebSockets framework

simpl

Highly pluggable WebSockets framework

Introduction

simpl is a framework over WebSockets, which allows extensions (or middleware) to be built that extend functionality with a clean and easy api.

Installation

npm install simpl

Full-featured example

Server:

var express = require('express')
var app = express.createServer()
app.use(express.static(__dirname + '/public'))
 
var simpl = require('simpl');
var server = simpl.createServer(app);
 
server.use(simpl.uid());
server.use(simpl.rpc({
  'multiply': function (a, b, callback) {
    callback(* b);
  }
}));
server.use(simpl.json());
server.use(simpl.log());
 
app.listen(8080);

Browser:

<script src="/simpl.js"></script>
<script>
  var simpl = require('simpl')
  var client = simpl.createClient()
    .use(simpl.uid())
    .use(simpl.rpc('multiply'))
    .use(simpl.json())
    .use(simpl.log())
</script> 
<input onkeyup="
  client.remote.multiply(this.value, this.value, function (result) { 
    document.getElementById('result').innerHTML = result;
  });
">
<div id="result"></div>

API

Server

server = simpl.createServer(port[, host])

Creates a webserver with a websocket server attached to it and listens on port and host.

server = simpl.createServer(app)

Attaches a websocket server to an existing express server.

Server Methods

server.use(fn || 'event', fn )

Use an EventStack middleware.

server.close()

Closes the server. In case where it's attached to a http server it closes the http server.

Server Events

ready

Emits when server is listening for connections.

connection (connection)

Emits when a client connects to the server. Callbacks a Connection object.

message (message, connection)

Emits when server receives a message.

Connection

Connection Methods

socket.send(message)

Sends a message.

socket.close()

Closes a connection.

Connection Events

message (message)

Emits when a message is received.

close

Emits when the connection closes.

Client

client = simpl.createClient(port[, host])

Creates a client and connects to a websocket server on port and host.

Client Methods

client.use(fn || 'event', fn)

Use an EventStack middleware.

client.send(message)

Sends a message to the server.

client.close()

Closes the connection.

Client Events

connect

Emits when the client connects to the server.

message (message)

Emits when the client receives a message.

Middleware

log -- Logs activity.

uid -- Provides a unique id to each outgoing message. Used by rpc.

sid -- Attach a unique id to the socket.

track -- Keep track of connected clients.

broadcast -- Adds a .broadcast method to the sockets.

json -- Send and receive objects (wrapper for JSON.parse/stringify). Used by almost all other middleware.

date -- Adds a date field to each outgoing message, and parses incoming dates to native Date objects.

rpc -- Remote Procedure Call. Used by events.

Example:

Server:

server.use(simpl.rpc({
  someMethod: function (x, y, z, callback) {
    // do stuff 
    callback(result);
  }
}));

Client:

client.use(simpl.rpc('someMethod'))
client.on('connect', function () {
  client.remote.someMethod('arg', 'arg', ..., function (result) {
    // do something with the result 
  });
})

events -- Emit events remotely.

Example:

Server:

server.use(simpl.events());
server.on('connection', function (socket) {
  socket.remote.on('some event', function (data) {
    // do something with the data 
  });
});

Client:

client.use(simpl.events());
client.on('connect', function () {
  client.remote.emit('some event', 'some data');
});

dict -- Dictionary (de)compressor.

Example:

var dict = [
  [ '{"some":"big","data":"thing"}', '^a' ],
  [ '{"some":"other","big":"data"}', '^b' ]
];
server.use(simpl.json());
server.use(simpl.dict(dict));

It will replace all occurrences of the first string in each array with the second on an outgoing message and run in reverse order for incoming messages. It can significantly reduce bandwidth in cases where the same pattern gets repeated in I/O. Use simpl.log() to find strings that are repeated often and copy & paste into the dictionary.

Licence

MIT/X11