# innkeeper-socket.io

> rooms++ for socket.io. Allows for private rooms where a key is used and storing data for a room.

Latest version **1.5.1** (published 2016-06-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install innkeeper-socket.io
pnpm add innkeeper-socket.io
yarn add innkeeper-socket.io
bun add innkeeper-socket.io
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.5.1 |
| Published | 2016-06-16 |
| First published | 2014-12-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Known vulnerabilities | 0 (+2 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 10 |
| Author | Mikko Haapoja |
| Maintainers | mikkoh |
| Keywords | innkeeper, socket.io, rooms, data, secret |

## Links

- npm: https://www.npmjs.com/package/innkeeper-socket.io
- Repository: https://github.com/Jam3/innkeeper-socket.io
- Issues: https://github.com/Jam3/innkeeper-socket.io/issues
- npm.io page: https://npm.io/package/innkeeper-socket.io

## Dependencies (4)

- [bluebird](https://npm.io/package/bluebird.md) ^2.9.8
- [innkeeper](https://npm.io/package/innkeeper.md) ^1.2.0
- [socket.io](https://npm.io/package/socket.io.md) ^1.4.5
- [socket.io-client](https://npm.io/package/socket.io-client.md) ^1.4.5

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 1.5.1 (latest) — 2016-06-16
- 1.5.0 — 2015-04-01
- 1.4.0 — 2015-02-24
- 1.3.1 — 2015-02-24
- 1.3.0 — 2015-02-24
- 1.2.0 — 2015-02-23
- 1.1.3 — 2015-02-20
- 1.1.2 — 2015-02-20
- 1.1.1 — 2015-02-20
- 1.1.0 — 2015-02-20
- 1.0.0 — 2014-12-05

## README

# innkeeper-socket.io

[![NPM](https://nodei.co/npm/innkeeper-socket.io.png)](https://www.npmjs.com/package/innkeeper-socket.io)

[![experimental](http://badges.github.io/stability-badges/dist/experimental.svg)](http://github.com/badges/stability-badges)

rooms++ for socket.io. Allows for private rooms where a key is used and storing data for a room.

## Usage

Example Server:
```javascript
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:
```javascript
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`](https://www.npmjs.com/package/innkeeper-storeredis).

Below is an example of creating a `innkeeper-socket.io` server using a redis store.
```javascript
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:

```javascript
{
  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](http://github.com/jam3/innkeeper-socket.io/blob/master/LICENSE.md) for details.

---
_Source: https://npm.io/package/innkeeper-socket.io · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._