@gwakko/shared-websocket 0.1.0

package/src/SharedWebSocket.ts

@@ -0,0 +1,225 @@
+import './utils/disposable';
+import { generateId } from './utils/id';
+import { MessageBus } from './MessageBus';
+import { TabCoordinator } from './TabCoordinator';
+import { SharedSocket } from './SharedSocket';
+import { WorkerSocket } from './WorkerSocket';
+import { SubscriptionManager } from './SubscriptionManager';
+import type { SharedWebSocketOptions, TabRole, Unsubscribe, EventHandler } from './types';
+
+/** Common interface for both SharedSocket and WorkerSocket. */
+interface SocketAdapter {
+  readonly state: string;
+  connect(): void;
+  send(data: unknown): void;
+  disconnect(): void;
+  onMessage(fn: EventHandler): Unsubscribe;
+  onStateChange(fn: (state: string) => void): Unsubscribe;
+  [Symbol.dispose](): void;
+}
+
+/**
+ * SharedWebSocket — shares ONE WebSocket connection across browser tabs.
+ *
+ * One tab becomes the "leader" and holds the WebSocket.
+ * Other tabs are "followers" receiving data via BroadcastChannel.
+ * If the leader closes, a new leader is elected automatically.
+ */
+export class SharedWebSocket implements Disposable {
+  private bus: MessageBus;
+  private coordinator: TabCoordinator;
+  private socket: SocketAdapter | null = null;
+  private subs = new SubscriptionManager();
+  private syncStore = new Map<string, unknown>();
+  private tabId: string;
+  private cleanups: Unsubscribe[] = [];
+  private disposed = false;
+
+  constructor(
+    private readonly url: string,
+    private readonly options: SharedWebSocketOptions = {},
+  ) {
+    this.tabId = generateId();
+    this.bus = new MessageBus('shared-ws', this.tabId);
+    this.coordinator = new TabCoordinator(this.bus, this.tabId, {
+      electionTimeout: options.electionTimeout,
+      heartbeatInterval: options.leaderHeartbeat,
+      leaderTimeout: options.leaderTimeout,
+    });
+
+    // When ANY tab receives a WS message via bus → emit to local subscribers
+    this.cleanups.push(
+      this.bus.subscribe<{ event: string; data: unknown }>('ws:message', (msg) => {
+        this.subs.emit(msg.event, msg.data);
+      }),
+    );
+
+    // Leader listens for send requests from followers
+    this.cleanups.push(
+      this.bus.subscribe<{ event: string; data: unknown }>('ws:send', (msg) => {
+        if (this.coordinator.isLeader && this.socket) {
+          this.socket.send({ event: msg.event, data: msg.data });
+        }
+      }),
+    );
+
+    // Sync across tabs
+    this.cleanups.push(
+      this.bus.subscribe<{ key: string; value: unknown }>('ws:sync', (msg) => {
+        this.syncStore.set(msg.key, msg.value);
+        this.subs.emit(`sync:${msg.key}`, msg.value);
+      }),
+    );
+
+    // Leader lifecycle
+    this.coordinator.onBecomeLeader(() => this.onBecomeLeader());
+    this.coordinator.onLoseLeadership(() => this.onLoseLeadership());
+
+    // Cleanup on tab close
+    if (typeof window !== 'undefined') {
+      const onBeforeUnload = () => this[Symbol.dispose]();
+      window.addEventListener('beforeunload', onBeforeUnload);
+      this.cleanups.push(() => window.removeEventListener('beforeunload', onBeforeUnload));
+    }
+  }
+
+  get connected(): boolean {
+    return this.socket?.state === 'connected' || !this.coordinator.isLeader;
+  }
+
+  get tabRole(): TabRole {
+    return this.coordinator.isLeader ? 'leader' : 'follower';
+  }
+
+  /** Start leader election and connect. */
+  async connect(): Promise<void> {
+    await this.coordinator.elect();
+  }
+
+  /** Subscribe to server events (works in ALL tabs). */
+  on(event: string, handler: EventHandler): Unsubscribe {
+    return this.subs.on(event, handler);
+  }
+
+  once(event: string, handler: EventHandler): Unsubscribe {
+    return this.subs.once(event, handler);
+  }
+
+  off(event: string, handler?: EventHandler): void {
+    this.subs.off(event, handler);
+  }
+
+  /** Async generator for consuming events. */
+  stream(event: string, signal?: AbortSignal): AsyncGenerator<unknown> {
+    return this.subs.stream(event, signal);
+  }
+
+  /** Send message to server (auto-routed through leader). */
+  send(event: string, data: unknown): void {
+    if (this.coordinator.isLeader && this.socket) {
+      this.socket.send({ event, data });
+    } else {
+      this.bus.publish('ws:send', { event, data });
+    }
+  }
+
+  /** Request/response through server via leader. */
+  async request<T>(event: string, data: unknown, timeout = 5000): Promise<T> {
+    return this.bus.request('ws:request', { event, data }, timeout);
+  }
+
+  /** Sync state across tabs (no server roundtrip). */
+  sync<T>(key: string, value: T): void {
+    this.syncStore.set(key, value);
+    this.bus.broadcast('ws:sync', { key, value });
+  }
+
+  getSync<T>(key: string): T | undefined {
+    return this.syncStore.get(key) as T | undefined;
+  }
+
+  onSync<T>(key: string, fn: (value: T) => void): Unsubscribe {
+    return this.subs.on(`sync:${key}`, fn as EventHandler);
+  }
+
+  disconnect(): void {
+    this[Symbol.dispose]();
+  }
+
+  private createSocket(): SocketAdapter {
+    const socketOptions = {
+      protocols: this.options.protocols,
+      reconnect: this.options.reconnect,
+      reconnectMaxDelay: this.options.reconnectMaxDelay,
+      heartbeatInterval: this.options.heartbeatInterval,
+      sendBuffer: this.options.sendBuffer,
+    };
+
+    if (this.options.useWorker) {
+      // WebSocket runs in a Web Worker — main thread stays free
+      return new WorkerSocket(this.url, {
+        ...socketOptions,
+        workerUrl: this.options.workerUrl,
+      });
+    }
+
+    // WebSocket runs in main thread (default)
+    return new SharedSocket(this.url, {
+      ...socketOptions,
+      auth: this.options.auth,
+    });
+  }
+
+  private onBecomeLeader(): void {
+    this.socket = this.createSocket();
+
+    this.socket.onMessage((data: any) => {
+      const event = data?.event ?? 'message';
+      const payload = data?.data ?? data;
+      // Broadcast to ALL tabs (including self)
+      this.bus.broadcast('ws:message', { event, data: payload });
+    });
+
+    // Handle send requests from followers (request/response pattern)
+    this.cleanups.push(
+      this.bus.respond<{ event: string; data: unknown }, unknown>('ws:request', async (req) => {
+        return new Promise((resolve) => {
+          const unsub = this.socket!.onMessage((response: any) => {
+            if (response?.event === req.event || response?.requestId) {
+              unsub();
+              resolve(response?.data ?? response);
+            }
+          });
+          this.socket!.send({ event: req.event, data: req.data });
+        });
+      }),
+    );
+
+    this.socket.connect();
+  }
+
+  private onLoseLeadership(): void {
+    if (this.socket) {
+      this.socket[Symbol.dispose]();
+      this.socket = null;
+    }
+  }
+
+  [Symbol.dispose](): void {
+    if (this.disposed) return;
+    this.disposed = true;
+
+    this.coordinator[Symbol.dispose]();
+
+    if (this.socket) {
+      this.socket[Symbol.dispose]();
+      this.socket = null;
+    }
+
+    for (const unsub of this.cleanups) unsub();
+    this.cleanups = [];
+    this.subs[Symbol.dispose]();
+    this.bus[Symbol.dispose]();
+    this.syncStore.clear();
+  }
+}

