SuperIO

Super Socket.io Client. A drop-in replacement for Automattic/socket.io-client.

Advantages

1. RegExp Events.
2. Backbone.js Style Event System.
3. Additional Request-Response Flow.
4. Configurable Agnostic (Non-Event) Messages.

Installation

SuperIO is released on npm and can be installed using:

npm install superio --save

How to use

SuperIO can be used with Browserify and stand-alone and has the same interface as socket.io-client.

Browserify (or Node.js)

var socket = require('superio')('http://localhost');
socket.on('connect', function(){
    socket.on('event', function(data){});
    socket.on('disconnect', function(){});
});

Stand-Alone Global

<script src="/superio/dist/superio.min.js"></script>
<script>
    var socket = superio('http://localhost');
    socket.on('connect', function(){
        socket.on('event', function(data){});
        socket.on('disconnect', function(){});
    });
</script>

Build The Stand-Alone Yourself

1. npm install - Install the build prerequisites.
2. gulp build - Build using Gulp. Result is in dist folder.
3. npm test - Run tests.

API

SuperIO(uri:String, options:Object): SuperIOSocket

Exposed as the superio namespace in the standalone build, or the result of calling require('superio').

The following options can be provided:

Name | Description | Default ----------------|-------------------------------------------|--------------- header | Header applied to each message | null messageEvent | Agnostic message event name | message errorEvent | Req-Res Error event name (prefix) | error: io | Socket.IO options. See Socket.IO | null

RegExp Events

Built-in support for Regular Expressions. Simply listen in on the expression.

Some Examples:

//Listen On All Transactions
socket.on('transaction:*', function(t){});

//Listen On All Transactions Except From Brokerage
socket.on('transaction:(?!brokerage:.*$).+', function(t){});

//Listen On Everything (Wildcard)
socket.on('.*', function(m){});

Backbone.js Style Event System.

Featuring a "sane" on/off event interface with optional (but super-awesome) context support.

socket.on(event, callback, [context])

The extra context support allows you to unbind based context. Its really handy when you want to destroy all listeners from an object during its destruction

// Removes just the `onTransaction` callback.
socket.off('transaction', onTransaction);

// Removes all 'transaction' callbacks.
socket.off('transaction');

// Removes the `onTransaction` callback for all events.
socket.off(null, onTransaction);

// Removes all callbacks for `myObject` for all events.
socket.off(null, null, myObject);

// Removes all callbacks on socket.
socket.off();

Keeps the zombie objects at bay!

Request-Response

A simple req-res interface. Emit an event, catch it back and then stop listening.

• Same event used to listen for a response.
• errorEvent prefix used to listen for an error. Default is 'error:'.
• Automatically unbinds and stops listening.

var joinMsg = { roomId: 'westminster' };
socket.reqRes('room:join', joinMsg, function(err, room){
    if(err) { return this.onError(err); }
    this.onJoin(room);
}, this);

The error prefix can be set as an option:

var superio = require('superio');

var socket = superio('http://localhost'{
    errorEvent: 'my_super_error:'
});

//Will Pass Error Events As: 'my_super_error:room:join'
socket.reqRes('room:join', {...}, function(err, room){
    ...
}, this);

Agnostic (Non-Event) Messages.

When you just want to send a message through a single entry point.

var message = { type: 'transaction', payload: { ... } };
socket.send(message);

This will emit a 'message' event to the server. Same as what Socket.io provides...

However, if you want to emit a different message or attach a header, you can easily pass those in as options.

var superio = require('superio');

var socket = superio('http://localhost'{
    messageEvent: 'client-request',
    header: { auth: 'username:password' }
});

//Will Add The Authentication Header Before Sending
socket.send({ type: 'chat', message: 'blah-blah' });

License

MIT