@gwakko/shared-websocket 0.1.0

package/dist/vue.js

@@ -0,0 +1,93 @@
+import {
+  SharedWebSocket
+} from "./chunk-TNEMKPGP.js";
+
+// src/adapters/vue.ts
+import {
+  ref,
+  onUnmounted,
+  inject,
+  readonly,
+  watch
+} from "vue";
+var SharedWebSocketKey = /* @__PURE__ */ Symbol("SharedWebSocket");
+function createSharedWebSocketPlugin(url, options) {
+  return {
+    install(app) {
+      const socket = new SharedWebSocket(url, options);
+      socket.connect();
+      app.provide(SharedWebSocketKey, socket);
+      const originalUnmount = app.unmount.bind(app);
+      app.unmount = () => {
+        socket[Symbol.dispose]();
+        originalUnmount();
+      };
+    }
+  };
+}
+function useSharedWebSocket() {
+  const socket = inject(SharedWebSocketKey);
+  if (!socket) {
+    throw new Error("useSharedWebSocket: SharedWebSocket not provided. Did you install the plugin?");
+  }
+  return socket;
+}
+function useSocketEvent(event) {
+  const socket = useSharedWebSocket();
+  const value = ref(void 0);
+  const unsub = socket.on(event, (data) => {
+    value.value = data;
+  });
+  onUnmounted(unsub);
+  return readonly(value);
+}
+function useSocketStream(event) {
+  const socket = useSharedWebSocket();
+  const items = ref([]);
+  const unsub = socket.on(event, (data) => {
+    items.value = [...items.value, data];
+  });
+  onUnmounted(unsub);
+  return readonly(items);
+}
+function useSocketSync(key, initialValue) {
+  const socket = useSharedWebSocket();
+  const value = ref(socket.getSync(key) ?? initialValue);
+  const unsub = socket.onSync(key, (v) => {
+    value.value = v;
+  });
+  watch(
+    value,
+    (newVal) => {
+      socket.sync(key, newVal);
+    },
+    { deep: true }
+  );
+  onUnmounted(unsub);
+  return value;
+}
+function useSocketStatus() {
+  const socket = useSharedWebSocket();
+  const connected = ref(socket.connected);
+  const tabRole = ref(socket.tabRole);
+  let timer;
+  timer = setInterval(() => {
+    connected.value = socket.connected;
+    tabRole.value = socket.tabRole;
+  }, 1e3);
+  onUnmounted(() => clearInterval(timer));
+  return {
+    connected: readonly(connected),
+    tabRole: readonly(tabRole)
+  };
+}
+export {
+  SharedWebSocketKey,
+  createSharedWebSocketPlugin,
+  useSharedWebSocket,
+  useSocketEvent,
+  useSocketStatus,
+  useSocketStream,
+  useSocketSync
+};
+//# sourceMappingURL=vue.js.map