package/src/SubscriptionManager.ts

@@ -0,0 +1,86 @@
+import './utils/disposable';
+import type { EventHandler, Unsubscribe } from './types';
+
+export class SubscriptionManager implements Disposable {
+  private handlers = new Map<string, Set<EventHandler>>();
+  private lastMessages = new Map<string, unknown>();
+
+  on(event: string, handler: EventHandler): Unsubscribe {
+    let set = this.handlers.get(event);
+    if (!set) {
+      set = new Set();
+      this.handlers.set(event, set);
+    }
+    set.add(handler);
+    return () => set!.delete(handler);
+  }
+
+  once(event: string, handler: EventHandler): Unsubscribe {
+    const wrapper: EventHandler = (data) => {
+      unsub();
+      handler(data);
+    };
+    const unsub = this.on(event, wrapper);
+    return unsub;
+  }
+
+  off(event: string, handler?: EventHandler): void {
+    if (handler) {
+      this.handlers.get(event)?.delete(handler);
+    } else {
+      this.handlers.delete(event);
+    }
+  }
+
+  emit(event: string, data: unknown): void {
+    this.lastMessages.set(event, data);
+    const set = this.handlers.get(event);
+    if (set) {
+      for (const fn of set) fn(data);
+    }
+  }
+
+  getLastMessage(event: string): unknown | undefined {
+    return this.lastMessages.get(event);
+  }
+
+  async *stream(event: string, signal?: AbortSignal): AsyncGenerator<unknown> {
+    const queue: unknown[] = [];
+    let resolve: (() => void) | null = null;
+    let done = false;
+
+    const unsub = this.on(event, (data) => {
+      queue.push(data);
+      resolve?.();
+    });
+
+    const onAbort = () => {
+      done = true;
+      resolve?.();
+    };
+    signal?.addEventListener('abort', onAbort);
+
+    try {
+      while (!done) {
+        if (queue.length > 0) {
+          yield queue.shift()!;
+        } else {
+          await new Promise<void>((r) => { resolve = r; });
+          resolve = null;
+        }
+      }
+    } finally {
+      unsub();
+      signal?.removeEventListener('abort', onAbort);
+    }
+  }
+
+  offAll(): void {
+    this.handlers.clear();
+    this.lastMessages.clear();
+  }
+
+  [Symbol.dispose](): void {
+    this.offAll();
+  }
+}

