WebSocketRoute

WebSocket endpoints.

WebSocketRoute is the RouteVariant.websocket member of the RouteBase family. It is the one route kind that does not produce a response: App.composeRoutes sees the variant and upgrades the connection instead, storing the route itself as the socket's data so that every later event can be dispatched back to its callbacks.

import { WebSocketRoute } from "@ozanarslan/corpus";

new WebSocketRoute("/chat", {
	onOpen: (ws) => ws.subscribe("room"),
	onMessage: (ws, message) => ws.publish("room", message),
});

Since one route instance backs every connection to that endpoint, per-socket state belongs on the socket — through Bun's subscribe/publish or a map keyed by socket — not on the route.

WebSocketRoute

class

class WebSocketRoute<E extends string = string>extends RouteBase<never, never, never, WebSocketRoute, E>

A WebSocket endpoint.

Constructing one registers it on the nearest App, which upgrades matching requests rather than responding to them. The callbacks are shared by every connection to the endpoint, and each event receives the socket it concerns.

Type parameters

• E — The literal endpoint type, carried so the endpoint stays narrowly typed at the call site.

WebSocketRoute.constructor()

constructor();
constructor(endpoint: E, definition: WebSocketRouteDefinition);
constructor(endpoint?: E, definition?: WebSocketRouteDefinition)

Creates a websocket route for subclasses, which declare WebSocketRoute.endpoint and the callbacks as class fields and call RouteBase.register themselves.

Creates a websocket route and registers it on the nearest App.

Parameters

• endpoint — The path clients connect to.
• definition — The WebSocketRouteDefinition holding the socket lifecycle callbacks.

WebSocketRoute.variant

override readonly variant: RouteVariant

Marks this route as RouteVariant.websocket, which is what tells App.composeRoutes to upgrade rather than respond.

WebSocketRoute.method

override readonly method: Method

Always Method.GET — an upgrade handshake is a GET request.

WebSocketRoute.endpoint

override endpoint!: E

The path clients connect to.

WebSocketRoute.config

override readonly config?: RouteConfig<never, never, never, WebSocketRoute<string>> | undefined

No schemas apply: an upgrade request carries no body, search or params to validate.

WebSocketRoute.handler

override readonly handler: ContextHandler<never, never, never, WebSocketRoute<string>>

Returns the route itself, which App.composeRoutes attaches to the socket as its data — that is how a message arriving minutes later finds its way back to WebSocketRoute.onMessage.

The upgrade itself still happens in App; this handler only supplies what the socket carries.

Returns — This route.

WebSocketRoute.onOpen

onOpen?: WebSocketOnOpen | undefined

Called once per connection, after the upgrade succeeds.

WebSocketRoute.onClose

onClose?: WebSocketOnClose | undefined

Called once per connection, when it closes.

WebSocketRoute.onMessage

onMessage!: WebSocketOnMessage

Called for every message received.

WebSocketOnMessage

type

type WebSocketOnMessage = (ws: ServerWebSocket, message: string | Buffer) => MaybePromise<void>;

Runs for each message a client sends.

Parameters

• ws — The ServerWebSocket the message arrived on.
• message — The payload: a string for text frames, a Buffer for binary ones.

WebSocketOnClose

type

type WebSocketOnClose = (ws: ServerWebSocket, code?: number, reason?: string) => MaybePromise<void>;

Runs when a connection closes, whichever side ended it.

Parameters

• ws — The closing ServerWebSocket.
• code — The WebSocket close code, when one was sent.
• reason — The accompanying reason, when one was sent.

WebSocketOnOpen

type

type WebSocketOnOpen = (ws: ServerWebSocket) => MaybePromise<void>;

Runs once a connection has been upgraded and is ready.

Parameters

• ws — The newly opened ServerWebSocket.

WebSocketRouteDefinition

interface

interface WebSocketRouteDefinition

The socket lifecycle callbacks a WebSocketRoute is built from.