Client

@wooksjs/ws-client is a type-safe WebSocket client with RPC support, automatic reconnection, and push event handling. It works in both browsers and Node.js.

For the full API reference, see the Wooks WS Client Documentation.

Installation

npm install @wooksjs/ws-client

No extra dependency is needed in browsers or Node.js >= 22 — the client uses the global WebSocket. Only on Node.js < 22 do you need a polyfill such as the ws package.

Quick Overview

import { createWsClient } from '@wooksjs/ws-client'

const client = createWsClient('ws://localhost:3000/ws', {
  reconnect: true,
  rpcTimeout: 5000,
})

The client provides three main communication patterns:

Method	Description
send(event, path, data?)	Fire-and-forget — no reply expected
call(event, path, data?)	RPC — returns a promise with server response
on(event, path, handler)	Listen for server-initiated push messages

Example

// RPC — join a room and get a response
const result = await client.call<{ joined: boolean }>(
  'join', '/chat/general', { name: 'Alice' },
)

// Listen for broadcasts from the room
client.on('message', '/chat/general', ({ data }) => {
  console.log(`${data.from}: ${data.text}`)
})

// Fire-and-forget — send a chat message
client.send('message', '/chat/general', { from: 'Alice', text: 'Hello!' })

Key Features

• RPC with correlation — call() auto-generates IDs and matches replies via promises
• Push listeners — on() supports exact path and wildcard (/chat/*) matching
• Auto-reconnection — configurable exponential or linear backoff, queues messages while disconnected
• Error handling — call() rejects with WsClientError (timeout, server errors)
• Lifecycle hooks — onOpen(), onClose(), onError(), onReconnect()
• Subscriptions — subscribe() with auto-resubscribe on reconnect

See the full client documentation for detailed API reference, configuration options, reconnection strategies, and error handling.