package/src/TabCoordinator.ts

@@ -0,0 +1,162 @@
+import './utils/disposable';
+import { MessageBus } from './MessageBus';
+import type { Unsubscribe } from './types';
+
+interface CoordinatorOptions {
+  electionTimeout?: number;   // ms to wait for rejection (default 200)
+  heartbeatInterval?: number; // ms between heartbeats (default 2000)
+  leaderTimeout?: number;     // ms without heartbeat to trigger election (default 5000)
+}
+
+export class TabCoordinator implements Disposable {
+  private _isLeader = false;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private leaderCheckTimer: ReturnType<typeof setInterval> | null = null;
+  private lastHeartbeat = 0;
+  private disposed = false;
+
+  private onBecomeLeaderFns = new Set<() => void>();
+  private onLoseLeadershipFns = new Set<() => void>();
+  private cleanups: Unsubscribe[] = [];
+
+  private readonly electionTimeout: number;
+  private readonly heartbeatInterval: number;
+  private readonly leaderTimeout: number;
+
+  constructor(
+    private readonly bus: MessageBus,
+    private readonly tabId: string,
+    options: CoordinatorOptions = {},
+  ) {
+    this.electionTimeout = options.electionTimeout ?? 200;
+    this.heartbeatInterval = options.heartbeatInterval ?? 2000;
+    this.leaderTimeout = options.leaderTimeout ?? 5000;
+
+    // Listen for election requests — reject if we are leader
+    this.cleanups.push(
+      this.bus.subscribe<{ tabId: string }>('coord:election', () => {
+        if (this._isLeader) {
+          this.bus.publish('coord:reject', { tabId: this.tabId });
+        }
+      }),
+    );
+
+    // Listen for heartbeats
+    this.cleanups.push(
+      this.bus.subscribe<{ tabId: string }>('coord:heartbeat', () => {
+        this.lastHeartbeat = Date.now();
+      }),
+    );
+
+    // Listen for abdication
+    this.cleanups.push(
+      this.bus.subscribe('coord:abdicate', () => {
+        if (!this._isLeader && !this.disposed) {
+          this.elect();
+        }
+      }),
+    );
+  }
+
+  get isLeader(): boolean {
+    return this._isLeader;
+  }
+
+  async elect(): Promise<void> {
+    if (this.disposed) return;
+
+    return new Promise<void>((resolve) => {
+      let rejected = false;
+
+      const unsub = this.bus.subscribe('coord:reject', () => {
+        rejected = true;
+        unsub();
+        // We are follower — start monitoring leader heartbeat
+        this.startLeaderCheck();
+        resolve();
+      });
+
+      this.bus.publish('coord:election', { tabId: this.tabId });
+
+      setTimeout(() => {
+        unsub();
+        if (!rejected && !this.disposed) {
+          this.becomeLeader();
+        }
+        resolve();
+      }, this.electionTimeout);
+    });
+  }
+
+  abdicate(): void {
+    if (!this._isLeader) return;
+    this._isLeader = false;
+    this.stopHeartbeat();
+    this.bus.publish('coord:abdicate', { tabId: this.tabId });
+    for (const fn of this.onLoseLeadershipFns) fn();
+  }
+
+  onBecomeLeader(fn: () => void): Unsubscribe {
+    this.onBecomeLeaderFns.add(fn);
+    return () => this.onBecomeLeaderFns.delete(fn);
+  }
+
+  onLoseLeadership(fn: () => void): Unsubscribe {
+    this.onLoseLeadershipFns.add(fn);
+    return () => this.onLoseLeadershipFns.delete(fn);
+  }
+
+  private becomeLeader(): void {
+    this._isLeader = true;
+    this.stopLeaderCheck();
+    this.startHeartbeat();
+    for (const fn of this.onBecomeLeaderFns) fn();
+  }
+
+  private startHeartbeat(): void {
+    this.stopHeartbeat();
+    this.heartbeatTimer = setInterval(() => {
+      this.bus.publish('coord:heartbeat', { tabId: this.tabId });
+    }, this.heartbeatInterval);
+    // Send immediately
+    this.bus.publish('coord:heartbeat', { tabId: this.tabId });
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+
+  private startLeaderCheck(): void {
+    this.stopLeaderCheck();
+    this.lastHeartbeat = Date.now();
+    this.leaderCheckTimer = setInterval(() => {
+      if (Date.now() - this.lastHeartbeat > this.leaderTimeout && !this.disposed) {
+        this.stopLeaderCheck();
+        this.elect();
+      }
+    }, 1000);
+  }
+
+  private stopLeaderCheck(): void {
+    if (this.leaderCheckTimer) {
+      clearInterval(this.leaderCheckTimer);
+      this.leaderCheckTimer = null;
+    }
+  }
+
+  [Symbol.dispose](): void {
+    this.disposed = true;
+    if (this._isLeader) {
+      this.abdicate();
+    }
+    this.stopHeartbeat();
+    this.stopLeaderCheck();
+    for (const unsub of this.cleanups) unsub();
+    this.cleanups = [];
+    this.onBecomeLeaderFns.clear();
+    this.onLoseLeadershipFns.clear();
+  }
+}

package/src/WorkerSocket.ts

@@ -0,0 +1,149 @@
+import './utils/disposable';
+import type { SocketState, Unsubscribe, EventHandler } from './types';
+
+/**
+ * WorkerSocket — WebSocket running inside a Web Worker.
+ *
+ * Same interface as SharedSocket, but WebSocket lives off main thread.
+ * Benefits: heartbeat timers and JSON parsing don't block UI rendering.
+ *
+ * Use when:
+ * - High message rate (50+ msgs/sec)
+ * - Heavy JSON payloads
+ * - UI does complex rendering that could block main thread
+ *
+ * Don't use when:
+ * - Low message rate (simple chat, notifications)
+ * - Bundle size matters (adds worker file)
+ * - Debugging (Worker DevTools is less convenient)
+ */
+export class WorkerSocket implements Disposable {
+  private worker: Worker | null = null;
+  private _state: SocketState = 'closed';
+
+  private onMessageFns = new Set<EventHandler>();
+  private onStateChangeFns = new Set<(state: SocketState) => void>();
+
+  constructor(
+    private url: string,
+    private options: {
+      protocols?: string[];
+      reconnect?: boolean;
+      reconnectMaxDelay?: number;
+      heartbeatInterval?: number;
+      sendBuffer?: number;
+      workerUrl?: string | URL;
+    } = {},
+  ) {}
+
+  get state(): SocketState {
+    return this._state;
+  }
+
+  connect(): void {
+    // Create worker from inline blob if no workerUrl provided
+    const workerUrl = this.options.workerUrl ?? this.createWorkerBlob();
+
+    this.worker = new Worker(workerUrl, { type: 'module' });
+
+    this.worker.onmessage = (ev: MessageEvent) => {
+      const msg = ev.data;
+
+      switch (msg.type) {
+        case 'state':
+          this._state = msg.state;
+          for (const fn of this.onStateChangeFns) fn(msg.state);
+          break;
+
+        case 'message':
+          for (const fn of this.onMessageFns) fn(msg.data);
+          break;
+
+        case 'open':
+          // State already set via 'state' message
+          break;
+
+        case 'close':
+          break;
+
+        case 'error':
+          console.error('WorkerSocket error:', msg.message);
+          break;
+      }
+    };
+
+    this.worker.postMessage({
+      type: 'connect',
+      url: this.url,
+      protocols: this.options.protocols ?? [],
+      reconnect: this.options.reconnect ?? true,
+      reconnectMaxDelay: this.options.reconnectMaxDelay ?? 30_000,
+      heartbeatInterval: this.options.heartbeatInterval ?? 30_000,
+      bufferSize: this.options.sendBuffer ?? 100,
+    });
+  }
+
+  send(data: unknown): void {
+    this.worker?.postMessage({ type: 'send', data });
+  }
+
+  disconnect(): void {
+    this.worker?.postMessage({ type: 'disconnect' });
+    setTimeout(() => {
+      this.worker?.terminate();
+      this.worker = null;
+    }, 100);
+    this._state = 'closed';
+  }
+
+  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 createWorkerBlob(): URL {
+    // Inline the worker code as a blob URL
+    // In production, use a bundler (Vite, webpack) to handle worker imports
+    const code = `
+      let ws = null, state = 'closed', buffer = [], disposed = false;
+      let heartbeatTimer = null, reconnectTimer = null;
+      let url = '', protocols = [], shouldReconnect = true;
+      let maxDelay = 30000, hbInterval = 30000, maxBuf = 100, delay = 1000;
+
+      function setState(s) { state = s; self.postMessage({ type: 'state', state: s }); }
+      function connect() {
+        if (disposed) return;
+        setState('connecting');
+        ws = new WebSocket(url, protocols);
+        ws.onopen = () => { setState('connected'); delay = 1000; self.postMessage({ type: 'open' }); flush(); startHB(); };
+        ws.onmessage = (e) => { let d; try { d = JSON.parse(e.data); } catch { d = e.data; } self.postMessage({ type: 'message', data: d }); };
+        ws.onclose = (e) => { stopHB(); self.postMessage({ type: 'close', code: e.code, reason: e.reason }); if (!disposed && shouldReconnect && e.code !== 1000) reconnect(); else setState('closed'); };
+        ws.onerror = () => { self.postMessage({ type: 'error', message: 'error' }); };
+      }
+      function send(d) { if (state === 'connected' && ws?.readyState === 1) ws.send(JSON.stringify(d)); else if (buffer.length < maxBuf) buffer.push(d); }
+      function flush() { const p = buffer.splice(0); p.forEach(send); }
+      function startHB() { stopHB(); heartbeatTimer = setInterval(() => { if (ws?.readyState === 1) ws.send('{"type":"ping"}'); }, hbInterval); }
+      function stopHB() { if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; } }
+      function reconnect() { setState('reconnecting'); const j = delay * 0.25 * (Math.random() * 2 - 1); reconnectTimer = setTimeout(() => { if (!disposed) connect(); }, Math.min(delay + j, maxDelay)); delay = Math.min(delay * 2, maxDelay); }
+      self.onmessage = (e) => {
+        const c = e.data;
+        if (c.type === 'connect') { url = c.url; protocols = c.protocols || []; shouldReconnect = c.reconnect ?? true; maxDelay = c.reconnectMaxDelay || 30000; hbInterval = c.heartbeatInterval || 30000; maxBuf = c.bufferSize || 100; connect(); }
+        if (c.type === 'send') send(c.data);
+        if (c.type === 'disconnect') { disposed = true; stopHB(); if (reconnectTimer) clearTimeout(reconnectTimer); if (ws) { ws.onclose = null; if (ws.readyState < 2) ws.close(1000); ws = null; } buffer = []; setState('closed'); }
+      };
+    `;
+    const blob = new Blob([code], { type: 'application/javascript' });
+    return new URL(URL.createObjectURL(blob));
+  }
+
+  [Symbol.dispose](): void {
+    this.disconnect();
+    this.onMessageFns.clear();
+    this.onStateChangeFns.clear();
+  }
+}

package/src/adapters/index.ts

@@ -0,0 +1,3 @@
+// Import framework-specific adapters directly:
+// import { createSharedWebSocket, useSocketEvent } from 'shared-websocket/adapters/react';
+// import { createSharedWebSocketPlugin, useSocketEvent } from 'shared-websocket/adapters/vue';