@gwakko/shared-websocket 0.1.0

package/src/adapters/react.ts

@@ -0,0 +1,189 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useState,
+  useEffectEvent,
+  type ReactNode,
+  createElement,
+} from 'react';
+import { SharedWebSocket } from '../SharedWebSocket';
+import type { SharedWebSocketOptions, TabRole } from '../types';
+
+// ─── Context ─────────────────────────────────────────────
+
+const SharedWSContext = createContext<SharedWebSocket | null>(null);
+
+/**
+ * Provider props — pass URL and options as props for flexibility.
+ *
+ * @example
+ * <SharedWebSocketProvider url="wss://api.example.com/ws" options={{ auth: getToken }}>
+ *   <App />
+ * </SharedWebSocketProvider>
+ */
+export interface SharedWebSocketProviderProps {
+  url: string;
+  options?: SharedWebSocketOptions;
+  children: ReactNode;
+}
+
+/**
+ * Provider component — creates SharedWebSocket from props, auto-disposes on unmount.
+ *
+ * @example
+ * function App() {
+ *   return (
+ *     <SharedWebSocketProvider
+ *       url="wss://api.example.com/ws"
+ *       options={{
+ *         auth: () => localStorage.getItem('token')!,
+ *         useWorker: true,
+ *       }}
+ *     >
+ *       <Dashboard />
+ *     </SharedWebSocketProvider>
+ *   );
+ * }
+ */
+export function SharedWebSocketProvider({ url, options, children }: SharedWebSocketProviderProps) {
+  const [socket] = useState(() => {
+    const ws = new SharedWebSocket(url, options);
+    ws.connect();
+    return ws;
+  });
+
+  useEffect(() => {
+    return () => {
+      socket[Symbol.dispose]();
+    };
+  }, [socket]);
+
+  return createElement(SharedWSContext.Provider, { value: socket }, children);
+}
+
+/**
+ * Access the SharedWebSocket instance from context.
+ *
+ * @example
+ * const ws = useSharedWebSocket();
+ * ws.send('chat.message', { text: 'Hello' });
+ */
+export function useSharedWebSocket(): SharedWebSocket {
+  const ctx = useContext(SharedWSContext);
+  if (!ctx) {
+    throw new Error('useSharedWebSocket must be used within <SharedWebSocketProvider>');
+  }
+  return ctx;
+}
+
+// ─── Hooks ───────────────────────────────────────────────
+
+/**
+ * Subscribe to a WebSocket event. Returns the latest received value.
+ * Uses useEffectEvent for a stable callback ref — no stale closures.
+ *
+ * @example
+ * const order = useSocketEvent<Order>('order.created');
+ */
+export function useSocketEvent<T>(event: string): T | undefined {
+  const socket = useSharedWebSocket();
+  const [value, setValue] = useState<T | undefined>(undefined);
+
+  const onEvent = useEffectEvent((data: T) => {
+    setValue(data);
+  });
+
+  useEffect(() => {
+    const unsub = socket.on(event, onEvent);
+    return unsub;
+  }, [socket, event]);
+
+  return value;
+}
+
+/**
+ * Accumulate WebSocket events into an array.
+ * Uses useEffectEvent — handler always sees latest state without re-subscribing.
+ *
+ * @example
+ * const messages = useSocketStream<ChatMessage>('chat.message');
+ */
+export function useSocketStream<T>(event: string): T[] {
+  const socket = useSharedWebSocket();
+  const [items, setItems] = useState<T[]>([]);
+
+  const onEvent = useEffectEvent((data: T) => {
+    setItems((prev) => [...prev, data]);
+  });
+
+  useEffect(() => {
+    setItems([]);
+    const unsub = socket.on(event, onEvent);
+    return unsub;
+  }, [socket, event]);
+
+  return items;
+}
+
+/**
+ * Two-way state sync across browser tabs.
+ * Uses useEffectEvent for stable sync callback.
+ *
+ * @example
+ * const [cart, setCart] = useSocketSync<Cart>('cart', { items: [] });
+ * // setCart in one tab → updates all tabs instantly
+ */
+export function useSocketSync<T>(
+  key: string,
+  initialValue: T,
+): [T, (value: T) => void] {
+  const socket = useSharedWebSocket();
+  const [value, setValue] = useState<T>(() => {
+    return socket.getSync<T>(key) ?? initialValue;
+  });
+
+  const onSync = useEffectEvent((synced: T) => {
+    setValue(synced);
+  });
+
+  useEffect(() => {
+    const unsub = socket.onSync<T>(key, onSync);
+    return unsub;
+  }, [socket, key]);
+
+  const setAndSync = useEffectEvent((newValue: T) => {
+    setValue(newValue);
+    socket.sync(key, newValue);
+  });
+
+  return [value, setAndSync];
+}
+
+/**
+ * Reactive connection status.
+ * Uses useEffectEvent to avoid re-creating interval on state change.
+ *
+ * @example
+ * const { connected, tabRole } = useSocketStatus();
+ */
+export function useSocketStatus(): {
+  connected: boolean;
+  tabRole: TabRole;
+} {
+  const socket = useSharedWebSocket();
+  const [connected, setConnected] = useState(socket.connected);
+  const [tabRole, setTabRole] = useState<TabRole>(socket.tabRole);
+
+  const tick = useEffectEvent(() => {
+    setConnected(socket.connected);
+    setTabRole(socket.tabRole);
+  });
+
+  useEffect(() => {
+    const interval = setInterval(tick, 1000);
+    return () => clearInterval(interval);
+  }, [socket]);
+
+  return { connected, tabRole };
+}

