Improved naming. Can now pass connection options (timeouts)

Author: deil

README.md

@@ -13,9 +13,9 @@ Over the past few years, I’ve had to implement WebSocket communication many ti
 
 This library grew out of my work on [theshutter.app](https://theshutter.app) ([@heyshutterapp](https://x.com/heyshutterapp)) — a platform for running remote photoshoots and recording video interviews — which involves a lot of real-time communication over WebSockets and WebRTC.
 
-### AlwaysConnected
+### WsConnectionMonitor
 
-The core of this library is `AlwaysConnected` — a finite state machine that keeps a WebSocket connection alive. It handles reconnection automatically, so you don't have to.
+The core of this library is `WsConnectionMonitor` — a finite state machine that keeps a WebSocket connection alive. It handles reconnection automatically, so you don't have to.
 
 #### State machine
 
@@ -34,23 +34,23 @@ Disconnected → Connecting → Limbo → Connected
 
 #### Application-level connection
 
-`AlwaysConnected` is protocol-agnostic. When the WebSocket opens, it transitions to **limbo** and calls your `onConnectedFn()`. This is where you authenticate, join a room, subscribe to topics, etc. Return `true` to confirm the connection is ready, which transitions to **connected**.
+`WsConnectionMonitor` is protocol-agnostic. When the WebSocket opens, it transitions to **limbo** and calls your `onConnectedFn()`. This is where you authenticate, join a room, subscribe to topics, etc. Return `true` to confirm the connection is ready, which transitions to **connected**.
 
 If your handshake doesn't complete within `connectionTimeout`, the connection is considered failed and reconnection is triggered.
 
 #### Heartbeats
 
 Heartbeat handling is split by responsibility:
 
-- **Outbound**: `AlwaysConnected` calls your `sendHeartbeat(ws, interval)` function at `heartbeatInterval`. You decide what to send (ping frame, JSON message, etc.).
+- **Outbound**: `WsConnectionMonitor` calls your `sendHeartbeat(ws, interval)` function at `heartbeatInterval`. You decide what to send (ping frame, JSON message, etc.).
 
 - **Inbound**: Your application tracks incoming heartbeats. When you detect a missing one, call `handleWebSocketHeartbeatTimeout()` to trigger reconnection.
 
-This design keeps `AlwaysConnected` unaware of your wire protocol.
+This design keeps `WsConnectionMonitor` unaware of your wire protocol.
 
 #### WebSocket factory
 
-`AlwaysConnected` doesn't create WebSockets directly. Instead, you provide a `createWs()` factory function. This allows you to:
+`WsConnectionMonitor` doesn't create WebSockets directly. Instead, you provide a `createWs()` factory function. This allows you to:
 - Use custom WebSocket implementations
 - Add logging or instrumentation
 
@@ -68,7 +68,7 @@ All timing is configurable via the options object:
 
 ### GreatWebSocket
 
-`GreatWebSocket` is the main class you'll use. It wraps `AlwaysConnected` and adds:
+`GreatWebSocket` is the main class you'll use. It wraps `WsConnectionMonitor` and adds:
 - Convenient `send()` method with connection checking
 - RPC-style request/response via `call()` and `tryHandleAsControlMessage()`
 - Connection state events

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@deilux/websocket-js",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Make WebSockets great again",
 	"main": "dist/cjs/index.js",
 	"module": "dist/esm/index.js",

src/events.ts

@@ -1,7 +1,6 @@
 import type { ConnectionState as ConnectionStateType } from "./models";
-import { ConnectionState } from "./models";
 
-export interface GreatWebSocketEventMap {
+export interface WebSocketEventMap {
   statechange: ConnectionStateChangeEvent;
   connectiontimeout: Event;
 }

src/index.ts

@@ -1,6 +1,9 @@
 export { ConnectionStateChangeEvent } from "./events";
-export { AlwaysConnected, AlwaysConnectedOptions } from "./keep-online";
 export { ConnectionState, createWebSocketFn, heartbeatFn } from "./models";
 export { RemoteCommand, ResponseMatcher } from "./rpc";
+export {
+  WsConnectionMonitor as AlwaysConnected,
+  WsConnectionOptions as AlwaysConnectedOptions,
+} from "./state-machine";
 export { GreatWebSocket } from "./websocket";
-export { createWebSocket } from "./websocket-factory";
+export { createDefaultWebSocket as createWebSocket } from "./websocket-factory";

src/models.ts

@@ -15,6 +15,7 @@ export interface WebSocketIsh {
 }
 
 export type createWebSocketFn = () => WebSocketIsh;
+
 export type heartbeatFn = (
   ws: WebSocketIsh,
   timeSinceLastHeartbeat: number,

src/keep-online.ts src/state-machine.tssrc/keep-online.ts renamed to src/state-machine.ts

@@ -1,7 +1,4 @@
-import {
-  ConnectionStateChangeEvent,
-  type GreatWebSocketEventMap,
-} from "./events";
+import { ConnectionStateChangeEvent, type WebSocketEventMap } from "./events";
 import {
   ConnectionState,
   type ConnectionState as ConnectionStateType,
@@ -10,13 +7,13 @@ import {
   type WebSocketIsh,
 } from "./models";
 
-export interface AlwaysConnectedOptions {
+export interface WsConnectionOptions {
   heartbeatInterval: number;
   reconnectDelay: number;
   connectionTimeout: number;
 }
 
-export class AlwaysConnected extends EventTarget {
+export class WsConnectionMonitor extends EventTarget {
   #active = false;
   #ws: WebSocketIsh | null = null;
   #state: ConnectionStateType = ConnectionState.Disconnected;
@@ -32,7 +29,7 @@ export class AlwaysConnected extends EventTarget {
     private readonly createWs: createWebSocketFn,
     private readonly onConnectedFn: () => Promise<boolean>,
     private readonly sendHeartbeat: heartbeatFn,
-    private readonly options: AlwaysConnectedOptions,
+    private readonly options: WsConnectionOptions,
   ) {
     super();
   }
@@ -179,15 +176,15 @@ export class AlwaysConnected extends EventTarget {
     }, this.options.reconnectDelay);
   }
 
-  addEventListener<K extends keyof GreatWebSocketEventMap>(
+  addEventListener<K extends keyof WebSocketEventMap>(
     type: K,
     listener: EventListenerOrEventListenerObject,
     options?: boolean | AddEventListenerOptions,
   ): void {
     super.addEventListener(type, listener, options);
   }
 
-  removeEventListener<K extends keyof GreatWebSocketEventMap>(
+  removeEventListener<K extends keyof WebSocketEventMap>(
     type: K,
     listener: EventListenerOrEventListenerObject,
     options?: boolean | EventListenerOptions,

src/websocket-factory.ts

@@ -1,36 +1,36 @@
 import type { WebSocketIsh } from "./models";
 
-export interface Operator {
+export interface ConnectionLifecycleHandler {
   handleWebSocketOpen(): void;
   handleWebSocketClosed(ws: WebSocket): void;
   handleWebSocketError(ws: WebSocket): void;
   handleWebSocketHeartbeatTimeout(): void;
 }
 
-export const createWebSocket = (
+export const createDefaultWebSocket = (
   wsUrl: string,
-  operator: Operator,
+  lifecycleHandler: ConnectionLifecycleHandler,
   onMessageFn: (ws: WebSocketIsh, ev: MessageEvent) => void,
 ): WebSocketIsh => {
   const ws = new WebSocket(wsUrl);
   ws.onerror = (error) => {
     console.error("WS error: ", error);
-    operator.handleWebSocketError(ws);
+    lifecycleHandler.handleWebSocketError(ws);
   };
 
   ws.onopen = async () => {
     console.log("Websocket connected");
 
     ws.onclose = (ev) => {
       console.log("WS closed: ", ev.reason, ev);
-      operator.handleWebSocketClosed(ws);
+      lifecycleHandler.handleWebSocketClosed(ws);
     };
 
     ws.onmessage = (ev) => {
       onMessageFn(ws, ev);
     };
 
-    operator.handleWebSocketOpen();
+    lifecycleHandler.handleWebSocketOpen();
   };
 
   return ws;

src/websocket.ts

@@ -1,34 +1,40 @@
-import type { GreatWebSocketEventMap } from "./events";
+import type { WebSocketEventMap } from "./events";
 import type { PendingCommand } from "./internal";
-import { AlwaysConnected } from "./keep-online";
 import { ConnectionState, type heartbeatFn } from "./models";
 import type { RemoteCommand } from "./rpc";
-import { createWebSocket, type Operator } from "./websocket-factory";
-
-export class GreatWebSocket implements Operator {
-  #ws: AlwaysConnected | null = null;
+import { WsConnectionMonitor, type WsConnectionOptions } from "./state-machine";
+import {
+  type ConnectionLifecycleHandler,
+  createDefaultWebSocket,
+} from "./websocket-factory";
+
+export const DEFAULT_CONNECTION_OPTIONS = {
+  heartbeatInterval: 15000,
+  reconnectDelay: 2000,
+  connectionTimeout: 15000,
+} as const satisfies WsConnectionOptions;
+
+export class GreatWebSocket implements ConnectionLifecycleHandler {
+  #ws: WsConnectionMonitor | null = null;
   #pendingCommands: PendingCommand[] = [];
 
   constructor(
     url: string,
     private readonly onConnectedFn: () => Promise<boolean>,
     private readonly onMessageFn: (ws: WebSocket, ev: MessageEvent) => void,
     private readonly sendHeartbeat: heartbeatFn,
+    private readonly options: WsConnectionOptions = DEFAULT_CONNECTION_OPTIONS,
   ) {
-    this.#ws = new AlwaysConnected(
+    this.#ws = new WsConnectionMonitor(
       () =>
-        createWebSocket(
+        createDefaultWebSocket(
           url,
           this,
           this.onMessageFn as (ws: unknown, ev: MessageEvent) => void,
         ),
       this.onConnectedFn,
       this.sendHeartbeat,
-      {
-        heartbeatInterval: 15000,
-        reconnectDelay: 2000,
-        connectionTimeout: 15000,
-      },
+      this.options,
     );
   }
 
@@ -76,15 +82,15 @@ export class GreatWebSocket implements Operator {
 
   //#region Events
 
-  addEventListener<K extends keyof GreatWebSocketEventMap>(
+  addEventListener<K extends keyof WebSocketEventMap>(
     type: K,
     listener: EventListenerOrEventListenerObject,
     options?: boolean | AddEventListenerOptions,
   ): void {
     this.#ws?.addEventListener(type, listener, options);
   }
 
-  removeEventListener<K extends keyof GreatWebSocketEventMap>(
+  removeEventListener<K extends keyof WebSocketEventMap>(
     type: K,
     listener: EventListenerOrEventListenerObject,
     options?: boolean | EventListenerOptions,

test/keep-online.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { ConnectionStateChangeEvent } from "../src/events";
-import { AlwaysConnected } from "../src/keep-online";
 import { ConnectionState } from "../src/models";
+import { WsConnectionMonitor } from "../src/state-machine";
 
 // Mock implementations
 class MockWebSocket {
@@ -12,12 +12,12 @@ class MockWebSocket {
   public removeEventListener = vi.fn();
 }
 
-describe("AlwaysConnected", () => {
+describe("WsConnectionMonitor", () => {
   let mockWebSocket: MockWebSocket;
   let createWebSocketFn: vi.MockedFunction<() => WebSocket>;
   let onConnectedFn: vi.MockedFunction<() => Promise<boolean>>;
   let sendHeartbeatFn: vi.MockedFunction<(ws: WebSocket) => void>;
-  let alwaysConnected: AlwaysConnected;
+  let alwaysConnected: WsConnectionMonitor;
 
   beforeEach(() => {
     vi.clearAllMocks();
@@ -29,7 +29,7 @@ describe("AlwaysConnected", () => {
     onConnectedFn = vi.fn().mockResolvedValue(true);
     sendHeartbeatFn = vi.fn();
 
-    alwaysConnected = new AlwaysConnected(
+    alwaysConnected = new WsConnectionMonitor(
       createWebSocketFn,
       onConnectedFn,
       sendHeartbeatFn,