The SubAtomPulse client coordinates WebSocket connection state, offline message buffering, reconnection timers, and RPC acknowledgements[cite: 2, 4].
TypeScript interfaces and signatures exported directly by subatom-pulse[cite: 2]:
1interface ClientOptions {1 protocols?: string | string[];1 reconnect?: boolean;1 reconnectAttempts?: number;1 reconnectDelayMs?: number;1 autoConnect?: boolean;1 auth?: { token?: string; [key: string]: unknown };1}11type ClientEventHandler = (data: unknown, ack?: (reply: unknown) => void) => void;21class SubAtomPulse {1 constructor(url: string, options?: ClientOptions);1 readonly connected: boolean;1 readonly state: "CONNECTING" | "OPEN" | "CLOSING" | "CLOSED";1 connect(): void;1 disconnect(): void;1 on(event: string, handler: ClientEventHandler): () => void;1 once(event: string, handler: ClientEventHandler): void;1 off(event: string, handler?: ClientEventHandler): void;1 emit(event: string, data: unknown, ack?: (reply: unknown) => void): void;1 emitWithAck<T = unknown>(event: string, data: unknown, timeoutMs?: number): Promise<T>;2}
ClientOptions)| Option | Type | Default | Meaning |
|---|---|---|---|
| protocols[cite: 2] | string | string[][cite: 2] | none[cite: 2] | WebSocket subprotocol or subprotocols passed to the native constructor[cite: 2]. |
| reconnect[cite: 2] | boolean[cite: 2] | true[cite: 2] | Retry automatically after an unplanned close[cite: 2]. Set to false for one-shot connections[cite: 4]. |
| reconnectAttempts[cite: 2] | number[cite: 2] | Infinity[cite: 2] | Maximum retry count before aborting reconnect attempts[cite: 2]. |
| reconnectDelayMs[cite: 2] | number[cite: 2] | 1500[cite: 2] | Fixed delay (in milliseconds) between reconnection attempts[cite: 2]. |
| autoConnect[cite: 2] | boolean[cite: 2] | true[cite: 2] | Automatically initiate connection handshake during class instantiation[cite: 2]. |
| auth.token[cite: 2] | string[cite: 2] | none[cite: 2] | Appends token to the connection URL query string (?token=...)[cite: 2]. |
Opens the WebSocket connection[cite: 2]. Use when autoConnect: false is set[cite: 4].
Cancels pending reconnection timers, clears buffered unsent frames, rejects open emitWithAck promises, and closes the transport with WebSocket code 1000[cite: 2, 4].
Registers an event handler and returns an unsubscribe cleanup function[cite: 2].
Sends a packet requesting server acknowledgement[cite: 2]. Defaults to a 5,000ms timeout[cite: 2]. Rejects if the server throws an error or the timeout expires[cite: 1, 2].
The client delivers three non-reserved lifecycle events locally[cite: 2]:
connect— Emitted when the WebSocket connection is established and ready[cite: 2].disconnect— Emitted when connection closes[cite: 2]. Receives { code, reason }[cite: 2].error— Emitted for transport errors or server protocol errors ({ code, message, details? })[cite: 2].emit() while offline are retained in an in-memory queue and flushed sequentially after the next successful connection[cite: 2, 4].Switch between JavaScript and TypeScript using the switcher in the header:
1import { SubAtomPulse } from "subatom-pulse";11// When running under Node.js, inject a WebSocket implementation:1// import { WebSocket } from "ws";1// globalThis.WebSocket = WebSocket as any;21const socket = new SubAtomPulse("ws://localhost:3000/ws", {1 auth: { token: "Bearer secret-app-token" },1 reconnect: true,1 reconnectAttempts: 10,1 reconnectDelayMs: 1500,1 autoConnect: true,1});31// Built-in client connection lifecycle events1socket.on("connect", () => {1 console.log("[WS Connected] State:", socket.state);2});41socket.on("disconnect", ({ code, reason }) => {1 console.log("[WS Closed]", code, reason);3});51socket.on("error", (err) => {1 console.error("[WS Error]", err);4});61// Fire-and-forget message1socket.emit("presence.ping", { timestamp: Date.now() });71// Request-response RPC with 5000ms timeout1try {1 const reply = await socket.emitWithAck<{ status: string }>(1 "order.status",1 { orderId: "ord_101" },1 50001 );1 console.log("Order confirmed:", reply.status);1} catch (err: any) {1 console.error("Ack rejected or timed out:", err.message);1}