WebSocketStream: close() method

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 close() method of the WebSocketStream interface closes the WebSocket connection. The method optionally accepts an object containing a custom code and/or reason indicating why the connection was closed.

An alternative mechanism for closing a WebSocketStream is to specify an AbortSignal in the signal option of the constructor upon creation. The associated AbortController can then be used to close the WebSocket connection. This is generally the preferred mechanism. However, close() can be used if you wish to specify a custom code and/or reason.

Syntax

close()
close(options)

Parameters

options Optional

An options object containing the following properties:

closeCode Optional: A number representing the closing code (see the full list of CloseEvent status codes).
reason Optional: A string representing a human-readable description of the reason why the socket connection is closed. The maximum allowed length for a reason string is 123 bytes. The string is automatically encoded as UTF-8 when the function is invoked.

Note: Depending on the server setup and status code you use, the server may choose to ignore a custom code in favor of a valid code that is correct for the closing reason. Valid codes are 1000, and any code within the range 3000 to 4999, inclusive.

Return value

None (undefined).

Exceptions

SyntaxError DOMException: Thrown if the provided reason is longer than the maximum allowed length of 123 bytes.

Examples

const wsURL = "wss://127.0.0.1/";
const wss = new WebSocketStream(wsURL);

setTimeout(() => {
  wss.close({
    code: 1000,
    reason: "That's all folks",
  });
}, 10000);

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