WebSocketStream
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.
The WebSocketStream
interface of the WebSockets API is a promise-based API for connecting to a WebSocket server. It uses streams to send and receive data on the connection, and can therefore take advantage of stream backpressure automatically, regulating the speed of reading or writing to avoid bottlenecks in the application.
Constructor
WebSocketStream()
Experimental-
Creates a new
WebSocketStream
object instance.
Instance properties
url
Read only Experimental-
Returns the URL of the WebSocket server that the
WebSocketStream
instance was created with. closed
Read only Experimental-
Returns a
Promise
that fulfills with an object once the socket connection is closed. The object contains the closing code and reason as sent by the server. opened
Read only Experimental-
Returns a
Promise
that fulfills with an object once the socket connection is successfully opened. Among other features, this object contains aReadableStream
and aWritableStream
instance for receiving and sending data on the connection.
Instance methods
close()
Experimental-
Closes the WebSocket connection.
Examples
const output = document.querySelector("#output");
function writeToScreen(message) {
const pElem = document.createElement("p");
pElem.textContent = message;
output.appendChild(pElem);
}
if (!("WebSocketStream" in self)) {
writeToScreen("Your browser does not support WebSocketStream");
} else {
const wsURL = "ws://127.0.0.1/";
const wss = new WebSocketStream(wsURL);
console.log(wss.url);
async function start() {
const { readable, writable, extensions, protocol } = await wss.opened;
writeToScreen("CONNECTED");
closeBtn.disabled = false;
const reader = readable.getReader();
const writer = writable.getWriter();
writer.write("ping");
writeToScreen("SENT: ping");
while (true) {
const { value, done } = await reader.read();
writeToScreen(`RECEIVED: ${value}`);
if (done) {
break;
}
setTimeout(() => {
writer.write("ping");
writeToScreen("SENT: ping");
}, 5000);
}
}
start();
}
See Using WebSocketStream to write a client for a complete example with full explanation.
Specifications
Not currently a part of any specification. See https://github.com/whatwg/websockets/pull/48 for standardization progress.
Browser compatibility
BCD tables only load in the browser
See also
- WebSocketStream: integrating streams with the WebSocket API, developer.chrome.com (2020)