@gwakko/shared-websocket 0.6.1 → 0.7.1

package/README.md

@@ -2,6 +2,43 @@
 
 Share ONE WebSocket connection across multiple browser tabs. Zero dependencies. React and Vue adapters included.
 
+## Table of Contents
+
+- [Problem](#problem)
+- [Solution](#solution)
+- [Installation](#installation)
+- [Usage — Vanilla TypeScript](#usage--vanilla-typescript)
+  - [Scoped Lifecycle — withSocket()](#scoped-lifecycle--withsocket)
+- [Usage — React](#usage--react)
+- [Usage — Vue 3](#usage--vue-3)
+- [API Reference](#api-reference)
+  - [Options](#options)
+  - [Authentication](#authentication)
+  - [React Hooks](#react-hooks-react-19-useeffectevent-for-stable-refs)
+  - [Vue Composables](#vue-composables)
+- [How It Works](#how-it-works)
+- [When to Use `useWorker: true`](#when-to-use-useworker-true)
+- [Typed Events](#typed-events)
+  - [Type narrowing](#type-narrowing-for-untyped-events)
+  - [Runtime validation with Zod](#runtime-validation-with-zod)
+- [Middleware](#middleware)
+- [Debug Mode & Custom Logger](#debug-mode--custom-logger)
+- [Custom Event Protocol](#custom-event-protocol)
+- [Advanced Examples](#advanced-examples)
+  - [Stream](#stream--consume-events-as-async-iterator)
+  - [Request](#request--requestresponse-through-server)
+  - [Protocols](#protocols--websocket-subprotocols)
+  - [Worker URL](#worker-url--custom-worker-file)
+  - [Lifecycle Hooks](#lifecycle-hooks)
+  - [Private Channels](#private-channels--chat-rooms-tenant-notifications)
+  - [Server-side channel handling](#server-side-channel-handling)
+- [Topics](#topics--server-side-filtered-subscriptions)
+- [Push Notifications](#push-notifications)
+- [Server-Side Implementation Guide](#server-side-implementation-guide)
+- [Exported Types](#exported-types)
+- [Browser Support](#browser-support)
+- [License](#license)
+
 ## Problem
 
 5 tabs open = 5 WebSocket connections = 5x server resources for the same user.
@@ -1040,6 +1077,394 @@ wss.on('connection', (ws) => {
 });
 ```
 
+## Topics — Server-Side Filtered Subscriptions
+
+Subscribe to specific topics so the server only sends relevant events:
+
+```typescript
+// Vanilla
+ws.subscribe('notifications:orders');
+ws.subscribe('notifications:payments');
+ws.subscribe(`user:${userId}:mentions`);
+
+// Later — unsubscribe
+ws.unsubscribe('notifications:orders');
+```
+
+```tsx
+// React — auto-subscribe on mount, unsubscribe on unmount
+function OrdersDashboard() {
+  useTopics(['notifications:orders', 'notifications:payments']);
+
+  const order = useSocketEvent('notifications:orders:new');
+  return order ? <div>New order #{order.id}</div> : null;
+}
+
+// Dynamic topics
+function UserMentions({ userId }: { userId: string }) {
+  useTopics([`user:${userId}:mentions`]);
+  useSocketCallback(`user:${userId}:mentions:mention`, showMentionToast);
+  return null;
+}
+```
+
+```vue
+<!-- Vue — same pattern -->
+<script setup>
+const props = defineProps<{ userId: string }>();
+useTopics([`user:${props.userId}:mentions`]);
+useSocketEvent(`user:${props.userId}:mentions:mention`, showToast);
+</script>
+```
+
+Server receives `$topic:subscribe` / `$topic:unsubscribe` events (configurable via `events.topicSubscribe`).
+
+## Push Notifications
+
+Two modes: **custom render** (sonner, react-hot-toast, your UI) and/or **browser Notification API**. Both respect `leaderOnly` + `onlyWhenHidden` to prevent duplicates across tabs.
+
+### Custom Render — you control the display
+
+```typescript
+// Vanilla — sonner toast
+import { toast } from 'sonner';
+
+ws.push('notification', {
+  render: (n) => toast(n.title, { description: n.body }),
+});
+
+ws.push('order.created', {
+  render: (order) => toast.success(`New Order #${order.id}`, {
+    description: `$${order.total} from ${order.customer}`,
+    action: { label: 'View', onClick: () => navigate(`/orders/${order.id}`) },
+  }),
+});
+```
+
+```tsx
+// React — sonner
+import { toast } from 'sonner';
+
+function NotificationSetup() {
+  usePush('notification', {
+    render: (n) => toast(n.title, { description: n.body }),
+  });
+
+  usePush('order.created', {
+    render: (order) => toast.success(`Order #${order.id} — $${order.total}`),
+  });
+
+  return null;
+}
+
+// React — react-hot-toast
+import hotToast from 'react-hot-toast';
+
+function NotificationSetup() {
+  usePush('notification', {
+    render: (n) => hotToast(n.title),
+  });
+  return null;
+}
+```
+
+```vue
+<!-- Vue — sonner-vue -->
+<script setup>
+import { toast } from 'sonner-vue';
+
+usePush('notification', {
+  render: (n) => toast(n.title, { description: n.body }),
+});
+
+usePush('order.created', {
+  render: (order) => toast.success(`Order #${order.id} — $${order.total}`),
+});
+</script>
+```
+
+### Browser Notification API — native OS notifications
+
+```typescript
+// Vanilla — browser native (no render needed)
+ws.push('notification', {
+  title: (n) => n.title,
+  body: (n) => n.body,
+  icon: '/icons/bell.png',
+  tag: (n) => `notif-${n.id}`,  // deduplication
+  onClick: (n) => window.open(n.url),
+  leaderOnly: true,       // default: true
+  onlyWhenHidden: true,   // default: true
+});
+```
+
+```tsx
+// React
+usePush('order.created', {
+  title: (order) => `New Order #${order.id}`,
+  body: (order) => `$${order.total}`,
+  icon: '/icons/order.png',
+  onClick: (order) => navigate(`/orders/${order.id}`),
+});
+```
+
+```vue
+<!-- Vue -->
+<script setup>
+usePush('order.created', {
+  title: (order) => `New Order #${order.id}`,
+  body: (order) => `$${order.total}`,
+});
+</script>
+```
+
+### Both — toast in UI + browser notification
+
+```typescript
+// Show sonner toast AND browser notification
+ws.push('order.created', {
+  render: (order) => toast.success(`Order #${order.id}`),  // in-app toast
+  title: (order) => `New Order #${order.id}`,              // + native notification
+  body: (order) => `$${order.total}`,
+});
+```
+
+## Server-Side Implementation Guide
+
+Complete server reference — what events to listen for and how to respond.
+
+### Message Format
+
+All messages are JSON with two fields (configurable via `events` option):
+
+```
+Client → Server: { "event": "event.name", "data": { ... } }
+Server → Client: { "event": "event.name", "data": { ... } }
+```
+
+### System Events (sent by client automatically)
+
+| Event | When | Payload | Your Server Should |
+|-------|------|---------|-------------------|
+| `ping` | Every 30s (heartbeat) | `{ "type": "ping" }` | Respond with `{ "type": "pong" }` or ignore |
+| `$channel:join` | `ws.channel('name')` | `{ "channel": "chat:room_1" }` | Track which channels this connection belongs to |
+| `$channel:leave` | `channel.leave()` | `{ "channel": "chat:room_1" }` | Remove connection from channel |
+| `$topic:subscribe` | `ws.subscribe('topic')` | `{ "topic": "notifications:orders" }` | Start sending events for this topic to this connection |
+| `$topic:unsubscribe` | `ws.unsubscribe('topic')` | `{ "topic": "notifications:orders" }` | Stop sending events for this topic |
+
+### Node.js (ws) — Complete Server Example
+
+```typescript
+import { WebSocketServer, WebSocket } from 'ws';
+
+const wss = new WebSocketServer({ port: 8080 });
+
+// Track per-connection state
+interface ClientState {
+  userId?: string;
+  channels: Set<string>;
+  topics: Set<string>;
+}
+
+const clients = new Map<WebSocket, ClientState>();
+
+wss.on('connection', (ws, req) => {
+  // Extract auth token from URL
+  const url = new URL(req.url!, `http://${req.headers.host}`);
+  const token = url.searchParams.get('token');
+  const userId = verifyToken(token);  // your auth logic
+
+  const state: ClientState = {
+    userId,
+    channels: new Set(),
+    topics: new Set(),
+  };
+  clients.set(ws, state);
+
+  // Send welcome
+  send(ws, 'welcome', { userId, timestamp: Date.now() });
+
+  ws.on('message', (raw) => {
+    const msg = JSON.parse(raw.toString());
+    const { event, data } = msg;
+
+    switch (event) {
+      // ─── System Events ───────────────────────
+
+      case 'ping':
+        // Respond to heartbeat (optional — some servers ignore pings)
+        ws.send(JSON.stringify({ type: 'pong' }));
+        break;
+
+      // ─── Channel Events ──────────────────────
+
+      case '$channel:join':
+        state.channels.add(data.channel);
+        console.log(`${userId} joined ${data.channel}`);
+        // Send channel history, presence, etc.
+        break;
+
+      case '$channel:leave':
+        state.channels.delete(data.channel);
+        console.log(`${userId} left ${data.channel}`);
+        break;
+
+      // ─── Topic Events ────────────────────────
+
+      case '$topic:subscribe':
+        state.topics.add(data.topic);
+        console.log(`${userId} subscribed to ${data.topic}`);
+        break;
+
+      case '$topic:unsubscribe':
+        state.topics.delete(data.topic);
+        break;
+
+      // ─── App Events ──────────────────────────
+
+      case 'chat.send':
+        // Broadcast to all clients in the same channel
+        const channel = data.roomId ? `chat:${data.roomId}` : null;
+        broadcastToChannel(channel, 'chat.message', {
+          id: crypto.randomUUID(),
+          userId: state.userId,
+          text: data.text,
+          timestamp: Date.now(),
+        });
+        break;
+
+      case 'chat.typing':
+        broadcastToChannel(`chat:${data.roomId}`, 'chat.typing', {
+          userId: state.userId,
+        }, ws);  // exclude sender
+        break;
+
+      default:
+        console.log('Unknown event:', event, data);
+    }
+  });
+
+  ws.on('close', () => {
+    clients.delete(ws);
+  });
+});
+
+// ─── Helpers ─────────────────────────────────────
+
+function send(ws: WebSocket, event: string, data: unknown) {
+  if (ws.readyState === WebSocket.OPEN) {
+    ws.send(JSON.stringify({ event, data }));
+  }
+}
+
+function broadcastToChannel(
+  channel: string | null,
+  event: string,
+  data: unknown,
+  exclude?: WebSocket,
+) {
+  for (const [ws, state] of clients) {
+    if (ws === exclude) continue;
+    if (channel && !state.channels.has(channel)) continue;
+    send(ws, event, data);
+  }
+}
+
+function broadcastToTopic(topic: string, event: string, data: unknown) {
+  for (const [ws, state] of clients) {
+    if (!state.topics.has(topic)) continue;
+    send(ws, `${topic}:${event}`, data);
+  }
+}
+
+// ─── Example: Send notifications by topic ────────
+
+function notifyNewOrder(order: Order) {
+  broadcastToTopic('notifications:orders', 'new', {
+    id: order.id,
+    total: order.total,
+    customer: order.customerName,
+  });
+  // Only clients who called ws.subscribe('notifications:orders') receive this
+}
+```
+
+### Go — Server Example
+
+```go
+// Message format
+type Message struct {
+    Event string          `json:"event"`
+    Data  json.RawMessage `json:"data"`
+}
+
+// Handle incoming messages
+func handleMessage(conn *websocket.Conn, state *ClientState, msg Message) {
+    switch msg.Event {
+    case "$channel:join":
+        var payload struct{ Channel string `json:"channel"` }
+        json.Unmarshal(msg.Data, &payload)
+        state.Channels[payload.Channel] = true
+
+    case "$channel:leave":
+        var payload struct{ Channel string `json:"channel"` }
+        json.Unmarshal(msg.Data, &payload)
+        delete(state.Channels, payload.Channel)
+
+    case "$topic:subscribe":
+        var payload struct{ Topic string `json:"topic"` }
+        json.Unmarshal(msg.Data, &payload)
+        state.Topics[payload.Topic] = true
+
+    case "$topic:unsubscribe":
+        var payload struct{ Topic string `json:"topic"` }
+        json.Unmarshal(msg.Data, &payload)
+        delete(state.Topics, payload.Topic)
+
+    case "chat.send":
+        // broadcast to channel...
+
+    case "ping":
+        conn.WriteJSON(Message{Event: "pong"})
+    }
+}
+```
+
+### PHP (Laravel + Ratchet/Swoole) — Server Example
+
+```php
+// Handle incoming WebSocket message
+public function onMessage(ConnectionInterface $conn, $msg): void
+{
+    $data = json_decode($msg, true);
+    $event = $data['event'] ?? 'message';
+    $payload = $data['data'] ?? [];
+
+    match ($event) {
+        '$channel:join' => $this->joinChannel($conn, $payload['channel']),
+        '$channel:leave' => $this->leaveChannel($conn, $payload['channel']),
+        '$topic:subscribe' => $this->subscribeTopic($conn, $payload['topic']),
+        '$topic:unsubscribe' => $this->unsubscribeTopic($conn, $payload['topic']),
+        'chat.send' => $this->handleChatMessage($conn, $payload),
+        'ping' => $conn->send(json_encode(['type' => 'pong'])),
+        default => logger()->warning("Unknown event: {$event}"),
+    };
+}
+
+// Send to topic subscribers
+public function notifyTopic(string $topic, string $event, array $data): void
+{
+    foreach ($this->connections as $conn) {
+        if (in_array($topic, $this->topics[$conn->resourceId] ?? [])) {
+            $conn->send(json_encode([
+                'event' => "{$topic}:{$event}",
+                'data' => $data,
+            ]));
+        }
+    }
+}
+```
+
 ## Exported Types
 
 All types are available for import in your projects:
@@ -1082,9 +1507,9 @@ import {
   useSocketStatus,
   useSocketLifecycle,
   useChannel,
+  useTopics,
+  usePush,
 } from '@gwakko/shared-websocket/react';
-
-import type { SharedWebSocketProviderProps } from '@gwakko/shared-websocket/react';
 ```
 
 ```typescript
@@ -1099,7 +1524,9 @@ import {
   useSocketStatus,
   useSocketLifecycle,
   useChannel,
-  SharedWebSocketKey,       // InjectionKey for custom provide/inject
+  useTopics,
+  usePush,
+  SharedWebSocketKey,
 } from '@gwakko/shared-websocket/vue';
 ```
 

package/dist/SharedWebSocket.d.ts

@@ -95,6 +95,78 @@ export declare class SharedWebSocket<TEvents extends EventMap = EventMap> implem
      * notifications.on('alert', (alert) => showToast(alert));
      */
     channel(name: string): Channel;
+    /**
+     * Subscribe to a server-side topic. Server will start sending events for this topic.
+     * Sends topicSubscribe event (default: "$topic:subscribe").
+     *
+     * @example
+     * ws.subscribe('notifications:orders');
+     * ws.subscribe('notifications:payments');
+     * ws.subscribe(`user:${userId}:mentions`);
+     */
+    subscribe(topic: string): void;
+    /**
+     * Unsubscribe from a server-side topic.
+     * Sends topicUnsubscribe event (default: "$topic:unsubscribe").
+     */
+    unsubscribe(topic: string): void;
+    /**
+     * Subscribe to an event and show notifications.
+     *
+     * Two modes:
+     * - **render** — you control how to display (sonner, react-hot-toast, custom UI)
+     * - **browser Notification API** — native OS notifications (title/body/icon)
+     *
+     * Both modes respect leaderOnly + onlyWhenHidden to prevent duplicates.
+     *
+     * @example
+     * // Custom render — sonner toast
+     * import { toast } from 'sonner';
+     * ws.push('notification', {
+     *   render: (data) => toast(data.title, { description: data.body }),
+     * });
+     *
+     * @example
+     * // Custom render — react-hot-toast
+     * import toast from 'react-hot-toast';
+     * ws.push('order.created', {
+     *   render: (order) => toast.success(`New Order #${order.id} — $${order.total}`),
+     * });
+     *
+     * @example
+     * // Browser Notification API (no render — uses title/body/icon)
+     * ws.push('notification', {
+     *   title: (data) => data.title,
+     *   body: (data) => data.body,
+     *   icon: '/icons/bell.png',
+     * });
+     *
+     * @example
+     * // Both — toast in UI + browser notification
+     * ws.push('order.created', {
+     *   render: (order) => toast(`Order #${order.id}`),
+     *   title: (order) => `New Order #${order.id}`,
+     *   body: (order) => `$${order.total}`,
+     * });
+     */
+    push<T = unknown>(event: string, config: {
+        /** Custom render function — you decide how to display. Called for every matching event. */
+        render?: (data: T) => void;
+        /** Title for browser Notification API (ignored if only render is used). */
+        title?: string | ((data: T) => string);
+        /** Body for browser Notification API. */
+        body?: string | ((data: T) => string);
+        /** Icon URL for browser Notification. */
+        icon?: string;
+        /** Tag for browser Notification deduplication. */
+        tag?: string | ((data: T) => string);
+        /** Only trigger from leader tab (default: true). Prevents N duplicates for N tabs. */
+        leaderOnly?: boolean;
+        /** Only trigger when tab is hidden/background (default: true). */
+        onlyWhenHidden?: boolean;
+        /** Called when browser Notification is clicked. */
+        onClick?: (data: T) => void;
+    }): Unsubscribe;
     disconnect(): void;
     private createSocket;
     private handleBecomeLeader;

package/dist/adapters/react.d.ts

@@ -164,3 +164,37 @@ export declare function useSocketLifecycle(handlers: SocketLifecycleHandlers): v
  * useSocketCallback(`tenant:${tenantId}:notifications:alert`, showToast);
  */
 export declare function useChannel(name: string): import("..").Channel;
+/**
+ * Subscribe to server-side topics. Auto-unsubscribes on unmount.
+ *
+ * @example
+ * useTopics(['notifications:orders', 'notifications:payments']);
+ * useTopics([`user:${userId}:mentions`]);
+ */
+export declare function useTopics(topics: string[]): void;
+/**
+ * Enable browser push notifications for an event. Auto-cleanup on unmount.
+ *
+ * @example
+ * usePush('notification', {
+ *   title: (n) => n.title,
+ *   body: (n) => n.body,
+ *   icon: '/icon.png',
+ * });
+ *
+ * @example
+ * usePush('order.created', {
+ *   title: (order) => `New Order #${order.id}`,
+ *   body: (order) => `$${order.total}`,
+ *   onClick: (order) => navigate(`/orders/${order.id}`),
+ * });
+ */
+export declare function usePush<T = unknown>(event: string, config: {
+    title: string | ((data: T) => string);
+    body?: string | ((data: T) => string);
+    icon?: string;
+    tag?: string | ((data: T) => string);
+    leaderOnly?: boolean;
+    onlyWhenHidden?: boolean;
+    onClick?: (data: T) => void;
+}): void;

package/dist/adapters/vue.d.ts

@@ -123,3 +123,29 @@ export declare function useSocketLifecycle(handlers: SocketLifecycleHandlers): v
  * // Send via chat.send('message', { text: 'Hello' })
  */
 export declare function useChannel(name: string): import("..").Channel;
+/**
+ * Subscribe to server-side topics. Auto-unsubscribes on unmount.
+ *
+ * @example
+ * useTopics(['notifications:orders', 'notifications:payments']);
+ */
+export declare function useTopics(topics: string[]): void;
+/**
+ * Enable browser push notifications for an event. Auto-cleanup on unmount.
+ *
+ * @example
+ * usePush('notification', {
+ *   title: (n) => n.title,
+ *   body: (n) => n.body,
+ *   icon: '/icon.png',
+ * });
+ */
+export declare function usePush<T = unknown>(event: string, config: {
+    title: string | ((data: T) => string);
+    body?: string | ((data: T) => string);
+    icon?: string;
+    tag?: string | ((data: T) => string);
+    leaderOnly?: boolean;
+    onlyWhenHidden?: boolean;
+    onClick?: (data: T) => void;
+}): void;