package/dist/vue.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/vue.ts"],"sourcesContent":["import {\n  ref,\n  onUnmounted,\n  inject,\n  readonly,\n  watch,\n  type Ref,\n  type InjectionKey,\n  type App,\n} from 'vue';\nimport { SharedWebSocket } from '../SharedWebSocket';\nimport type { SharedWebSocketOptions, TabRole } from '../types';\n\n// ─── Plugin ──────────────────────────────────────────────\n\nexport const SharedWebSocketKey: InjectionKey<SharedWebSocket> = Symbol('SharedWebSocket');\n\n/**\n * Vue 3 plugin for SharedWebSocket.\n *\n * @example\n * const app = createApp(App);\n * app.use(createSharedWebSocketPlugin('wss://api.example.com/ws'));\n */\nexport function createSharedWebSocketPlugin(url: string, options?: SharedWebSocketOptions) {\n  return {\n    install(app: App) {\n      const socket = new SharedWebSocket(url, options);\n      socket.connect();\n      app.provide(SharedWebSocketKey, socket);\n\n      // Cleanup on app unmount\n      const originalUnmount = app.unmount.bind(app);\n      app.unmount = () => {\n        socket[Symbol.dispose]();\n        originalUnmount();\n      };\n    },\n  };\n}\n\n/**\n * Access the SharedWebSocket instance from provided context.\n *\n * @example\n * const ws = useSharedWebSocket();\n */\nexport function useSharedWebSocket(): SharedWebSocket {\n  const socket = inject(SharedWebSocketKey);\n  if (!socket) {\n    throw new Error('useSharedWebSocket: SharedWebSocket not provided. Did you install the plugin?');\n  }\n  return socket;\n}\n\n// ─── Composables ─────────────────────────────────────────\n\n/**\n * Subscribe to a WebSocket event. Returns reactive ref with latest value.\n *\n * @example\n * const order = useSocketEvent<Order>('order.created');\n */\nexport function useSocketEvent<T>(event: string): Ref<T | undefined> {\n  const socket = useSharedWebSocket();\n  const value = ref<T | undefined>(undefined) as Ref<T | undefined>;\n\n  const unsub = socket.on(event, (data: T) => {\n    value.value = data;\n  });\n\n  onUnmounted(unsub);\n  return readonly(value) as Ref<T | undefined>;\n}\n\n/**\n * Accumulate WebSocket events into reactive array.\n *\n * @example\n * const messages = useSocketStream<ChatMessage>('chat.message');\n */\nexport function useSocketStream<T>(event: string): Ref<T[]> {\n  const socket = useSharedWebSocket();\n  const items = ref<T[]>([]) as Ref<T[]>;\n\n  const unsub = socket.on(event, (data: T) => {\n    items.value = [...items.value, data];\n  });\n\n  onUnmounted(unsub);\n  return readonly(items) as Ref<T[]>;\n}\n\n/**\n * Two-way state sync across browser tabs via reactive ref.\n *\n * @example\n * const cart = useSocketSync<Cart>('cart', { items: [] });\n * cart.value = { items: [1, 2, 3] }; // syncs to all tabs\n */\nexport function useSocketSync<T>(key: string, initialValue: T): Ref<T> {\n  const socket = useSharedWebSocket();\n  const value = ref<T>(socket.getSync<T>(key) ?? initialValue) as Ref<T>;\n\n  const unsub = socket.onSync<T>(key, (v) => {\n    value.value = v;\n  });\n\n  // Watch for local changes → sync to other tabs\n  watch(\n    value,\n    (newVal) => {\n      socket.sync(key, newVal);\n    },\n    { deep: true },\n  );\n\n  onUnmounted(unsub);\n  return value;\n}\n\n/**\n * Reactive connection status.\n *\n * @example\n * const { connected, tabRole } = useSocketStatus();\n */\nexport function useSocketStatus(): {\n  connected: Ref<boolean>;\n  tabRole: Ref<TabRole>;\n} {\n  const socket = useSharedWebSocket();\n  const connected = ref(socket.connected);\n  const tabRole = ref<TabRole>(socket.tabRole);\n\n  let timer: ReturnType<typeof setInterval>;\n\n  timer = setInterval(() => {\n    connected.value = socket.connected;\n    tabRole.value = socket.tabRole;\n  }, 1000);\n\n  onUnmounted(() => clearInterval(timer));\n\n  return {\n    connected: readonly(connected) as Ref<boolean>,\n    tabRole: readonly(tabRole) as Ref<TabRole>,\n  };\n}\n"],"mappings":";;;;;AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAIK;AAMA,IAAM,qBAAoD,uBAAO,iBAAiB;AASlF,SAAS,4BAA4B,KAAa,SAAkC;AACzF,SAAO;AAAA,IACL,QAAQ,KAAU;AAChB,YAAM,SAAS,IAAI,gBAAgB,KAAK,OAAO;AAC/C,aAAO,QAAQ;AACf,UAAI,QAAQ,oBAAoB,MAAM;AAGtC,YAAM,kBAAkB,IAAI,QAAQ,KAAK,GAAG;AAC5C,UAAI,UAAU,MAAM;AAClB,eAAO,OAAO,OAAO,EAAE;AACvB,wBAAgB;AAAA,MAClB;AAAA,IACF;AAAA,EACF;AACF;AAQO,SAAS,qBAAsC;AACpD,QAAM,SAAS,OAAO,kBAAkB;AACxC,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI,MAAM,+EAA+E;AAAA,EACjG;AACA,SAAO;AACT;AAUO,SAAS,eAAkB,OAAmC;AACnE,QAAM,SAAS,mBAAmB;AAClC,QAAM,QAAQ,IAAmB,MAAS;AAE1C,QAAM,QAAQ,OAAO,GAAG,OAAO,CAAC,SAAY;AAC1C,UAAM,QAAQ;AAAA,EAChB,CAAC;AAED,cAAY,KAAK;AACjB,SAAO,SAAS,KAAK;AACvB;AAQO,SAAS,gBAAmB,OAAyB;AAC1D,QAAM,SAAS,mBAAmB;AAClC,QAAM,QAAQ,IAAS,CAAC,CAAC;AAEzB,QAAM,QAAQ,OAAO,GAAG,OAAO,CAAC,SAAY;AAC1C,UAAM,QAAQ,CAAC,GAAG,MAAM,OAAO,IAAI;AAAA,EACrC,CAAC;AAED,cAAY,KAAK;AACjB,SAAO,SAAS,KAAK;AACvB;AASO,SAAS,cAAiB,KAAa,cAAyB;AACrE,QAAM,SAAS,mBAAmB;AAClC,QAAM,QAAQ,IAAO,OAAO,QAAW,GAAG,KAAK,YAAY;AAE3D,QAAM,QAAQ,OAAO,OAAU,KAAK,CAAC,MAAM;AACzC,UAAM,QAAQ;AAAA,EAChB,CAAC;AAGD;AAAA,IACE;AAAA,IACA,CAAC,WAAW;AACV,aAAO,KAAK,KAAK,MAAM;AAAA,IACzB;AAAA,IACA,EAAE,MAAM,KAAK;AAAA,EACf;AAEA,cAAY,KAAK;AACjB,SAAO;AACT;AAQO,SAAS,kBAGd;AACA,QAAM,SAAS,mBAAmB;AAClC,QAAM,YAAY,IAAI,OAAO,SAAS;AACtC,QAAM,UAAU,IAAa,OAAO,OAAO;AAE3C,MAAI;AAEJ,UAAQ,YAAY,MAAM;AACxB,cAAU,QAAQ,OAAO;AACzB,YAAQ,QAAQ,OAAO;AAAA,EACzB,GAAG,GAAI;AAEP,cAAY,MAAM,cAAc,KAAK,CAAC;AAEtC,SAAO;AAAA,IACL,WAAW,SAAS,SAAS;AAAA,IAC7B,SAAS,SAAS,OAAO;AAAA,EAC3B;AACF;","names":[]}

