wshe

WS Helper

A simple yet modern websocket client.

Installation

pnpm i wshe

Usage

import { createWSHE } from 'wshe'

const wshe = createWSHE('wss://echo.websocket.org', {
  // Pass this to automatically connect on creation
  immediate: true
})

// You can also connect manually
wshe.connect()

// You can send something
wshe.send('<eventName>', '<eventPayload>')

// or send raw data
wshe.sendRaw('<rawData>')
wshe.subscribeRaw((data) => {})

// You can listen to messages
const unsubscribe = wshe.subscribe('<eventName>', (payload) => {})

Server implementation

You should implement a server to transfer messages between clients.

And do this on onmessage to handle heartbeat requests:

import { getHeartbeatResponse, isHeartbeatRequest } from 'wshe/server'

ws.onmessage = (message) => {
  if (isHeartbeatRequest(message)) {
    ws.send(getHeartbeatResponse(message))
    return
  }
  // do your own logic here..., e.g.
  JSON.parse(message)
}

Options

interface WSHEConfig {
  /**
   * onConnected event callback
   * @default
   * () => {}
   */
  onConnected?: (ws: WebSocket, event: Event) => void
  /**
   * onDisconnected event callback
   * @default
   * () => {}
   */
  onDisconnected?: (ws: WebSocket, event: CloseEvent) => void
  /**
   * onMessage event callback
   * @default
   * () => {}
   */
  onError?: (ws: WebSocket, event: Event) => void

  /**
   * Debugging log
   * @default false
   */
  debugging?: boolean
  /**
   * Connection ws immediately
   * @default false
   */
  immediate?: boolean
  /**
   * Heartbeat configuration
   * @default
   */
  heartbeat?: WSHEHeartbeatConfig

  /**
   * Auto reconnect
   * @default false
   */
  autoReconnect?: boolean
}

interface WSHEHeartbeatConfig {
  /**
   * @default 5000
   */
  interval?: number
  /**
   * @default "ping"
   */
  pingMessage?: string
  /**
   * @default "pong"
   */
  pongMessage?: string
  /**
   * @default 10000
   */
  timeout?: number
}

TypeScript Support

This library is written in TypeScript and provides good support for it.

Set message type will be like this:

const wshe = createWSHE<{
  foo: {
    bar: string
  }
  baz: {
    qux: number
  }
}>('...')

wshe.subscribe('foo', (payload) => {
  //                   ^? { bar: string }
})

wshe.subscribe('baz', (payload) => {
  //                   ^? { qux: number }
})

Credits

This project is highly inspired by wsgo.

License

MIT