@orkestrel/websocket 0.0.10 → 0.0.11

package/dist/src/server/index.d.cts

@@ -4,7 +4,7 @@ import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
 
 /**
- * Compute the `Sec-WebSocket-Accept` response value for an RFC 6455 upgrade.
+ * Computes the `Sec-WebSocket-Accept` response value for an RFC 6455 upgrade.
  *
  * @remarks
  * The base64-encoded SHA-1 of the client's `Sec-WebSocket-Key` concatenated with the
@@ -17,10 +17,10 @@ import { EmitterInterface } from '@orkestrel/emitter';
 export declare function computeWebSocketAccept(key: string): string;
 
 /**
- * Create a server-native WebSocket over a raw upgraded `node:stream` Duplex socket.
+ * Creates a server-native WebSocket over a raw upgraded `node:stream` Duplex socket.
  *
  * @remarks
- * The construction entry point for the {@link NodeWebSocketInterface} (AGENTS §8). Pass
+ * The construction entry point for the {@link NodeWebSocketInterface}. Pass
  * the upgraded `socket` plus the client's `Sec-WebSocket-Key` as `key` to run in SERVER
  * mode — the wrapper writes the `101 Switching Protocols` handshake and sends unmasked
  * frames; omit `key` for CLIENT mode (no handshake, masked frames). This is the
@@ -31,6 +31,7 @@ export declare function computeWebSocketAccept(key: string): string;
  * @param options - The {@link NodeWebSocketOptions} (`socket`, optional `key` / `head` /
  *   `protocol` / `on`)
  * @returns A typed {@link NodeWebSocketInterface}
+ * @throws A `WebSocketError` coded `OPTION` when `payload`, `timeout`, `key`, or `protocol` is refused, thrown before the wrapper writes to or assumes ownership of the `socket`
  *
  * @example
  * ```ts
@@ -38,9 +39,14 @@ export declare function computeWebSocketAccept(key: string): string;
  *
  * // In a node:http 'upgrade' handler — server mode, identified by the client key:
  * server.on('upgrade', (request, socket, head) => {
+ * 	const key = request.headers['sec-websocket-key']
+ * 	if (typeof key !== 'string') {
+ * 		socket.destroy()
+ * 		return
+ * 	}
  * 	const ws = createNodeWebSocket({
  * 		socket,
- * 		key: request.headers['sec-websocket-key'],
+ * 		key, // present => server mode + 101 handshake
  * 		head,
  * 		on: { message: (text) => ws.send(`echo: ${text}`) },
  * 	})
@@ -50,28 +56,29 @@ export declare function computeWebSocketAccept(key: string): string;
 export declare function createNodeWebSocket(options: NodeWebSocketOptions): NodeWebSocketInterface;
 
 /**
- * Encode a single RFC 6455 frame to its wire bytes — the inverse of
- * {@link parseWebSocketFrame}.
+ * Encodes a single RFC 6455 frame to its wire bytes — the inverse of
+ * `parseWebSocketFrame`.
  *
  * @remarks
  * Builds a final (FIN-set) frame: byte 0 is `0x80 | opcode`; the payload length uses
  * the 7-bit form below 126, the `126` + 16-bit form below 65 536, or the `127` +
  * 64-bit form beyond; when `masked` is set the mask bit is set, a 4-byte key (supplied
- * via `options.mask`, else random) is written, and the payload is XOR-masked. Server→
+ * through `options.mask`, else random) is written, and the payload is XOR-masked. Server→
  * client frames are unmasked (the default); pass `masked: true` to encode a CLIENT
- * frame (e.g. to feed the parser in a test). A `string` payload is encoded as UTF-8.
- * Returns one contiguous `Buffer` (header + payload), so the wrapper writes it with a
- * single `socket.write`. Pure.
+ * frame (for example to feed the parser in a test). A `string` payload is encoded as
+ * UTF-8. Returns one contiguous `Buffer` (header + payload), so the wrapper writes it
+ * with a single `socket.write`. Pure.
  *
  * @param opcode - The frame opcode (a `WEBSOCKET_OPCODE_*` value)
  * @param payload - The payload, a `Buffer` or a UTF-8 `string`
  * @param options - Masking control ({@link WebSocketEncodeOptions}); defaults to unmasked
  * @returns The complete frame as wire bytes
+ * @throws A {@link WebSocketError} coded `FRAME` when `opcode` is outside the four-bit wire field, when `options.mask` is not 4 bytes, or when `options.mask` is supplied without `masked: true`
  */
 export declare function encodeWebSocketFrame(opcode: number, payload: Buffer | string, options?: WebSocketEncodeOptions): Buffer;
 
 /**
- * Whether a numeric value is a valid RFC 6455 close status code to RECEIVE (§7.4.1).
+ * Checks whether a numeric value is a valid RFC 6455 close status code to RECEIVE (§7.4.1).
  *
  * @remarks
  * True for `1000`–`1003`, `1007`–`1014`, and the application range `3000`–`4999`; false
@@ -84,7 +91,7 @@ export declare function encodeWebSocketFrame(opcode: number, payload: Buffer | s
  * never throws.
  *
  * @param code - The close status code to validate
- * @returns `true` when `code` is a valid RFC 6455 close code
+ * @returns True if `code` is a valid RFC 6455 close code; false otherwise
  *
  * @example
  * ```ts
@@ -94,25 +101,26 @@ export declare function encodeWebSocketFrame(opcode: number, payload: Buffer | s
 export declare function isCloseCode(code: number): boolean;
 
 /**
- * Whether the next frame uses the shortest valid RFC 6455 payload-length encoding.
- *
- * @remarks
- * Returns `undefined` until the complete length prefix is buffered. The 16-bit form
- * is canonical only for lengths at least 126; the 64-bit form only for lengths at
- * least 65,536 and with its most-significant bit clear (RFC 6455 §5.2).
+ * Checks whether a value is a {@link WebSocketError}.
  *
- * @param buffer - The accumulation buffer containing the next frame header
- * @returns Its canonicality, or `undefined` while the length prefix is incomplete
+ * @param value - The value to test (typically a `catch` binding)
+ * @returns True if `value` is a `WebSocketError`; false otherwise
  *
  * @example
  * ```ts
- * if (isWebSocketFrameCanonical(buffer) === false) fail(WEBSOCKET_CLOSE_PROTOCOL)
+ * import { isWebSocketError } from '@src/server'
+ *
+ * try {
+ * 	ws.close(1000.5)
+ * } catch (error) {
+ * 	if (isWebSocketError(error) && error.code === 'CLOSE') ws.close()
+ * }
  * ```
  */
