Ws plus

Dead Simple Websockets

Version: 2.4.0 Updated: 05/14/2021

By: foxxyz License: MIT

Downloads Last 30 Days: 69

Install

npm i ws-plus
yarn add ws-plus

Repository: https://github.com/foxxyz/ws-plus

CDNs

bundle.run: https://bundle.run/ws-plus

jsDelivr: https://cdn.jsdelivr.net/npm/ws-plus

unpkg: https://unpkg.com/ws-plus

WS+: Dead Simple WebSockets

tests

Dead simple WebSocket communication for both Node.js and in-browser.

  • Abstraction on top of the wonderful ws library
  • Event-based
  • Automatic reconnections
  • Automatic connection support
  • Subscription support
  • ES7 / Async support
  • Vue plugin support (Vue 3 supported!)
  • Fully tested
Contents

Requirements

  • Node 10+

Installation

npm install ws-plus

Usage Examples

Server

const { Server } = require('ws-plus')

// Start server on port
const server = new Server({ port: 8088 })

// React to an incoming message
server.on('ticket/request', (data, client) => {
    // Respond to client
    client.send('ticket/response', { ticket: '123' })
    // Or respond to all clients
    server.broadcast('ticket/response', ...)
})

Client

import { Client } from 'ws-plus'

const client = new Client('ws://localhost:8082')

// Observe connect events
client.on('connect', () => {
    console.info('Connection successful!')
})

// React to specific events
client.on('ticket/response', ({ ticket }) => {
    console.info(`Ticket received: ${ticket}`)
})

// Send a message
client.send('ticket/request', { someData: 'etc' })

Subscriptions

WS+ supports subscriptions to allow clients to only receive certain messages if they are interested in them. Example below.

Example

Server-Side
// Only clients that have subscribed to `specialMessage` will receive this
server.broadcastSubscribers('specialMessage', { secretCode: 1234 })
Client-Side
client.on('specialMessage', ({ secretCode }) => {
    // Do some secret things
})

// Required to receive the message above
client.send('subscribe', 'specialMessage')

Multiple Subscriptions

You can also subscribe to multiple actions at the same time:

client.send('subscribe', ['specialMessage', 'anotherAction'])

Unsubscribing

Unsubscribing is handled the same way as subscribing.

client.send('unsubscribe', ['specialMessage', 'anotherAction'])

Vue Plugin

When creating your app:

Vue 2
import { Client } from 'ws-plus'

// Create your client
const socketClient = new Client('ws://localhost:8082')

// Make socket available to all components
Vue.use(socketClient, { name: 'ws' })
Vue 3
import { createSocket } from 'ws-plus/vue'

// Create your client
const socketClient = createSocket('ws://localhost:8082')

// Make socket available to all components
app.use(socketClient)

Usage in a Component

export default {
    ...
    click() {
        this.$ws.send('ticket/request', { data: ... })
    }
}

Using with the Vue 3 Component API

The listen helper automatically calls .on and .off for specified action when the component is mounted and unmounted.

import { inject } from 'vue'
import { listen } from 'ws-plus/vue'

export default {
    setup() {
        function receive({ ticket }) {
            console.info(`Ticket received: ${ticket}`)
        }

        listen({
            'ticket/receive': receive
        })

        const ws = inject('$ws')
        ws.send('ticket/request', { data: ... })
    }
}

Multiple Clients

You can connect to multiple WebSocket servers by passing a different name when calling app.use() (Vue 3) or Vue.use() (Vue 2). The default name is ws.

import { createSocket } from 'ws-plus/vue'

// Connect to one client
const client1 = createSocket('ws://localhost:8082')
// Connect to another
const client2 = createSocket('ws://localhost:15600')

// Will be accessible as inject('$foo')
app.use(client1, { name: 'foo' })
// Will be accessible as inject('$bar')
app.use(client2, { name: 'bar' })

📝 API Docs

Class Client

Clients connect to other WebSocket servers and can be created either in a back-end (Node) or front-end (browser) environment.

All incoming messages are emitted as action events and can be subscribed to via client.on().

new Client(url : String, options? = { reconnectInterval?, maxQueueSize?, autoConnect?, rootObject?, verbosity? })

