Manage events, callbacks and rooms over a socket connection
npm install jandalAn event handler for socket interfaces. It was built for use with
SockJS, but can be used with any
socket interface, such as node streams.
It has a similar feature set to Socket.io, including rooms
and broadcasting.
Jandal has a maximum of three arguments per event. This restriction vastly
improves performance in most browsers and in nodejs.
This may sound harsh, but you probably don't need to use more than three args
anyway. You can always store extra args in an array or object.
There is also the deprecated
multi-args branch
- but it is not kept up to date.
Add it to your project with npm install --save jandal.
``javascript
var http, Jandal, sockjs, server, conn;
http = require('http');
Jandal = require('jandal');
sockjs = require('sockjs');
// standard sockjs stuff
server = http.createServer();
conn = sockjs.createServer();
conn.installHandlers(server, { prefix: '/socket' });
server.listen(8080);
// Listen for new connections
conn.on('connection', function (socket) {
var jandal;
// wrap the socket in a Jandal
jandal = new Jandal(socket, 'stream');
// listening for the 'log' event
jandal.on('log', function (text) {
console.log('log: ' + text);
});
// listening for an event with a callback
jandal.on('echo', function (text, callback) {
callback(text);
});
// send an event to the client
jandal.emit('weclome', {
id: socket.id,
time: Date.now()
});
});
`
Grab a copy of /client.js from this repo, or use CommonJS compiler andjandal/client
require .
`javascript
var conn, socket;
// use browserify
// or load the libraries as seperate scripts
require('sockjs');
require('jandal/client');
conn = new SockJS('http://localhost:8080/socket');
socket = new Jandal(conn, 'websocket');
// Wait for socket to connect
socket.on('socket.open', function () {
// listen for events
socket.on('welcome', function (info) {
console.log(info);
});
// send a message to the server
socket.emit('log', 'the time is' + Date.now());
// Send a message to the server with a callback
socket.emit('echo', 'hello', function (reply) {
assert(reply === 'hello');
});
});
`
`javascript
conn.on('connection', function (socket) {
var jandal;
// wrap the socket
jandal = new Jandal(socket, 'stream');
// add it to a room
jandal.join('my_room');
// emit to all other sockets in a room
jandal.broadcast.to('my_room').emit('a new socket has joined', jandal.id);
// remove it from a room
jandal.leave('my_room');
});
`
The Jandal class has a couple of static properties useful for managing
connected sockets.
This is a Room instance that holds all the connected sockets. See the Room
docs for more info.
Example:
`javascript
// Emitting
Jandal.all.emit('hello', 1, 2,3);
// Broadcasting
Jandal.all.broadcast('socket-id', 'hello', 1, 2, 3);
`
Easily access any sockets in any room. See the Room docs for more info.
Parameters:
- room (string) : the name of the room
Example:
`javascript`
Jandal.in('my-room').emit('hello');
Every Jandal instance extends the NodeJS EventEmitter so you can also use
methods like: once, removeAllListeners and setMaxListeners. See the
EventEmitter docs for more information.
An array that holds all the rooms the socket is currently joined to.
Parameters:
- socket (object) : an object that represents a socket
- handle (string|object) : a handle name or an object to use as a handle
Example:
`javascript
var jandal, conn;
jandal = new Jandal();
conn = new SockJS(config.url);
jandal.connect(conn, 'websocket');
`
Example with custom handles:
`javascript
var jandal, handle, socket;
jandal = new Jandal();
socket = new EventEmitter();
handle = {
write: function (socket, message) {
socket.emit('message', message);
},
onread: (socket, fn) {
socket.on('message', fn);
},
...
};
jandal.connect(socket, handle);
`
This is very similar to the NodeJS EventEmitter, but you are limited to three
arguments.
Parameters:
- event (string) : the event to emit
- arg1 (dynamic)
- arg2 (dynamic)
- arg3 (dynamic)
Arguments can be strings, numbers, booleans, dates, objects, arrays, etc...
Basically anything that JSON.stringify can handle.
Callbacks:
You can also send one function for use as a callback.
- It must always be passed as the last argument.
- Callbacks will only be run once.
- They can take 0 to 3 arguments.
Example:
`javascript
var jandal;
jandal = new Jandal();
// lots of different data types
jandal.emit('my-event', 'arg 1', ['arg 2'], {arg: 3})
// passing functions as callbacks
jandal.emit('my-callback', 'some data', function (response) {
console.log('running the callback with', response);
});
`
Works very similar to the EventEmitter.
Parameters:
- event (string) : event to listen for
- listener (function) : function to run when the event is emitted
Example:
`javascript
jandal.on('my-event', function (arg1, arg2, arg3) {
console.log('"my-event" has been emitted with', arguments);
});
// listening for a namespace + event
jandal.on('task.create', listener);
// this is the same as
jandal.namespace('task').on('create', listener);
`
Return a new Namespace instance. If the namespace already exists, it will
use that instead of creating a new one. See the Namespace docs for more info.
Parameters:
- name (string) : namespace name
Example:
`javascript
var jandal, ns;
jandal = new Jandal();
ns = jandal.namespace('app');
// sends "app.hello()"
ns.emit('hello');
// listens for "app.goodbye"
ns.on('goodbye', function () {
console.log('bye');
});
`
Put the socket in a room.
Parameters:
- room (string) : name of the room
Example:
`javascript`
jandal.join('my-room');
Remove the socket from a room.
Parameters:
- room (string) : name of the room
Example:
`javascript`
jandal.leave('my-room');
Returns a room. Same as Jandal.in.
Parameters:
- room (string) : name of the room
Example:
`javascript
// add the socket to the room
jandal.join('my-room');
// get the room
var room = jandal.room('my-room');
// emit to all the sockets in the room
room.emit('hello');
`
Remove the socket from all the rooms it is currently in.
Example:
`javascript`
jandal.release();
Rooms are just a collection of sockets. You can add or remove sockets from
them, and emit events to all sockets in that room, or broadcast events from a
socket to all other sockets.
Every socket is added to the 'all' room, which can be acessed through
Jandal.all.
Returns the number of connected sockets in a room.
Parameters:
No parameters
Example:
`javascript`
Jandal.in('my-room').length();
Check if a socket is in a room. Returns true or false.
Parameters
- jandal (Jandal) : an instance of a Jandal
Example:
`javascript
var a, b;
a = new Jandal();
a.join('my-room');
b = new Jandal();
Jandal.in('my-room').contains(a); // true
Jandal.in('my-room').contains(b); // false
`
Exactly the same as jandal.emit but will be sent to all connected sockets.
Parameters:
- event (string) : name of the event
- arg1 (dynamic)
- arg2 (dynamic)
- arg3 (dynamic)
Example:
`javascript`
Jandal.in('my-room').emit('hello', 1, 2, 3);
Just like emit, but will not send to the 'sender' socket.
Parameters:
- sender (dynamic)
- event (string)
- arg1 (dynamic)
- arg2 (dynamic)
- arg3 (dynamic)
Example:
`javascript`
Jandal.in('my-room').broadcast('some-id', 'bye', 1, 2, 3);
Get a namespace for a room.
Parameters:
- name (string) : the name of the namespace
Example:
`javascript`
Jandal.in('my-room').namespace('tasks').emit('create', 'something');
Destroy all sockets in a room
`javascript`
Jandal.in('my-room').destroy()
Handles are used as an interface between Jandal and a socket.
There are two handles bundled by default: stream and websocket.
Works with SockJS-Node
Source Code:
`javascript`
stream: {
identify: function (socket) {
return socket.id;
},
write: function (socket, message) {
socket.write(message);
},
onread: function (socket, fn) {
socket.on('data', fn);
},
onclose: function (socket, fn) {
socket.on('close', fn);
},
onerror: function(socket, fn) {
socket.on('error', fn);
},
onopen: function(socket, fn) {
setTimeout(fn, 0);
},
release: function (socket) {
socket.removeAllListeners('data');
socket.removeAllListeners('close');
socket.removeAllListeners('error');
}
}
Works with the WebSocket API (and also SockJS-Client).
Source Code:
`javascript
websocketsId = 0;
...
websocket: {
identify: function (socket) {
if (socket.hasOwnProperty('id')) return socket.id;
socket.id = ++websocketsId;
return socket.id;
},
write: function (socket, message) {
socket.send(message);
},
onread: function (socket, fn) {
socket.onmessage = function (e) { fn(e.data); };
},
onclose: function (socket, fn) {
socket.onclose = fn;
},
onerror: function(socket, fn) {
socket.onerror = fn;
},
onopen: function(socket, fn) {
socket.onopen = fn;
},
release: function (socket) {
delete socket.onmessage;
delete socket.onclose;
delete socket.onerror;
delete socket.onopen;
}
}
`
Return something that identifies this socket, like an ID.
Parameters:
- socket (Socket) : the socket to identify
Example:
`javascript
var handler = {
identify: function (socket) {
// if your sockets already have an id
return socket.id;
// maybe assign an id?
// HINT: better to use
return socket.id || socket.id = ++someNumber;
// if you don't care about anything
return socket;
}
};
`
Write a message to the socket. Will be called whenever a message needs to be
sent.
Parameters:
- socket (socket) : the socket to send the message with
- message (string) : the message to send
Example:
`javascript`
var handler = {
write: function (socket, message) {
socket.write(message);
}
};
Listen for messages. Will be called once per each socket. Expects the fn
callback to be passed a message whenever one is sent.
Parameters:
- socket (socket) : the socket to listen to
- fn (function) : the callback to run
Callback Parameters:
- message (string) : the message that has been sent to the socket
Example:
`javascript`
var handler = {
onread: function (socket, fn) {
socket.on('read', fn);
}
};
Listen for errors on the socket. Will be called only once per each socket.
Expects fn to be called whenever the socket has an error. Accepts onesocket.error
argument that will be be passed through to the event.
Parameters:
- socket (socket) : the socket to listen to
- fn (function) : the callback to run
Callback Parameters:
- err (dynamic) : an error message
Example:
`javascript`
var handler = {
onerror: function (socket, fn) {
socket.on('error', function (err) {
fn(err);
});
}
};
Listen for the socket connection to be opened. Will be called once per each
socket. Expects the fn callback to called once when the socket has connected.socket.open
If the socket is already open, the you can run the callback immediately. Will
be passed through to the event.
Parameters:
- socket (socket) : the socket to listen to
- fn (function) : the callback to run
Callback Parameters:
- event (dymanic) : an optional argument to pass through to socket.open
Example:
`javascript`
var handler = {
onopen: function (socket, fn) {
socket.on('open', fn);
}
};
Listen for the socket to be closed. Will be called once per each socket.
Expects the fn callback to be called only once, and only when the socket hassocket.close
been closed. Arguments will be passed through to the event.
Parameters:
- socket (socket) : the socket to listen to
- fn (function) : the callback to run
Callback Parameters:
- status (number) : error code
- message (string) : error message
Example:
`javascript`
var handler = {
onclose: function (socket, fn) {
socket.on('close', fn);
}
};
Disconnect the raw socket from the jandal instance.
Parameters:
- socket (socket) : the socket to listen to
Example:
`javascript`
var handler = {
release: function (socket) {
socket.off('data');
socket.off('open');
socket.off('close');
socket.off('error');
}
};
Jandal uses a simple protocol for encoding messages. It's based on the
javascript syntax for objects and functions. Arguments are encoded using
JSON.stringify.
There are four parts to a message:
- namespace
- event
- args
- callback
The namespace and callback are both optional.
Example messages:
`javascript
// event + single arg
fetch("info")
// event + multiple args
fetch("info",{"count":40})
// event + arg + callback
fetch("info").fn(10)
// namespace + event + arg
user.load("numbers",[10,20,30])
// namespace + event + arg + callback
task.create({"name":"this is a new task"}).fn(1)
`
Callbacks:
Each message can have a single callback. The callback must be the last
arguments, and can only be called once.
Callbacks are just like regular events, so you can also have a callback
on a callback.
`javascript
// send a message with a callback
app.login('username', 'password').fn(32)
// response running the callback with args
socket.fn_23({login: success})
// callback with a callback
socket.fn_24({login: fail}).fn(25)
`
The same code can be run in the browser by using Browserify.
This also allows you to use the library to communicate between servers, as it
acts as the client and the server.
To compile for the browser:
npm run-script build
And then either copy/paste the client.js file into your project, orrequire('jandal/client');
include it via .
The MIT License (MIT)
Copyright (c) 2014 George Czabania
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
- When broadcasting from a socket, check socket.id !== sender instead ofsocket !== sender
. This requires all sockets to have an 'id' attribute.socket
- Use the namespace instead of Jandal for handling callbacks.serialize
- Make and parse private methods of a Jandal instance.namespaces
- Make and callbacks private properties of a Jandal instance.Room.prototype.join
- Fix bug where Jandal would crash if a callback is called more than once
- Make and Room.prototype.leave private.Jandal.handle()
- Fix bug where a socket could be added to the same room twice
- Remove . Instead pass the handler to the Jandal
constructor. e.g: .room.destroy()
- Replace with room.empty(). No longer destroys room, justRoom.remove()
removes all the connected sockets.
- Remove .var = a, b, c;
- Add MIT License
- Switch from to var a = 1; \n var b = 2; var c = 3;
- Rebuild client.js
- The onclose handler now accepts two arguments that will be passed throughsocket.close
to the event.
- Move client.js to the root directory. You should now userequire('jandal/client')
.
- Allow users to supply a custom socket handler.
- Add socket events: socket.open, socket.close, socket.error.Socket.prototype.serialize
- Fix an off by error with , where callbacks could
not be the last argument.
- Use .fn(20) instead of __fn__20 for callbacks.Socket.prototype.parse
- Make sure that will only accept strings.
- Protect Socket.prototype.parse against crashing on invalid messages.
- Add Socket.prototype.room to access rooms from a jandal instance.
- Limit event arguments to a maximum of three.
- Clean up code.
- Add examples to readme.
- Use browserify to compile for browsers.
- Use uglify to minify client.js.
- Set main to source/jandal.js.
- Add namespaces to broadcasting
- Redo the room api
- Split code into multiple files.
- Add support for sorting sockets into rooms
- Use handles to interface betwen jandals and sockets.
- Fix bug with parsing messages.
- Add Jandal.noConflict for browsers.
- Start project
- Write jandal.js` and tests
- Can serialize and parse messages
- Add namespaces
- Can emit messages and listen for them
- Add callback functions