A Socket represents one individual accepted connection admitted through the HTTP upgrade sequence[cite: 2]. Each instance manages its own lifecycle machine, event registry, bounded outbound queue, and room membership[cite: 1, 5].
TypeScript signatures exported directly by subatom-pulse[cite: 2]:
1class Socket {1 /** Unique connection identifier generated during admission */1 readonly id: string;11 /** Read-only authentication metadata populated during HTTP Upgrade */1 readonly metadata: Record<string, unknown>;21 /** Subscribes this socket to a named room */1 join(room: string): void;31 /** Unsubscribes this socket from a named room */1 leave(room: string): void;41 /** Registers an event handler scoped exclusively to this connection */1 on(1 event: string,1 handler: (1 data: unknown,1 ack?: (reply: unknown) => void1 ) => void | Promise<void>1 ): void;51 /** Delivers a message strictly to this connection */1 emit(event: string, data: unknown): void;61 /** Broadcasts a message to all members in a room, excluding this socket */1 to(room: string): { emit(event: string, data: unknown): void };71 /** Closes the transport immediately with WebSocket code 1000 */1 disconnect(): void;1}
| Property | Type | Description |
|---|---|---|
| id | string | Immutable unique connection identifier assigned when the connection passes upgrade admission[cite: 2, 4]. |
| metadata | Record<string, unknown> | Read-only object copied directly from AuthResult.metadata returned by your server authenticator[cite: 2, 4]. |
Serializes payload as JSON and pushes it into this connection's isolated OutboundQueue[cite: 1, 3]. It delivers strictly to this peer and does not trigger adapter broadcast events[cite: 2].
Sends the packet to every other connection currently registered in the specified room, excluding the calling socket. If a cluster adapter is present, it publishes across nodes[cite: 2, 3].
Adds the socket identifier to the in-memory RoomRegistry set in $O(1)$ algorithmic complexity.
Removes the socket identifier from the room index[cite: 1, 2]. Future room broadcasts will no longer be addressed to this connection buffer[cite: 1, 3].
Registers an event handler scoped to this socket[cite: 2]. Handlers can be synchronous or return Promise<void>. If an acknowledged event handler throws an exception, the engine catches it and sends an error ack with code HANDLER_ERROR[cite: 4].
Immediately closes the underlying WebSocket connection frame with standard close code 1000[cite: 2].
socket.on("disconnect", ...) behaves as an ordinary packet handler: it triggers only if a client explicitly sends a packet with type "disconnect"[cite: 4]. It is not automatically invoked when the transport layer closes or drops[cite: 4].subatom-pulse unlinks all room memberships in RoomRegistry, deregisters heartbeats, and clears queued delivery buffers automatically to prevent memory leaks[cite: 1, 4, 5].Common server patterns inside io.onConnection((socket) => { ... })[cite: 2]:
1import { subatomPulse } from "subatom-pulse";11const io = subatomPulse({1 path: "/ws",1 authenticator: async (req) => {1 // Populate metadata during HTTP upgrade handshake1 return {1 authenticated: true,1 metadata: { userId: "usr_42", role: "admin", team: "core" },1 };1 },1});21io.onConnection((socket) => {1 // 1. Read-only metadata inspection1 const userId = socket.metadata.userId as string;1 console.log(`Socket connected: ${socket.id} (User: ${userId})`);31 // 2. Room isolation: join user inbox and team broadcast rooms1 socket.join(`user:${userId}`);1 socket.join("team:core");41 // 3. Direct messaging back to this specific socket1 socket.emit("session.ready", {1 socketId: socket.id,1 connectedAt: Date.now(),1 });51 // 4. Room emission excluding sender1 socket.to("team:core").emit("team.member_joined", {1 userId,2 socketId: socket.id,2 });61 // 5. Handling events with synchronous or asynchronous acknowledgements1 socket.on("message.send", async (data: { text?: string }, ack) => {1 if (!data?.text) {1 return ack?.({ ok: false, error: "Text payload required" });1 }71 // Forward to room peers1 socket.to("team:core").emit("message.received", {1 from: userId,1 text: data.text,1 });81 // Acknowledge receipt to caller1 ack?.({ ok: true, timestamp: Date.now() });3 });91 // 6. Manual termination1 socket.on("session.logout", () => {1 socket.disconnect(); // Closes transport with status code 10004 });2});