@ayonli/jsext/types/ws/base.d.ts

A JavaScript extension package for building strong and modern applications.

import "../external/event-target-polyfill/index.ts";
import type { Ensured } from "../types.ts";
declare const _source: unique symbol;
declare const _ws: unique symbol;
export type WebSocketLike = Ensured<Partial<WebSocket>, "readyState" | "close" | "send">;
/**
 * This class represents a WebSocket connection on the server side.
 * Normally we don't create instances of this class directly, but rather use
 * the {@link WebSocketServer} to handle WebSocket connections, which will
 * create the instance for us.
 *
 * **Events:**
 *
 * - `open` - Dispatched when the connection is ready.
 * - `message` - Dispatched when a message is received.
 * - `error` - Dispatched when an error occurs, such as network failure. After
 *   this event is dispatched, the connection will be closed and the `close`
 *   event will be dispatched.
 * - `close` - Dispatched when the connection is closed. If the connection is
 *   closed due to some error, the `error` event will be dispatched before this
 *   event, and the close event will have the `wasClean` set to `false`, and the
 *   `reason` property contains the error message, if any.
 */
export declare class WebSocketConnection extends EventTarget implements AsyncIterable<string | Uint8Array> {
    private [_source];
    private [_ws];
    constructor(source: Promise<WebSocketLike>);
    /**
     * A promise that resolves when the connection is ready to send and receive
     * messages.
     *
     * @deprecated Listen for the `open` event instead.
     */
    get ready(): Promise<this>;
    /**
     * The current state of the WebSocket connection.
     */
    get readyState(): number;
    /**
     * Sends data to the WebSocket client.
     */
    send(data: string | ArrayBufferLike | ArrayBufferView): void;
    /**
     * Closes the WebSocket connection.
     */
    close(code?: number | undefined, reason?: string | undefined): void;
    /**
     * Adds an event listener that will be called when the connection is ready.
     */
    addEventListener(type: "open", listener: (this: WebSocketConnection, ev: Event) => void, options?: boolean | AddEventListenerOptions): void;
    /**
     * Adds an event listener that will be called when a message is received.
     */
    addEventListener(type: "message", listener: (this: WebSocketConnection, ev: MessageEvent<string | Uint8Array>) => void, options?: boolean | AddEventListenerOptions): void;
    /**
     * Adds an event listener that will be called when the connection is
     * interrupted. After this event is dispatched, the connection will be
     * closed and the `close` event will be dispatched.
     */
    addEventListener(type: "error", listener: (this: WebSocketConnection, ev: ErrorEvent) => void, options?: boolean | AddEventListenerOptions): void;
    /**
     * Adds an event listener that will be called when the connection is closed.
     * If the connection is closed due to some error, the `error` event will be
     * dispatched before this event, and the close event will have the `wasClean`
     * set to `false`, and the `reason` property contains the error message, if
     * any.
     */
    addEventListener(type: "close", listener: (this: WebSocketConnection, ev: CloseEvent) => void, options?: boolean | AddEventListenerOptions): void;
    addEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions): void;
    removeEventListener(type: "open", listener: (this: WebSocketConnection, ev: Event) => void, options?: boolean | EventListenerOptions): void;
    removeEventListener(type: "message", listener: (this: WebSocketConnection, ev: MessageEvent<string | Uint8Array>) => void, options?: boolean | EventListenerOptions): void;
    removeEventListener(type: "error", listener: (this: WebSocketConnection, ev: ErrorEvent) => void, options?: boolean | EventListenerOptions): void;
    removeEventListener(type: "close", listener: (this: WebSocketConnection, ev: CloseEvent) => void, options?: boolean | EventListenerOptions): void;
    removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions): void;
    [Symbol.asyncIterator](): AsyncIterableIterator<string | Uint8Array>;
}
/**
 * WebSocket handler function for the {@link WebSocketServer} constructor.
 */
export type WebSocketHandler = (socket: WebSocketConnection) => void;
/**
 * Options for the {@link WebSocketServer} constructor.
 */
export interface ServerOptions {
    /**
     * The idle timeout in seconds. The server will close the connection if no
     * messages are received within this time.
     *
     * NOTE: Currently, this option is only supported in Deno and Bun, in other
     * environments, the option is ignored.
     */
    idleTimeout?: number;
    /**
     * Whether to enable per-message deflate compression.
     *
     * NOTE: Currently, this option is only supported in Node.js and Bun, in
     * other environments, the option is ignored.
     */
    perMessageDeflate?: boolean;
}
export {};