Creates a new client. Every call returns an independent instance — there is no
shared singleton.
import { defineClient } from " durablews " ;
const client = defineClient ( { url: " wss://example.com/socket " } );
Typing, three ways: pass a schema (types inferred + runtime validation),
pass generics (defineClient<Incoming, Outgoing>(config)), or neither
(messages are unknown).
Option Type Default urlstring | URL— required protocolsstring | string[]— passed to the underlying WebSocket codecCodecjsonCodecthe wire seam reconnectfalse | ReconnectOptionson durability tuning queuefalse | QueueOptionson, maxSize: 256 queueing heartbeatHeartbeatOptionsoff heartbeat schemaStandardSchemaV1— typed messages
Member Signature Notes stateConnectionStatelive getter: idle | connecting | open | closing | reconnecting | closed connect()() => Promise<void>resolves on first open (incl. a successful retry); idempotent; rejects only on terminal failure — details send(data)(data: TOut) => voidqueues while connecting/reconnecting; throws in idle/closing/closed close(code?, reason?)never triggers reconnection on(event, handler)returns unsubscribe typed per event (below) use(middleware)returns the client bare function = inbound; { inbound?, outbound? } = per direction — middleware getState()() => ClientStatefrozen { state, lastError, retryAttempt, queueLength }; referentially stable between changes subscribe(listener)returns unsubscribe fires on any snapshot change
Event Payload Fires when open— the socket opened (after the queue flushed) messageTIna message was decoded and (if configured) validated closeCloseEventthe socket closed, clean or not errorEvent | Errortransport error, middleware throw, schema failure (SchemaValidationError), heartbeat timeout statechange{ previous, current }the FSM transitioned reconnecting{ attempt, delay }a retry was scheduled (once per attempt) drop{ data: TOut, reason: "overflow" | "close" }a queued message will never be sent
Export What it is jsonCodecthe default codec (JSON with binary passthrough) pingpongopt-in inbound middleware: auto-replies to "ping" with "pong", without emitting message RECONNECT_DEFAULTS / QUEUE_DEFAULTSthe resolved default option values HEARTBEAT_TIMEOUT_CODE4408 — the close code a heartbeat timeout uses (filter it in shouldReconnect)SchemaValidationErrorthe error payload for invalid inbound messages; carries the schema’s issues
All public types are exported: WebSocketClient, WebSocketClientConfig,
Codec, ConnectionState, ClientState, ClientEventMap, Middleware,
MessageContext, OutboundMiddleware, OutboundContext,
DirectionalMiddleware, ReconnectOptions, QueueOptions,
HeartbeatOptions, DropEvent, ReconnectingEvent, StateChange,
StandardSchemaV1.
Subpath Export durablews/vueuseWebSocket composableVue guide — optional peer vue >= 3.2durablews/reactuseWebSocket hookReact guide — optional peer react >= 18
Installing durablews without the frameworks never warns; framework code
loads only via its subpath.