Create a new WebSocket client.

  • url: URL to connect to (example: ws://localhost:8090)

Options:

  • autoConnect: Automatically connect during construction. Set this to false if you prefer to call .connect() manually. (default: true)
  • maxQueueSize: Maximum amount of messages to queue when not connected (for example, if still awaiting connection) (default: 100)
  • reconnectInterval: How many seconds to wait until attempting a reconnect when disconnected (default: 10)
  • rootObject: Serialize messages as JSON objects instead of JSON arrays. Useful when dealing with servers that don't support top-level arrays. (default: false)
  • verbosity: Show more/less log messages (default: 1). Set to 0 to silence.

Event: 'connect'

Emitted when connection to a server succeeds.

Event: 'close'

Emitted when the client closes, either normally or abnormally (E.G. during a reconnect).

client.broadcast(action : String, data : Any)

Send message to all other connected clients (including yourself).

Alias for calling client.send(action, data, true).

client.close()

Close socket.

client.connect()

Connect this client. Called automatically if reconnectInterval is set.

client.on(eventName : String, listener : function(data) {})

Listen for messages or events.

  • eventName: Event to listen for. Can be one of the default events or any message action sent by the server.
  • listener: Function to be called with data when action is received

client.off(eventName : String, listener : Function)

Stop listening for messages or events.

Alias for client.removeListener()

  • eventName: Event to unregister. Can be one of the default events or any message action sent by the server.
  • listener: Function to unregister

client.send(action : String, data : Any, bounce? : Boolean)

Send message to server.

  • action: Action name
  • data: Data to send
  • bounce: Bounce message back to this and all other connected clients on the server (default: false)

Class Server

Listens and waits for clients. Can only be used in back-end environments, not in-browser.

new Server(options? = { host?, port?, maxSendBuffer?, rootObject?, verbosity? })

Create a new server.

Options:

  • host: Host to listen on (default: 127.0.0.1). Use 0.0.0.0 to accept any incoming connection.
  • port: Port to listen on (default: 8090)
  • maxSendBuffer: Size of the send buffer in bytes. This governs how much the server can queue to an unacknowledging recipient (for example, during slow connections) before giving up. Messages that exceed the send buffer are dropped. (default: 20000)
  • rootObject: Serialize messages as JSON objects instead of JSON arrays. Useful when handling clients that don't support top-level arrays. (default: false)
  • verbosity: Show more/less log messages (default 1). Use 0 to silence.

Event: 'connect'

Special event emitted when a client connects to this server.

On emission, the listening function will be called with the ServerClient instance of the newly connected client.

server.broadcast(action : String, data : Any, skipClient? : ServerClient) : Promise

Broadcast a message to all clients.

  • action: Action name
  • data: Data to send
  • skipClient: A ServerClient that should not receive this broadcast

server.broadcastSubscribers(action : String, data : Any) : Promise

Broadcast a message only to clients subscribed to this action.

For more information, see subscriptions.

  • action: Action name
  • data: Data to send

server.close() : Promise

Close this server. await this method to ensure all clients have disconnected.

server.on(eventName : String, listener : function(data, client) {})

Listen for specific message actions from clients or events.

  • eventName: Event to listen for. Can be one of the default events or any message action sent by a client.
  • listener: Function to be called with the incoming data and the specific client who sent it

Class ServerClient

A representation of each client connected to the server. These instances are automatically created by the server and should not be instantiated directly. However, ServerClient instances may be interacted with via event listeners on Server.

serverClient.deliver(action : String, data : Any) : Promise

Deliver a message to this client only. Rejects if message could not be delivered.

Useful for critical information.

  • action: Action name
  • data: Data to send

serverClient.send(action : String, data : Any) : Promise

Send a message to this client only. Failures will not reject, but will log.

  • action: Action name
  • data: Data to send

serverClient.toString() : String

Return a string representation of this client.

Vue Module (ws-plus/vue)

This module contains functions to ease development using Vue.js.

Usage Examples

createSocket(url: String, options? : {}) : Client

Create and return a reactive socket.

  • url: URL to connect to (example: ws://localhost:8090)
  • options: Options to pass to to Client (see new Client() for all options)

listen(actions : Object, options? : { name? })

Register multiple listeners at once on a particular client.

  • actions: Object with action names as keys and listener functions as values

Options:

  • name: Websocket name to listen to (default: ws)

Example:

function foo(incoming) {
    console.log(incoming)
}

listen({
    action1: foo,
    action2: foo
})

Equivalent to doing:

const client = inject('$ws')

onMounted(() => {
    client.on('action1', foo)
    client.on('action2', foo)
})

onUnmounted(() => {
    client.off('action1', foo)
    client.off('action2', foo)
})

Contributing & Tests

  1. Install development dependencies: npm install
  2. Run tests: npm test

License

MIT

Categories: Vue js