WebSocketStream: WebSocketStream() constructor

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

Note: This feature is available in Web Workers.

Non-standard: This feature is not standardized. We do not recommend using non-standard features in production, as they have limited browser support, and may change or be removed. However, they can be a suitable alternative in specific cases where no standard option exists.

The WebSocketStream() constructor creates a new WebSocketStream object instance.

Syntax

js
new WebSocketStream(url)
new WebSocketStream(url, options)

Parameters

url

A string representing the URL of the WebSocket server you want to connect to with this WebSocketStream instance. Allowed URL schemes are "ws", "wss", "http", and "https".

options Optional

An object that can contain the following properties:

protocols Optional

A single string or an array of strings representing the sub-protocol(s) that the client would like to use, for example "amqp" or "mqtt". Subprotocols may be selected from the IANA WebSocket Subprotocol Name Registry or may be custom names jointly understood by the client and the server. A single server can implement multiple WebSocket sub-protocols, and handle different types of interactions depending on the specified value. If it is omitted, an empty array is used by default. If protocols is included, the connection will only be established if the server reports that it has selected one of these sub-protocols.

signal Optional

An AbortSignal, which can be used to abort the connection before the handshake has completed (that is, before the opened promise resolves). This is primarily intended to help implement connection timeouts. As such, it does nothing after the connection is established.

js
const queueWSS = new WebSocketStream("wss://example.com/queue", {
  signal: AbortSignal.timeout(5000),
});

Note that if you're connecting to localhost, it's likely to succeed or fail before the connection attempt times out.

Once the connection is established, signal has no effect: to close a connection that's already established, call the WebSocketStream.close() method. Closing the underlying WritableStream or WritableStreamDefaultWriter also closes the socket.

See Using WebSocketStream to write a client for a complete example with full explanation.