ws-messaging

ws-messaging

Just a really thin abstraction layer on top of WebSocket for Node.js and Web browsers with a Promises and EventEmitter based APIs.

Features

• Send notifications via an EventEmitter-like API.

• Request-reply API using promises (works in both directions, without any connection blocking during processing).

• Built-in auth via WebSocket messages exchange (no more query strings).

• Reconnection method is provided.

• Binary messages support via custom encoders/decoders.

• Reasonable client size (15KB minified, including a Promise polyfill).

Table of Contents

• Installation
• Usage
• API
• Contribute
• License

Installation

npm i ws-messaging

Usage

On a server:

const Server = require('ws-messaging')

const port = 8000

function connectionHook (client, authData) {
  // check an authData
  // then assign client events handlers
  // return a promise
}

let server = new Server({port}, {connectionHook})

On a client:

const Client = require('ws-messaging/client')

const url = `ws://localhost:${port}`
const auth = { /* will be authData in connectionHook */ }

let client = new Client(url, auth)

client.on('someEvent', (...data) => { /* do smth */ })

client.register('someMethod', (..args) => { /* do smth, return a promise */ })

client.on('connection', () => {
  /* now this client can send messages */
  client.send('myEvent', ...someData)
  /* or use request-reply (RPC) API */
  client.invoke('myMethod', ...someArgs)
    .then(result => { /* do smth */ })
    .catch(error => { /* do smth */ })
})

client.on('close', ev => {
  /* close */
  if (!client.terminated) {
    /* but a client is able to try to reconnect */
    setTimeout(client.reconnect.bind(client), 2000)
  }
})

See tests in test/index.js for more usage examples.

API

Server API and Client API documentation is available online.

Contribute

If you encounter a bug in this package, please submit a bug report to github repo issues.

PRs are also accepted.

License

MIT

Changelog

0.3.0 (2016-09-28)

Bug Fixes

• returning an empty result from RPC (103d0e9)
• use standalone bundle (c6fca77)

Code Refactoring

• allow reconnect on terminated clients (ab0b806)
• rename option (2d95d5e)
• rename option (b117cc4)

Features

• emit errors without throwing on 0 listeners (7675db2)
• send pings for network failures detection (2c7ee8d)
• separate ping timeout option (0ba3ef3)
• use emit as an alias for send (a142bed)

BREAKING CHANGES

• Server option is renamed to WebSocketServer.
• terminated state now is not checked by the reconnect method.
• rename ackWaitTimeout to ackTimeout.
• emit method semantics changed.

<a name="0.2.0"></a>