innkeeper-socket.io v1.5.1
innkeeper-socket.io
rooms++ for socket.io. Allows for private rooms where a key is used and storing data for a room.
Usage
Example Server:
var app = require('http').createServer( function(){} );
var io = require( 'socket.io' )( app );
var innkeeper = require( 'innkeeper-socket.io' );
var keeper = innkeeper( { io: io } );
app.listen( 8888 );
Example Client:
var ioClient = require( 'socket.io-client' );
var io = ioClient( 'http://localhost:8333' );
var innkeeper = require( 'innkeeper-socket.io/client' );
var keeper = innkeeper( { io: io } );
// create a room other users/sockets can join
// reserver returns a promise which returns a room object
keeper.reserve()
.then( function( room ) {
// watch for room data changes
room.on( 'data', function( data, action ) {
console.log( data ); // current room data
console.log( action ); // what was done to change room data
});
// create a variable which will be stored for the room
room.setVar( 'variable_name', 'some value' );
.then( function( value ) {
console.log( value ); // "some value"
});
});
API
Server
Constructor -
Optionally in the options object you may pass a memory store. By default an in memory store will be used however Redis can be easily used by using innkeeper-storeredis
.
Below is an example of creating a innkeeper-socket.io
server using a redis store.
var app = require('http').createServer( function(){} );
var io = require( 'socket.io' )( app );
var innkeeper = require( 'innkeeper-socket.io' );
var redis = redis = require( 'redis' );
var keeper = innkeeper({
io: io,
memory: require('innkeeper-storeredis')(redis.createClient())
});
app.listen( 8888 );
Client
Constructor -
client = require( 'innkeeper-socket.io/client' )(opts);
-
Will construct a new client. A settings object must be passed which must include a variable io
which will be an instance of a Socket.io client.
Properties -
client.rooms
-
An object which will store all rooms created or joined by this client. The room's id is the key/variable name of the object.
Methods -
client.reserve()
-
Reserve a room. A promise is returned which when it succeeds returns a room
instance.
client.enter( roomid )
-
Enter a premade room using the rooms id. A promise is returned which when it succeeds returns a room
instance. This promise will fail when an incorrect room id was passed or the room doesn't exist anymore.
client.enterWithKey( key )
-
Enter a premade room using a key. A key is a short numeric pin which a room can have. A room can have
both a room id and a key. A promise is returned which when it succeeds returns a room
instance. This promise will fail when an incorrect room key was passed or the room doesn't exist anymore.
client.leave( roomid )
-
Leave a premade room using the room id. A promise is returned which when it succeeds returns a room
instance for the room which you left.
Room
Properties -
room.id
-
Room id. This can be shared to enter into a room. A room id is longer than a room key.
room.users
-
Users in the room. An array of all the users in a room.
room.roomData
-
Current data in the room.
Methods -
room.getKey()
-
Will reserve a key for this room. This key can be shared to allow other users to enter into this room. A some point in time this key should be returned. So for instance if we're expecting a room to become "full" when there are 3 users then we can return the key. The key is also automatically returned when the room becomes empty. A promise is returned which when it resolved returns the key. If it fails most likely the server has run out of keys.
room.returnKey()
-
Returns a key which has been reserved for this room. A promise is returned which will always resolve.
room.setVar( key, value )
-
adds or sets a variable on a room. key
is the name of the variable. value
is the value for the variable.
The value of the variable should be a primitive type. (no Arrays or Objects). When a room variable is set
everyone receives an event notifiying that a variable has been changed. Room variables are handy to have a
shared model to save the state of your application. A promise is returned which will return the value of the
variable.
room.getVar( key )
-
get the value of a variable. key
is the name of the variable. A promise is returned which when it resolves
returns the value of the variable. If the variable doesn't exist the promise returns null.
room.deleteVar( key )
-
delete a room variable. key
is the name of the variable. A promise is returned which will resolve once the
variable has been deleted.
room.setRoomData( data )
-
set multiple variables at the same time. This is a convenient way to initialize room variables. data
is
an Object with values for the room. Values of variables should be Javascript primitive values.
room.getRoomData()
-
get all variables and values stored for the room. A promise is returned. When this promise resolved an Object
is returned.
Events -
room.on( 'data', function( data, action ) { } );
An event 'data'
is emitted whenever the rooms data is changed. data
is an Object which is the rooms current
data. action
has details about the action which was taken to modify the rooms data for instance calling
room.setVar( key, value )
would return the following action
data:
{
roomID: id, // id of the room in which data was changed
action: 'set', // what action was performed such as 'set' or 'delete'
key: key, // the variable name or key in the object which was changed
value: value // the value of the variable
}
If room.setRoomData( data )
is used then action
will be null
.
License
MIT, see LICENSE.md for details.