package/dist/withSocket.d.ts

@@ -0,0 +1,51 @@
+import { SharedWebSocket } from './SharedWebSocket';
+import type { SharedWebSocketOptions } from './types';
+/**
+ * Callback context — destructure what you need.
+ */
+export interface SocketScope {
+    /** The SharedWebSocket instance. */
+    ws: SharedWebSocket;
+    /** AbortSignal — aborted when scope exits (use with stream/fetch). */
+    signal: AbortSignal;
+}
+export interface WithSocketOptions extends SharedWebSocketOptions {
+    /** External AbortSignal — aborts the scope and disposes the socket. */
+    signal?: AbortSignal;
+}
+/**
+ * Scoped WebSocket lifecycle — creates, connects, and auto-disposes.
+ * Guarantees cleanup even on errors. No polyfills needed.
+ *
+ * @example
+ * // Basic — destructure { ws }
+ * await withSocket('wss://api.example.com/ws', async ({ ws }) => {
+ *   ws.on('order.created', (order) => console.log(order));
+ *   await longRunningWork();
+ * });
+ *
+ * @example
+ * // With auth and signal
+ * await withSocket('wss://api.example.com/ws', {
+ *   auth: () => localStorage.getItem('token')!,
+ * }, async ({ ws, signal }) => {
+ *   for await (const msg of ws.stream('chat.messages', signal)) {
+ *     renderMessage(msg);
+ *   }
+ * });
+ *
+ * @example
+ * // External cancellation
+ * const controller = new AbortController();
+ * setTimeout(() => controller.abort(), 30_000);
+ *
+ * await withSocket('wss://api.example.com/ws', {
+ *   signal: controller.signal,
+ * }, async ({ ws, signal }) => {
+ *   ws.on('notifications', (n) => showToast(n));
+ *   // Stays alive until controller aborts or scope exits
+ *   await new Promise((_, reject) => signal.addEventListener('abort', reject));
+ * });
+ */
+export declare function withSocket(url: string, optionsOrCallback: WithSocketOptions | WithSocketCallback, maybeCallback?: WithSocketCallback): Promise<void>;
+export type WithSocketCallback = (scope: SocketScope) => void | Promise<void>;

