The WebSocket API provides a way to manage a WebSocket connection to a\nserver, allowing bidirectional communication. It follows the\nWHATWG WebSocket specification and RFC 6455, and is intended to be\ninterchangeable with the global WebSocket available in browsers.
import { WebSocket } from 'undici'\n\nconst ws = new WebSocket('wss://echo.websocket.events')\n\nws.addEventListener('open', () => {\n ws.send('Hello, world!')\n})\n\nws.addEventListener('message', (event) => {\n console.log('received:', event.data)\n})\nIn addition to the standard WebSocket interface, this module exports the\nstreams-based WebSocketStream and WebSocketError APIs, as well as a\nping() helper for sending ping frames.
<EventTarget>The WebSocket object represents a single WebSocket connection. Constructing a\nWebSocket immediately begins the opening handshake; the connection cannot be\nreused once it has been closed.
Creates a new WebSocket and begins connecting to url. The second argument\nmay be a string or array of subprotocols, or a WebSocketInit object. The\nobject form is an undici extension and is not available in browsers; it allows a\ncustom dispatcher and additional headers to be supplied.
If a value in protocols is repeated or is not a valid subprotocol name, the\nconstructor throws a SyntaxError DOMException.
import { WebSocket } from 'undici'\n\nconst ws = new WebSocket('wss://echo.websocket.events', ['echo', 'chat'])\nTo route the connection through a custom dispatcher, such as a\nProxyAgent, pass a WebSocketInit object:
import { WebSocket, ProxyAgent } from 'undici'\n\nconst dispatcher = new ProxyAgent('http://localhost:8080')\n\nconst ws = new WebSocket('wss://echo.websocket.events', {\n dispatcher,\n protocols: ['echo', 'chat']\n})\nWebSocket over HTTP/2 is experimental and may change in the future. It can be\nenabled by passing a dispatcher configured with allowH2:
import { WebSocket, Agent } from 'undici'\n\nconst dispatcher = new Agent({ allowH2: true })\n\nconst ws = new WebSocket('wss://echo.websocket.events', {\n dispatcher,\n protocols: ['echo', 'chat']\n})\nStarts the closing handshake. The code is clamped to an unsigned 16-bit\ninteger; when omitted, no status code is sent. The reason is encoded as\nUTF-8 and must not exceed 123 bytes.
ws.close(1000, 'Done')\nEnqueues data to be transmitted to the server. String data is sent as a text\nframe; ArrayBuffer, any TypedArray, DataView, and Blob values are sent\nas binary frames. The number of bytes queued is added to\nwebsocket.bufferedAmount.
If websocket.readyState is CONNECTING, an InvalidStateError\nDOMException is thrown. If the connection is closing or already closed, the\ncall is silently ignored.
ws.send('a text message')\nws.send(new Uint8Array([1, 2, 3]))\nThe current state of the connection. One of the numeric constants\nWebSocket.CONNECTING (0), WebSocket.OPEN (1),\nWebSocket.CLOSING (2), or WebSocket.CLOSED (3). This property is\nread-only.
The number of bytes of data that have been queued using\nwebsocket.send() but not yet transmitted to the network. This value\nresets to 0 once all queued data is sent. This property is read-only.
The absolute URL of the WebSocket as resolved during construction. This\nproperty is read-only.
" }, { "textRaw": "Type: {string}", "name": "extensions", "type": "string", "meta": { "added": [ "v5.15.0" ], "changes": [] }, "desc": "The extensions negotiated by the server, taken from the\nSec-WebSocket-Extensions response header. Empty until the connection is\nestablished. This property is read-only.
The subprotocol selected by the server, taken from the\nSec-WebSocket-Protocol response header. Empty until the connection is\nestablished and only set when a subprotocol was negotiated. This property is\nread-only.
Controls the type used to represent binary data delivered by the\n'message' event. Must be either 'blob' (binary frames are exposed as a\nBlob) or 'arraybuffer' (binary frames are exposed as an ArrayBuffer).\nAssigning any other value resets it to 'blob'.
An event handler for the 'open' event. Setting this property replaces any\npreviously registered onopen handler.
An event handler for the 'error' event. Setting this property replaces any\npreviously registered onerror handler.
An event handler for the 'close' event. Setting this property replaces any\npreviously registered onclose handler.
An event handler for the 'message' event. Setting this property replaces\nany previously registered onmessage handler.
Emitted when the WebSocket connection is established. After this event,\nwebsocket.readyState is OPEN and data may be sent with\nwebsocket.send(). The listener receives an Event.
Emitted when a message is received from the server. The listener receives a\nMessageEvent whose data property is a string for text frames, and either a\nBlob or an ArrayBuffer for binary frames depending on\nwebsocket.binaryType. The event's origin is the origin of\nwebsocket.url.
Emitted when the connection is terminated abnormally, for example when no close\nframe was received before the underlying transport was lost. The listener\nreceives an ErrorEvent.
Emitted when the connection is closed. The listener receives a CloseEvent\nwhose code and reason describe why the connection closed, and whose\nwasClean property is true only when the closing handshake completed in both\ndirections.
WebSocketStream is a streams-based alternative to the event-based\nWebSocket interface, exposing a connection as a pair of ReadableStream\nand WritableStream objects. See MDN for background.
Constructing a WebSocketStream for the first time emits an\nExperimentalWarning with the code UNDICI-WSS.
Creates a new WebSocketStream and begins connecting to url. As with\nnew WebSocket(), a repeated or invalid subprotocol causes a SyntaxError\nDOMException to be thrown.
import { WebSocketStream } from 'undici'\n\nconst stream = new WebSocketStream('wss://echo.websocket.events')\nconst { readable, writable } = await stream.opened\n\nconst writer = writable.getWriter()\nawait writer.write('Hello, world!')\nwriter.releaseLock()\n\nconst reader = readable.getReader()\nconst { value } = await reader.read()\nconsole.log('received:', value)\nThe serialized URL of the WebSocket. This property is read-only.
" }, { "textRaw": "Type: {Promise} Fulfills once the connection is established.", "name": "opened", "type": "Promise", "meta": { "added": [ "v5.15.0" ], "changes": [] }, "stability": 1, "stabilityText": "Experimental", "desc": "A promise that resolves with an object describing the open connection, or\nrejects if the connection could not be established. The fulfillment value has\nthe following shape:
\nextensions <string> The negotiated extensions.protocol <string> The negotiated subprotocol.readable <ReadableStream> A stream of incoming messages. Text frames are\ndelivered as strings and binary frames as Uint8Array chunks.writable <WritableStream> A stream for sending messages. Writing a string\nsends a text frame; writing a BufferSource sends a binary frame.A promise that resolves with a WebSocketCloseInfo object when the connection\ncloses cleanly, or rejects with a WebSocketError when it closes\nabnormally. The fulfillment value has the following shape:
closeCode <number> The status code the connection was closed with.reason <string> The reason the connection was closed with.Starts the closing handshake. When closeInfo is omitted, the connection is\nclosed without a status code.
<DOMException>An error type used by WebSocketStream to report close information. It is\nused to reject webSocketStream.closed when the connection closes\nabnormally, and may be passed to a stream's abort or cancel operations to close\nthe connection with a specific code and reason.
Creates a new WebSocketError. If reason is non-empty but no closeCode is\ngiven, closeCode defaults to 1000 (\"Normal Closure\"). The closeCode and\nreason are validated, so an out-of-range code or an over-long reason throws.
The status code associated with the error, or null if none was set. This\nproperty is read-only.
The reason associated with the error. This property is read-only.
" } ] } ], "methods": [ { "textRaw": "`ping(websocket[, payload])`", "name": "ping", "type": "method", "meta": { "added": [ "v7.12.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`websocket` {WebSocket} The WebSocket to send the ping frame on.", "name": "websocket", "type": "WebSocket", "desc": "The WebSocket to send the ping frame on." }, { "textRaw": "`payload` {Buffer} Optional payload to include in the ping frame. Must not exceed 125 bytes. **Default:** `undefined`.", "name": "payload", "type": "Buffer", "default": "`undefined`", "desc": "Optional payload to include in the ping frame. Must not exceed 125 bytes.", "optional": true } ] } ], "desc": "Sends a ping control frame to the server. A conforming server replies with a\npong frame containing the same payload, which can be used to keep the connection\nalive or to verify that it is still active.
\nThe frame is only sent when the connection is open; if it is connecting,\nclosing, or closed, the call is a no-op. A TypeError is thrown if payload\nis not a Buffer or is larger than 125 bytes.
import { WebSocket, ping } from 'undici'\n\nconst ws = new WebSocket('wss://echo.websocket.events')\n\nws.addEventListener('open', () => {\n ping(ws)\n ping(ws, Buffer.from('hello'))\n})\n