package/src/adapters/vue.ts

@@ -0,0 +1,149 @@
+import {
+  ref,
+  onUnmounted,
+  inject,
+  readonly,
+  watch,
+  type Ref,
+  type InjectionKey,
+  type App,
+} from 'vue';
+import { SharedWebSocket } from '../SharedWebSocket';
+import type { SharedWebSocketOptions, TabRole } from '../types';
+
+// ─── Plugin ──────────────────────────────────────────────
+
+export const SharedWebSocketKey: InjectionKey<SharedWebSocket> = Symbol('SharedWebSocket');
+
+/**
+ * Vue 3 plugin for SharedWebSocket.
+ *
+ * @example
+ * const app = createApp(App);
+ * app.use(createSharedWebSocketPlugin('wss://api.example.com/ws'));
+ */
+export function createSharedWebSocketPlugin(url: string, options?: SharedWebSocketOptions) {
+  return {
+    install(app: App) {
+      const socket = new SharedWebSocket(url, options);
+      socket.connect();
+      app.provide(SharedWebSocketKey, socket);
+
+      // Cleanup on app unmount
+      const originalUnmount = app.unmount.bind(app);
+      app.unmount = () => {
+        socket[Symbol.dispose]();
+        originalUnmount();
+      };
+    },
+  };
+}
+
+/**
+ * Access the SharedWebSocket instance from provided context.
+ *
+ * @example
+ * const ws = useSharedWebSocket();
+ */
+export function useSharedWebSocket(): SharedWebSocket {
+  const socket = inject(SharedWebSocketKey);
+  if (!socket) {
+    throw new Error('useSharedWebSocket: SharedWebSocket not provided. Did you install the plugin?');
+  }
+  return socket;
+}
+
+// ─── Composables ─────────────────────────────────────────
+
+/**
+ * Subscribe to a WebSocket event. Returns reactive ref with latest value.
+ *
+ * @example
+ * const order = useSocketEvent<Order>('order.created');
+ */
+export function useSocketEvent<T>(event: string): Ref<T | undefined> {
+  const socket = useSharedWebSocket();
+  const value = ref<T | undefined>(undefined) as Ref<T | undefined>;
+
+  const unsub = socket.on(event, (data: T) => {
+    value.value = data;
+  });
+
+  onUnmounted(unsub);
+  return readonly(value) as Ref<T | undefined>;
+}
+
+/**
+ * Accumulate WebSocket events into reactive array.
+ *
+ * @example
+ * const messages = useSocketStream<ChatMessage>('chat.message');
+ */
+export function useSocketStream<T>(event: string): Ref<T[]> {
+  const socket = useSharedWebSocket();
+  const items = ref<T[]>([]) as Ref<T[]>;
+
+  const unsub = socket.on(event, (data: T) => {
+    items.value = [...items.value, data];
+  });
+
+  onUnmounted(unsub);
+  return readonly(items) as Ref<T[]>;
+}
+
+/**
+ * Two-way state sync across browser tabs via reactive ref.
+ *
+ * @example
+ * const cart = useSocketSync<Cart>('cart', { items: [] });
+ * cart.value = { items: [1, 2, 3] }; // syncs to all tabs
+ */
+export function useSocketSync<T>(key: string, initialValue: T): Ref<T> {
+  const socket = useSharedWebSocket();
+  const value = ref<T>(socket.getSync<T>(key) ?? initialValue) as Ref<T>;
+
+  const unsub = socket.onSync<T>(key, (v) => {
+    value.value = v;
+  });
+
+  // Watch for local changes → sync to other tabs
+  watch(
+    value,
+    (newVal) => {
+      socket.sync(key, newVal);
+    },
+    { deep: true },
+  );
+
+  onUnmounted(unsub);
+  return value;
+}
+
+/**
+ * Reactive connection status.
+ *
+ * @example
+ * const { connected, tabRole } = useSocketStatus();
+ */
+export function useSocketStatus(): {
+  connected: Ref<boolean>;
+  tabRole: Ref<TabRole>;
+} {
+  const socket = useSharedWebSocket();
+  const connected = ref(socket.connected);
+  const tabRole = ref<TabRole>(socket.tabRole);
+
+  let timer: ReturnType<typeof setInterval>;
+
+  timer = setInterval(() => {
+    connected.value = socket.connected;
+    tabRole.value = socket.tabRole;
+  }, 1000);
+
+  onUnmounted(() => clearInterval(timer));
+
+  return {
+    connected: readonly(connected) as Ref<boolean>,
+    tabRole: readonly(tabRole) as Ref<TabRole>,
+  };
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export { SharedWebSocket } from './SharedWebSocket';
+export { withSocket, type WithSocketCallback, type WithSocketOptions, type SocketScope } from './withSocket';
+export { MessageBus } from './MessageBus';
+export { TabCoordinator } from './TabCoordinator';
+export { SharedSocket } from './SharedSocket';
+export { WorkerSocket } from './WorkerSocket';
+export { SubscriptionManager } from './SubscriptionManager';
+export type { SharedWebSocketOptions, SocketState, TabRole, Unsubscribe, EventHandler } from './types';

package/src/types.ts

@@ -0,0 +1,29 @@
+export type SocketState = 'connecting' | 'connected' | 'reconnecting' | 'closed';
+export type TabRole = 'leader' | 'follower';
+export type Unsubscribe = () => void;
+export type EventHandler = (data: any) => void;
+
+export interface BusMessage {
+  id: string;
+  source: string;
+  topic: string;
+  type: 'publish' | 'request' | 'response' | 'broadcast';
+  data: unknown;
+  timestamp: number;
+}
+
+export interface SharedWebSocketOptions {
+  protocols?: string[];
+  reconnect?: boolean;
+  reconnectMaxDelay?: number;
+  heartbeatInterval?: number;
+  electionTimeout?: number;
+  leaderHeartbeat?: number;
+  leaderTimeout?: number;
+  sendBuffer?: number;
+  auth?: () => string | Promise<string>;
+  /** Run WebSocket inside a Web Worker (offloads JSON parsing, heartbeat from main thread). */
+  useWorker?: boolean;
+  /** Custom worker URL (if useWorker is true and you want to provide your own worker file). */
+  workerUrl?: string | URL;
+}

package/src/utils/backoff.ts

@@ -0,0 +1,9 @@
+/** Exponential backoff generator with jitter. */
+export function* backoff(base = 1000, max = 30_000): Generator<number> {
+  let delay = base;
+  while (true) {
+    const jitter = delay * 0.25 * (Math.random() * 2 - 1);
+    yield Math.min(delay + jitter, max);
+    delay = Math.min(delay * 2, max);
+  }
+}

package/src/utils/disposable.ts

@@ -0,0 +1,4 @@
+/** Polyfill Symbol.dispose if not available. */
+if (typeof Symbol.dispose === 'undefined') {
+  (Symbol as any).dispose = Symbol('Symbol.dispose');
+}

package/src/utils/id.ts

@@ -0,0 +1,6 @@
+export function generateId(): string {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}

package/src/withSocket.ts

@@ -0,0 +1,89 @@
+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 async function withSocket(
+  url: string,
+  optionsOrCallback: WithSocketOptions | WithSocketCallback,
+  maybeCallback?: WithSocketCallback,
+): Promise<void> {
+  let options: WithSocketOptions | undefined;
+  let callback: WithSocketCallback;
+
+  if (typeof optionsOrCallback === 'function') {
+    callback = optionsOrCallback;
+  } else {
+    options = optionsOrCallback;
+    callback = maybeCallback!;
+  }
+
+  const ws = new SharedWebSocket(url, options);
+  const controller = new AbortController();
+
+  // Link external signal
+  if (options?.signal) {
+    if (options.signal.aborted) {
+      ws[Symbol.dispose]();
+      throw options.signal.reason ?? new Error('Aborted');
+    }
+    options.signal.addEventListener('abort', () => controller.abort(options!.signal!.reason), { once: true });
+  }
+
+  try {
+    await ws.connect();
+    await callback({ ws, signal: controller.signal });
+  } finally {
+    controller.abort();
+    ws[Symbol.dispose]();
+  }
+}
+
+export type WithSocketCallback = (scope: SocketScope) => void | Promise<void>;

package/src/worker/socket.worker.ts

@@ -0,0 +1,205 @@
+/**
+ * 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;
+}
+
+let ws: WebSocket | null = null;
+let state: SocketState = 'closed';
+let buffer: unknown[] = [];
+let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+let disposed = false;
+
+let currentUrl = '';
+let currentProtocols: string[] = [];
+let shouldReconnect = true;
+let maxDelay = 30_000;
+let heartbeatInterval = 30_000;
+let maxBuffer = 100;
+
+// Backoff state
+let backoffDelay = 1000;
+
+function setState(s: SocketState) {
+  state = s;
+  self.postMessage({ type: 'state', state: s });
+}
+
+function connect(url: string, protocols: string[]) {
+  if (disposed) return;
+
+  currentUrl = url;
+  currentProtocols = protocols;
+  backoffDelay = 1000;
+
+  doConnect();
+}
+
+function doConnect() {
+  if (disposed) return;
+  setState('connecting');
+
+  try {
+    ws = new WebSocket(currentUrl, currentProtocols);
+  } catch (e) {
+    self.postMessage({ type: 'error', message: String(e) });
+    if (shouldReconnect) scheduleReconnect();
+    return;
+  }
+
+  ws.onopen = () => {
+    setState('connected');
+    backoffDelay = 1000;
+    self.postMessage({ type: 'open' });
+    flushBuffer();
+    startHeartbeat();
+  };
+
+  ws.onmessage = (ev: MessageEvent) => {
+    let data: unknown;
+    try {
+      data = JSON.parse(ev.data as string);
+    } catch {
+      data = ev.data;
+    }
+    self.postMessage({ type: 'message', data });
+  };
+
+  ws.onclose = (ev) => {
+    stopHeartbeat();
+    self.postMessage({ type: 'close', code: ev.code, reason: ev.reason });
+
+    if (!disposed && shouldReconnect && ev.code !== 1000) {
+      scheduleReconnect();
+    } else {
+      setState('closed');
+    }
+  };
+
+  ws.onerror = () => {
+    self.postMessage({ type: 'error', message: 'WebSocket error' });
+  };
+}
+
+function send(data: unknown) {
+  if (state === 'connected' && ws?.readyState === WebSocket.OPEN) {
+    ws.send(JSON.stringify(data));
+  } else if (state === 'connecting' || state === 'reconnecting') {
+    if (buffer.length < maxBuffer) {
+      buffer.push(data);
+    }
+  }
+}
+
+function disconnect() {
+  disposed = true;
+  shouldReconnect = false;
+  stopHeartbeat();
+  clearReconnect();
+
+  if (ws) {
+    ws.onclose = null;
+    ws.onmessage = null;
+    ws.onerror = null;
+    if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+      ws.close(1000, 'worker disconnect');
+    }
+    ws = null;
+  }
+
+  buffer = [];
+  setState('closed');
+}
+
+function flushBuffer() {
+  const pending = buffer.splice(0);
+  for (const item of pending) {
+    send(item);
+  }
+}
+
+function startHeartbeat() {
+  stopHeartbeat();
+  heartbeatTimer = setInterval(() => {
+    if (ws?.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({ type: 'ping' }));
+    }
+  }, heartbeatInterval);
+}
+
+function stopHeartbeat() {
+  if (heartbeatTimer) {
+    clearInterval(heartbeatTimer);
+    heartbeatTimer = null;
+  }
+}
+
+function scheduleReconnect() {
+  setState('reconnecting');
+  clearReconnect();
+
+  const jitter = backoffDelay * 0.25 * (Math.random() * 2 - 1);
+  const delay = Math.min(backoffDelay + jitter, maxDelay);
+
+  reconnectTimer = setTimeout(() => {
+    if (!disposed) doConnect();
+  }, delay);
+
+  backoffDelay = Math.min(backoffDelay * 2, maxDelay);
+}
+
+function clearReconnect() {
+  if (reconnectTimer) {
+    clearTimeout(reconnectTimer);
+    reconnectTimer = null;
+  }
+}
+
+// Listen for commands from main thread
+self.onmessage = (ev: MessageEvent<WorkerCommand>) => {
+  const cmd = ev.data;
+
+  switch (cmd.type) {
+    case 'connect':
+      if (cmd.reconnect !== undefined) shouldReconnect = cmd.reconnect;
+      if (cmd.reconnectMaxDelay) maxDelay = cmd.reconnectMaxDelay;
+      if (cmd.heartbeatInterval) heartbeatInterval = cmd.heartbeatInterval;
+      if (cmd.bufferSize) maxBuffer = cmd.bufferSize;
+      connect(cmd.url!, cmd.protocols ?? []);
+      break;
+
+    case 'send':
+      send(cmd.data);
+      break;
+
+    case 'disconnect':
+      disconnect();
+      break;
+  }
+};