@proj-airi/better-ws

Runtime-agnostic WebSocket primitives for reliable realtime connections.

What it does

• Provides createClient(...) and createServer(...) runtime primitives.
• Tracks client connection state and schedules reconnects after unexpected closes.
• Tracks server peers and supports peer send, broadcast, and named groups.
• Dispatches raw caller-owned messages without imposing an event, RPC, or extension protocol.

How to use

import { createClient } from '@proj-airi/better-ws'
import { createServer } from '@proj-airi/better-ws/server'

const client = createClient({
  url: 'ws://localhost:3000/ws',
  // Reconnect is enabled by default; pass an object to customize the policy.
  reconnect: {
    retries: Number.POSITIVE_INFINITY,
    delay: attempt => Math.min(1000 * 2 ** (attempt - 1), 30_000),
  },
})

await client.connect()
client.send('hello')

const server = createServer<string>()

server.onMessage(({ server, message }) => {
  server.broadcast(message)
})

const peer = server.accept({
  id: 'peer-1',
  send(message) {
    console.info('send to runtime', message)
    return true
  },
})

peer.receive('hello')

Server peer liveness is opt-in and scheduler-driven. It tracks inbound traffic without imposing any protocol event shape. checkLiveness() evaluates peers.unhealthyTimeout and peers.closeTimeout; server-side heartbeat mode, interval, message, and isResponse are reserved for app or adapter driven scheduling and do not automatically send pings or classify responses.

const server = createServer<string>({
  peers: {
    unhealthyTimeout: 60_000,
    closeTimeout: 120_000,
  },
  heartbeat: {
    timeout: 60_000,
  },
})

server.onPeerHealthChange(({ peer, healthy, silentFor }) => {
  console.info('peer health changed', peer.id, healthy, silentFor)
})

setInterval(() => {
  server.checkLiveness()
}, 30_000)

Heartbeat is opt-in. This example uses an application-level message heartbeat. Message heartbeat mode requires message so the client knows what to send:

const client = createClient({
  url: 'ws://localhost:3000/ws',
  heartbeat: {
    mode: 'message',
    message: 'ping',
    isResponse: message => message === 'pong',
    interval: 30_000,
    timeout: 10_000,
  },
})

Native ping heartbeat is used only when a connector exposes ping(). In auto mode, the client uses native ping() when available and falls back to message heartbeat only when message is provided. The built-in browser WebSocket adapter does not expose native ping frames.

When isResponse is provided, heartbeat uses strict response matching: only a matching inbound message clears the pending heartbeat timeout. When isResponse is omitted, any inbound message is treated as liveness and clears the pending timeout.

For non-text messages or non-native runtimes, pass a connector. The connector owns parsing and serialization:

const client = createClient<string>({
  connector: {
    async connect(events) {
      const ws = new WebSocket('ws://localhost:3000/ws')
      ws.addEventListener('message', event => events.message(String(event.data)))
      ws.addEventListener('close', event => events.close({ code: event.code, reason: event.reason, wasClean: event.wasClean }))
      ws.addEventListener('error', event => events.error(event))

      await new Promise<void>((resolve) => {
        ws.addEventListener('open', () => resolve(), { once: true })
      })

      return {
        send: next => ws.send(next),
        close: (code, reason) => ws.close(code, reason),
      }
    },
  },
})

await client.connect()
client.send('hello')

When to use

• You need connection lifecycle, peer registry, reconnect, and broadcast primitives.
• You want to keep message shape controlled by the application or a higher-level adapter.
• You are building an Eventa, JSON-RPC, extension, or custom protocol adapter on top.

When not to use

• You need a full application protocol out of the box.
• You want Socket.IO-compatible clients or packet formats.
• You only need one direct native WebSocket without reconnect or peer management.

License

MIT