WebSockets
Enable real-time communication between clients and servers using WebSockets. Tools to create interactive and dynamic applications.
Eg WebSocket
interface CloseEvent
The CloseEvent interface represents an event that occurs when a WebSocket connection is closed.
This event is sent to the client when the connection is closed, providing information about why the connection was closed through the code, reason, and wasClean properties.
Examples
// Handling a close event
ws.addEventListener("close", (event: CloseEvent) => {
console.log(`Connection closed with code ${event.code}`);
console.log(`Reason: ${event.reason}`);
console.log(`Clean close: ${event.wasClean}`);
if (event.code === 1006) {
console.log("Connection closed abnormally");
}
});
Properties
See
variable CloseEvent
Constructor interface for creating CloseEvent instances.
Examples
// Creating a custom close event
const event = new CloseEvent("close", {
code: 1000,
reason: "Normal closure",
wasClean: true,
});
// Dispatching the event
myWebSocket.dispatchEvent(event);
Properties
prototype: CloseEvent See
interface CloseEventInit
Configuration options for a WebSocket "close" event.
Examples
// Creating a custom close event with specific parameters
const closeEventInit: CloseEventInit = {
code: 1000,
reason: "Normal closure",
wasClean: true,
};
const event = new CloseEvent("close", closeEventInit);
Properties
See
interface WebSocket
Provides the API for creating and managing a WebSocket connection to a server, as well as for sending and receiving data on the connection.
If you are looking to create a WebSocket server, please take a look at Deno.upgradeWebSocket().
Examples
// Creating a WebSocket connection
const ws = new WebSocket("ws://localhost:8080");
// Setting up event handlers
ws.onopen = (event) => {
console.log("Connected to the server");
ws.send("Hello Server!");
};
ws.onmessage = (event) => {
console.log(`Received: ${event.data}`);
};
ws.onerror = (event) => {
console.error("WebSocket error observed:", event);
};
ws.onclose = (event) => {
console.log(`WebSocket closed: Code=${event.code}, Reason=${event.reason}`);
};
Properties
Returns a string that indicates how binary data from the WebSocket object is exposed to scripts:
Can be set, to change how binary data is returned. The default is "blob".
const ws = new WebSocket("ws://localhost:8080");
ws.binaryType = "arraybuffer";
bufferedAmount: number Returns the number of bytes of application data (UTF-8 text and binary data) that have been queued using send() but not yet been transmitted to the network.
If the WebSocket connection is closed, this attribute's value will only increase with each call to the send() method. (The number does not reset to zero once the connection closes.)
const ws = new WebSocket("ws://localhost:8080");
ws.send("Hello, world!");
console.log(ws.bufferedAmount); // 13
extensions: string Returns the extensions selected by the server, if any.
WebSocket extensions add optional features negotiated during the handshake via the Sec-WebSocket-Extensions header.
At the time of writing, there are two registered extensions:
-
permessage-deflate: Enables per-message compression using DEFLATE. -
bbf-usp-protocol: Used by the Broadband Forum's User Services Platform (USP).
See the full list at IANA WebSocket Extensions.
Example:
const ws = new WebSocket("ws://localhost:8080");
console.log(ws.extensions); // e.g., "permessage-deflate"
onclose: ((
this: WebSocket,
ev: CloseEvent,
) => any) | null onerror: ((
this: WebSocket,
ev: Event | ErrorEvent,
) => any) | null onmessage: ((
this: WebSocket,
ev: MessageEvent,
) => any) | null protocol: string Returns the subprotocol selected by the server, if any. It can be used in conjunction with the array form of the constructor's second argument to perform subprotocol negotiation.
readyState: number Returns the state of the WebSocket object's connection. It can have the values described below.
url: string Returns the URL that was used to establish the WebSocket connection.
CLOSED: number CLOSING: number CONNECTING: number OPEN: number Methods
close(
code?: number,
reason?: string,
): void Closes the WebSocket connection, optionally using code as the WebSocket connection close code and reason as the WebSocket connection close reason.
Transmits data using the WebSocket connection. data can be a string, a Blob, an ArrayBuffer, or an ArrayBufferView.
addEventListener<K extends keyof WebSocketEventMap>(
type: K,
listener: (
this: WebSocket,
ev: WebSocketEventMap[K],
) => any,
options?: boolean | AddEventListenerOptions,
): void addEventListener(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | AddEventListenerOptions,
): void removeEventListener<K extends keyof WebSocketEventMap>(
type: K,
listener: (
this: WebSocket,
ev: WebSocketEventMap[K],
) => any,
options?: boolean | EventListenerOptions,
): void removeEventListener(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | EventListenerOptions,
): void See
variable WebSocket
Constructor interface for creating WebSocket instances.
The WebSocket constructor creates and returns a new WebSocket object that represents a connection to a WebSocket server.
Examples
// Basic WebSocket connection
const ws = new WebSocket("ws://localhost:8080");
// WebSocket with protocol specification
const wsWithProtocol = new WebSocket("ws://localhost:8080", "json");
// WebSocket with multiple protocol options (server will select one)
const wsWithProtocols = new WebSocket("ws://localhost:8080", ["json", "xml"]);
// Using URL object instead of string
const url = new URL("ws://localhost:8080/path");
const wsWithUrl = new WebSocket(url);
// WebSocket with headers
const wsWithProtocols = new WebSocket("ws://localhost:8080", {
headers: {
"Authorization": "Bearer foo",
},
});
Properties
See
interface WebSocketConnection
Properties
readable: ReadableStream<string | Uint8Array<ArrayBuffer>> writable: WritableStream<string | Uint8Array<ArrayBufferLike>> extensions: string protocol: string interface WebSocketEventMap
Interface mapping WebSocket event names to their corresponding event types. Used for strongly typed event handling with addEventListener and removeEventListener.
Examples
// Using with TypeScript for strongly-typed event handling
const ws = new WebSocket("ws://localhost:8080");
ws.addEventListener("open", (event) => {
console.log("Connection established");
});
ws.addEventListener("message", (event: MessageEvent) => {
console.log(`Received: ${event.data}`);
});
Properties
interface WebSocketOptions
Options for a WebSocket instance. This feature is non-standard.
Properties
protocols: string | string[] The sub-protocol(s) that the client would like to use, in order of preference.
headers: HeadersInit A Headers object, an object literal, or an array of two-item arrays to set handshake's headers. This feature is non-standard.
client: Deno.HttpClient An HttpClient instance to use when creating the WebSocket connection. This is useful when you need to connect through a proxy or customize TLS settings.
const client = Deno.createHttpClient({
proxy: {
transport: "unix",
path: "/path/to/socket",
},
});
const ws = new WebSocket("ws://localhost:8000/socket", { client });
type alias BinaryType
Specifies the type of binary data being received over a WebSocket connection.
-
"blob": Binary data is returned asBlobobjects -
"arraybuffer": Binary data is returned asArrayBufferobjects
Examples
// Setting up WebSocket for binary data as ArrayBuffer
const ws = new WebSocket("ws://localhost:8080");
ws.binaryType = "arraybuffer";
ws.onmessage = (event) => {
if (event.data instanceof ArrayBuffer) {
// Process binary data
const view = new Uint8Array(event.data);
console.log(`Received binary data of ${view.length} bytes`);
} else {
// Process text data
console.log(`Received text: ${event.data}`);
}
};
// Sending binary data
const binaryData = new Uint8Array([1, 2, 3, 4]);
ws.send(binaryData.buffer);
Definition
"arraybuffer" | "blob" See
© 2018–2025 the Deno authors
Licensed under the MIT License.
https://docs.deno.com/api/web/websockets
