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 (14KB 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', () => { /* do smth */ })

client.register('someMethod', () => { /* 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', () => {
  /* close, but a client is able to try to reconnect */
  if (!client.terminated) {
    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