package/dist/worker/socket.worker.d.ts

@@ -0,0 +1,51 @@
+/**
+ * WebSocket Worker — runs WebSocket connection off the main thread.
+ *
+ * Communication with main thread via postMessage:
+ *
+ * Main → Worker:
+ *   { type: 'connect', url: string, protocols?: string[] }
+ *   { type: 'send', data: unknown }
+ *   { type: 'disconnect' }
+ *
+ * Worker → Main:
+ *   { type: 'open' }
+ *   { type: 'message', data: unknown }
+ *   { type: 'close', code: number, reason: string }
+ *   { type: 'error', message: string }
+ *   { type: 'state', state: SocketState }
+ */
+type SocketState = 'connecting' | 'connected' | 'reconnecting' | 'closed';
+interface WorkerCommand {
+    type: 'connect' | 'send' | 'disconnect';
+    url?: string;
+    protocols?: string[];
+    data?: unknown;
+    reconnect?: boolean;
+    reconnectMaxDelay?: number;
+    heartbeatInterval?: number;
+    bufferSize?: number;
+}
+declare let ws: WebSocket | null;
+declare let state: SocketState;
+declare let buffer: unknown[];
+declare let heartbeatTimer: ReturnType<typeof setInterval> | null;
+declare let reconnectTimer: ReturnType<typeof setTimeout> | null;
+declare let disposed: boolean;
+declare let currentUrl: string;
+declare let currentProtocols: string[];
+declare let shouldReconnect: boolean;
+declare let maxDelay: number;
+declare let heartbeatInterval: number;
+declare let maxBuffer: number;
+declare let backoffDelay: number;
+declare function setState(s: SocketState): void;
+declare function connect(url: string, protocols: string[]): void;
+declare function doConnect(): void;
+declare function send(data: unknown): void;
+declare function disconnect(): void;
+declare function flushBuffer(): void;
+declare function startHeartbeat(): void;
+declare function stopHeartbeat(): void;
+declare function scheduleReconnect(): void;
+declare function clearReconnect(): void;

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@gwakko/shared-websocket",
+  "version": "0.1.0",
+  "description": "Share ONE WebSocket connection across browser tabs — leader election, BroadcastChannel sync, optional Web Worker",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./react": {
+      "import": "./dist/react.js",
+      "require": "./dist/react.cjs",
+      "types": "./dist/react.d.ts"
+    },
+    "./vue": {
+      "import": "./dist/vue.js",
+      "require": "./dist/vue.cjs",
+      "types": "./dist/vue.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "websocket",
+    "broadcast-channel",
+    "shared",
+    "tabs",
+    "leader-election",
+    "real-time",
+    "react",
+    "vue",
+    "web-worker",
+    "sync"
+  ],
+  "author": "gwakko",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Gwakko/shared-websocket.git"
+  },
+  "homepage": "https://github.com/Gwakko/shared-websocket#readme",
+  "peerDependencies": {
+    "react": ">=19.0.0",
+    "vue": ">=3.4.0"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true },
+    "vue": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "react": "^19.2.5",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4",
+    "vue": "^3.5.32"
+  }
+}

package/src/MessageBus.ts

