angelia.io

WebSockets Server and Client API for Node.js and the browser, with rooms support.

The goal of this project is to provide a developer friendly API that just works™.

Installation

npm install angelia.io

Example

// server.js (node.js)

import Server from 'angelia.io/server'

class FancyChat {
	typing(socket, data, callback) {
		console.log('Im', data ? ' typing' : ' not typing')
	}
	theMessage(socket, data, callback) {
		console.log('the message is', data, socket)
		socket.emit('gotIt', 'thanks')
		callback('yes Im sure')
	}
}

Server.on(FancyChat)

class myConnection {
	connect(socket, request) {
		console.log('socket connected', socket)
	}
	disconnect(socket, code, message) {
		console.log('socket disconnected', code, message, socket)
	}
}
Server.on(myConnection)

Server.listen()

// index.js (browser)

import Client from 'angelia.io/client'

const socket = new Client('ws://localhost:3001')

socket.emit('typing', true)

setTimeout(() => {
	socket.emit('typing', false)
	socket.emit('theMessage', 'hi there!', data => {
		console.log('yep', data)
	})
}, 5000)

socket.on('gotIt', message => {
	console.log('Server got it', message)
})

Server Documentation (Node.js)

Server.listen Options

| name | kind | default | description | | -------------------- | ------- | --------- | ------------------------------------------------------------------------------ | | hostname | String | undefined | the hostname if any | | port | Number | 3001 | the port to use for this server | | maxMessageSize | Number | 5 | max size in mb of a message received | | maxPostSize | Number | 50 | max size in mb of a POST message | | skipUTF8Validation | Boolean | false | allows to skip utf8 validation | | timeout | Number | 60000 | time in milliseconds after a socket is considered gone, minimum value is 10000 |

Server Object

The server object can be accessed from everywhere

List of Server Object Properties

| signature | kind | description | | ------------------------------------- | -------- | ---------------------------------------------------------------------------------------------- | | since | Number | timestamp of initialization | | now | Number | timestamp that updates every half a second | | port | Number | port used by this server | | hostname | String | the hostname if any | | maxMessageSize | Number | maximum message size in mb | | maxPostSize | Number | maximum POST size in mb | | timeout | Number | after how long the socket is considered gone, in ms | | connections | Number | count of sockets connected | | served | Number | count of sockets ever connected | | bytesReceived | Number | sum of bytes the server has ever received | | bytesSent | Number | sum of bytes sent by the server | | messagesGarbage | Number | count of messages without a listener | | messagesReceived | Number | count of messages ever received | | messagesSent | Number | count of messages ever sent | | messagesSentCacheHit | Number | count of messages ever sent that were cached | | serverErrors | Number | count of server errors | | socketErrors | Number | count of socket errors | | events | Object | ref to events, ex: server.events.typing() to dispatch typing to anyone listening to it | | on(Class) | Function | attaches all methods of a Class as listeners | | emit(key, [value]) | Function | emits to all connected sockets | | once(key, [value]) | Function | emits to the sockets and replace if exists a pending message with the same key | | broadcast(sender, key, [value]) | Function | emits to all connected sockets except sender | | broadcastOnce(sender, key, [value]) | Function | emits to the sockets except sender and replace if exists a pending message with the same key | | sockets | Set | a Set() with all the current connected sockets |

Socket Object

The socket object is given to you by a listener

List of Socket Object Properties

| signature | kind | description | | --------------------------- | -------- | ----------------------------------------------------------------------------- | | server | Object | reference to the server | | ip | String | ip of the socket | | userAgent | String | user agent of the socket | | params | Object | the params sent via the client constructor | | since | Number | timestamp of first seen | | seen | Number | timestamp of last received message | | ping | Number | delay with the socket in milliseconds (full round trip) | | timedout | Boolean | whether we lost connection with this socket | | bytesSent | Number | sum of bytes sent to this socket | | bytesReceived | Number | sum of bytes received from this socket | | messagesSent | Number | count of messages sent to this socket | | messagesReceived | Number | count of messages received from this socket | | rooms | Set | a set with the rooms where this socket is in | | emit(key, [value]) | Function | emits to client | | once(key, [value]) | Function | replace if exists a pending message with the same key from emit queue | | disconnect([noReconnect]) | Function | disconnects the socket from the server, pass true to prevent re-connections |

Server Listeners

Listen to an event by creating a class with any name, and give to methods the name of the things you want to listen to. Then add the class to the listeners as Server.on(MyClass) and you are done.

On user defined listeners, the listener receives three things as sent by the client: socket, data and a callback; Example: class FancyChat { typing(socket, data, callback?) { console.log(socket, data) }}.

List of Predefined Server Events

There's a bunch of handy predefined events dispatched

| signature | description | | ----------------------------------- | ----------------------------------------------------------------------------------------- | | listen() | when the server is about to listen | | connect(socket, request) | when a socket connects | | disconnect(socket, code, message) | when a socket gets disconnected | | ping(socket) | when we got an update of the ping for a socket | | timeout(socket, delay) | when we are about to disconnect a timedout socket, gives the delay in milliseconds | | garbage(socket, data) | if the client sends a message that the server has no listener this will be dispatched | | incoming(socket, messages) | for debugging: ref to array of incoming messages received before dispatching to listeners | | outgoing(socket, messages) | for debugging: ref to array of outgoing messages before sending to socket |

Client API (Browser)

Client Options

Arguments for the constructor

