@gwakko/shared-websocket 0.3.0 → 0.6.2

package/README.md

@@ -2,6 +2,40 @@
 
 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)
+- [Exported Types](#exported-types)
+- [Browser Support](#browser-support)
+- [License](#license)
+
 ## Problem
 
 5 tabs open = 5 WebSocket connections = 5x server resources for the same user.
@@ -359,6 +393,8 @@ All hooks use context internally — no need to pass `ws`. Every hook accepts an
 | `useSocketSync<T>(key, init, cb?)` | Returns `[T, setter]` | `cb(value)` — side effects on sync |
 | `useSocketCallback<T>(event, cb)` | — | Fire-and-forget (no state) |
 | `useSocketStatus()` | `{ connected, tabRole }` | — |
+| `useSocketLifecycle(handlers)` | — | onConnect, onDisconnect, onReconnecting, onLeaderChange, onError |
+| `useChannel(name)` | `Channel` handle | Auto-join/leave on mount/unmount |
 
 ```tsx
 // Without callback — reactive state
@@ -439,6 +475,692 @@ const ws = new SharedWebSocket(url, { useWorker: true });
 // API is identical — only internal transport changes
 ```
 
+## Typed Events
+
+Define your event map for full type safety across on/send/stream:
+
+```typescript
+type Events = {
+  'chat.message': { text: string; userId: string; timestamp: number };
+  'chat.typing': { userId: string };
+  'order.created': { id: string; total: number; items: string[] };
+  'notification': { title: string; body: string; type: 'info' | 'error' };
+};
+
+const ws = new SharedWebSocket<Events>('wss://api.example.com/ws');
+
+// ✅ Type-safe — msg is { text, userId, timestamp }
+ws.on('chat.message', (msg) => {
+  console.log(msg.text);     // string
+  console.log(msg.userId);   // string
+});
+
+// ✅ Type-safe send
+ws.send('chat.message', { text: 'hi', userId: '1', timestamp: Date.now() });
+
+// ❌ TypeScript error — wrong payload type
+ws.send('chat.message', { wrong: 'field' });
+
+// ✅ Type-safe stream
+for await (const order of ws.stream('order.created')) {
+  console.log(order.id);   // string
+  console.log(order.total); // number
+}
+
+// Still works with untyped events
+ws.on('any.custom.event', (data) => { /* data: any */ });
+```
+
+```tsx
+// React — pass type to hooks
+const msg = useSocketEvent<Events['chat.message']>('chat.message');
+// msg: { text, userId, timestamp } | undefined
+```
+
+### Type narrowing for untyped events
+
+When working without EventMap, data is `unknown`. Use narrowing:
+
+```typescript
+// Type guard
+function isChatMessage(data: unknown): data is { text: string; userId: string } {
+  return typeof data === 'object' && data !== null && 'text' in data && 'userId' in data;
+}
+
+// Vanilla
+ws.on('chat.message', (data) => {
+  if (isChatMessage(data)) {
+    console.log(data.text);  // ← now typed as string
+  }
+});
+```
+
+```tsx
+// React
+useSocketEvent('chat.message', (data) => {
+  if (isChatMessage(data)) renderMessage(data);
+});
+```
+
+```vue
+<!-- Vue -->
+<script setup>
+useSocketEvent('chat.message', (data) => {
+  if (isChatMessage(data)) renderMessage(data);
+});
+</script>
+```
+
+### Runtime validation with Zod
+
+```typescript
+import { z } from 'zod';
+
+const ChatMessageSchema = z.object({
+  text: z.string(),
+  userId: z.string(),
+  timestamp: z.number(),
+});
+
+type ChatMessage = z.infer<typeof ChatMessageSchema>;
+
+// Validate on receive — drop invalid messages via middleware
+ws.use('incoming', (raw) => {
+  const msg = raw as Record<string, unknown>;
+  const data = msg?.data;
+  const result = ChatMessageSchema.safeParse(data);
+  if (!result.success) {
+    console.warn('Invalid message:', result.error.issues);
+    return null;  // drop
+  }
+  return raw;  // pass through
+});
+
+// Or validate in handler
+ws.on('chat.message', (data) => {
+  const result = ChatMessageSchema.safeParse(data);
+  if (!result.success) return;
+
+  const msg: ChatMessage = result.data;
+  console.log(msg.text);  // fully typed and validated
+});
+
+// Zod middleware factory (reusable)
+function zodValidate<T>(schema: z.ZodType<T>): Middleware {
+  return (raw) => {
+    const msg = raw as Record<string, unknown>;
+    const result = schema.safeParse(msg?.data ?? msg);
+    return result.success ? raw : null;
+  };
+}
+
+ws.use('incoming', zodValidate(ChatMessageSchema));
+ws.use('incoming', zodValidate(OrderSchema));
+```
+
+```tsx
+// React — Zod validated hook
+function useSafeSocketEvent<T>(event: string, schema: z.ZodType<T>): T | undefined {
+  const [value, setValue] = useState<T>();
+
+  useSocketEvent(event, (data) => {
+    const result = schema.safeParse(data);
+    if (result.success) setValue(result.data);
+  });
+
+  return value;
+}
+
+// Usage
+const msg = useSafeSocketEvent('chat.message', ChatMessageSchema);
+// msg: ChatMessage | undefined — guaranteed valid
+```
+
+```vue
+<!-- Vue — Zod validated composable -->
+<script setup lang="ts">
+import { z } from 'zod';
+
+const ChatMessageSchema = z.object({
+  text: z.string(),
+  userId: z.string(),
+});
+
+// Composable with validation
+function useSafeSocketEvent<T>(event: string, schema: z.ZodType<T>) {
+  const value = ref<T>();
+  useSocketEvent(event, (data) => {
+    const result = schema.safeParse(data);
+    if (result.success) value.value = result.data as T;
+  });
+  return readonly(value);
+}
+
+const msg = useSafeSocketEvent('chat.message', ChatMessageSchema);
+// msg.value: ChatMessage | undefined — guaranteed valid
+</script>
+```
+
+## Middleware
+
+Transform or inspect messages before send / after receive:
+
+```typescript
+const ws = new SharedWebSocket(url);
+
+// Add timestamp to every outgoing message
+ws.use('outgoing', (msg) => ({ ...msg, timestamp: Date.now() }));
+
+// Decrypt incoming messages
+ws.use('incoming', (msg) => ({ ...msg, data: decrypt(msg.data) }));
+
+// Drop messages from blocked users (return null to drop)
+ws.use('incoming', (msg) => blockedUsers.has(msg.userId) ? null : msg);
+
+// Log everything
+ws.use('incoming', (msg) => { console.log('← recv', msg); return msg; });
+ws.use('outgoing', (msg) => { console.log('→ send', msg); return msg; });
+
+// Chain multiple — executed in order
+ws.use('outgoing', addTimestamp)
+  .use('outgoing', addRequestId)
+  .use('incoming', decryptPayload)
+  .use('incoming', validateSchema);
+```
+
+```tsx
+// React — configure middleware in Provider
+function App() {
+  const wsRef = useRef<SharedWebSocket>();
+
+  return (
+    <SharedWebSocketProvider
+      url="wss://api.example.com/ws"
+      options={{ debug: true }}
+      ref={(provider) => {
+        // Access ws instance after mount to add middleware
+      }}
+    >
+      <SetupMiddleware />
+      <Dashboard />
+    </SharedWebSocketProvider>
+  );
+}
+
+// Or setup middleware in a component
+function SetupMiddleware() {
+  const ws = useSharedWebSocket();
+
+  useEffect(() => {
+    ws.use('outgoing', (msg) => ({ ...msg, timestamp: Date.now() }));
+    ws.use('incoming', zodValidate(MessageSchema));
+  }, [ws]);
+
+  return null;
+}
+```
+
+```vue
+<!-- Vue — configure middleware after plugin install -->
+<script setup>
+// In any component
+const ws = useSharedWebSocket();
+ws.use('outgoing', (msg) => ({ ...msg, timestamp: Date.now() }));
+ws.use('incoming', zodValidate(MessageSchema));
+</script>
+```
+
+## Debug Mode & Custom Logger
+
+```typescript
+// Debug mode — logs all events to console
+new SharedWebSocket(url, { debug: true });
+// [SharedWS] init { tabId: "abc-123", url: "wss://..." }
+// [SharedWS] 👑 became leader
+// [SharedWS] ✓ connected
+// [SharedWS] → send chat.message { text: "hi" }
+// [SharedWS] ← recv chat.message { text: "hello" }
+// [SharedWS] 🔄 reconnecting
+
+// Custom logger (pino, winston, bunyan, etc.)
+import pino from 'pino';
+new SharedWebSocket(url, {
+  debug: true,
+  logger: pino({ name: 'ws' }),
+});
+
+// Sentry integration — errors + breadcrumbs
+import * as Sentry from '@sentry/browser';
+new SharedWebSocket(url, {
+  debug: true,
+  logger: {
+    debug: (msg, ...args) => Sentry.addBreadcrumb({
+      category: 'websocket',
+      message: msg,
+      data: args[0] as Record<string, unknown>,
+      level: 'debug',
+    }),
+    info: (msg, ...args) => Sentry.addBreadcrumb({
+      category: 'websocket',
+      message: msg,
+      level: 'info',
+    }),
+    warn: (msg, ...args) => Sentry.addBreadcrumb({
+      category: 'websocket',
+      message: msg,
+      level: 'warning',
+    }),
+    error: (msg, ...args) => {
+      Sentry.captureException(args[0] instanceof Error ? args[0] : new Error(msg));
+    },
+  },
+});
+
+// Logger interface — implement debug/info/warn/error
+import type { Logger } from '@gwakko/shared-websocket';
+const myLogger: Logger = { debug() {}, info() {}, warn() {}, error() {} };
+```
+
+```tsx
+// React — debug + Sentry in Provider
+<SharedWebSocketProvider
+  url="wss://api.example.com/ws"
+  options={{
+    debug: process.env.NODE_ENV === 'development',
+    logger: sentryLogger,  // your Sentry logger object
+  }}
+>
+  <App />
+</SharedWebSocketProvider>
+```
+
+```vue
+<!-- Vue — debug + Sentry in plugin -->
+<script>
+// main.ts
+app.use(createSharedWebSocketPlugin('wss://api.example.com/ws', {
+  debug: import.meta.env.DEV,
+  logger: sentryLogger,
+}));
+</script>
+```
+
+## Custom Event Protocol
+
+Override event/field names when your server uses different conventions.
+
+```typescript
+// Default: { event: 'chat.message', data: { text: 'hi' } }
+new SharedWebSocket(url);
+
+// Socket.IO style: { type: 'chat.message', payload: { text: 'hi' } }
+new SharedWebSocket(url, {
+  events: {
+    eventField: 'type',       // message field for event name
+    dataField: 'payload',     // message field for payload
+  },
+});
+
+// Phoenix/Elixir style: join/leave events + custom ping
+new SharedWebSocket(url, {
+  events: {
+    channelJoin: 'phx_join',
+    channelLeave: 'phx_leave',
+    ping: { event: 'heartbeat', payload: {} },
+  },
+});
+
+// Laravel Echo / Pusher style
+new SharedWebSocket(url, {
+  events: {
+    eventField: 'event',
+    dataField: 'data',
+    channelJoin: 'pusher:subscribe',
+    channelLeave: 'pusher:unsubscribe',
+    ping: { event: 'pusher:ping', data: {} },
+  },
+});
+
+// Action Cable (Rails) style
+new SharedWebSocket(url, {
+  events: {
+    eventField: 'type',
+    dataField: 'message',
+    channelJoin: 'subscribe',
+    channelLeave: 'unsubscribe',
+    ping: { type: 'ping' },
+    defaultEvent: 'message',
+  },
+});
+```
+
+All fields in `events` are optional — override only what differs from defaults.
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `eventField` | `"event"` | Message field name for event type |
+| `dataField` | `"data"` | Message field name for payload |
+| `channelJoin` | `"$channel:join"` | Event sent when joining a channel |
+| `channelLeave` | `"$channel:leave"` | Event sent when leaving a channel |
+| `ping` | `{ type: "ping" }` | Heartbeat payload |
+| `defaultEvent` | `"message"` | Fallback event when message has no event field |
+
+## Advanced Examples
+
+### Stream — consume events as async iterator
+
+```typescript
+// Vanilla
+await withSocket(url, async ({ ws, signal }) => {
+  for await (const tick of ws.stream('trading.tick', signal)) {
+    updateChart(tick);  // yields one event at a time
+  }
+  // auto-cleanup: unsubscribes when signal aborts or loop breaks
+});
+```
+
+```tsx
+// React — stream into state with limit
+const [logs, setLogs] = useState<LogEntry[]>([]);
+useSocketStream<LogEntry>('server.log', (entry) => {
+  setLogs(prev => [...prev, entry].slice(-500));
+});
+```
+
+```vue
+<!-- Vue — stream into ref -->
+<script setup>
+const logs = ref<LogEntry[]>([]);
+useSocketStream<LogEntry>('server.log', (entry) => {
+  logs.value = [...logs.value, entry].slice(-500);
+});
+</script>
+```
+
+### Request — request/response through server
+
+```typescript
+// Vanilla — request user profile via server
+await withSocket(url, async ({ ws }) => {
+  const user = await ws.request<User>('user.profile', { id: 123 }, 5000);
+  console.log(user.name);  // response from server, 5s timeout
+});
+```
+
+```tsx
+// React
+function UserProfile({ userId }: { userId: string }) {
+  const ws = useSharedWebSocket();
+  const [user, setUser] = useState<User | null>(null);
+
+  useEffect(() => {
+    ws.request<User>('user.profile', { id: userId }).then(setUser);
+  }, [userId]);
+
+  return user ? <div>{user.name}</div> : <div>Loading...</div>;
+}
+```
+
+### Protocols — WebSocket subprotocols
+
+```typescript
+// Pass subprotocols for server-side protocol negotiation
+new SharedWebSocket('wss://api.example.com/ws', {
+  protocols: ['graphql-ws', 'graphql-transport-ws'],
+});
+
+// Common protocols:
+// 'graphql-ws' — GraphQL over WebSocket
+// 'mqtt' — MQTT over WebSocket
+// 'wamp.2.json' — WAMP v2
+```
+
+### Worker URL — custom worker file
+
+```typescript
+// Default: inline blob worker (no extra files needed)
+new SharedWebSocket(url, { useWorker: true });
+
+// Custom worker file (for CSP restrictions or custom logic):
+new SharedWebSocket(url, {
+  useWorker: true,
+  workerUrl: '/workers/socket.worker.js',  // your own worker file
+});
+
+// Or as URL object:
+new SharedWebSocket(url, {
+  useWorker: true,
+  workerUrl: new URL('./socket.worker.ts', import.meta.url),  // Vite handles this
+});
+```
+
+### Lifecycle Hooks
+
+```typescript
+// Vanilla
+await withSocket(url, async ({ ws }) => {
+  ws.onConnect(() => console.log('Connected!'));
+  ws.onDisconnect(() => showOfflineBanner());
+  ws.onReconnecting(() => showSpinner());
+  ws.onLeaderChange((isLeader) => console.log('Leader:', isLeader));
+  ws.onError((err) => reportToSentry(err));
+});
+```
+
+```tsx
+// React
+useSocketLifecycle({
+  onConnect: () => toast.success('Connected'),
+  onDisconnect: () => toast.error('Connection lost'),
+  onReconnecting: () => toast.loading('Reconnecting...'),
+  onLeaderChange: (isLeader) => {
+    if (isLeader) console.log('This tab is now the leader');
+  },
+  onError: (err) => Sentry.captureException(err),
+});
+```
+
+```vue
+<!-- Vue -->
+<script setup>
+useSocketLifecycle({
+  onConnect: () => toast.success('Connected'),
+  onDisconnect: () => toast.error('Connection lost'),
+  onReconnecting: () => toast.loading('Reconnecting...'),
+  onError: (err) => reportError(err),
+});
+</script>
+```
+
+### Private Channels — chat rooms, tenant notifications
+
+The `channel()` method creates a scoped handle. Events are prefixed with the channel name. Server receives `$channel:join` / `$channel:leave` events.
+
+```typescript
+// Vanilla — private chat room
+await withSocket(url, { auth: () => getToken() }, async ({ ws }) => {
+  const chat = ws.channel('chat:room_42');
+
+  chat.on('message', (msg) => renderMessage(msg));
+  chat.on('typing', (user) => showTyping(user));
+  chat.send('message', { text: 'Hello room!' });
+
+  // When done:
+  chat.leave();  // sends $channel:leave to server, unsubscribes all
+});
+
+// Tenant-scoped notifications
+await withSocket(url, { auth: () => getToken() }, async ({ ws }) => {
+  const notifs = ws.channel(`tenant:${tenantId}:notifications`);
+  notifs.on('alert', (alert) => showToast(alert));
+  notifs.on('update', (update) => refreshDashboard(update));
+
+  // User's private channel
+  const user = ws.channel(`user:${userId}`);
+  user.on('message', (dm) => showDirectMessage(dm));
+  user.on('mention', (mention) => highlightMention(mention));
+});
+```
+
+```tsx
+// React — auto join/leave on mount/unmount
+function ChatRoom({ roomId }: { roomId: string }) {
+  const chat = useChannel(`chat:${roomId}`);
+
+  // Events are prefixed: 'chat:room_42:message'
+  const message = useSocketEvent<Message>(`chat:${roomId}:message`);
+  const typing = useSocketEvent<User>(`chat:${roomId}:typing`);
+
+  function send(text: string) {
+    chat.send('message', { text });
+  }
+
+  return (/* ... */);
+}
+// When ChatRoom unmounts → chat.leave() called automatically
+
+// Tenant notifications
+function TenantAlerts({ tenantId }: { tenantId: string }) {
+  const channel = useChannel(`tenant:${tenantId}:notifications`);
+
+  useSocketCallback(`tenant:${tenantId}:notifications:alert`, (alert) => {
+    showToast(alert);
+  });
+
+  return null;
+}
+```
+
+```vue
+<!-- Vue — private channel -->
+<script setup>
+const props = defineProps<{ roomId: string }>();
+
+const chat = useChannel(`chat:${props.roomId}`);
+const message = useSocketEvent<Message>(`chat:${props.roomId}:message`);
+
+function send(text: string) {
+  chat.send('message', { text });
+}
+// Auto-leave on unmount
+</script>
+```
+
+### Server-side channel handling
+
+```typescript
+// Node.js — handle channel join/leave
+wss.on('connection', (ws) => {
+  const channels = new Set<string>();
+
+  ws.on('message', (raw) => {
+    const msg = JSON.parse(raw.toString());
+
+    if (msg.event === '$channel:join') {
+      channels.add(msg.data.channel);
+      console.log(`Client joined ${msg.data.channel}`);
+      return;
+    }
+
+    if (msg.event === '$channel:leave') {
+      channels.delete(msg.data.channel);
+      return;
+    }
+
+    // Route channel messages
+    // msg.event = 'chat:room_42:message'
+    // Extract channel: 'chat:room_42'
+  });
+});
+```
+
+## Exported Types
+
+All types are available for import in your projects:
+
+```typescript
+import type {
+  // Core
+  SharedWebSocketOptions,  // constructor options
+  SocketState,             // 'connecting' | 'connected' | 'reconnecting' | 'closed'
+  TabRole,                 // 'leader' | 'follower'
+  Unsubscribe,             // () => void
+  EventHandler,            // (data: any) => void
+
+  // Channels
+  Channel,                 // scoped channel handle from ws.channel()
+  EventProtocol,           // custom event/field names
+
+  // Lifecycle
+  SocketLifecycleHandlers, // { onConnect?, onDisconnect?, onReconnecting?, ... }
+
+  // withSocket
+  SocketScope,             // { ws, signal } — callback argument
+  WithSocketOptions,       // extends SharedWebSocketOptions + signal
+  WithSocketCallback,      // (scope: SocketScope) => void | Promise<void>
+
+  // Internal (advanced)
+  BusMessage,              // BroadcastChannel message envelope
+} from '@gwakko/shared-websocket';
+```
+
+```tsx
+// React — all hooks + types
+import {
+  SharedWebSocketProvider,
+  useSharedWebSocket,
+  useSocketEvent,
+  useSocketStream,
+  useSocketSync,
+  useSocketCallback,
+  useSocketStatus,
+  useSocketLifecycle,
+  useChannel,
+} from '@gwakko/shared-websocket/react';
+
+import type { SharedWebSocketProviderProps } from '@gwakko/shared-websocket/react';
+```
+
+```typescript
+// Vue — all composables + types
+import {
+  createSharedWebSocketPlugin,
+  useSharedWebSocket,
+  useSocketEvent,
+  useSocketStream,
+  useSocketSync,
+  useSocketCallback,
+  useSocketStatus,
+  useSocketLifecycle,
+  useChannel,
+  SharedWebSocketKey,       // InjectionKey for custom provide/inject
+} from '@gwakko/shared-websocket/vue';
+```
+
+### Usage with custom types
+
+```typescript
+import type { Channel, SocketLifecycleHandlers, EventProtocol } from '@gwakko/shared-websocket';
+
+// Type your channel
+const chat: Channel = ws.channel('chat:room_1');
+
+// Type lifecycle handlers separately
+const handlers: SocketLifecycleHandlers = {
+  onConnect: () => setStatus('online'),
+  onDisconnect: () => setStatus('offline'),
+};
+useSocketLifecycle(handlers);
+
+// Type your protocol config
+const protocol: Partial<EventProtocol> = {
+  eventField: 'type',
+  dataField: 'payload',
+  channelJoin: 'subscribe',
+};
+new SharedWebSocket(url, { events: protocol });
+```
+
 ## Browser Support
 
 | API | Chrome | Firefox | Safari | Edge |