{ "type": "module", "source": "doc/api/api-websocket.md", "modules": [ { "textRaw": "Class: WebSocket", "name": "class:_websocket", "type": "module", "desc": "

Extends: EventTarget

\n

The WebSocket object provides a way to manage a WebSocket connection to a server, allowing bidirectional communication. The API follows the WebSocket spec and RFC 6455.

", "signatures": [ { "textRaw": "`new WebSocket(url[, protocol])`", "name": "WebSocket", "type": "ctor", "params": [ { "name": "url" }, { "name": "protocol", "optional": true } ], "desc": "

Arguments:

\n", "modules": [ { "textRaw": "WebSocketInit", "name": "websocketinit", "type": "module", "desc": "

When passing an object as the second argument, the following options are available:

\n", "displayName": "WebSocketInit" }, { "textRaw": "Example:", "name": "example:", "type": "module", "desc": "

This example will not work in browsers or other platforms that don't allow passing an object.

\n
import { WebSocket, ProxyAgent } from 'undici'\n\nconst proxyAgent = new ProxyAgent('my.proxy.server')\n\nconst ws = new WebSocket('wss://echo.websocket.events', {\n  dispatcher: proxyAgent,\n  protocols: ['echo', 'chat']\n})\n
\n

If you do not need a custom Dispatcher, it's recommended to use the following pattern:

\n
import { WebSocket } from 'undici'\n\nconst ws = new WebSocket('wss://echo.websocket.events', ['echo', 'chat'])\n
", "displayName": "Example:" }, { "textRaw": "Example with HTTP/2:", "name": "example_with_http/2:", "type": "module", "desc": "
\n

⚠️ Warning: WebSocket over HTTP/2 is experimental, it is likely to change in the future.

\n
\n
\n

🗒️ Note: WebSocket over HTTP/2 may be enabled by default in a future version,\nthis will happen by enabling HTTP/2 connections as the default behavior of Undici's Agent as well the global dispatcher.\nStay tuned to the changelog for more information.

\n
\n

This example will not work in browsers or other platforms that don't allow passing an object.

\n
import { Agent } from 'undici'\n\nconst agent = new Agent({ allowH2: true })\n\nconst ws = new WebSocket('wss://echo.websocket.events', {\n  dispatcher: agent,\n  protocols: ['echo', 'chat']\n})\n
", "displayName": "Example with HTTP/2:" }, { "textRaw": "WebSocketInit", "name": "websocketinit", "type": "module", "desc": "

When passing an object as the second argument, the following options are available:

\n", "displayName": "WebSocketInit" }, { "textRaw": "Example:", "name": "example:", "type": "module", "desc": "

This example will not work in browsers or other platforms that don't allow passing an object.

\n
import { WebSocket, ProxyAgent } from 'undici'\n\nconst proxyAgent = new ProxyAgent('my.proxy.server')\n\nconst ws = new WebSocket('wss://echo.websocket.events', {\n  dispatcher: proxyAgent,\n  protocols: ['echo', 'chat']\n})\n
\n

If you do not need a custom Dispatcher, it's recommended to use the following pattern:

\n
import { WebSocket } from 'undici'\n\nconst ws = new WebSocket('wss://echo.websocket.events', ['echo', 'chat'])\n
", "displayName": "Example:" }, { "textRaw": "Example with HTTP/2:", "name": "example_with_http/2:", "type": "module", "desc": "
\n

⚠️ Warning: WebSocket over HTTP/2 is experimental, it is likely to change in the future.

\n
\n
\n

🗒️ Note: WebSocket over HTTP/2 may be enabled by default in a future version,\nthis will happen by enabling HTTP/2 connections as the default behavior of Undici's Agent as well the global dispatcher.\nStay tuned to the changelog for more information.

\n
\n

This example will not work in browsers or other platforms that don't allow passing an object.

\n
import { Agent } from 'undici'\n\nconst agent = new Agent({ allowH2: true })\n\nconst ws = new WebSocket('wss://echo.websocket.events', {\n  dispatcher: agent,\n  protocols: ['echo', 'chat']\n})\n
", "displayName": "Example with HTTP/2:" } ] }, { "textRaw": "`new WebSocket(url[, protocol])`", "name": "WebSocket", "type": "ctor", "params": [ { "name": "url" }, { "name": "protocol", "optional": true } ], "desc": "

Arguments:

\n", "modules": [ { "textRaw": "WebSocketInit", "name": "websocketinit", "type": "module", "desc": "

When passing an object as the second argument, the following options are available:

\n", "displayName": "WebSocketInit" }, { "textRaw": "Example:", "name": "example:", "type": "module", "desc": "

This example will not work in browsers or other platforms that don't allow passing an object.

\n
import { WebSocket, ProxyAgent } from 'undici'\n\nconst proxyAgent = new ProxyAgent('my.proxy.server')\n\nconst ws = new WebSocket('wss://echo.websocket.events', {\n  dispatcher: proxyAgent,\n  protocols: ['echo', 'chat']\n})\n
\n

If you do not need a custom Dispatcher, it's recommended to use the following pattern:

\n
import { WebSocket } from 'undici'\n\nconst ws = new WebSocket('wss://echo.websocket.events', ['echo', 'chat'])\n
", "displayName": "Example:" }, { "textRaw": "Example with HTTP/2:", "name": "example_with_http/2:", "type": "module", "desc": "
\n

⚠️ Warning: WebSocket over HTTP/2 is experimental, it is likely to change in the future.

\n
\n
\n

🗒️ Note: WebSocket over HTTP/2 may be enabled by default in a future version,\nthis will happen by enabling HTTP/2 connections as the default behavior of Undici's Agent as well the global dispatcher.\nStay tuned to the changelog for more information.

\n
\n

This example will not work in browsers or other platforms that don't allow passing an object.

\n
import { Agent } from 'undici'\n\nconst agent = new Agent({ allowH2: true })\n\nconst ws = new WebSocket('wss://echo.websocket.events', {\n  dispatcher: agent,\n  protocols: ['echo', 'chat']\n})\n
", "displayName": "Example with HTTP/2:" }, { "textRaw": "WebSocketInit", "name": "websocketinit", "type": "module", "desc": "

When passing an object as the second argument, the following options are available:

\n", "displayName": "WebSocketInit" }, { "textRaw": "Example:", "name": "example:", "type": "module", "desc": "

This example will not work in browsers or other platforms that don't allow passing an object.

\n
import { WebSocket, ProxyAgent } from 'undici'\n\nconst proxyAgent = new ProxyAgent('my.proxy.server')\n\nconst ws = new WebSocket('wss://echo.websocket.events', {\n  dispatcher: proxyAgent,\n  protocols: ['echo', 'chat']\n})\n
\n

If you do not need a custom Dispatcher, it's recommended to use the following pattern:

\n
import { WebSocket } from 'undici'\n\nconst ws = new WebSocket('wss://echo.websocket.events', ['echo', 'chat'])\n
", "displayName": "Example:" }, { "textRaw": "Example with HTTP/2:", "name": "example_with_http/2:", "type": "module", "desc": "
\n

⚠️ Warning: WebSocket over HTTP/2 is experimental, it is likely to change in the future.

\n
\n
\n

🗒️ Note: WebSocket over HTTP/2 may be enabled by default in a future version,\nthis will happen by enabling HTTP/2 connections as the default behavior of Undici's Agent as well the global dispatcher.\nStay tuned to the changelog for more information.

\n
\n

This example will not work in browsers or other platforms that don't allow passing an object.

\n
import { Agent } from 'undici'\n\nconst agent = new Agent({ allowH2: true })\n\nconst ws = new WebSocket('wss://echo.websocket.events', {\n  dispatcher: agent,\n  protocols: ['echo', 'chat']\n})\n
", "displayName": "Example with HTTP/2:" } ] } ], "displayName": "Class: WebSocket" }, { "textRaw": "Class: WebSocketStream", "name": "class:_websocketstream", "type": "module", "desc": "
\n

⚠️ Warning: the WebSocketStream API has not been finalized and is likely to change.

\n
\n

See MDN for more information.

", "signatures": [ { "textRaw": "`new WebSocketStream(url[, protocol])`", "name": "WebSocketStream", "type": "ctor", "params": [ { "name": "url" }, { "name": "protocol", "optional": true } ], "desc": "

Arguments:

\n", "modules": [ { "textRaw": "WebSocketStream Example", "name": "websocketstream_example", "type": "module", "desc": "
const stream = new WebSocketStream('https://echo.websocket.org/')\nconst { readable, writable } = await stream.opened\n\nasync function read () {\n  /** @type {ReadableStreamReader} */\n  const reader = readable.getReader()\n\n  while (true) {\n    const { done, value } = await reader.read()\n    if (done) break\n\n    // do something with value\n  }\n}\n\nasync function write () {\n  /** @type {WritableStreamDefaultWriter} */\n  const writer = writable.getWriter()\n  writer.write('Hello, world!')\n  writer.releaseLock()\n}\n\nread()\n\nsetInterval(() => write(), 5000)\n\n
", "displayName": "WebSocketStream Example" }, { "textRaw": "WebSocketStream Example", "name": "websocketstream_example", "type": "module", "desc": "
const stream = new WebSocketStream('https://echo.websocket.org/')\nconst { readable, writable } = await stream.opened\n\nasync function read () {\n  /** @type {ReadableStreamReader} */\n  const reader = readable.getReader()\n\n  while (true) {\n    const { done, value } = await reader.read()\n    if (done) break\n\n    // do something with value\n  }\n}\n\nasync function write () {\n  /** @type {WritableStreamDefaultWriter} */\n  const writer = writable.getWriter()\n  writer.write('Hello, world!')\n  writer.releaseLock()\n}\n\nread()\n\nsetInterval(() => write(), 5000)\n\n
", "displayName": "WebSocketStream Example" } ] }, { "textRaw": "`new WebSocketStream(url[, protocol])`", "name": "WebSocketStream", "type": "ctor", "params": [ { "name": "url" }, { "name": "protocol", "optional": true } ], "desc": "

Arguments:

\n", "modules": [ { "textRaw": "WebSocketStream Example", "name": "websocketstream_example", "type": "module", "desc": "
const stream = new WebSocketStream('https://echo.websocket.org/')\nconst { readable, writable } = await stream.opened\n\nasync function read () {\n  /** @type {ReadableStreamReader} */\n  const reader = readable.getReader()\n\n  while (true) {\n    const { done, value } = await reader.read()\n    if (done) break\n\n    // do something with value\n  }\n}\n\nasync function write () {\n  /** @type {WritableStreamDefaultWriter} */\n  const writer = writable.getWriter()\n  writer.write('Hello, world!')\n  writer.releaseLock()\n}\n\nread()\n\nsetInterval(() => write(), 5000)\n\n
", "displayName": "WebSocketStream Example" }, { "textRaw": "WebSocketStream Example", "name": "websocketstream_example", "type": "module", "desc": "
const stream = new WebSocketStream('https://echo.websocket.org/')\nconst { readable, writable } = await stream.opened\n\nasync function read () {\n  /** @type {ReadableStreamReader} */\n  const reader = readable.getReader()\n\n  while (true) {\n    const { done, value } = await reader.read()\n    if (done) break\n\n    // do something with value\n  }\n}\n\nasync function write () {\n  /** @type {WritableStreamDefaultWriter} */\n  const writer = writable.getWriter()\n  writer.write('Hello, world!')\n  writer.releaseLock()\n}\n\nread()\n\nsetInterval(() => write(), 5000)\n\n
", "displayName": "WebSocketStream Example" } ] } ], "modules": [ { "textRaw": "ping(websocket, payload)", "name": "ping(websocket,_payload)", "type": "module", "desc": "

Arguments:

\n\n

Sends a ping frame to the WebSocket server. The server must respond with a pong frame containing the same payload data. This can be used for keepalive purposes or to verify that the connection is still active.

", "modules": [ { "textRaw": "Example:", "name": "example:", "type": "module", "desc": "
import { WebSocket, ping } from 'undici'\n\nconst ws = new WebSocket('wss://echo.websocket.events')\n\nws.addEventListener('open', () => {\n  // Send ping with no payload\n  ping(ws)\n\n  // Send ping with payload\n  const payload = Buffer.from('hello')\n  ping(ws, payload)\n})\n
\n

Note: A ping frame cannot have a payload larger than 125 bytes. The ping will only be sent if the WebSocket connection is in the OPEN state.

", "displayName": "Example:" }, { "textRaw": "Example:", "name": "example:", "type": "module", "desc": "
import { WebSocket, ping } from 'undici'\n\nconst ws = new WebSocket('wss://echo.websocket.events')\n\nws.addEventListener('open', () => {\n  // Send ping with no payload\n  ping(ws)\n\n  // Send ping with payload\n  const payload = Buffer.from('hello')\n  ping(ws, payload)\n})\n
\n

Note: A ping frame cannot have a payload larger than 125 bytes. The ping will only be sent if the WebSocket connection is in the OPEN state.

", "displayName": "Example:" } ], "displayName": "ping(websocket, payload)" }, { "textRaw": "Read More", "name": "read_more", "type": "module", "desc": "", "displayName": "Read More" }, { "textRaw": "ping(websocket, payload)", "name": "ping(websocket,_payload)", "type": "module", "desc": "

Arguments:

\n\n

Sends a ping frame to the WebSocket server. The server must respond with a pong frame containing the same payload data. This can be used for keepalive purposes or to verify that the connection is still active.

", "modules": [ { "textRaw": "Example:", "name": "example:", "type": "module", "desc": "
import { WebSocket, ping } from 'undici'\n\nconst ws = new WebSocket('wss://echo.websocket.events')\n\nws.addEventListener('open', () => {\n  // Send ping with no payload\n  ping(ws)\n\n  // Send ping with payload\n  const payload = Buffer.from('hello')\n  ping(ws, payload)\n})\n
\n

Note: A ping frame cannot have a payload larger than 125 bytes. The ping will only be sent if the WebSocket connection is in the OPEN state.

", "displayName": "Example:" }, { "textRaw": "Example:", "name": "example:", "type": "module", "desc": "
import { WebSocket, ping } from 'undici'\n\nconst ws = new WebSocket('wss://echo.websocket.events')\n\nws.addEventListener('open', () => {\n  // Send ping with no payload\n  ping(ws)\n\n  // Send ping with payload\n  const payload = Buffer.from('hello')\n  ping(ws, payload)\n})\n
\n

Note: A ping frame cannot have a payload larger than 125 bytes. The ping will only be sent if the WebSocket connection is in the OPEN state.

", "displayName": "Example:" } ], "displayName": "ping(websocket, payload)" }, { "textRaw": "Read More", "name": "read_more", "type": "module", "desc": "", "displayName": "Read More" } ], "displayName": "Class: WebSocketStream" } ] }