class WebSocketConnection
Since 0.1.0

A live WebSocket connection.

Tracks the monotonic timestamp of the last inbound frame so the heartbeat sweeper can find idle peers, and refuses writes once closed rather than failing deep inside a platform socket.

Constructors

WebSocketConnection(
id: string,
path: string,
now: number,
heartbeat?: boolean
)

Creates a connection.

Parameters
id: string

Unique connection ID (from runtime.uuid())

path: string

The path the connection was opened on

The runtime-agnostic socket

now: number

The current monotonic timestamp (runtime.hrtime())

optional
heartbeat: boolean = true

Whether this connection participates in the shared heartbeat sweep

Properties

readonly
data: Map<string, unknown>

Per-connection application state, the socket-lifetime analogue of IRequestContext.state. Use it to attach an authenticated user id, a tenant, or any value later handlers and broadcasts need.

readonly
id: string

Unique connection ID (from runtime.uuid()).

readonly
isOpen: boolean

Whether the connection is still writable.

readonly
lastSeenAt: number

The monotonic timestamp of the most recent inbound frame. Compared against another runtime.hrtime() reading — never against a wall clock.

readonly
participatesInHeartbeat: boolean

Whether the shared heartbeat sweeper should include this connection. When false, the sweeper skips both the payload send and idle eviction.

readonly
path: string

The path this connection was opened on.

Current lifecycle state.

Methods

close(
code?: number,
reason?: string
): void

Closes the connection. Idempotent.

markClosed(): void

Marks the connection closed without touching the transport — used when the peer closed first, so the socket is already gone.

send(data: string | Uint8Array): void

Sends a frame to this peer.

sendJson<T>(payload: T): void

Serializes a value to JSON and sends it as a text frame.

touch(now: number): void

Records that a frame arrived, resetting the idle countdown.

Usage

import { WebSocketConnection } from "websocket-plugin/src/index.ts";