websocket

@nostrwatch/websocket

Cross-platform WebSocket client with a unified event-driven API for Node.js, browser, and Deno.

Overview

@nostrwatch/websocket wraps platform-specific WebSocket implementations behind the UniversalWebSocket class, providing a consistent on/once/off event API and connection lifecycle management across Node.js, browser, and Deno environments. The class detects the runtime automatically and selects the appropriate underlying implementation (ws in Node.js, native WebSocket in browser/Deno). It is the WebSocket foundation used by the relay check adapters in @nostrwatch/nocap.

A relay in Nostr is a WebSocket server (identified by a wss:// URL) that stores and forwards signed protocol messages (events). UniversalWebSocket connects to these endpoints and handles connection state, message dispatch, and graceful teardown regardless of the JavaScript runtime.

Installation

pnpm add @nostrwatch/websocket

Or with npm:

npm install @nostrwatch/websocket

Quick Start

import {UniversalWebSocket} from '@nostrwatch/websocket'

const ws = new UniversalWebSocket('wss://relay.damus.io')
ws.on('open', () => console.log('connected'))
ws.on('message', (ev) => console.log('received:', ev.data))
await ws.connect()

ws.send(JSON.stringify(['REQ', 'sub1', {kinds: [1], limit: 1}]))
// received: ["EVENT","sub1",{"id":"...","kind":1,...}]

API

UniversalWebSocket

class UniversalWebSocket {
  constructor(relay: string, protocols?: string | string[], options?: UniversalWebSocketOptions)
  static create(relay: string, protocols?: string | string[], options?: UniversalWebSocketOptions): Promise<UniversalWebSocket>
}

Constructor

new UniversalWebSocket(relay: string, protocols?, options?)

Creates a new cross-platform WebSocket instance. By default (autoConnect: true), begins connecting immediately in the background. To control connection timing manually, set autoConnect: false and call connect() when ready.

Parameter	Type	Description
relay	string	WebSocket URL of the relay (e.g. wss://relay.damus.io)
protocols	string | string[]	Optional WebSocket subprotocols
options	UniversalWebSocketOptions	Optional configuration object

UniversalWebSocketOptions

Option	Type	Default	Description
autoConnect	boolean	true	Connect automatically on construction
connectTimeout	number	10000	Timeout in milliseconds before connect() rejects
agent	unknown	undefined	HTTP agent for Node.js proxy support
wsOptions	Record<string, unknown>	undefined	Additional options forwarded to the underlying ws constructor in Node.js

---

UniversalWebSocket.create()

static async create(relay: string, protocols?, options?): Promise<UniversalWebSocket>

Factory method that creates an instance with autoConnect: false, calls connect(), and resolves when the connection is open. Use this when you need to await a fully connected socket before proceeding.

---

Event methods

on(type, listener)

on<K extends WebSocketEventType>(type: K, listener: WebSocketListener<K>): void

Registers a persistent event listener. Fires on every occurrence of the event.

once(type, listener)

once<K extends WebSocketEventType>(type: K, listener: WebSocketListener<K>): void

Registers a one-shot event listener. Automatically removed after the first invocation.

off(type?, listener?)

off<K extends WebSocketEventType>(type?: K, listener?: WebSocketListener<K>): void

Removes event listeners. With no arguments, clears all listeners for all event types. With only type, clears all listeners for that type. With both arguments, removes the specific listener.

addEventListener(type, listener) / removeEventListener(type, listener)

DOM-compatible aliases for on and off. Useful when passing a UniversalWebSocket to code that expects a native WebSocket.

---

Lifecycle methods

connect()

async connect(): Promise<boolean>

Initiates the WebSocket connection. Resolves true when the connection opens, false if the connection fails or times out. Safe to call multiple times — concurrent calls share the same promise.

ready()

async ready(): Promise<void>

Awaits a successful connection. Throws if the connection fails. Use this when you want to ensure the socket is open before sending.

closed()

async closed(): Promise<void>

Resolves when the socket transitions to the CLOSED state.

close(code?, reason?)

close(code?: number, reason?: string): void

Initiates a graceful WebSocket close handshake with an optional close code and reason string.

terminate()

terminate(): void

Forcefully destroys the connection without completing the close handshake. In browser environments where terminate() is not available on native WebSocket, falls back to close().

---

Communication

send(data)

send(data: unknown): void

Sends data over the open WebSocket. Accepts strings, Blob, ArrayBuffer, ArrayBufferView, plain objects (JSON-serialized automatically), or arrays (JSON-serialized automatically). Throws if the socket is not connected.

---

Properties

Property	Type	Description
readyState	number	Current connection state: 0 CONNECTING, 1 OPEN, 2 CLOSING, 3 CLOSED
url	string	The relay URL this socket was constructed with
CONNECTED	boolean	Alias for readyState === 1
CONNECTING	boolean	Alias for readyState === 0
CLOSING	boolean	Alias for readyState === 2
CLOSED	boolean	Alias for readyState === 3
BUSY	boolean	True while CONNECTING or CLOSING
OPEN	boolean	Alias for CONNECTED

Convenience state-check methods: isConnecting(), isConnected(), isOpen(), isClosing(), isClosed().

---

Events

Event	Payload type	Description
open	Event	Connection established
message	MessageEvent<string | Buffer | ArrayBuffer | Blob>	Message received from the relay
close	CloseEvent	Connection closed; inspect ev.code and ev.reason
error	Event	Connection error occurred

---

Types

type WebSocketEventType = 'open' | 'close' | 'error' | 'message'
type Sendable = string | ArrayBufferLike | Blob | ArrayBufferView
type WebSocketData = Sendable | Buffer

interface UniversalWebSocketOptions {
  agent?: unknown
  connectTimeout?: number
  autoConnect?: boolean
  wsOptions?: Record<string, unknown>
}

Known Limitations

No known limitations at this time.

Agent Skills

No agent skills defined yet for this package.

Related Packages

• @nostrwatch/nocap — relay capability checker; uses @nostrwatch/websocket as its underlying WebSocket transport via the websocket adapter
• @nostrwatch/route66 — relay aggregation layer; websocket adapter wraps UniversalWebSocket for connection pooling
• @nostrwatch/memory-relay — in-memory relay for testing; pairs with UniversalWebSocket in integration test scenarios

License

MIT