socket-event-manager

socket-event-manager is a tiny (1.7kb gzipped) client library designed to help you manage sending and recieving JSON messages from websocket servers in the browser.

Table of Contents

1. Installing
2. Getting Started
3. Documentation
   • Creating a SocketEventManager Instance
   • Connecting the Websocket
   • Adding Event Listeners
   • Removing Event Listeners
   • Default Events
   • Sending Actions Down the Socket
   • Pinging the Server
   • Disconnecting
   • Debugging Events
4. Contributing

Installing

npm

npm install socket-event-manager --save

// CommonJS
var SocketEventManager = require('socket-event-manager')
// es6
import SocketEventManager from 'socket-event-manager'

Include the built JS file

Inside the dist directory you'll find the minimized code in socketEventManager.min.js. You can simply download & include this on your webpage.

<script src="./path/to/socketEventManager.min.js"></script>

Getting Started

import SocketEventManager from 'socket-event-manager'

var exampleSocket = new SocketEventManager('wss://example.com/socket')

exampleSocket.connect()

exampleSocket.on('open', function (event) {
  // send this as soon as the socket opens
  exampleSocket.send({
    type: 'connected',
    text: 'We have connected!'
  })
})

/* Add listeners */

exampleSocket.on('notification', function (event) {
  // do something with the notification
})

exampleSocket.on('like', function (event) {
  // ... etc.
})

// disconnect the socket
exampleSocket.disconnect()

Documentation

Creating a SocketEventManager Instance

var exampleSocket = new SocketEventManager(websocketUrl, options)

You can use different instances of SocketEventManager to manage different websockets easily. To get started all you have to do is create a new instance pass in the websocket url:

var exampleSocket = new SocketEventManager('wss://example.com/socket')

Passing Options to SocketEventManager

You can add what ever propties you want to the options object when you a new SocketEventManager instance and they will be available on the options property of the instance. There is one property in particular however that has an impact on how the instance behaves. This is identifier:

var exampleSocket = new SocketEventManager('wss://example.com/socket', {
  identifier: 'event', // defaults to `type`
})

By default socket-event-manager will use the type property of any messages that get sent from the websocket for the event listeners, but you can change this with the identifier property of the options.

Connecting the Websocket

exampleSocket.connect()

connect attempts to connect to the websocket url specified when the instance was created. Once connected the "connected" event will be fired, so you know when the socket is ready to send messages to.

If you ever need access to the websocket itself just look at exampleSocket.webSocket

Adding Event Listeners

 exampleSocket.on('event', function (data) {
   // event callback
 })

You can create an event listener for any event type. When a message gets sent from the websocket server the type property (or a custom identifier specified in options) of the message data is used as the identifier for the events. The data is then passed into the callback.

You can also add as many callbacks as you like to each event.

Removing Event Listeners

 exampleSocket.off('event', callback)

Removing event listeners is just like adding them but you use off instead of on and pass in the callback that you want to remove.

Sending Actions Down the Socket

exampleSocket.send({
  property: value
})

To send data back to the websocket simple call .send() and pass in the data that you want to send.

Default Events

There are 4 default events that you can hook into to add callbacks for the web socket events onopen, onclose, onmessage, and onerror.

exampleSocket.on('open', function (event) {
  // fired when the socket first opens
})

exampleSocket.on('close', function (event) {
  // fired when the socket connection closes
})

exampleSocket.on('message', function (event) {
  // fired when the socket client receives a message of any kind
})

exampleSocket.on('error', function (event) {
  // fired when the socket experiences an error
})

Pinging the Server

If you need to ping the server at an interval then socket-event-manager makes it easy. Use the startPing method, and pass in the action you want to send to ping, and how often you want to send it, in milliseconds (defaults to 20 seconds)

exampleSocket.startPing({
  type: 'ping'
}, 10000)

The ping interval will be cleared when the socket is closed or disconnected. So you don't need to worry about clearing it. If you do need to stop it however, it's easy.

exampleSocket.stopPing()

Disconnecting

To disconnect the websocket just call:

exampleSocket.disconnect()

Debugging events

If you are having trouble debugging which event listeners are currently live on your SocketEventManager then you can just call debugEvents. To list all the events, don't pass in any arguments, if you are looking for a particular event, then pass in that event.

exampleSocket.debugEvents('messagereceived')

In development each event that's received will be logged to console along with it's payload. This will only be present in development. If you don't wish for events to be logged you can pass {logEvents: false} into the options when you create the SocketEventManager instance.

Contributing

Bug reports and feature requests welcome.

This library is written in Standard, so if you want to contribute make sure to run npm run lint to lint your code.