superio

1.0.4 • Public • Published

SuperIO

Build Status Coverage Status

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

Package Sidebar

Install

npm i superio

Weekly Downloads

0

Version

1.0.4

License

MIT

Last publish

Collaborators

  • alexcurtis