Negating Past Mistakes

    ws-messaging

    2.0.0 • Public • Published

    ws-messaging

    NPM Version Build Status Appveyor status Coverage Status Dependency Status JavaScript Style Guide

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

    Features

    • Send and receive notifications (events) via an EventEmitter 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).

    • Auto reconnection is provided.

    • Binary messages support via custom encoders/decoders.

    • Reasonable client size: around 14KB minified, 5KB gziped.

    Table of Contents

    Background

    Read this article for more background information.

    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://${HOST}:${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('connect', () => {
      /* 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 */ })
    })

    Essentially there are two usage patterns that are working in both directions. Fire and forget via send/on, and RPC-style via invoke/register. Unlike on, only a single handler function can be registered per a method name.

    API

    Server API and Client API documentation is available online.

    Network format description

    This section describes what data is actually passed to an encoder.

    There are only two types of messages. The first one is for normal messages:

    {
      name: string,
      args: Array,
      id?: number
    }

    An id field is present for invoke calls. The second one is for ack (replies for invoke calls) messages:

    {
      id: number
      result?: Object
      error?: Object
    }

    Either a result or an error field is included. Note that an error is the value returned by an errorFormatter, by default String is used as an errorFormatter.

    Data validation

    All incoming data must be validated on a server side, including errors that are passed to a catch callback. By default only the network format itself is validated. Validation can be made by a custom decoder (useful when a decoder is already using some scheme) or via a receiveHook, or inside a handler itself (useful for registered procedures). When validation is done inside decoder/receiveHook, just throw an error or reject a promise to fail a validation and prevent handlers execution. Also note that a promise returned by invoke can be rejected locally either with Client.ConnectionError or with Client.TimeoutError.

    Contribute

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

    PRs are also accepted.

    License

    MIT

    Install

    npm i ws-messaging

    DownloadsWeekly Downloads

    9

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    58.4 kB

    Total Files

    17

    Last publish

    Collaborators

    • an-sh