jandal

    0.0.15 • Public • Published

    Jandal

    An 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.

    Important

    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.

    Example Usage

    Server

    Add it to your project with npm install --save jandal.

    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()
        });
     
    });

    Client

    Grab a copy of /client.js from this repo, or use CommonJS compiler and require jandal/client.

    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');
        });
     
    });

    Rooms

     
    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');
     
    });

    Jandal Class

    Static Properties

    The Jandal class has a couple of static properties useful for managing connected sockets.

    Jandal.all

    This is a Room instance that holds all the connected sockets. See the Room docs for more info.

    Example:

    // Emitting
    Jandal.all.emit('hello', 1, 2,3);
     
    // Broadcasting
    Jandal.all.broadcast('socket-id', 'hello', 1, 2, 3);

    Jandal.in(room)

    Easily access any sockets in any room. See the Room docs for more info.

    Parameters:

    • room (string) : the name of the room

    Example:

    Jandal.in('my-room').emit('hello');

    Instance Properties

    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.

    jandal.rooms

    An array that holds all the rooms the socket is currently joined to.

    jandal.connect

    Parameters:

    • socket (object) : an object that represents a socket
    • handle (string|object) : a handle name or an object to use as a handle

    Example:

    var jandal, conn;
     
    jandal = new Jandal();
    conn = new SockJS(config.url);
     
    jandal.connect(conn, 'websocket');

    Example with custom handles:

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

    jandal.emit

    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:

    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);
    });

    jandal.on

    Works very similar to the EventEmitter.

    Parameters:

    • event (string) : event to listen for
    • listener (function) : function to run when the event is emitted

    Example:

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

    jandal.namespace

    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:

    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');
    });

    jandal.join

    Put the socket in a room.

    Parameters:

    • room (string) : name of the room

    Example:

    jandal.join('my-room');

    jandal.leave

    Remove the socket from a room.

    Parameters:

    • room (string) : name of the room

    Example:

    jandal.leave('my-room');

    jandal.room

    Returns a room. Same as Jandal.in.

    Parameters:

    • room (string) : name of the room

    Example:

    // 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');

    jandal.release

    Remove the socket from all the rooms it is currently in.

    Example:

    jandal.release();

    Room Class

    Instance Methods

    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.

    room.length

    Returns the number of connected sockets in a room.

    Parameters:

    No parameters

    Example:

    Jandal.in('my-room').length();

    room.contains

    Check if a socket is in a room. Returns true or false.

    Parameters

    • jandal (Jandal) : an instance of a Jandal

    Example:

    var a, b;
     
    = new Jandal();
    a.join('my-room');
     
    = new Jandal();
     
    Jandal.in('my-room').contains(a); // true
    Jandal.in('my-room').contains(b); // false

    room.emit

    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:

    Jandal.in('my-room').emit('hello', 1, 2, 3);

    room.broadcast

    Just like emit, but will not send to the 'sender' socket.

    Parameters:

    • sender (dynamic)
    • event (string)
    • arg1 (dynamic)
    • arg2 (dynamic)
    • arg3 (dynamic)

    Example:

    Jandal.in('my-room').broadcast('some-id', 'bye', 1, 2, 3);

    room.namespace

    Get a namespace for a room.

    Parameters:

    • name (string) : the name of the namespace

    Example:

    Jandal.in('my-room').namespace('tasks').emit('create', 'something');

    room.destroy

    Destroy all sockets in a room

    Jandal.in('my-room').destroy()

    Handle

    Handles are used as an interface between Jandal and a socket.

    There are two handles bundled by default: stream and websocket.

    Default Handles

    Stream

    Works with SockJS-Node

    Source Code:

    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');
        }
    }

    WebSocket

    Works with the WebSocket API (and also SockJS-Client).

    Source Code:

    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;
        }
    }

    Methods

    identify

    Return something that identifies this socket, like an ID.

    Parameters:

    • socket (Socket) : the socket to identify

    Example:

    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

    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:

    var handler = {
        write: function (socket, message) {
            socket.write(message);
        }
    };

    onread

    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:

    var handler = {
        onread: function (socket, fn) {
            socket.on('read', fn);
        }
    };

    onerror(socket, 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 one argument that will be be passed through to the socket.error event.

    Parameters:

    • socket (socket) : the socket to listen to
    • fn (function) : the callback to run

    Callback Parameters:

    • err (dynamic) : an error message

    Example:

    var handler = {
        onerror: function (socket, fn) {
            socket.on('error', function (err) {
                fn(err);
            });
        }
    };

    onopen(socket, fn)

    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. If the socket is already open, the you can run the callback immediately. Will be passed through to the socket.open 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:

    var handler = {
        onopen: function (socket, fn) {
            socket.on('open', fn);
        }
    };

    onclose(socket, 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 has been closed. Arguments will be passed through to the socket.close 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:

    var handler = {
        onclose: function (socket, fn) {
            socket.on('close', fn);
        }
    };

    release(socket)

    Disconnect the raw socket from the jandal instance.

    Parameters:

    • socket (socket) : the socket to listen to

    Example:

    var handler = {
        release: function (socket) {
            socket.off('data');
            socket.off('open');
            socket.off('close');
            socket.off('error');
        }
    };

    Protocol

    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:

    // 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.

    // 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)

    Browsers

    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, or include it via require('jandal/client');.

    License

    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.

    Changelog

    0.0.15

    • When broadcasting from a socket, check socket.id !== sender instead of socket !== sender. This requires all sockets to have an 'id' attribute.
    • Use the socket namespace instead of Jandal for handling callbacks.
    • Make serialize and parse private methods of a Jandal instance.
    • Make namespaces and callbacks private properties of a Jandal instance.
    • Fix bug where Jandal would crash if a callback is called more than once
    • Make Room.prototype.join and Room.prototype.leave private.
    • Fix bug where a socket could be added to the same room twice
    • Remove Jandal.handle(). Instead pass the handler to the Jandal constructor. e.g: new Jandal(socket, 'stream');.
    • Replace room.destroy() with room.empty(). No longer destroys room, just removes all the connected sockets.
    • Remove Room.remove().
    • Add MIT License
    • Switch from var = a, b, c; to var a = 1; \n var b = 2; var c = 3;

    0.0.14

    • Rebuild client.js

    0.0.13

    • The onclose handler now accepts two arguments that will be passed through to the socket.close event.

    0.0.12

    • Move client.js to the root directory. You should now use require('jandal/client').
    • Allow users to supply a custom socket handler.

    0.0.11

    • Add socket events: socket.open, socket.close, socket.error.
    • Fix an off by error with Socket.prototype.serialize, where callbacks could not be the last argument.

    0.0.10

    • Use .fn(20) instead of __fn__20 for callbacks.
    • Make sure that Socket.prototype.parse will only accept strings.

    0.0.9

    • Protect Socket.prototype.parse against crashing on invalid messages.

    0.0.8

    • Add Socket.prototype.room to access rooms from a jandal instance.
    • Limit event arguments to a maximum of three.

    0.0.7

    • Clean up code.
    • Add examples to readme.

    0.0.6

    • Use browserify to compile for browsers.
    • Use uglify to minify client.js.

    0.0.5

    • Set main to source/jandal.js.

    0.0.4

    • Add namespaces to broadcasting
    • Redo the room api

    0.0.3

    • Split code into multiple files.
    • Add support for sorting sockets into rooms

    0.0.2

    • Use handles to interface betwen jandals and sockets.
    • Fix bug with parsing messages.
    • Add Jandal.noConflict for browsers.

    0.0.1

    • Start project
    • Write jandal.js and tests
    • Can serialize and parse messages
    • Add namespaces
    • Can emit messages and listen for them
    • Add callback functions

    Install

    npm i jandal

    DownloadsWeekly Downloads

    1

    Version

    0.0.15

    License

    MIT

    Last publish

    Collaborators

    • stayradiated