Novelty Plastic Moustache


    2.0.0 • Public • Published


    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.


    • 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


    Read this article for more background information.


    npm i ws-messaging


    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', ( => { /* 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.


    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.


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

    PRs are also accepted.




    npm i ws-messaging

    DownloadsWeekly Downloads






    Unpacked Size

    58.4 kB

    Total Files


    Last publish


    • an-sh