@@ -0,0 +1,112 @@
+import './utils/disposable';
+import { generateId } from './utils/id';
+import type { BusMessage, Unsubscribe } from './types';
+
+type Listener = (msg: BusMessage) => void;
+
+export class MessageBus implements Disposable {
+  private channel: BroadcastChannel;
+  private listeners = new Map<string, Set<Listener>>();
+  private pendingRequests = new Map<string, { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }>();
+
+  constructor(
+    channelName: string,
+    private readonly tabId: string,
+  ) {
+    this.channel = new BroadcastChannel(channelName);
+    this.channel.onmessage = (ev: MessageEvent<BusMessage>) => {
+      this.handleMessage(ev.data);
+    };
+  }
+
+  subscribe<T>(topic: string, fn: (data: T) => void): Unsubscribe {
+    const wrapper: Listener = (msg) => {
+      if (msg.source !== this.tabId) fn(msg.data as T);
+    };
+    this.addListener(topic, wrapper);
+    return () => this.removeListener(topic, wrapper);
+  }
+
+  publish<T>(topic: string, data: T): void {
+    this.postMessage({ topic, type: 'publish', data });
+  }
+
+  broadcast<T>(topic: string, data: T): void {
+    const msg = this.createMessage(topic, 'broadcast', data);
+    this.channel.postMessage(msg);
+    // Also deliver to self
+    this.handleMessage(msg);
+  }
+
+  async request<T, R>(topic: string, data: T, timeout = 5000): Promise<R> {
+    const msg = this.createMessage(topic, 'request', data);
+    return new Promise<R>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(msg.id);
+        reject(new Error(`MessageBus.request: timeout for topic "${topic}"`));
+      }, timeout);
+      this.pendingRequests.set(msg.id, { resolve: resolve as (v: unknown) => void, reject, timer });
+      this.channel.postMessage(msg);
+    });
+  }
+
+  respond<T, R>(topic: string, fn: (data: T) => R | Promise<R>): Unsubscribe {
+    const wrapper: Listener = async (msg) => {
+      if (msg.type !== 'request' || msg.source === this.tabId) return;
+      const result = await fn(msg.data as T);
+      this.postMessage({ topic, type: 'response', data: { requestId: msg.id, result } });
+    };
+    this.addListener(topic, wrapper);
+    return () => this.removeListener(topic, wrapper);
+  }
+
+  private handleMessage(msg: BusMessage): void {
+    // Handle response to pending request
+    if (msg.type === 'response') {
+      const payload = msg.data as { requestId: string; result: unknown };
+      const pending = this.pendingRequests.get(payload.requestId);
+      if (pending) {
+        clearTimeout(pending.timer);
+        this.pendingRequests.delete(payload.requestId);
+        pending.resolve(payload.result);
+        return;
+      }
+    }
+
+    const listeners = this.listeners.get(msg.topic);
+    if (listeners) {
+      for (const fn of listeners) fn(msg);
+    }
+  }
+
+  private postMessage(partial: Pick<BusMessage, 'topic' | 'type' | 'data'>): void {
+    this.channel.postMessage(this.createMessage(partial.topic, partial.type, partial.data));
+  }
+
+  private createMessage(topic: string, type: BusMessage['type'], data: unknown): BusMessage {
+    return { id: generateId(), source: this.tabId, topic, type, data, timestamp: Date.now() };
+  }
+
+  private addListener(topic: string, fn: Listener): void {
+    let set = this.listeners.get(topic);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(topic, set);
+    }
+    set.add(fn);
+  }
+
+  private removeListener(topic: string, fn: Listener): void {
+    this.listeners.get(topic)?.delete(fn);
+  }
+
+  [Symbol.dispose](): void {
+    for (const pending of this.pendingRequests.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error('MessageBus disposed'));
+    }
+    this.pendingRequests.clear();
+    this.listeners.clear();
+    this.channel.close();
+  }
+}

package/src/SharedSocket.ts

