Neglected Parking Meter


    1.0.1 • Public • Published


    distributed websocket publish/subscribe

    CircleCI npm

    dwsps is a distributed nodejs pub/sub system. It uses websockets to transmit messages between client and server, and between peered servers.


    dwsps uses a heirarchical topic system for client subscriptions, each level divided by a full-stop .. For example, a client could subscribe to the topic They would then recieve messages published to,, etc. but not from or

    Note: if a client is subscribed to a parent topic and a sub-topic of the parent, unsubscribing from the parent topic will not also unsubscribe the client from the sub-topic. Each subscription must be unsubscribed from explicitly.


    Messages are JSON format and look like the following:

      "type": "publish",
      "timestamp": "2020-01-21T17:03:13.625Z",
      "topic": "",
      "context": "news",
      "message": "Hello channel!"
    • topic lets a client know where the message was published to
    • context lets a client know why they are receiving a certain message - in this instance the client is subscribed to news, where they received it, but not, where it was sent.
    • message can be any valid JSON data


    When a client performs an action, the server will send an acknowledgment in reply if it received the message and executed the action correctly. These can be listened for with the client ack event.

    Ack messages look like this:

      "type": "ack",
      "action": "subscribe",
      "timestamp": "2020-01-22T15:44:04.674Z",
      "topic": "news"


    Multiple dwsps servers can be peered with one another to create a distributed network. Once servers are peered, then a message published to one server will also be published to all servers, and delivered to their own subscribed clients respectively. Subscribed clients are not replicated between servers, instead held in memory on a per server basis.

    Messages that were forwarded from another server will also contain a fromPeerServer: true flag.

    Note: adding Server A as a peer of Server B will not enable 2-way communication: B will forward messages to A but not vice versa. Server B must also be added as a peer of Server A. See example.js for an example of peering servers.


    Basic server example

    const PSServer = require('dwsps/server')
    const server = new PSServer({ port: 8000 })
    server.on('subscribe', (topic, client) => {
      console.log(`${client} subscribed to ${topic}`)

    Basic client example

    In this example, an event listener is used to receive all messages from every topic the client is subscribed to.

    const PSClient = require('dwsps/client')
    //            or require('dwsps')
    const client = new PSClient('ws://localhost:8000')
    // Must wait for client to establish connection before performing actions
    client.on('open', () => {
      client.publish('news', 'Hello news channel!')
      client.publish('', 'Hello channel!')
    // Log acknowledgments from the server
    client.on('ack', ack => {
    // Log messages received by the client
    client.on('message', message => {

    If you only want to take action on certain received messages, you can either:

    • Implement this yourself using the event listener method and parsing the message topic, or
    • Pass a callback function to the subscribe method which will only be called when a message is received matching that particular subscription.
    const PSClient = require('dwsps/client')
    const client = new PSClient('ws://localhost:8000')
    // Create a callback function that will be called when the client receives a
    // message matching the topic `news`.
    const newsHandler = message => {
    // Must wait for client to establish connection before performing actions
    client.on('open', () => {
      client.subscribe('news', newsHandler)
      client.publish('news', 'Hello news channel!')






    npm i dwsps

    DownloadsWeekly Downloads






    Unpacked Size

    18.4 kB

    Total Files


    Last publish


    • tdjsnelling