@gwakko/shared-websocket 0.2.1 → 0.6.1

package/dist/SharedSocket.d.ts

@@ -7,6 +7,10 @@ interface SharedSocketOptions {
     heartbeatInterval?: number;
     sendBuffer?: number;
     auth?: () => string | Promise<string>;
+    authToken?: string;
+    authParam?: string;
+    /** Heartbeat payload (default: { type: "ping" }). */
+    pingPayload?: unknown;
 }
 export declare class SharedSocket implements Disposable {
     private url;
@@ -31,6 +35,7 @@ export declare class SharedSocket implements Disposable {
     private startHeartbeat;
     private stopHeartbeat;
     private clearReconnect;
+    private buildUrl;
     private setState;
     [Symbol.dispose](): void;
 }

package/dist/SharedWebSocket.d.ts

@@ -1,13 +1,20 @@
 import './utils/disposable';
-import type { SharedWebSocketOptions, TabRole, Unsubscribe, EventHandler } from './types';
+import type { SharedWebSocketOptions, TabRole, Unsubscribe, EventHandler, Channel, EventMap, Middleware } from './types';
 /**
  * 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.
+ * @typeParam TEvents - Event map for type-safe subscriptions.
+ *
+ * @example
+ * // Typed events
+ * type Events = {
+ *   'chat.message': { text: string; userId: string };
+ *   'order.created': { id: string; total: number };
+ * };
+ * const ws = new SharedWebSocket<Events>(url);
+ * ws.on('chat.message', (msg) => msg.text); // ← msg: { text, userId }
  */
-export declare class SharedWebSocket implements Disposable {
+export declare class SharedWebSocket<TEvents extends EventMap = EventMap> implements Disposable {
     private readonly url;
     private readonly options;
     private bus;
@@ -18,18 +25,53 @@ export declare class SharedWebSocket implements Disposable {
     private tabId;
     private cleanups;
     private disposed;
-    constructor(url: string, options?: SharedWebSocketOptions);
+    private readonly proto;
+    private readonly log;
+    private outgoingMiddleware;
+    private incomingMiddleware;
+    constructor(url: string, options?: SharedWebSocketOptions<TEvents>);
     get connected(): boolean;
     get tabRole(): TabRole;
     /** Start leader election and connect. */
     connect(): Promise<void>;
-    /** Subscribe to server events (works in ALL tabs). */
-    on(event: string, handler: EventHandler): Unsubscribe;
-    once(event: string, handler: EventHandler): Unsubscribe;
+    /** Called when WebSocket connection opens (broadcast to all tabs). */
+    onConnect(fn: () => void): Unsubscribe;
+    /** Called when WebSocket connection closes (broadcast to all tabs). */
+    onDisconnect(fn: () => void): Unsubscribe;
+    /** Called when WebSocket starts reconnecting (broadcast to all tabs). */
+    onReconnecting(fn: () => void): Unsubscribe;
+    /** Called when this tab becomes leader or loses leadership. */
+    onLeaderChange(fn: (isLeader: boolean) => void): Unsubscribe;
+    /** Called on WebSocket or network error (broadcast to all tabs). */
+    onError(fn: (error: unknown) => void): Unsubscribe;
+    /**
+     * Add middleware to transform messages before send or after receive.
+     * Return null from middleware to drop the message.
+     *
+     * @example
+     * // Add timestamp to every outgoing message
+     * ws.use('outgoing', (msg) => ({ ...msg, timestamp: Date.now() }));
+     *
+     * @example
+     * // Decrypt incoming messages
+     * ws.use('incoming', (msg) => ({ ...msg, data: decrypt(msg.data) }));
+     *
+     * @example
+     * // Drop messages from blocked users
+     * ws.use('incoming', (msg) => blockedUsers.has(msg.userId) ? null : msg);
+     */
+    use(direction: 'outgoing' | 'incoming', fn: Middleware): this;
+    /** Subscribe to server events (works in ALL tabs). Type-safe with EventMap. */
+    on<K extends string & keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): Unsubscribe;
+    on(event: string, handler: EventHandler<unknown>): Unsubscribe;
+    once<K extends string & keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): Unsubscribe;
+    once(event: string, handler: EventHandler<unknown>): Unsubscribe;
     off(event: string, handler?: EventHandler): void;
-    /** Async generator for consuming events. */
+    /** Async generator for consuming events. Type-safe with EventMap. */
+    stream<K extends string & keyof TEvents>(event: K, signal?: AbortSignal): AsyncGenerator<TEvents[K]>;
     stream(event: string, signal?: AbortSignal): AsyncGenerator<unknown>;
-    /** Send message to server (auto-routed through leader). */
+    /** Send message to server (auto-routed through leader). Type-safe with EventMap. */
+    send<K extends string & keyof TEvents>(event: K, data: TEvents[K]): void;
     send(event: string, data: unknown): void;
     /** Request/response through server via leader. */
     request<T>(event: string, data: unknown, timeout?: number): Promise<T>;
@@ -37,9 +79,25 @@ export declare class SharedWebSocket implements Disposable {
     sync<T>(key: string, value: T): void;
     getSync<T>(key: string): T | undefined;
     onSync<T>(key: string, fn: (value: T) => void): Unsubscribe;
+    /**
+     * Subscribe to a private/scoped channel. Returns a channel handle with
+     * scoped on/send/stream methods. Sends join on subscribe, leave on unsubscribe.
+     *
+     * @example
+     * const chat = ws.channel('chat:room_123');
+     * chat.on('message', (msg) => render(msg));
+     * chat.send('message', { text: 'Hello' });
+     * chat.leave(); // sends leave + unsubscribes
+     *
+     * @example
+     * // Private notifications for tenant
+     * const notifications = ws.channel(`tenant:${tenantId}:notifications`);
+     * notifications.on('alert', (alert) => showToast(alert));
+     */
+    channel(name: string): Channel;
     disconnect(): void;
     private createSocket;
-    private onBecomeLeader;
-    private onLoseLeadership;
+    private handleBecomeLeader;
+    private handleLoseLeadership;
     [Symbol.dispose](): void;
 }

package/dist/adapters/react.d.ts

@@ -1,6 +1,6 @@
 import { type ReactNode } from 'react';
 import { SharedWebSocket } from '../SharedWebSocket';
-import type { SharedWebSocketOptions, TabRole } from '../types';
+import type { SharedWebSocketOptions, TabRole, SocketLifecycleHandlers } from '../types';
 /**
  * Provider props — pass URL and options as props for flexibility.
  *
@@ -32,7 +32,7 @@ export interface SharedWebSocketProviderProps {
  *   );
  * }
  */
-export declare function SharedWebSocketProvider({ url, options, children }: SharedWebSocketProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<SharedWebSocket | null>>;
+export declare function SharedWebSocketProvider({ url, options, children }: SharedWebSocketProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<SharedWebSocket<import("..").EventMap> | null>>;
 /**
  * Access the SharedWebSocket instance from context.
  *
@@ -137,3 +137,30 @@ export declare function useSocketStatus(): {
     connected: boolean;
     tabRole: TabRole;
 };
+/**
+ * Lifecycle hooks — react to connection state changes.
+ *
+ * @example
+ * useSocketLifecycle({
+ *   onConnect: () => console.log('Connected!'),
+ *   onDisconnect: () => console.log('Disconnected'),
+ *   onReconnecting: () => showSpinner(),
+ *   onLeaderChange: (isLeader) => console.log('Leader:', isLeader),
+ *   onError: (err) => reportError(err),
+ * });
+ */
+export declare function useSocketLifecycle(handlers: SocketLifecycleHandlers): void;
+/**
+ * Subscribe to a private channel. Auto-joins on mount, leaves on unmount.
+ *
+ * @example
+ * const chat = useChannel('chat:room_123');
+ * const message = useSocketEvent('chat:room_123:message');
+ * chat.send('message', { text: 'Hello' });
+ *
+ * @example
+ * // Tenant notifications
+ * const notifications = useChannel(`tenant:${tenantId}:notifications`);
+ * useSocketCallback(`tenant:${tenantId}:notifications:alert`, showToast);
+ */
+export declare function useChannel(name: string): import("..").Channel;

package/dist/adapters/vue.d.ts

@@ -1,6 +1,6 @@
 import { type Ref, type InjectionKey, type App } from 'vue';
 import { SharedWebSocket } from '../SharedWebSocket';
-import type { SharedWebSocketOptions, TabRole } from '../types';
+import type { SharedWebSocketOptions, TabRole, SocketLifecycleHandlers } from '../types';
 export declare const SharedWebSocketKey: InjectionKey<SharedWebSocket>;
 /**
  * Vue 3 plugin for SharedWebSocket.
@@ -101,3 +101,25 @@ export declare function useSocketStatus(): {
     connected: Ref<boolean>;
     tabRole: Ref<TabRole>;
 };
+/**
+ * Lifecycle hooks — react to connection state changes.
+ *
+ * @example
+ * useSocketLifecycle({
+ *   onConnect: () => console.log('Connected!'),
+ *   onDisconnect: () => showOfflineBanner(),
+ *   onReconnecting: () => showSpinner(),
+ *   onLeaderChange: (isLeader) => console.log('Leader:', isLeader),
+ *   onError: (err) => reportError(err),
+ * });
+ */
+export declare function useSocketLifecycle(handlers: SocketLifecycleHandlers): void;
+/**
+ * Subscribe to a private channel. Auto-joins on mount, leaves on unmount.
+ *
+ * @example
+ * const chat = useChannel('chat:room_123');
+ * // Listen via useSocketEvent('chat:room_123:message')
+ * // Send via chat.send('message', { text: 'Hello' })
+ */
+export declare function useChannel(name: string): import("..").Channel;

package/dist/{chunk-TNEMKPGP.js → chunk-4D2ZDCA6.js}

@@ -251,7 +251,10 @@ var SharedSocket = class {
       reconnectMaxDelay: options.reconnectMaxDelay ?? 3e4,
       heartbeatInterval: options.heartbeatInterval ?? 3e4,
       sendBuffer: options.sendBuffer ?? 100,
-      auth: options.auth
+      auth: options.auth,
+      authToken: options.authToken,
+      authParam: options.authParam ?? "token",
+      pingPayload: options.pingPayload ?? { type: "ping" }
     };
   }
   url;
@@ -270,12 +273,7 @@ var SharedSocket = class {
   async connect() {
     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)}`;
-    }
+    const connectUrl = await this.buildUrl();
     this.ws = new WebSocket(connectUrl, this.opts.protocols);
     this.ws.onopen = () => {
       this.setState("connected");
@@ -356,7 +354,7 @@ var SharedSocket = class {
     this.stopHeartbeat();
     this.heartbeatTimer = setInterval(() => {
       if (this.ws?.readyState === WebSocket.OPEN) {
-        this.ws.send(JSON.stringify({ type: "ping" }));
+        this.ws.send(JSON.stringify(this.opts.pingPayload));
       }
     }, this.opts.heartbeatInterval);
   }
@@ -372,6 +370,19 @@ var SharedSocket = class {
       this.reconnectTimer = null;
     }
   }
+  async buildUrl() {
+    let token;
+    if (this.opts.auth) {
+      token = await this.opts.auth();
+    } else if (this.opts.authToken) {
+      token = this.opts.authToken;
+    }
+    if (!token) return this.url;
+    const httpUrl = this.url.replace(/^ws(s?):\/\//, "http$1://");
+    const parsed = new URL(httpUrl);
+    parsed.searchParams.set(this.opts.authParam, token);
+    return parsed.toString().replace(/^http(s?):\/\//, "ws$1://");
+  }
   setState(state) {
     this._state = state;
     for (const fn of this.onStateChangeFns) fn(state);
@@ -566,11 +577,32 @@ var SubscriptionManager = class {
 };
 
 // src/SharedWebSocket.ts
+var DEFAULT_PROTOCOL = {
+  eventField: "event",
+  dataField: "data",
+  channelJoin: "$channel:join",
+  channelLeave: "$channel:leave",
+  ping: { type: "ping" },
+  defaultEvent: "message"
+};
+var NOOP_LOGGER = {
+  debug() {
+  },
+  info() {
+  },
+  warn() {
+  },
+  error() {
+  }
+};
 var SharedWebSocket = class {
   constructor(url, options = {}) {
     this.url = url;
     this.options = options;
+    this.proto = { ...DEFAULT_PROTOCOL, ...options.events };
+    this.log = options.debug ? options.logger ?? console : NOOP_LOGGER;
     this.tabId = generateId();
+    this.log.debug("[SharedWS] init", { tabId: this.tabId, url });
     this.bus = new MessageBus("shared-ws", this.tabId);
     this.coordinator = new TabCoordinator(this.bus, this.tabId, {
       electionTimeout: options.electionTimeout,
@@ -585,7 +617,7 @@ var SharedWebSocket = class {
     this.cleanups.push(
       this.bus.subscribe("ws:send", (msg) => {
         if (this.coordinator.isLeader && this.socket) {
-          this.socket.send({ event: msg.event, data: msg.data });
+          this.socket.send({ [this.proto.eventField]: msg.event, [this.proto.dataField]: msg.data });
         }
       })
     );
@@ -595,8 +627,35 @@ var SharedWebSocket = class {
         this.subs.emit(`sync:${msg.key}`, msg.value);
       })
     );
-    this.coordinator.onBecomeLeader(() => this.onBecomeLeader());
-    this.coordinator.onLoseLeadership(() => this.onLoseLeadership());
+    this.coordinator.onBecomeLeader(() => {
+      this.handleBecomeLeader();
+      this.bus.broadcast("ws:lifecycle", { type: "leader", isLeader: true });
+    });
+    this.coordinator.onLoseLeadership(() => {
+      this.handleLoseLeadership();
+      this.bus.broadcast("ws:lifecycle", { type: "leader", isLeader: false });
+    });
+    this.cleanups.push(
+      this.bus.subscribe("ws:lifecycle", (msg) => {
+        switch (msg.type) {
+          case "connect":
+            this.subs.emit("$lifecycle:connect", void 0);
+            break;
+          case "disconnect":
+            this.subs.emit("$lifecycle:disconnect", void 0);
+            break;
+          case "reconnecting":
+            this.subs.emit("$lifecycle:reconnecting", void 0);
+            break;
+          case "leader":
+            this.subs.emit("$lifecycle:leader", msg.isLeader);
+            break;
+          case "error":
+            this.subs.emit("$lifecycle:error", msg.error);
+            break;
+        }
+      })
+    );
     if (typeof window !== "undefined") {
       const onBeforeUnload = () => this[Symbol.dispose]();
       window.addEventListener("beforeunload", onBeforeUnload);
@@ -613,6 +672,10 @@ var SharedWebSocket = class {
   tabId;
   cleanups = [];
   disposed = false;
+  proto;
+  log;
+  outgoingMiddleware = [];
+  incomingMiddleware = [];
   get connected() {
     return this.socket?.state === "connected" || !this.coordinator.isLeader;
   }
@@ -623,24 +686,78 @@ var SharedWebSocket = class {
   async connect() {
     await this.coordinator.elect();
   }
-  /** Subscribe to server events (works in ALL tabs). */
+  // ─── Lifecycle Hooks ─────────────────────────────────
+  /** Called when WebSocket connection opens (broadcast to all tabs). */
+  onConnect(fn) {
+    return this.subs.on("$lifecycle:connect", fn);
+  }
+  /** Called when WebSocket connection closes (broadcast to all tabs). */
+  onDisconnect(fn) {
+    return this.subs.on("$lifecycle:disconnect", fn);
+  }
+  /** Called when WebSocket starts reconnecting (broadcast to all tabs). */
+  onReconnecting(fn) {
+    return this.subs.on("$lifecycle:reconnecting", fn);
+  }
+  /** Called when this tab becomes leader or loses leadership. */
+  onLeaderChange(fn) {
+    return this.subs.on("$lifecycle:leader", fn);
+  }
+  /** Called on WebSocket or network error (broadcast to all tabs). */
+  onError(fn) {
+    return this.subs.on("$lifecycle:error", fn);
+  }
+  // ─── Middleware ───────────────────────────────────────
+  /**
+   * Add middleware to transform messages before send or after receive.
+   * Return null from middleware to drop the message.
+   *
+   * @example
+   * // Add timestamp to every outgoing message
+   * ws.use('outgoing', (msg) => ({ ...msg, timestamp: Date.now() }));
+   *
+   * @example
+   * // Decrypt incoming messages
+   * ws.use('incoming', (msg) => ({ ...msg, data: decrypt(msg.data) }));
+   *
+   * @example
+   * // Drop messages from blocked users
+   * ws.use('incoming', (msg) => blockedUsers.has(msg.userId) ? null : msg);
+   */
+  use(direction, fn) {
+    if (direction === "outgoing") {
+      this.outgoingMiddleware.push(fn);
+    } else {
+      this.incomingMiddleware.push(fn);
+    }
+    return this;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   on(event, handler) {
     return this.subs.on(event, handler);
   }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   once(event, handler) {
     return this.subs.once(event, handler);
   }
   off(event, handler) {
     this.subs.off(event, handler);
   }
-  /** Async generator for consuming events. */
   stream(event, signal) {
     return this.subs.stream(event, signal);
   }
-  /** Send message to server (auto-routed through leader). */
   send(event, data) {
+    let payload = { [this.proto.eventField]: event, [this.proto.dataField]: data };
+    for (const mw of this.outgoingMiddleware) {
+      payload = mw(payload);
+      if (payload === null) {
+        this.log.debug("[SharedWS] \u2717 outgoing dropped by middleware", event);
+        return;
+      }
+    }
+    this.log.debug("[SharedWS] \u2192 send", event, data);
     if (this.coordinator.isLeader && this.socket) {
-      this.socket.send({ event, data });
+      this.socket.send(payload);
     } else {
       this.bus.publish("ws:send", { event, data });
     }
@@ -660,6 +777,50 @@ var SharedWebSocket = class {
   onSync(key, fn) {
     return this.subs.on(`sync:${key}`, fn);
   }
+  /**
+   * Subscribe to a private/scoped channel. Returns a channel handle with
+   * scoped on/send/stream methods. Sends join on subscribe, leave on unsubscribe.
+   *
+   * @example
+   * const chat = ws.channel('chat:room_123');
+   * chat.on('message', (msg) => render(msg));
+   * chat.send('message', { text: 'Hello' });
+   * chat.leave(); // sends leave + unsubscribes
+   *
+   * @example
+   * // Private notifications for tenant
+   * const notifications = ws.channel(`tenant:${tenantId}:notifications`);
+   * notifications.on('alert', (alert) => showToast(alert));
+   */
+  channel(name) {
+    this.send(this.proto.channelJoin, { channel: name });
+    const self = this;
+    const unsubs = [];
+    return {
+      name,
+      on(event, handler) {
+        const unsub = self.subs.on(`${name}:${event}`, handler);
+        unsubs.push(unsub);
+        return unsub;
+      },
+      once(event, handler) {
+        const unsub = self.subs.once(`${name}:${event}`, handler);
+        unsubs.push(unsub);
+        return unsub;
+      },
+      send(event, data) {
+        self.send(`${name}:${event}`, data);
+      },
+      stream(event, signal) {
+        return self.subs.stream(`${name}:${event}`, signal);
+      },
+      leave() {
+        self.send(self.proto.channelLeave, { channel: name });
+        for (const unsub of unsubs) unsub();
+        unsubs.length = 0;
+      }
+    };
+  }
   disconnect() {
     this[Symbol.dispose]();
   }
@@ -669,7 +830,8 @@ var SharedWebSocket = class {
       reconnect: this.options.reconnect,
       reconnectMaxDelay: this.options.reconnectMaxDelay,
       heartbeatInterval: this.options.heartbeatInterval,
-      sendBuffer: this.options.sendBuffer
+      sendBuffer: this.options.sendBuffer,
+      pingPayload: this.proto.ping
     };
     if (this.options.useWorker) {
       return new WorkerSocket(this.url, {
@@ -679,23 +841,51 @@ var SharedWebSocket = class {
     }
     return new SharedSocket(this.url, {
       ...socketOptions,
-      auth: this.options.auth
+      auth: this.options.auth,
+      authToken: this.options.authToken,
+      authParam: this.options.authParam
     });
   }
-  onBecomeLeader() {
+  handleBecomeLeader() {
+    this.log.info("[SharedWS] \u{1F451} became leader");
     this.socket = this.createSocket();
-    this.socket.onMessage((data) => {
-      const event = data?.event ?? "message";
-      const payload = data?.data ?? data;
+    this.socket.onMessage((raw) => {
+      let data = raw;
+      for (const mw of this.incomingMiddleware) {
+        data = mw(data);
+        if (data === null) {
+          this.log.debug("[SharedWS] \u2717 incoming dropped by middleware");
+          return;
+        }
+      }
+      const msg = data;
+      const event = msg?.[this.proto.eventField] ?? this.proto.defaultEvent;
+      const payload = msg?.[this.proto.dataField] ?? data;
+      this.log.debug("[SharedWS] \u2190 recv", event, payload);
       this.bus.broadcast("ws:message", { event, data: payload });
     });
+    this.socket.onStateChange((state) => {
+      this.log.info("[SharedWS]", state === "connected" ? "\u2713 connected" : state === "reconnecting" ? "\u{1F504} reconnecting" : `state: ${state}`);
+      switch (state) {
+        case "connected":
+          this.bus.broadcast("ws:lifecycle", { type: "connect" });
+          break;
+        case "closed":
+          this.bus.broadcast("ws:lifecycle", { type: "disconnect" });
+          break;
+        case "reconnecting":
+          this.bus.broadcast("ws:lifecycle", { type: "reconnecting" });
+          break;
+      }
+    });
     this.cleanups.push(
       this.bus.respond("ws:request", async (req) => {
         return new Promise((resolve) => {
           const unsub = this.socket.onMessage((response) => {
-            if (response?.event === req.event || response?.requestId) {
+            const res = response;
+            if (res?.[this.proto.eventField] === req.event || res?.requestId) {
               unsub();
-              resolve(response?.data ?? response);
+              resolve(res?.[this.proto.dataField] ?? response);
             }
           });
           this.socket.send({ event: req.event, data: req.data });
@@ -704,7 +894,7 @@ var SharedWebSocket = class {
     );
     this.socket.connect();
   }
-  onLoseLeadership() {
+  handleLoseLeadership() {
     if (this.socket) {
       this.socket[Symbol.dispose]();
       this.socket = null;
@@ -734,4 +924,4 @@ export {
   SubscriptionManager,
   SharedWebSocket
 };
-//# sourceMappingURL=chunk-TNEMKPGP.js.map
+//# sourceMappingURL=chunk-4D2ZDCA6.js.map