@@ -0,0 +1,183 @@
+import './utils/disposable';
+import { backoff } from './utils/backoff';
+import type { SocketState, Unsubscribe, EventHandler } from './types';
+
+interface SharedSocketOptions {
+  protocols?: string[];
+  reconnect?: boolean;
+  reconnectMaxDelay?: number;
+  heartbeatInterval?: number;
+  sendBuffer?: number;
+  auth?: () => string | Promise<string>;
+}
+
+export class SharedSocket implements Disposable {
+  private ws: WebSocket | null = null;
+  private _state: SocketState = 'closed';
+  private buffer: unknown[] = [];
+  private disposed = false;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+
+  private onMessageFns = new Set<EventHandler>();
+  private onStateChangeFns = new Set<(state: SocketState) => void>();
+
+  private readonly opts: Required<Omit<SharedSocketOptions, 'auth'>> & { auth?: () => string | Promise<string> };
+
+  constructor(
+    private url: string,
+    options: SharedSocketOptions = {},
+  ) {
+    this.opts = {
+      protocols: options.protocols ?? [],
+      reconnect: options.reconnect ?? true,
+      reconnectMaxDelay: options.reconnectMaxDelay ?? 30_000,
+      heartbeatInterval: options.heartbeatInterval ?? 30_000,
+      sendBuffer: options.sendBuffer ?? 100,
+      auth: options.auth,
+    };
+  }
+
+  get state(): SocketState {
+    return this._state;
+  }
+
+  async connect(): Promise<void> {
+    if (this.disposed) return;
+
+    this.setState('connecting');
+
+    let connectUrl = this.url;
+    if (this.opts.auth) {
+      const token = await this.opts.auth();
+      const sep = connectUrl.includes('?') ? '&' : '?';
+      connectUrl = `${connectUrl}${sep}token=${encodeURIComponent(token)}`;
+    }
+
+    this.ws = new WebSocket(connectUrl, this.opts.protocols);
+
+    this.ws.onopen = () => {
+      this.setState('connected');
+      this.flushBuffer();
+      this.startHeartbeat();
+    };
+
+    this.ws.onmessage = (ev: MessageEvent) => {
+      let data: unknown;
+      try {
+        data = JSON.parse(ev.data as string);
+      } catch {
+        data = ev.data;
+      }
+      for (const fn of this.onMessageFns) fn(data);
+    };
+
+    this.ws.onclose = () => {
+      this.stopHeartbeat();
+      if (!this.disposed && this.opts.reconnect) {
+        this.reconnect();
+      } else {
+        this.setState('closed');
+      }
+    };
+
+    this.ws.onerror = () => {
+      // onclose will fire after onerror
+    };
+  }
+
+  disconnect(): void {
+    this.disposed = true;
+    this.stopHeartbeat();
+    this.clearReconnect();
+
+    if (this.ws) {
+      this.ws.onclose = null;
+      this.ws.onmessage = null;
+      this.ws.onerror = null;
+      if (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING) {
+        this.ws.close(1000, 'client disconnect');
+      }
+      this.ws = null;
+    }
+
+    this.setState('closed');
+  }
+
+  send(data: unknown): void {
+    if (this._state === 'connected' && this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(data));
+    } else if (this._state === 'reconnecting' || this._state === 'connecting') {
+      if (this.buffer.length < this.opts.sendBuffer) {
+        this.buffer.push(data);
+      }
+    }
+  }
+
+  onMessage(fn: EventHandler): Unsubscribe {
+    this.onMessageFns.add(fn);
+    return () => this.onMessageFns.delete(fn);
+  }
+
+  onStateChange(fn: (state: SocketState) => void): Unsubscribe {
+    this.onStateChangeFns.add(fn);
+    return () => this.onStateChangeFns.delete(fn);
+  }
+
+  private reconnect(): void {
+    this.setState('reconnecting');
+    const gen = backoff(1000, this.opts.reconnectMaxDelay);
+
+    const attempt = () => {
+      if (this.disposed) return;
+      const delay = gen.next().value;
+      this.reconnectTimer = setTimeout(() => {
+        if (!this.disposed) this.connect();
+      }, delay);
+    };
+
+    attempt();
+  }
+
+  private flushBuffer(): void {
+    const pending = this.buffer.splice(0);
+    for (const item of pending) {
+      this.send(item);
+    }
+  }
+
+  private startHeartbeat(): void {
+    this.stopHeartbeat();
+    this.heartbeatTimer = setInterval(() => {
+      if (this.ws?.readyState === WebSocket.OPEN) {
+        this.ws.send(JSON.stringify({ type: 'ping' }));
+      }
+    }, this.opts.heartbeatInterval);
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+
+  private clearReconnect(): void {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+
+  private setState(state: SocketState): void {
+    this._state = state;
+    for (const fn of this.onStateChangeFns) fn(state);
+  }
+
+  [Symbol.dispose](): void {
+    this.disconnect();
+    this.onMessageFns.clear();
+    this.onStateChangeFns.clear();
+    this.buffer = [];
+  }
+}