-export declare function isWebSocketFrameCanonical(buffer: Buffer): boolean | undefined;
+export declare function isWebSocketError(value: unknown): value is WebSocketError;
 
 /**
- * Whether a value is a canonical RFC 6455 `Sec-WebSocket-Key`.
+ * Checks whether a value is a canonical RFC 6455 `Sec-WebSocket-Key`.
  *
  * @remarks
  * A valid key is exactly 16 random bytes encoded as 24 characters of base64, ending
@@ -120,7 +128,7 @@ export declare function isWebSocketFrameCanonical(buffer: Buffer): boolean | und
  * malformed or non-canonical encodings return `false`; nothing is thrown.
  *
  * @param key - The proposed `Sec-WebSocket-Key` header value
- * @returns `true` when `key` is the canonical base64 encoding of 16 bytes
+ * @returns True if `key` is the canonical base64 encoding of 16 bytes; false otherwise
  *
  * @example
  * ```ts
@@ -131,7 +139,7 @@ export declare function isWebSocketFrameCanonical(buffer: Buffer): boolean | und
 export declare function isWebSocketKey(key: string): boolean;
 
 /**
- * Whether a value is one valid WebSocket subprotocol token.
+ * Checks whether a value is one valid WebSocket subprotocol token.
  *
  * @remarks
  * Subprotocols use the HTTP `token` grammar. Whitespace, separators, commas, and
@@ -139,22 +147,42 @@ export declare function isWebSocketKey(key: string): boolean;
  * second handshake header.
  *
  * @param protocol - The negotiated subprotocol to validate
- * @returns `true` when `protocol` is one non-empty HTTP token
+ * @returns True if `protocol` is one non-empty HTTP token; false otherwise
  *
  * @example
  * ```ts
- * if (!isWebSocketProtocol(protocol)) throw new RangeError('invalid protocol')
+ * if (!isWebSocketProtocol(protocol)) socket.destroy()
  * ```
  */
 export declare function isWebSocketProtocol(protocol: string): boolean;
 
 /**
- * Read the declared payload length off the front of a buffer, without buffering or
+ * Checks whether the next frame uses the shortest valid RFC 6455 payload-length encoding.
+ *
+ * @remarks
+ * Returns `undefined` until the complete length prefix is buffered. The 16-bit form
+ * is canonical only for lengths at least 126; the 64-bit form only for lengths at
+ * least 65,536 and with its most-significant bit clear (RFC 6455 §5.2). Reads the same
+ * length prefix as {@link measureWebSocketFrame}, under the same incomplete-buffer
+ * contract. Pure; never throws.
+ *
+ * @param buffer - The accumulation buffer containing the next frame header
+ * @returns Its canonicality, or `undefined` while the length prefix is incomplete
+ *
+ * @example
+ * ```ts
+ * if (matchesWebSocketCanonical(buffer) === false) fail(WEBSOCKET_CLOSE_PROTOCOL)
+ * ```
+ */
+export declare function matchesWebSocketCanonical(buffer: Buffer): boolean | undefined;
+
+/**
+ * Reads the declared payload length off the front of a buffer, without buffering or
  * reading the payload itself.
  *
  * @remarks
  * Decodes only byte 1's 7-bit length field, extended by the 16-bit (`126`) or 64-bit
- * (`127`) form exactly like {@link parseWebSocketFrame} — but stops there, so a caller
+ * (`127`) form exactly like `parseWebSocketFrame` — but stops there, so a caller
  * can reject an over-cap frame the moment its length is known, before the payload
  * bytes have even arrived. Returns `undefined` until the length field itself is fully
  * buffered (mirrors the parser's incomplete-buffer contract). Pure; never throws.
@@ -165,13 +193,13 @@ export declare function isWebSocketProtocol(protocol: string): boolean;
  * @example
  * ```ts
  * const declared = measureWebSocketFrame(buffer)
- * if (declared !== undefined && declared > limit) fail(WEBSOCKET_CLOSE_TOOBIG)
+ * if (declared !== undefined && declared > limit) fail(WEBSOCKET_CLOSE_TOO_BIG)
  * ```
  */
 export declare function measureWebSocketFrame(buffer: Buffer): number | undefined;
 
 /**
- * A server-native WebSocket over a raw upgraded `node:stream` Duplex — the lean
+ * Represents a server-native WebSocket over a raw upgraded `node:stream` Duplex — the lean
  * wrapper around the RFC 6455 wire protocol.
  *
  * @remarks
@@ -184,34 +212,59 @@ export declare function measureWebSocketFrame(buffer: Buffer): number | undefine
  * `fin: false` frames — decodes to UTF-8 and emits `message`; a PING is auto-answered
  * with a PONG and emits `ping`; a PONG emits `pong`; a CLOSE is echoed and ends the
  * socket, emitting `close`. `send` writes a text frame, `ping` a ping, `close` a close
- * frame; `destroy` tears down immediately. It owns a typed `#emitter` (AGENTS §13) that
- * isolates a throwing listener and routes the error to its own `error` handler (the `error`
- * option) — the socket never crashes. An underlying socket error emits the domain
- * `error` event and terminates the wrapper. The untyped socket `data` is narrowed to a
- * `Buffer` with a guard, never an assertion (AGENTS §14).
+ * frame; `destroy` tears down immediately. It owns a typed `#emitter` by composition, and
+ * the emitter isolates a throwing listener and routes the error to its own `error` handler
+ * (the `error` option) — the socket never crashes. An underlying socket error emits the
+ * domain `error` event and terminates the wrapper. The untyped socket `data` is narrowed
+ * to a `Buffer` with a guard, never an assertion.
+ *
+ * @example
+ * ```ts
+ * import { NodeWebSocket } from '@src/server'
+ *
+ * // In a node:http 'upgrade' handler, over the socket the server already handed over:
+ * const key = request.headers['sec-websocket-key']
+ * if (typeof key !== 'string') {
+ * 	socket.destroy()
+ * 	return
+ * }
+ * const ws = new NodeWebSocket({ socket, key, head })
+ * ws.emitter.on('message', (text) => ws.send(`echo: ${text}`))
+ * ```
  */
 export declare class NodeWebSocket implements NodeWebSocketInterface {
     #private;
+    /**
+     * Creates a WebSocket wrapper over an already-upgraded Duplex socket.
+     *
+     * @remarks
+     * `key` selects the mode: present runs SERVER mode and writes the `101 Switching
+     * Protocols` handshake, omitted runs CLIENT mode and masks every outgoing frame.
+     * {@link NodeWebSocketOptions} describes every member.
+     *
+     * @param options - The {@link NodeWebSocketOptions} the wrapper is built from
+     * @throws A {@link WebSocketError} coded `OPTION` when `payload`, `timeout`, `key`, or `protocol` is refused, or when `protocol` is supplied without a server `key`, thrown before the wrapper writes to or assumes ownership of the `socket`
+     */
     constructor(options: NodeWebSocketOptions);
     get emitter(): EmitterInterface<NodeWebSocketEventMap>;
     get readyState(): WebSocketReadyState;
-    send(data: string): void;
-    ping(data?: string): void;
+    send(message: string): void;
+    ping(payload?: string): void;
     close(code?: number, reason?: string): void;
     destroy(): void;
 }
 
 /**
- * The event map of a {@link NodeWebSocketInterface} (AGENTS §13).
+ * Represents the event map of a {@link NodeWebSocketInterface}.
  *
  * @remarks
  * `open` — the handshake completed and the socket is ready. `message` — a text frame
- * arrived (its decoded UTF-8 string). `close` — the connection ended (its
- * {@link WebSocketClose} metadata). `error` — the underlying socket faulted (a DOMAIN
- * event and then terminates the wrapper). `ping` / `pong` — a control frame arrived
- * (a ping is auto-answered with a pong).
- * Listener isolation is the emitter's (AGENTS §13): a listener throw is routed to the
- * emitter's `error` handler (the `error` option), never onto this map, so a buggy observer
+ * arrived (its decoded UTF-8 string). `close` — the connection ended, carrying the
+ * labeled `[code, reason]` tuple (each `undefined` when the peer sent none). `error` —
+ * the underlying socket faulted (a DOMAIN event and then terminates the wrapper).
+ * `ping` / `pong` — a control frame arrived (a ping is auto-answered with a pong).
+ * Listener isolation is the emitter's: a listener throw is routed to the emitter's
+ * `error` handler (the `error` option), never onto this map, so a buggy observer
  * never breaks the socket.
  */
 export declare type NodeWebSocketEventMap = {
@@ -224,7 +277,7 @@ export declare type NodeWebSocketEventMap = {
 };
 
 /**
- * A server-native WebSocket over a raw upgraded socket — the behavioral contract.
+ * Represents a server-native WebSocket over a raw upgraded socket — the behavioral contract.
  *
  * @remarks
  * Created by `createNodeWebSocket`. In server mode it writes the RFC 6455 handshake
@@ -234,20 +287,24 @@ export declare type NodeWebSocketEventMap = {
  * frame is echoed and ends the socket, emitting `close`. `send` writes a text frame;
  * `ping` writes a ping; `close` writes a close frame (the 2-byte code + optional
  * reason); `destroy` tears the socket down immediately. `readyState` tracks the
- * lifecycle. It owns a typed `emitter` (AGENTS §13) and never throws on a faulty
+ * lifecycle. It owns a typed `emitter` by composition and never throws on a faulty
  * listener — the emitter routes it to its `error` handler (the `error` option).
+ * `ping` throws a `LIMIT`-coded `WebSocketError` when its UTF-8 payload exceeds
+ * `WEBSOCKET_CONTROL_MAX_LENGTH`; `close` throws a `CLOSE`-coded one for a status code
+ * `isCloseCode` refuses and a `LIMIT`-coded one for a reason past
+ * `WEBSOCKET_CLOSE_REASON_MAX_LENGTH`, in each case without changing `readyState`.
  */
 export declare interface NodeWebSocketInterface {
     readonly emitter: EmitterInterface<NodeWebSocketEventMap>;
     readonly readyState: WebSocketReadyState;
-    send(data: string): void;
-    ping(data?: string): void;
+    send(message: string): void;
+    ping(payload?: string): void;
     close(code?: number, reason?: string): void;
     destroy(): void;
 }
 
 /**
- * Options for `createNodeWebSocket`.
+ * Represents the options for `createNodeWebSocket`.
  *
  * @remarks
  * `socket` is the upgraded `node:stream` Duplex (the raw TCP stream after the HTTP
@@ -256,8 +313,8 @@ export declare interface NodeWebSocketInterface {
  * frames; omit it for CLIENT mode — no handshake is written and frames are MASKED (RFC
  * 6455 §5.3). `head` is any bytes buffered after the upgrade headers (replayed through
  * the parser). `protocol` is a negotiated subprotocol to echo in the handshake. `on`
- * wires initial listeners at construction (AGENTS §8 reserved option); `error` is the
- * emitter's listener-error handler (§13 — a listener throw routes here). `payload` caps
+ * wires initial listeners at construction — the reserved `on` option; `error` is the
+ * emitter's listener-error handler, where a listener throw routes. `payload` caps
  * both a single inbound frame's declared length AND the total bytes of a reassembled
  * fragmented message (default `WEBSOCKET_MAX_PAYLOAD`) — a breach closes 1009. `timeout`
  * is how long the wrapper waits, after sending a close frame, for the peer's echo before
@@ -265,7 +322,8 @@ export declare interface NodeWebSocketInterface {
  * is the external cancellation seam — on abort the socket destroys; composes with the
  * line's `@orkestrel/abort` and `@orkestrel/timeout` primitives, which expose native
  * `AbortSignal`s. An already-aborted signal tears the socket down immediately after
- * construction.
+ * construction. A refused member throws an `OPTION`-coded `WebSocketError` before the
+ * wrapper writes to or assumes ownership of the `socket`.
  */
 export declare interface NodeWebSocketOptions {
     readonly socket: Duplex;
@@ -273,7 +331,7 @@ export declare interface NodeWebSocketOptions {
     readonly head?: Buffer;
     readonly protocol?: string;
     readonly on?: EmitterHooks<NodeWebSocketEventMap>;
-    /** The emitter's listener-error handler (AGENTS §13) — a listener throw routes here, not to a domain event. */
+    /** Holds the emitter's listener-error handler — a listener throw routes here, not to a domain event. */
     readonly error?: EmitterErrorHandler;
     readonly payload?: number;
     readonly timeout?: number;
@@ -281,12 +339,12 @@ export declare interface NodeWebSocketOptions {
 }
 
 /**
- * Decode a byte sequence as strict UTF-8, or signal it is malformed.
+ * Decodes a byte sequence as strict UTF-8, or signals it is malformed.
  *
  * @remarks
  * Wraps `TextDecoder('utf-8', { fatal: true })` in a try/catch so a malformed sequence
- * returns `undefined` instead of throwing (AGENTS §14 — a guard-adjacent coercer never
- * throws on bad input). Pure.
+ * returns `undefined` instead of throwing — a guard-adjacent coercer never throws on bad
+ * input. Pure.
  *
  * @param bytes - The raw bytes to decode
  * @returns The decoded string, or `undefined` when `bytes` is not valid UTF-8
@@ -300,7 +358,7 @@ export declare interface NodeWebSocketOptions {
 export declare function parseUTF8(bytes: Buffer): string | undefined;
 
 /**
- * Decode a single RFC 6455 frame from the front of a buffer.
+ * Decodes a single RFC 6455 frame from the front of a buffer.
  *
  * @remarks
  * Reads the FIN bit and opcode (byte 0), the mask bit and 7-bit payload length (byte
@@ -310,44 +368,49 @@ export declare function parseUTF8(bytes: Buffer): string | undefined;
  * 6455 §5.3; an unmasked frame still decodes, leaving the payload as-is, so the caller
  * can enforce policy). Returns `undefined` the moment the buffer is too short for the
  * part it is up to (the length prefix, the mask, or the full payload) — the signal to
- * the caller to read more bytes and retry, exactly like {@link SSEParser} on a partial
- * line. `consumed` is the total bytes the frame occupied, so the caller slices the
- * remainder. Pure; never throws on a short buffer.
+ * the caller to read more bytes and retry. `consumed` is the total bytes the frame
+ * occupied, so the caller slices the remainder. Pure; never throws on a short buffer.
  *
  * @param buffer - The accumulation buffer to decode the next frame from
  * @returns The parsed {@link WebSocketFrame}, or `undefined` when the buffer is incomplete
+ *
+ * @example
+ * ```ts
+ * const frame = parseWebSocketFrame(buffer)
+ * if (frame === undefined) return // incomplete — wait for more bytes
+ * ```
  */
 export declare function parseWebSocketFrame(buffer: Buffer): WebSocketFrame | undefined;
 
-/** Invalid-frame-payload-data status code (RFC 6455 §7.4.1) — e.g. non-UTF-8 text or an unparseable close reason. */
+/** Names the invalid-frame-payload-data status code (RFC 6455 §7.4.1) — for example non-UTF-8 text or an unparseable close reason. */
 export declare const WEBSOCKET_CLOSE_INVALID = 1007;
 
-/** Normal-closure status code (RFC 6455 §7.4.1) — the default `close` code. */
+/** Names the normal-closure status code (RFC 6455 §7.4.1) — the default `close` code. */
 export declare const WEBSOCKET_CLOSE_NORMAL = 1000;
 
-/** Protocol-error status code (RFC 6455 §7.4.1) — a framing/state rule was violated. */
+/** Names the protocol-error status code (RFC 6455 §7.4.1) — a framing/state rule was violated. */
 export declare const WEBSOCKET_CLOSE_PROTOCOL = 1002;
 
-/** The maximum UTF-8 close-reason length after the two-byte status code. */
-export declare const WEBSOCKET_CLOSE_REASON_MAXLEN: number;
+/** Names the maximum UTF-8 close-reason length after the two-byte status code. */
+export declare const WEBSOCKET_CLOSE_REASON_MAX_LENGTH: number;
 
-/** The default close-handshake timeout in milliseconds — how long `close()` waits for the peer's echo before tearing the socket down. */
+/** Names the default close-handshake timeout in milliseconds — how long `close()` waits for the peer's echo before tearing the socket down. */
 export declare const WEBSOCKET_CLOSE_TIMEOUT_MS = 30000;
 
-/** Message-too-big status code (RFC 6455 §7.4.1) — a reassembled message exceeded the payload cap. */
-export declare const WEBSOCKET_CLOSE_TOOBIG = 1009;
+/** Names the message-too-big status code (RFC 6455 §7.4.1) — a reassembled message exceeded the payload cap. */
+export declare const WEBSOCKET_CLOSE_TOO_BIG = 1009;
 
-/** Unsupported-data status code (RFC 6455 §7.4.1) — the endpoint received a data type it cannot accept (e.g. binary on a text-only endpoint). */
+/** Names the unsupported-data status code (RFC 6455 §7.4.1) — the endpoint received a data type it cannot accept, for example binary on a text-only endpoint. */
 export declare const WEBSOCKET_CLOSE_UNSUPPORTED = 1003;
 
-/** The maximum control-frame payload length in bytes (RFC 6455 §5.5). */
-export declare const WEBSOCKET_CONTROL_MAXLEN = 125;
+/** Names the maximum control-frame payload length in bytes (RFC 6455 §5.5). */
+export declare const WEBSOCKET_CONTROL_MAX_LENGTH = 125;
 
-/** The post-`#fail` flush grace in milliseconds — how long a validation-breach close frame is given to flush through the socket's write buffer before the hard `destroy()` fallback fires (the normal path destroys sooner, on the `end()` flush callback). */
+/** Names the post-`#fail` flush grace in milliseconds — how long a validation-breach close frame is given to flush through the socket's write buffer before the hard `destroy()` fallback fires (the normal path destroys sooner, on the `end()` flush callback). */
 export declare const WEBSOCKET_FAIL_TIMEOUT_MS = 1000;
 
 /**
- * The RFC 6455 GUID concatenated to a client's `Sec-WebSocket-Key` before the SHA-1
+ * Names the RFC 6455 GUID concatenated to a client's `Sec-WebSocket-Key` before the SHA-1
  * hash that yields the `Sec-WebSocket-Accept` response value.
  *
  * @remarks
@@ -356,59 +419,44 @@ export declare const WEBSOCKET_FAIL_TIMEOUT_MS = 1000;
  */
 export declare const WEBSOCKET_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
 
-/** The default maximum inbound single-frame length AND reassembled-message total byte count (100 MiB — the `ws` package default). */
+/** Names the default maximum inbound single-frame length AND reassembled-message total byte count (100 MiB — the `ws` package default). */
 export declare const WEBSOCKET_MAX_PAYLOAD = 104857600;
 
-/** Binary frame opcode — a raw byte payload (RFC 6455 §5.6). */
+/** Names the binary frame opcode — a raw byte payload (RFC 6455 §5.6). */
 export declare const WEBSOCKET_OPCODE_BINARY = 2;
 
-/** Close frame opcode — a control frame ending the connection (RFC 6455 §5.5.1). */
+/** Names the close frame opcode — a control frame ending the connection (RFC 6455 §5.5.1). */
 export declare const WEBSOCKET_OPCODE_CLOSE = 8;
 
-/** Continuation frame opcode — the next fragment of an open data message (RFC 6455 §5.4). */
+/** Names the continuation frame opcode — the next fragment of an open data message (RFC 6455 §5.4). */
 export declare const WEBSOCKET_OPCODE_CONTINUATION = 0;
 
-/** Ping frame opcode — a control frame the peer must answer with a pong (RFC 6455 §5.5.2). */
+/** Names the ping frame opcode — a control frame the peer must answer with a pong (RFC 6455 §5.5.2). */
 export declare const WEBSOCKET_OPCODE_PING = 9;
 
-/** Pong frame opcode — a control frame answering a ping (RFC 6455 §5.5.3). */
+/** Names the pong frame opcode — a control frame answering a ping (RFC 6455 §5.5.3). */
 export declare const WEBSOCKET_OPCODE_PONG = 10;
 
-/** Text frame opcode — a UTF-8 payload (RFC 6455 §5.6). */
+/** Names the text frame opcode — a UTF-8 payload (RFC 6455 §5.6). */
 export declare const WEBSOCKET_OPCODE_TEXT = 1;
 
-/** Ready state for a closed WebSocket (the socket ended). */
+/** Names the ready state for a closed WebSocket (the socket ended). */
 export declare const WEBSOCKET_READY_CLOSED: WebSocketReadyState;
 
-/** Ready state for a closing WebSocket (a close frame was sent or received). */
+/** Names the ready state for a closing WebSocket (a close frame was sent or received). */
 export declare const WEBSOCKET_READY_CLOSING: WebSocketReadyState;
 
-/** Ready state for a connecting WebSocket (before the handshake completes). */
+/** Names the ready state for a connecting WebSocket (before the handshake completes). */
 export declare const WEBSOCKET_READY_CONNECTING: WebSocketReadyState;
 
-/** Ready state for an open WebSocket (the handshake completed; frames flow). */
+/** Names the ready state for an open WebSocket (the handshake completed; frames flow). */
 export declare const WEBSOCKET_READY_OPEN: WebSocketReadyState;
 
-/** The WebSocket protocol version this wrapper speaks (`Sec-WebSocket-Version: 13`). */
+/** Names the WebSocket protocol version this wrapper speaks (`Sec-WebSocket-Version: 13`). */
 export declare const WEBSOCKET_VERSION = "13";
 
 /**
- * The metadata of a closed WebSocket — why the connection ended.
- *
- * @remarks
- * `code` is the RFC 6455 close status code (undefined when the peer closed with no
- * payload); `reason` is the optional UTF-8 reason text (undefined when empty).
- */
-export declare interface WebSocketClose {
-    readonly code: number | undefined;
-    readonly reason: string | undefined;
-}
-
-/** A WebSocket close status code (RFC 6455 §7.4) — e.g. `WEBSOCKET_CLOSE_NORMAL` (1000). */
-export declare type WebSocketCloseCode = number;
-
-/**
- * Options for {@link encodeWebSocketFrame} — how a frame is masked on the wire.
+ * Represents the options for {@link encodeWebSocketFrame} — how a frame is masked on the wire.
  *
  * @remarks
  * `masked` toggles the mask bit (server→client frames are NOT masked, the default;
@@ -422,7 +470,57 @@ export declare interface WebSocketEncodeOptions {
 }
 
 /**
- * A parsed RFC 6455 frame — the structured result of decoding one frame off the wire.
+ * Represents an error thrown by the WebSocket wrapper for a refused caller-supplied value.
+ *
+ * @remarks
+ * Carries a {@link WebSocketErrorCode} and an optional `context` record holding the
+ * refused value under a key naming it: an `'OPTION'` carries the offending option
+ * (`payload`, `timeout`, `key`, or `protocol`), a `'LIMIT'` carries `size` and the
+ * `limit` it exceeded, a `'CLOSE'` carries the refused close `code`, and a `'FRAME'`
+ * carries `opcode` or the mask's `size`. Narrow a caught value with
+ * {@link isWebSocketError}.
+ *
+ * @example
+ * ```ts
+ * import { createNodeWebSocket, isWebSocketError } from '@src/server'
+ *
+ * try {
+ * 	createNodeWebSocket({ socket, key: 'not-base64' })
+ * } catch (error) {
+ * 	if (isWebSocketError(error) && error.code === 'OPTION') socket.destroy()
+ * }
+ * ```
+ */
+export declare class WebSocketError extends Error {
+    readonly code: WebSocketErrorCode;
+    readonly context?: Readonly<Record<string, unknown>>;
+    /**
+     * Creates a WebSocket error carrying a machine-readable code.
+     *
+     * @param code - The machine-readable {@link WebSocketErrorCode} a `catch` branches on
+     * @param message - The human-readable description, carried as the `Error` message
+     * @param context - The refused value keyed by name; omitted leaves `context` `undefined`
+     */
+    constructor(code: WebSocketErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
+}
+
+/**
+ * Represents the subject an {@link import('./errors.js').WebSocketError} names as refused.
+ *
+ * @remarks
+ * `OPTION` — a {@link NodeWebSocketOptions} member was refused at construction
+ * (`payload`, `timeout`, `key`, `protocol`, or a `protocol` given without a server
+ * `key`). `LIMIT` — an outbound control-frame payload exceeded its RFC 6455 §5.5 cap
+ * (a `ping` payload past `WEBSOCKET_CONTROL_MAX_LENGTH`, a `close` reason past
+ * `WEBSOCKET_CLOSE_REASON_MAX_LENGTH`). `CLOSE` — a close status code `isCloseCode` refuses
+ * was passed to `close`. `FRAME` — an `encodeWebSocketFrame` frame-header argument was
+ * refused (an opcode outside the four-bit wire field, a mask that is not 4 bytes, or a
+ * mask supplied without `masked: true`).
+ */
+export declare type WebSocketErrorCode = 'OPTION' | 'LIMIT' | 'CLOSE' | 'FRAME';
+
+/**
+ * Represents a parsed RFC 6455 frame — the structured result of decoding one frame off the wire.
  *
  * @remarks
  * `fin` is the final-fragment bit (false for a continued fragment); `opcode`
@@ -444,13 +542,8 @@ export declare interface WebSocketFrame {
     readonly rsv: number;
 }
 
-/** A decoded text message received from, or to send to, a WebSocket peer. */
-export declare interface WebSocketMessage {
-    readonly data: string;
-}
-
 /**
- * A WebSocket ready state — the four browser-compatible lifecycle values.
+ * Represents a WebSocket ready state — the four browser-compatible lifecycle values.
  *
  * @remarks
  * `0` connecting, `1` open, `2` closing, `3` closed — the same numbering the DOM