websocket-toolkit — Universal WebSocket Client

A standalone, universal WebSocket client that works with any backend. One script tag. Zero dependencies.

Also published as wskit-client.

Install

npm

npm install websocket-toolkit

ES Modules

import WSKit from 'websocket-toolkit';

CommonJS

const WSKit = require('websocket-toolkit');

Script Tag

<script src="https://unpkg.com/websocket-toolkit/wskit.js"></script>

Quick Start

const ws = WSKit.connect('wss://yourserver.com/ws', {
  onOpen: () => console.log('Connected'),
  onMessage: (msg) => console.log('Received:', msg),
});

ws.send({ type: 'chat', text: 'Hello!' });

Features

Channels

Route messages by type:

// Subscribe — returns an unsubscribe function
const off = ws.on('chat', (msg) => {
  console.log(msg.user + ':', msg.text);
});

// Unsubscribe
off();

// Or unsubscribe by type
ws.off('chat');

Messages are routed by the type field by default (configurable via typeField).

Request/Response

Send a message and wait for a matching response:

const user = await ws.request({ type: 'getUser', id: 123 });
console.log(user.name);

The server should include the same _id field in its response. The _id is auto-generated and matched.

// Server-side example (Node.js)
socket.on('message', (raw) => {
  const msg = JSON.parse(raw);
  if (msg.type === 'getUser') {
    socket.send(JSON.stringify({
      _id: msg._id,  // echo back the _id
      name: 'John',
      email: 'john@example.com',
    }));
  }
});

Message Queue

Messages sent while disconnected are buffered and flushed on reconnect:

const ws = WSKit.connect(url, {
  queueWhileDisconnected: true,  // default
  maxQueueSize: 100,             // default
});

// These will be queued if not connected yet
ws.send({ type: 'init', token: 'abc' });
ws.send({ type: 'subscribe', channel: 'updates' });

// Check queue
console.log(ws.queueSize); // 2

// Clear queue if needed
ws.clearQueue();

Front-End Configuration

const ws = WSKit.connect('wss://yourserver.com/ws', {
  // Reconnection
  reconnect: true,              // auto-reconnect (default: true)
  reconnectBaseMs: 1000,        // initial delay (default: 1000)
  reconnectMaxMs: 30000,        // max delay (default: 30000)
  maxReconnectAttempts: 0,      // 0 = unlimited (default: 0)

  // Heartbeat
  heartbeatMs: 30000,           // ping interval (default: 30000)
  heartbeatMessage: { type: 'ping' },

  // Message queue
  queueWhileDisconnected: true, // buffer sends (default: true)
  maxQueueSize: 100,            // max queue size (default: 100)

  // JSON
  autoJSON: true,               // auto parse/stringify (default: true)
  typeField: 'type',            // channel routing field (default: 'type')

  // Request/response
  requestTimeout: 10000,        // timeout in ms (default: 10000)
  idField: '_id',               // matching field (default: '_id')

  // Debug
  debug: false,                 // console logging (default: false)

  // Callbacks
  onOpen: () => {},
  onClose: (e) => {},
  onError: (e) => {},
  onMessage: (data) => {},
  onReconnect: (attempt) => {},
  onStateChange: (newState, prevState) => {},
});

API

Related Packages

Website: rte.whitneys.co · GitHub: MIR-2025/rte

Backend Examples

Node.js (ws)

import { WebSocketServer } from 'ws';

const wss = new WebSocketServer({ port: 8080 });

wss.on('connection', (socket) => {
  socket.on('message', (raw) => {
    const msg = JSON.parse(raw);

    switch (msg.type) {
      case 'chat':
        // Broadcast to all clients
        wss.clients.forEach((client) => {
          if (client.readyState === 1) {
            client.send(JSON.stringify(msg));
          }
        });
        break;

      case 'getUser':
        // Request/response — echo back _id
        socket.send(JSON.stringify({
          _id: msg._id,
          name: 'John',
          email: 'john@example.com',
        }));
        break;

      case 'ping':
        socket.send(JSON.stringify({ type: 'pong' }));
        break;
    }
  });
});

Python (websockets)

import asyncio, json, websockets

connected = set()

async def handler(ws):
    connected.add(ws)
    try:
        async for raw in ws:
            msg = json.loads(raw)

            if msg.get("type") == "chat":
                for client in connected:
                    if client != ws:
                        await client.send(json.dumps(msg))

            elif msg.get("type") == "getUser":
                await ws.send(json.dumps({
                    "_id": msg["_id"],
                    "name": "John",
                    "email": "john@example.com",
                }))

            elif msg.get("type") == "ping":
                await ws.send(json.dumps({"type": "pong"}))
    finally:
        connected.discard(ws)

asyncio.run(websockets.serve(handler, "0.0.0.0", 8080))

Go (gorilla/websocket)

package main

import (
    "encoding/json"
    "log"
    "net/http"
    "github.com/gorilla/websocket"
)

var upgrader = websocket.Upgrader{CheckOrigin: func(r *http.Request) bool { return true }}

func handler(w http.ResponseWriter, r *http.Request) {
    conn, _ := upgrader.Upgrade(w, r, nil)
    defer conn.Close()

    for {
        _, raw, err := conn.ReadMessage()
        if err != nil { break }

        var msg map[string]interface{}
        json.Unmarshal(raw, &msg)

        switch msg["type"] {
        case "getUser":
            resp, _ := json.Marshal(map[string]interface{}{
                "_id":   msg["_id"],
                "name":  "John",
                "email": "john@example.com",
            })
            conn.WriteMessage(websocket.TextMessage, resp)

        case "ping":
            resp, _ := json.Marshal(map[string]string{"type": "pong"})
            conn.WriteMessage(websocket.TextMessage, resp)
        }
    }
}

func main() {
    http.HandleFunc("/ws", handler)
    log.Fatal(http.ListenAndServe(":8080", nil))
}

PHP (Ratchet)

<?php
// composer require cboden/ratchet

use Ratchet\MessageComponentInterface;
use Ratchet\ConnectionInterface;
use Ratchet\Server\IoServer;
use Ratchet\Http\HttpServer;
use Ratchet\WebSocket\WsServer;

require __DIR__ . '/vendor/autoload.php';

class Handler implements MessageComponentInterface {
    protected $clients;

    public function __construct() {
        $this->clients = new \SplObjectStorage;
    }

    public function onOpen(ConnectionInterface $conn) {
        $this->clients->attach($conn);
    }

    public function onMessage(ConnectionInterface $from, $raw) {
        $msg = json_decode($raw, true);

        switch ($msg['type'] ?? '') {
            case 'chat':
                // Broadcast to all other clients
                foreach ($this->clients as $client) {
                    if ($client !== $from) {
                        $client->send(json_encode($msg));
                    }
                }
                break;

            case 'getUser':
                // Request/response — echo back _id
                $from->send(json_encode([
                    '_id'   => $msg['_id'],
                    'name'  => 'John',
                    'email' => 'john@example.com',
                ]));
                break;

            case 'ping':
                $from->send(json_encode(['type' => 'pong']));
                break;
        }
    }

    public function onClose(ConnectionInterface $conn) {
        $this->clients->detach($conn);
    }

    public function onError(ConnectionInterface $conn, \Exception $e) {
        $conn->close();
    }
}

$server = IoServer::factory(
    new HttpServer(new WsServer(new Handler())),
    8080
);
$server->run();

License

MIT — phpMyDEV, LLC