const socket = new Client({
	url: 'ws://localhost:3001',
	params: function () {
		return { fast: 'data', test: 'a space' }
	},
	noConnect: true,
})
socket.connect()

You may also do like this if you don't need any option

const socket = new Client('ws://localhost:3001')

Client API

The client API is similar to regular event handling

| signature | kind | description | | ------------------------------ | -------- | ------------------------------------------------------------------ | | connected | Boolean | true when the socket is connected else false | | connect() | Function | connects to the server, it auto-connects on disconnection | | disconnect([noReconnect]) | Function | disconnects from the server, pass true to prevent re-connections | | on(key, callback) | Function | listens for an event, returns an off function to stop listening | | emit(key, [value, callback]) | Function | emits data to the server |

List of Predefined Client Events

As in socket.on('connect', () => console.log('connect happened!'))

| signature | description | | ------------ | -------------------------------------------------------------------------------------------------------- | | connect | this happens only once when we connect to the server, any future connection is a reconnect | | reconnect | if we were connected at least once, then any re-connection will dispatch this event instead of connect | | disconnect | when we disconnect from the server |

Rooms

Via a Rooms list

1. Create a room class that extends Room
2. Create a room list that will allow joining sockets
3. Join a socket in a room, a socket may join multiple rooms. Rooms are created when the id of the room doesn't exists, and deleted when there are no sockets in the room and the room doesn't have the flag persistent
4. A socket will leave automatically all rooms on disconnection
5. socket.rooms is a set with all the rooms the socket joined
6. id is assigned to the room on creation

import { Room, Rooms } from 'angelia.io/server'

class GameRoom extends Room {
	persistent = false

	onCreate(socket) {
		console.log('creating room', this.id, socket)
	}
	onDelete(socket) {
		console.log('deleting room', this.id, socket)
	}

	onJoin(socket) {
		console.log('socket joined room', this.id, socket)
		socket.game = this
		this.emit('user joined', 'data here')
	}
	onLeave(socket) {
		console.log('socket left room', this.id, socket)
		socket.game = undefined
		this.emit('user left', 'data here')
	}
}

// games is a room list
const games = new Rooms(GameRoom)

class Connection {
	connect(socket) {
		games.join(socket, 'room id here')
		socket.game.id === 'room id here'
		console.log(socket.rooms)
		games.leave(socket, 'room id here')

		games.join(socket, 'a different room')
		socket.game.id === 'a different room'
		games.leave(socket, 'a different room')
	}
}

Server.on(Connection)
Server.listen()

Rooms Class

Iterating returns the rooms

| signature | kind | description | | ------------------------------------- | -------- | --------------------------------------------- | | get(id) | method | gets room with such an id | | join(socket, [id]) | method | adds socket to room id | | leave(socket, [id]) | method | removes socket from room id | | connections | number | number of sockets in this room list | | sockets | Iterator | sockets in this room list | | emit(key, [value]) | method | emits to all sockets in this room list | | once(key, [value]) | method | emits once to all sockets in this room list | | broadcast(socket, key, [value]) | method | emits to other sockets in this room list | | broadcastOnce(socket, key, [value]) | method | emits once to other sockets in this room list | | map(fn) | method | returns mapped array | | filter(fn) | method | returns mapped filtered array |

Via a Room

1. Create a room instance that extends Room
2. Join a socket in a room, a socket may join multiple rooms.
3. A socket will leave automatically all rooms on disconnection
4. socket.rooms is a set with all the rooms the socket joined
5. Keep in mind that onCreate and onDelete are not dispatched when the room is manged by yourself. The construtor could be used for simulating onCreate and onDelete only you will know when to dispose such a variable.

import { Room } from 'angelia.io/server'

class Lobby extends Room {
	persistent = true
	id = 'lobby'
	onJoin(socket) {
		console.log('socket joined room', this.id, socket)
	}
}

// lobby is just 1 room
const lobby = new Lobby()

class Connection {
	connect(socket) {
		lobby.join(socket)

		lobby.leave(socket)
	}
}

Server.on(Connection)
Server.listen()

Room Class

Iterating returns the sockets

| signature | kind | description | | ------------------------------------- | ------- | ------------------------------------------------ | | onCreate(socket) | method | dispatched when the room is created | | onDelete(socket) | method | dispatched when the room is deleted | | onJoin(socket) | method | dispatched when a socket joins the room | | onLeave(socket) | method | dispatched when a socket leaves the room | | persistent | boolean | to not delete rooms when there are no sockets in | | connections | number | number of sockets in the room | | sockets | Set | sockets in the room | | emit(key, [value]) | method | emits to all sockets in the room | | once(key, [value]) | method | emits once to all sockets in the room | | broadcast(socket, key, [value]) | method | emits to other sockets in the room | | broadcastOnce(socket, key, [value]) | method | emits once to other sockets in the room | | id | any | the room id | | join(socket) | method | adds a socket to the room | | leave(socket) | method | remves a socket from the room |

sockets Object in Room and Rooms

Like Set but with two aditional methods

| signature | kind | description | | ------------ | ------ | ----------------------------- | | map(fn) | method | returns mapped array | | filter(fn) | method | returns mapped filtered array |

Authors

• Tito Bouzout https://github.com/titoBouzout
• Anthony K. https://github.com/boredofnames

URLs

• https://github.com/titoBouzout/angelia.io
• https://www.npmjs.com/package/angelia.io