@gwakko/shared-websocket 0.1.1 → 0.2.1

package/README.md

@@ -308,26 +308,58 @@ Callback receives `{ ws, signal }` — destructure what you need. Signal aborts
 | `connected` | `boolean` | Connection status |
 | `tabRole` | `'leader' \| 'follower'` | Current tab's role |
 
-### React Hooks (React 19, uses `useEffectEvent` for stable refs)
+### React Hooks (React 19, `useEffectEvent` for stable refs)
 
-| Hook | Returns | Description |
-|------|---------|-------------|
-| `useSharedWebSocket()` | `SharedWebSocket` | Access instance from context |
-| `useSocketEvent<T>(event)` | `T \| undefined` | Latest event value |
-| `useSocketStream<T>(event)` | `T[]` | Accumulated events |
-| `useSocketSync<T>(key, init)` | `[T, setter]` | Cross-tab synced state |
-| `useSocketStatus()` | `{ connected, tabRole }` | Connection status |
+All hooks use context internally — no need to pass `ws`. Every hook accepts an **optional callback** for custom handling.
 
-All hooks use context internally — no need to pass `ws` as argument.
+| Hook | Without callback | With callback |
+|------|-----------------|---------------|
+| `useSharedWebSocket()` | `SharedWebSocket` | — |
+| `useSocketEvent<T>(event, cb?)` | Returns `T \| undefined` | `cb(data)` on each event |
+| `useSocketStream<T>(event, cb?)` | Returns `T[]` (accumulated) | `cb(data)` — manage your own state |
+| `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 }` | — |
+
+```tsx
+// Without callback — reactive state
+const order = useSocketEvent<Order>('order.created');
+
+// With callback — custom logic, stable ref
+useSocketEvent<Order>('order.created', (order) => {
+  playSound('new-order');
+  analytics.track('order_received', order);
+});
+
+// Stream with limit
+const [msgs, setMsgs] = useState<Message[]>([]);
+useSocketStream<Message>('chat.message', (msg) => {
+  setMsgs(prev => [msg, ...prev].slice(0, 50));
+});
+
+// Sync with side effect
+const [cart, setCart] = useSocketSync('cart', { items: [] }, (cart) => {
+  document.title = `Cart (${cart.items.length})`;
+});
+
+// Fire-and-forget
+useSocketCallback<Notification>('notification', (n) => {
+  if (ws.tabRole === 'leader') new Notification(n.title);
+});
+```
 
 ### Vue Composables
 
-| Composable | Returns | Description |
-|-----------|---------|-------------|
-| `useSocketEvent<T>(event)` | `Ref<T>` | Latest event value |
-| `useSocketStream<T>(event)` | `Ref<T[]>` | Accumulated events |
-| `useSocketSync<T>(key, init)` | `Ref<T>` | Cross-tab synced state (two-way) |
-| `useSocketStatus()` | `{ connected, tabRole }` | Reactive connection status |
+All composables accept an **optional callback** — same pattern as React hooks.
+
+| Composable | Without callback | With callback |
+|-----------|-----------------|---------------|
+| `useSharedWebSocket()` | `SharedWebSocket` | — |
+| `useSocketEvent<T>(event, cb?)` | `Ref<T>` | `cb(data)` on each event |
+| `useSocketStream<T>(event, cb?)` | `Ref<T[]>` | `cb(data)` — manage your own ref |
+| `useSocketSync<T>(key, init, cb?)` | `Ref<T>` (two-way) | `cb(value)` — side effects on sync |
+| `useSocketCallback<T>(event, cb)` | — | Fire-and-forget |
+| `useSocketStatus()` | `{ connected, tabRole }` | — |
 
 ## How It Works
 

package/dist/adapters/react.d.ts

@@ -42,30 +42,90 @@ export declare function SharedWebSocketProvider({ url, options, children }: Shar
  */
 export declare function useSharedWebSocket(): SharedWebSocket;
 /**
- * Subscribe to a WebSocket event. Returns the latest received value.
- * Uses useEffectEvent for a stable callback ref — no stale closures.
+ * Subscribe to a WebSocket event.
+ * - Without callback: returns the latest received value (reactive state).
+ * - With callback: calls your handler on each event (stable ref via useEffectEvent).
  *
  * @example
+ * // Reactive state — returns latest value
  * const order = useSocketEvent<Order>('order.created');
+ *
+ * @example
+ * // Custom callback — full control, no state
+ * useSocketEvent<Order>('order.created', (order) => {
+ *   playSound('new-order');
+ *   analytics.track('order_received', order);
+ * });
+ *
+ * @example
+ * // Custom callback with transform — store in your own state
+ * const [orders, setOrders] = useState<Order[]>([]);
+ * useSocketEvent<Order>('order.created', (order) => {
+ *   setOrders(prev => [order, ...prev].slice(0, 50)); // keep last 50
+ * });
  */
-export declare function useSocketEvent<T>(event: string): T | undefined;
+export declare function useSocketEvent<T>(event: string, callback?: (data: T) => void): T | undefined;
 /**
  * Accumulate WebSocket events into an array.
- * Uses useEffectEvent — handler always sees latest state without re-subscribing.
+ * - Without callback: returns accumulated array (reactive state).
+ * - With callback: calls your handler on each event, you manage your own state.
  *
  * @example
+ * // Default — accumulates all events
  * const messages = useSocketStream<ChatMessage>('chat.message');
+ *
+ * @example
+ * // Custom callback — keep only last 50, transform, filter, etc.
+ * const [messages, setMessages] = useState<ChatMessage[]>([]);
+ * useSocketStream<ChatMessage>('chat.message', (msg) => {
+ *   setMessages(prev => [msg, ...prev].slice(0, 50));
+ * });
+ *
+ * @example
+ * // Custom callback — filter by type
+ * const [errors, setErrors] = useState<LogEntry[]>([]);
+ * useSocketStream<LogEntry>('log.entry', (entry) => {
+ *   if (entry.level === 'error') setErrors(prev => [...prev, entry]);
+ * });
  */
-export declare function useSocketStream<T>(event: string): T[];
+export declare function useSocketStream<T>(event: string, callback?: (data: T) => void): T[];
 /**
  * Two-way state sync across browser tabs.
- * Uses useEffectEvent for stable sync callback.
+ * - Without callback: returns [value, setter] (like useState but synced).
+ * - With callback: calls your handler when any tab updates this key.
  *
  * @example
+ * // Default — reactive synced state
  * const [cart, setCart] = useSocketSync<Cart>('cart', { items: [] });
- * // setCart in one tab → updates all tabs instantly
+ *
+ * @example
+ * // Custom callback — side effects on sync
+ * const [cart, setCart] = useSocketSync<Cart>('cart', { items: [] }, (cart) => {
+ *   document.title = `Cart (${cart.items.length})`;
+ *   analytics.track('cart_updated', { count: cart.items.length });
+ * });
+ */
+export declare function useSocketSync<T>(key: string, initialValue: T, callback?: (value: T) => void): [T, (value: T) => void];
+/**
+ * Subscribe to a WebSocket event with just a callback — no state, no return value.
+ * Fire-and-forget: side effects, logging, analytics, sounds, browser notifications.
+ * Stable ref via useEffectEvent — callback always sees latest closure values.
+ *
+ * @example
+ * useSocketCallback<Order>('order.created', (order) => {
+ *   playSound('new-order');
+ *   analytics.track('order_received', { id: order.id });
+ * });
+ *
+ * @example
+ * // Browser notification only from leader tab
+ * useSocketCallback<Notification>('notification', (notif) => {
+ *   if (ws.tabRole === 'leader' && document.hidden) {
+ *     new Notification(notif.title, { body: notif.body });
+ *   }
+ * });
  */
-export declare function useSocketSync<T>(key: string, initialValue: T): [T, (value: T) => void];
+export declare function useSocketCallback<T>(event: string, callback: (data: T) => void): void;
 /**
  * Reactive connection status.
  * Uses useEffectEvent to avoid re-creating interval on state change.

package/dist/adapters/vue.d.ts

@@ -7,7 +7,10 @@ export declare const SharedWebSocketKey: InjectionKey<SharedWebSocket>;
  *
  * @example
  * const app = createApp(App);
- * app.use(createSharedWebSocketPlugin('wss://api.example.com/ws'));
+ * app.use(createSharedWebSocketPlugin('wss://api.example.com/ws', {
+ *   auth: () => localStorage.getItem('token')!,
+ *   useWorker: true,
+ * }));
  */
 export declare function createSharedWebSocketPlugin(url: string, options?: SharedWebSocketOptions): {
     install(app: App): void;
@@ -17,30 +20,77 @@ export declare function createSharedWebSocketPlugin(url: string, options?: Share
  *
  * @example
  * const ws = useSharedWebSocket();
+ * ws.send('chat.message', { text: 'Hello' });
  */
 export declare function useSharedWebSocket(): SharedWebSocket;
 /**
- * Subscribe to a WebSocket event. Returns reactive ref with latest value.
+ * Subscribe to a WebSocket event.
+ * - Without callback: returns reactive ref with latest value.
+ * - With callback: calls your handler on each event.
  *
  * @example
+ * // Reactive state
  * const order = useSocketEvent<Order>('order.created');
+ *
+ * @example
+ * // Custom callback
+ * useSocketEvent<Order>('order.created', (order) => {
+ *   playSound('new-order');
+ *   analytics.track('order_received', order);
+ * });
  */
-export declare function useSocketEvent<T>(event: string): Ref<T | undefined>;
+export declare function useSocketEvent<T>(event: string, callback?: (data: T) => void): Ref<T | undefined>;
 /**
- * Accumulate WebSocket events into reactive array.
+ * Accumulate WebSocket events.
+ * - Without callback: returns reactive array.
+ * - With callback: calls your handler — manage your own state.
  *
  * @example
+ * // Default accumulation
  * const messages = useSocketStream<ChatMessage>('chat.message');
+ *
+ * @example
+ * // Custom — keep last 50
+ * const messages = ref<ChatMessage[]>([]);
+ * useSocketStream<ChatMessage>('chat.message', (msg) => {
+ *   messages.value = [msg, ...messages.value].slice(0, 50);
+ * });
+ *
+ * @example
+ * // Custom — filter by type
+ * const errors = ref<LogEntry[]>([]);
+ * useSocketStream<LogEntry>('log.entry', (entry) => {
+ *   if (entry.level === 'error') errors.value = [...errors.value, entry];
+ * });
  */
-export declare function useSocketStream<T>(event: string): Ref<T[]>;
+export declare function useSocketStream<T>(event: string, callback?: (data: T) => void): Ref<T[]>;
 /**
- * Two-way state sync across browser tabs via reactive ref.
+ * Two-way state sync across browser tabs.
+ * - Without callback: reactive ref synced across tabs.
+ * - With callback: called when any tab updates this key — side effects.
  *
  * @example
+ * // Reactive two-way sync
  * const cart = useSocketSync<Cart>('cart', { items: [] });
  * cart.value = { items: [1, 2, 3] }; // syncs to all tabs
+ *
+ * @example
+ * // With side effect callback
+ * const cart = useSocketSync<Cart>('cart', { items: [] }, (cart) => {
+ *   document.title = `Cart (${cart.items.length})`;
+ *   analytics.track('cart_updated');
+ * });
+ */
+export declare function useSocketSync<T>(key: string, initialValue: T, callback?: (value: T) => void): Ref<T>;
+/**
+ * Fire-and-forget event handler — no state, no ref.
+ *
+ * @example
+ * useSocketCallback<Notification>('notification', (n) => {
+ *   showToast(n.title);
+ * });
  */
-export declare function useSocketSync<T>(key: string, initialValue: T): Ref<T>;
+export declare function useSocketCallback<T>(event: string, callback: (data: T) => void): void;
 /**
  * Reactive connection status.
  *

package/dist/react.cjs

@@ -1,4 +1,4 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
 
 var _chunkSMH3X34Ncjs = require('./chunk-SMH3X34N.cjs');
 
@@ -32,38 +32,47 @@ function useSharedWebSocket() {
   }
   return ctx;
 }
-function useSocketEvent(event) {
+function useSocketEvent(event, callback) {
   const socket = useSharedWebSocket();
   const [value, setValue] = _react.useState.call(void 0, void 0);
   const onEvent = _react.useEffectEvent.call(void 0, (data) => {
-    setValue(data);
+    if (callback) {
+      callback(data);
+    } else {
+      setValue(data);
+    }
   });
   _react.useEffect.call(void 0, () => {
     const unsub = socket.on(event, onEvent);
     return unsub;
   }, [socket, event]);
-  return value;
+  return callback ? void 0 : value;
 }
-function useSocketStream(event) {
+function useSocketStream(event, callback) {
   const socket = useSharedWebSocket();
   const [items, setItems] = _react.useState.call(void 0, []);
   const onEvent = _react.useEffectEvent.call(void 0, (data) => {
-    setItems((prev) => [...prev, data]);
+    if (callback) {
+      callback(data);
+    } else {
+      setItems((prev) => [...prev, data]);
+    }
   });
   _react.useEffect.call(void 0, () => {
-    setItems([]);
+    if (!callback) setItems([]);
     const unsub = socket.on(event, onEvent);
     return unsub;
   }, [socket, event]);
-  return items;
+  return callback ? [] : items;
 }
-function useSocketSync(key, initialValue) {
+function useSocketSync(key, initialValue, callback) {
   const socket = useSharedWebSocket();
   const [value, setValue] = _react.useState.call(void 0, () => {
     return _nullishCoalesce(socket.getSync(key), () => ( initialValue));
   });
   const onSync = _react.useEffectEvent.call(void 0, (synced) => {
     setValue(synced);
+    _optionalChain([callback, 'optionalCall', _ => _(synced)]);
   });
   _react.useEffect.call(void 0, () => {
     const unsub = socket.onSync(key, onSync);
@@ -75,6 +84,16 @@ function useSocketSync(key, initialValue) {
   });
   return [value, setAndSync];
 }
+function useSocketCallback(event, callback) {
+  const socket = useSharedWebSocket();
+  const handler = _react.useEffectEvent.call(void 0, (data) => {
+    callback(data);
+  });
+  _react.useEffect.call(void 0, () => {
+    const unsub = socket.on(event, handler);
+    return unsub;
+  }, [socket, event]);
+}
 function useSocketStatus() {
   const socket = useSharedWebSocket();
   const [connected, setConnected] = _react.useState.call(void 0, socket.connected);
@@ -96,5 +115,6 @@ function useSocketStatus() {
 
 
 
-exports.SharedWebSocketProvider = SharedWebSocketProvider; exports.useSharedWebSocket = useSharedWebSocket; exports.useSocketEvent = useSocketEvent; exports.useSocketStatus = useSocketStatus; exports.useSocketStream = useSocketStream; exports.useSocketSync = useSocketSync;
+
+exports.SharedWebSocketProvider = SharedWebSocketProvider; exports.useSharedWebSocket = useSharedWebSocket; exports.useSocketCallback = useSocketCallback; exports.useSocketEvent = useSocketEvent; exports.useSocketStatus = useSocketStatus; exports.useSocketStream = useSocketStream; exports.useSocketSync = useSocketSync;
 //# sourceMappingURL=react.cjs.map

package/dist/react.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/gwakko/Projects/shared-websocket/dist/react.cjs","../src/adapters/react.ts"],"names":[],"mappings":"AAAA;AACE;AACF,wDAA6B;AAC7B;AACA;ACJA;AACE;AACA;AACA;AACA;AACA;AAEA;AAAA,8BACK;AAMP,IAAM,gBAAA,EAAkB,kCAAA,IAA0C,CAAA;AAkC3D,SAAS,uBAAA,CAAwB,EAAE,GAAA,EAAK,OAAA,EAAS,SAAS,CAAA,EAAiC;AAChG,EAAA,MAAM,CAAC,MAAM,EAAA,EAAI,6BAAA,CAAS,EAAA,GAAM;AAC9B,IAAA,MAAM,GAAA,EAAK,IAAI,sCAAA,CAAgB,GAAA,EAAK,OAAO,CAAA;AAC3C,IAAA,EAAA,CAAG,OAAA,CAAQ,CAAA;AACX,IAAA,OAAO,EAAA;AAAA,EACT,CAAC,CAAA;AAED,EAAA,8BAAA,CAAU,EAAA,GAAM;AACd,IAAA,OAAO,CAAA,EAAA,GAAM;AACX,MAAA,MAAA,CAAO,MAAA,CAAO,OAAO,CAAA,CAAE,CAAA;AAAA,IACzB,CAAA;AAAA,EACF,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA;AAEX,EAAA,OAAO,kCAAA,eAAc,CAAgB,QAAA,EAAU,EAAE,KAAA,EAAO,OAAO,CAAA,EAAG,QAAQ,CAAA;AAC5E;AASO,SAAS,kBAAA,CAAA,EAAsC;AACpD,EAAA,MAAM,IAAA,EAAM,+BAAA,eAA0B,CAAA;AACtC,EAAA,GAAA,CAAI,CAAC,GAAA,EAAK;AACR,IAAA,MAAM,IAAI,KAAA,CAAM,kEAAkE,CAAA;AAAA,EACpF;AACA,EAAA,OAAO,GAAA;AACT;AAWO,SAAS,cAAA,CAAkB,KAAA,EAA8B;AAC9D,EAAA,MAAM,OAAA,EAAS,kBAAA,CAAmB,CAAA;AAClC,EAAA,MAAM,CAAC,KAAA,EAAO,QAAQ,EAAA,EAAI,6BAAA,KAAwB,CAAS,CAAA;AAE3D,EAAA,MAAM,QAAA,EAAU,mCAAA,CAAgB,IAAA,EAAA,GAAY;AAC1C,IAAA,QAAA,CAAS,IAAI,CAAA;AAAA,EACf,CAAC,CAAA;AAED,EAAA,8BAAA,CAAU,EAAA,GAAM;AACd,IAAA,MAAM,MAAA,EAAQ,MAAA,CAAO,EAAA,CAAG,KAAA,EAAO,OAAO,CAAA;AACtC,IAAA,OAAO,KAAA;AAAA,EACT,CAAA,EAAG,CAAC,MAAA,EAAQ,KAAK,CAAC,CAAA;AAElB,EAAA,OAAO,KAAA;AACT;AASO,SAAS,eAAA,CAAmB,KAAA,EAAoB;AACrD,EAAA,MAAM,OAAA,EAAS,kBAAA,CAAmB,CAAA;AAClC,EAAA,MAAM,CAAC,KAAA,EAAO,QAAQ,EAAA,EAAI,6BAAA,CAAe,CAAC,CAAA;AAE1C,EAAA,MAAM,QAAA,EAAU,mCAAA,CAAgB,IAAA,EAAA,GAAY;AAC1C,IAAA,QAAA,CAAS,CAAC,IAAA,EAAA,GAAS,CAAC,GAAG,IAAA,EAAM,IAAI,CAAC,CAAA;AAAA,EACpC,CAAC,CAAA;AAED,EAAA,8BAAA,CAAU,EAAA,GAAM;AACd,IAAA,QAAA,CAAS,CAAC,CAAC,CAAA;AACX,IAAA,MAAM,MAAA,EAAQ,MAAA,CAAO,EAAA,CAAG,KAAA,EAAO,OAAO,CAAA;AACtC,IAAA,OAAO,KAAA;AAAA,EACT,CAAA,EAAG,CAAC,MAAA,EAAQ,KAAK,CAAC,CAAA;AAElB,EAAA,OAAO,KAAA;AACT;AAUO,SAAS,aAAA,CACd,GAAA,EACA,YAAA,EACyB;AACzB,EAAA,MAAM,OAAA,EAAS,kBAAA,CAAmB,CAAA;AAClC,EAAA,MAAM,CAAC,KAAA,EAAO,QAAQ,EAAA,EAAI,6BAAA,CAAY,EAAA,GAAM;AAC1C,IAAA,wBAAO,MAAA,CAAO,OAAA,CAAW,GAAG,CAAA,UAAK,cAAA;AAAA,EACnC,CAAC,CAAA;AAED,EAAA,MAAM,OAAA,EAAS,mCAAA,CAAgB,MAAA,EAAA,GAAc;AAC3C,IAAA,QAAA,CAAS,MAAM,CAAA;AAAA,EACjB,CAAC,CAAA;AAED,EAAA,8BAAA,CAAU,EAAA,GAAM;AACd,IAAA,MAAM,MAAA,EAAQ,MAAA,CAAO,MAAA,CAAU,GAAA,EAAK,MAAM,CAAA;AAC1C,IAAA,OAAO,KAAA;AAAA,EACT,CAAA,EAAG,CAAC,MAAA,EAAQ,GAAG,CAAC,CAAA;AAEhB,EAAA,MAAM,WAAA,EAAa,mCAAA,CAAgB,QAAA,EAAA,GAAgB;AACjD,IAAA,QAAA,CAAS,QAAQ,CAAA;AACjB,IAAA,MAAA,CAAO,IAAA,CAAK,GAAA,EAAK,QAAQ,CAAA;AAAA,EAC3B,CAAC,CAAA;AAED,EAAA,OAAO,CAAC,KAAA,EAAO,UAAU,CAAA;AAC3B;AASO,SAAS,eAAA,CAAA,EAGd;AACA,EAAA,MAAM,OAAA,EAAS,kBAAA,CAAmB,CAAA;AAClC,EAAA,MAAM,CAAC,SAAA,EAAW,YAAY,EAAA,EAAI,6BAAA,MAAS,CAAO,SAAS,CAAA;AAC3D,EAAA,MAAM,CAAC,OAAA,EAAS,UAAU,EAAA,EAAI,6BAAA,MAAkB,CAAO,OAAO,CAAA;AAE9D,EAAA,MAAM,KAAA,EAAO,mCAAA,CAAe,EAAA,GAAM;AAChC,IAAA,YAAA,CAAa,MAAA,CAAO,SAAS,CAAA;AAC7B,IAAA,UAAA,CAAW,MAAA,CAAO,OAAO,CAAA;AAAA,EAC3B,CAAC,CAAA;AAED,EAAA,8BAAA,CAAU,EAAA,GAAM;AACd,IAAA,MAAM,SAAA,EAAW,WAAA,CAAY,IAAA,EAAM,GAAI,CAAA;AACvC,IAAA,OAAO,CAAA,EAAA,GAAM,aAAA,CAAc,QAAQ,CAAA;AAAA,EACrC,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA;AAEX,EAAA,OAAO,EAAE,SAAA,EAAW,QAAQ,CAAA;AAC9B;ADjGA;AACE;AACA;AACA;AACA;AACA;AACA;AACF,iRAAC","file":"/Users/gwakko/Projects/shared-websocket/dist/react.cjs","sourcesContent":[null,"import {\n  createContext,\n  useContext,\n  useEffect,\n  useState,\n  useEffectEvent,\n  type ReactNode,\n  createElement,\n} from 'react';\nimport { SharedWebSocket } from '../SharedWebSocket';\nimport type { SharedWebSocketOptions, TabRole } from '../types';\n\n// ─── Context ─────────────────────────────────────────────\n\nconst SharedWSContext = createContext<SharedWebSocket | null>(null);\n\n/**\n * Provider props — pass URL and options as props for flexibility.\n *\n * @example\n * <SharedWebSocketProvider url=\"wss://api.example.com/ws\" options={{ auth: getToken }}>\n *   <App />\n * </SharedWebSocketProvider>\n */\nexport interface SharedWebSocketProviderProps {\n  url: string;\n  options?: SharedWebSocketOptions;\n  children: ReactNode;\n}\n\n/**\n * Provider component — creates SharedWebSocket from props, auto-disposes on unmount.\n *\n * @example\n * function App() {\n *   return (\n *     <SharedWebSocketProvider\n *       url=\"wss://api.example.com/ws\"\n *       options={{\n *         auth: () => localStorage.getItem('token')!,\n *         useWorker: true,\n *       }}\n *     >\n *       <Dashboard />\n *     </SharedWebSocketProvider>\n *   );\n * }\n */\nexport function SharedWebSocketProvider({ url, options, children }: SharedWebSocketProviderProps) {\n  const [socket] = useState(() => {\n    const ws = new SharedWebSocket(url, options);\n    ws.connect();\n    return ws;\n  });\n\n  useEffect(() => {\n    return () => {\n      socket[Symbol.dispose]();\n    };\n  }, [socket]);\n\n  return createElement(SharedWSContext.Provider, { value: socket }, children);\n}\n\n/**\n * Access the SharedWebSocket instance from context.\n *\n * @example\n * const ws = useSharedWebSocket();\n * ws.send('chat.message', { text: 'Hello' });\n */\nexport function useSharedWebSocket(): SharedWebSocket {\n  const ctx = useContext(SharedWSContext);\n  if (!ctx) {\n    throw new Error('useSharedWebSocket must be used within <SharedWebSocketProvider>');\n  }\n  return ctx;\n}\n\n// ─── Hooks ───────────────────────────────────────────────\n\n/**\n * Subscribe to a WebSocket event. Returns the latest received value.\n * Uses useEffectEvent for a stable callback ref — no stale closures.\n *\n * @example\n * const order = useSocketEvent<Order>('order.created');\n */\nexport function useSocketEvent<T>(event: string): T | undefined {\n  const socket = useSharedWebSocket();\n  const [value, setValue] = useState<T | undefined>(undefined);\n\n  const onEvent = useEffectEvent((data: T) => {\n    setValue(data);\n  });\n\n  useEffect(() => {\n    const unsub = socket.on(event, onEvent);\n    return unsub;\n  }, [socket, event]);\n\n  return value;\n}\n\n/**\n * Accumulate WebSocket events into an array.\n * Uses useEffectEvent — handler always sees latest state without re-subscribing.\n *\n * @example\n * const messages = useSocketStream<ChatMessage>('chat.message');\n */\nexport function useSocketStream<T>(event: string): T[] {\n  const socket = useSharedWebSocket();\n  const [items, setItems] = useState<T[]>([]);\n\n  const onEvent = useEffectEvent((data: T) => {\n    setItems((prev) => [...prev, data]);\n  });\n\n  useEffect(() => {\n    setItems([]);\n    const unsub = socket.on(event, onEvent);\n    return unsub;\n  }, [socket, event]);\n\n  return items;\n}\n\n/**\n * Two-way state sync across browser tabs.\n * Uses useEffectEvent for stable sync callback.\n *\n * @example\n * const [cart, setCart] = useSocketSync<Cart>('cart', { items: [] });\n * // setCart in one tab → updates all tabs instantly\n */\nexport function useSocketSync<T>(\n  key: string,\n  initialValue: T,\n): [T, (value: T) => void] {\n  const socket = useSharedWebSocket();\n  const [value, setValue] = useState<T>(() => {\n    return socket.getSync<T>(key) ?? initialValue;\n  });\n\n  const onSync = useEffectEvent((synced: T) => {\n    setValue(synced);\n  });\n\n  useEffect(() => {\n    const unsub = socket.onSync<T>(key, onSync);\n    return unsub;\n  }, [socket, key]);\n\n  const setAndSync = useEffectEvent((newValue: T) => {\n    setValue(newValue);\n    socket.sync(key, newValue);\n  });\n\n  return [value, setAndSync];\n}\n\n/**\n * Reactive connection status.\n * Uses useEffectEvent to avoid re-creating interval on state change.\n *\n * @example\n * const { connected, tabRole } = useSocketStatus();\n */\nexport function useSocketStatus(): {\n  connected: boolean;\n  tabRole: TabRole;\n} {\n  const socket = useSharedWebSocket();\n  const [connected, setConnected] = useState(socket.connected);\n  const [tabRole, setTabRole] = useState<TabRole>(socket.tabRole);\n\n  const tick = useEffectEvent(() => {\n    setConnected(socket.connected);\n    setTabRole(socket.tabRole);\n  });\n\n  useEffect(() => {\n    const interval = setInterval(tick, 1000);\n    return () => clearInterval(interval);\n  }, [socket]);\n\n  return { connected, tabRole };\n}\n"]}
+{"version":3,"sources":["/Users/gwakko/Projects/shared-websocket/dist/react.cjs","../src/adapters/react.ts"],"names":[],"mappings":"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","file":"/Users/gwakko/Projects/shared-websocket/dist/react.cjs","sourcesContent":[null,"import {\n  createContext,\n  useContext,\n  useEffect,\n  useState,\n  useEffectEvent,\n  type ReactNode,\n  createElement,\n} from 'react';\nimport { SharedWebSocket } from '../SharedWebSocket';\nimport type { SharedWebSocketOptions, TabRole } from '../types';\n\n// ─── Context ─────────────────────────────────────────────\n\nconst SharedWSContext = createContext<SharedWebSocket | null>(null);\n\n/**\n * Provider props — pass URL and options as props for flexibility.\n *\n * @example\n * <SharedWebSocketProvider url=\"wss://api.example.com/ws\" options={{ auth: getToken }}>\n *   <App />\n * </SharedWebSocketProvider>\n */\nexport interface SharedWebSocketProviderProps {\n  url: string;\n  options?: SharedWebSocketOptions;\n  children: ReactNode;\n}\n\n/**\n * Provider component — creates SharedWebSocket from props, auto-disposes on unmount.\n *\n * @example\n * function App() {\n *   return (\n *     <SharedWebSocketProvider\n *       url=\"wss://api.example.com/ws\"\n *       options={{\n *         auth: () => localStorage.getItem('token')!,\n *         useWorker: true,\n *       }}\n *     >\n *       <Dashboard />\n *     </SharedWebSocketProvider>\n *   );\n * }\n */\nexport function SharedWebSocketProvider({ url, options, children }: SharedWebSocketProviderProps) {\n  const [socket] = useState(() => {\n    const ws = new SharedWebSocket(url, options);\n    ws.connect();\n    return ws;\n  });\n\n  useEffect(() => {\n    return () => {\n      socket[Symbol.dispose]();\n    };\n  }, [socket]);\n\n  return createElement(SharedWSContext.Provider, { value: socket }, children);\n}\n\n/**\n * Access the SharedWebSocket instance from context.\n *\n * @example\n * const ws = useSharedWebSocket();\n * ws.send('chat.message', { text: 'Hello' });\n */\nexport function useSharedWebSocket(): SharedWebSocket {\n  const ctx = useContext(SharedWSContext);\n  if (!ctx) {\n    throw new Error('useSharedWebSocket must be used within <SharedWebSocketProvider>');\n  }\n  return ctx;\n}\n\n// ─── Hooks ───────────────────────────────────────────────\n\n/**\n * Subscribe to a WebSocket event.\n * - Without callback: returns the latest received value (reactive state).\n * - With callback: calls your handler on each event (stable ref via useEffectEvent).\n *\n * @example\n * // Reactive state — returns latest value\n * const order = useSocketEvent<Order>('order.created');\n *\n * @example\n * // Custom callback — full control, no state\n * useSocketEvent<Order>('order.created', (order) => {\n *   playSound('new-order');\n *   analytics.track('order_received', order);\n * });\n *\n * @example\n * // Custom callback with transform — store in your own state\n * const [orders, setOrders] = useState<Order[]>([]);\n * useSocketEvent<Order>('order.created', (order) => {\n *   setOrders(prev => [order, ...prev].slice(0, 50)); // keep last 50\n * });\n */\nexport function useSocketEvent<T>(event: string, callback?: (data: T) => void): T | undefined {\n  const socket = useSharedWebSocket();\n  const [value, setValue] = useState<T | undefined>(undefined);\n\n  const onEvent = useEffectEvent((data: T) => {\n    if (callback) {\n      callback(data);\n    } else {\n      setValue(data);\n    }\n  });\n\n  useEffect(() => {\n    const unsub = socket.on(event, onEvent);\n    return unsub;\n  }, [socket, event]);\n\n  return callback ? undefined : value;\n}\n\n/**\n * Accumulate WebSocket events into an array.\n * - Without callback: returns accumulated array (reactive state).\n * - With callback: calls your handler on each event, you manage your own state.\n *\n * @example\n * // Default — accumulates all events\n * const messages = useSocketStream<ChatMessage>('chat.message');\n *\n * @example\n * // Custom callback — keep only last 50, transform, filter, etc.\n * const [messages, setMessages] = useState<ChatMessage[]>([]);\n * useSocketStream<ChatMessage>('chat.message', (msg) => {\n *   setMessages(prev => [msg, ...prev].slice(0, 50));\n * });\n *\n * @example\n * // Custom callback — filter by type\n * const [errors, setErrors] = useState<LogEntry[]>([]);\n * useSocketStream<LogEntry>('log.entry', (entry) => {\n *   if (entry.level === 'error') setErrors(prev => [...prev, entry]);\n * });\n */\nexport function useSocketStream<T>(event: string, callback?: (data: T) => void): T[] {\n  const socket = useSharedWebSocket();\n  const [items, setItems] = useState<T[]>([]);\n\n  const onEvent = useEffectEvent((data: T) => {\n    if (callback) {\n      callback(data);\n    } else {\n      setItems((prev) => [...prev, data]);\n    }\n  });\n\n  useEffect(() => {\n    if (!callback) setItems([]);\n    const unsub = socket.on(event, onEvent);\n    return unsub;\n  }, [socket, event]);\n\n  return callback ? [] : items;\n}\n\n/**\n * Two-way state sync across browser tabs.\n * - Without callback: returns [value, setter] (like useState but synced).\n * - With callback: calls your handler when any tab updates this key.\n *\n * @example\n * // Default — reactive synced state\n * const [cart, setCart] = useSocketSync<Cart>('cart', { items: [] });\n *\n * @example\n * // Custom callback — side effects on sync\n * const [cart, setCart] = useSocketSync<Cart>('cart', { items: [] }, (cart) => {\n *   document.title = `Cart (${cart.items.length})`;\n *   analytics.track('cart_updated', { count: cart.items.length });\n * });\n */\nexport function useSocketSync<T>(\n  key: string,\n  initialValue: T,\n  callback?: (value: T) => void,\n): [T, (value: T) => void] {\n  const socket = useSharedWebSocket();\n  const [value, setValue] = useState<T>(() => {\n    return socket.getSync<T>(key) ?? initialValue;\n  });\n\n  const onSync = useEffectEvent((synced: T) => {\n    setValue(synced);\n    callback?.(synced);\n  });\n\n  useEffect(() => {\n    const unsub = socket.onSync<T>(key, onSync);\n    return unsub;\n  }, [socket, key]);\n\n  const setAndSync = useEffectEvent((newValue: T) => {\n    setValue(newValue);\n    socket.sync(key, newValue);\n  });\n\n  return [value, setAndSync];\n}\n\n/**\n * Subscribe to a WebSocket event with just a callback — no state, no return value.\n * Fire-and-forget: side effects, logging, analytics, sounds, browser notifications.\n * Stable ref via useEffectEvent — callback always sees latest closure values.\n *\n * @example\n * useSocketCallback<Order>('order.created', (order) => {\n *   playSound('new-order');\n *   analytics.track('order_received', { id: order.id });\n * });\n *\n * @example\n * // Browser notification only from leader tab\n * useSocketCallback<Notification>('notification', (notif) => {\n *   if (ws.tabRole === 'leader' && document.hidden) {\n *     new Notification(notif.title, { body: notif.body });\n *   }\n * });\n */\nexport function useSocketCallback<T>(event: string, callback: (data: T) => void): void {\n  const socket = useSharedWebSocket();\n\n  const handler = useEffectEvent((data: T) => {\n    callback(data);\n  });\n\n  useEffect(() => {\n    const unsub = socket.on(event, handler);\n    return unsub;\n  }, [socket, event]);\n}\n\n/**\n * Reactive connection status.\n * Uses useEffectEvent to avoid re-creating interval on state change.\n *\n * @example\n * const { connected, tabRole } = useSocketStatus();\n */\nexport function useSocketStatus(): {\n  connected: boolean;\n  tabRole: TabRole;\n} {\n  const socket = useSharedWebSocket();\n  const [connected, setConnected] = useState(socket.connected);\n  const [tabRole, setTabRole] = useState<TabRole>(socket.tabRole);\n\n  const tick = useEffectEvent(() => {\n    setConnected(socket.connected);\n    setTabRole(socket.tabRole);\n  });\n\n  useEffect(() => {\n    const interval = setInterval(tick, 1000);\n    return () => clearInterval(interval);\n  }, [socket]);\n\n  return { connected, tabRole };\n}\n"]}

package/dist/react.js

@@ -32,38 +32,47 @@ function useSharedWebSocket() {
   }
   return ctx;
 }
-function useSocketEvent(event) {
+function useSocketEvent(event, callback) {
   const socket = useSharedWebSocket();
   const [value, setValue] = useState(void 0);
   const onEvent = useEffectEvent((data) => {
-    setValue(data);
+    if (callback) {
+      callback(data);
+    } else {
+      setValue(data);
+    }
   });
   useEffect(() => {
     const unsub = socket.on(event, onEvent);
     return unsub;
   }, [socket, event]);
-  return value;
+  return callback ? void 0 : value;
 }
-function useSocketStream(event) {
+function useSocketStream(event, callback) {
   const socket = useSharedWebSocket();
   const [items, setItems] = useState([]);
   const onEvent = useEffectEvent((data) => {
-    setItems((prev) => [...prev, data]);
+    if (callback) {
+      callback(data);
+    } else {
+      setItems((prev) => [...prev, data]);
+    }
   });
   useEffect(() => {
-    setItems([]);
+    if (!callback) setItems([]);
     const unsub = socket.on(event, onEvent);
     return unsub;
   }, [socket, event]);
-  return items;
+  return callback ? [] : items;
 }
-function useSocketSync(key, initialValue) {
+function useSocketSync(key, initialValue, callback) {
   const socket = useSharedWebSocket();
   const [value, setValue] = useState(() => {
     return socket.getSync(key) ?? initialValue;
   });
   const onSync = useEffectEvent((synced) => {
     setValue(synced);
+    callback?.(synced);
   });
   useEffect(() => {
     const unsub = socket.onSync(key, onSync);
@@ -75,6 +84,16 @@ function useSocketSync(key, initialValue) {
   });
   return [value, setAndSync];
 }
+function useSocketCallback(event, callback) {
+  const socket = useSharedWebSocket();
+  const handler = useEffectEvent((data) => {
+    callback(data);
+  });
+  useEffect(() => {
+    const unsub = socket.on(event, handler);
+    return unsub;
+  }, [socket, event]);
+}
 function useSocketStatus() {
   const socket = useSharedWebSocket();
   const [connected, setConnected] = useState(socket.connected);
@@ -92,6 +111,7 @@ function useSocketStatus() {
 export {
   SharedWebSocketProvider,
   useSharedWebSocket,
+  useSocketCallback,
   useSocketEvent,
   useSocketStatus,
   useSocketStream,

package/dist/react.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/adapters/react.ts"],"sourcesContent":["import {\n  createContext,\n  useContext,\n  useEffect,\n  useState,\n  useEffectEvent,\n  type ReactNode,\n  createElement,\n} from 'react';\nimport { SharedWebSocket } from '../SharedWebSocket';\nimport type { SharedWebSocketOptions, TabRole } from '../types';\n\n// ─── Context ─────────────────────────────────────────────\n\nconst SharedWSContext = createContext<SharedWebSocket | null>(null);\n\n/**\n * Provider props — pass URL and options as props for flexibility.\n *\n * @example\n * <SharedWebSocketProvider url=\"wss://api.example.com/ws\" options={{ auth: getToken }}>\n *   <App />\n * </SharedWebSocketProvider>\n */\nexport interface SharedWebSocketProviderProps {\n  url: string;\n  options?: SharedWebSocketOptions;\n  children: ReactNode;\n}\n\n/**\n * Provider component — creates SharedWebSocket from props, auto-disposes on unmount.\n *\n * @example\n * function App() {\n *   return (\n *     <SharedWebSocketProvider\n *       url=\"wss://api.example.com/ws\"\n *       options={{\n *         auth: () => localStorage.getItem('token')!,\n *         useWorker: true,\n *       }}\n *     >\n *       <Dashboard />\n *     </SharedWebSocketProvider>\n *   );\n * }\n */\nexport function SharedWebSocketProvider({ url, options, children }: SharedWebSocketProviderProps) {\n  const [socket] = useState(() => {\n    const ws = new SharedWebSocket(url, options);\n    ws.connect();\n    return ws;\n  });\n\n  useEffect(() => {\n    return () => {\n      socket[Symbol.dispose]();\n    };\n  }, [socket]);\n\n  return createElement(SharedWSContext.Provider, { value: socket }, children);\n}\n\n/**\n * Access the SharedWebSocket instance from context.\n *\n * @example\n * const ws = useSharedWebSocket();\n * ws.send('chat.message', { text: 'Hello' });\n */\nexport function useSharedWebSocket(): SharedWebSocket {\n  const ctx = useContext(SharedWSContext);\n  if (!ctx) {\n    throw new Error('useSharedWebSocket must be used within <SharedWebSocketProvider>');\n  }\n  return ctx;\n}\n\n// ─── Hooks ───────────────────────────────────────────────\n\n/**\n * Subscribe to a WebSocket event. Returns the latest received value.\n * Uses useEffectEvent for a stable callback ref — no stale closures.\n *\n * @example\n * const order = useSocketEvent<Order>('order.created');\n */\nexport function useSocketEvent<T>(event: string): T | undefined {\n  const socket = useSharedWebSocket();\n  const [value, setValue] = useState<T | undefined>(undefined);\n\n  const onEvent = useEffectEvent((data: T) => {\n    setValue(data);\n  });\n\n  useEffect(() => {\n    const unsub = socket.on(event, onEvent);\n    return unsub;\n  }, [socket, event]);\n\n  return value;\n}\n\n/**\n * Accumulate WebSocket events into an array.\n * Uses useEffectEvent — handler always sees latest state without re-subscribing.\n *\n * @example\n * const messages = useSocketStream<ChatMessage>('chat.message');\n */\nexport function useSocketStream<T>(event: string): T[] {\n  const socket = useSharedWebSocket();\n  const [items, setItems] = useState<T[]>([]);\n\n  const onEvent = useEffectEvent((data: T) => {\n    setItems((prev) => [...prev, data]);\n  });\n\n  useEffect(() => {\n    setItems([]);\n    const unsub = socket.on(event, onEvent);\n    return unsub;\n  }, [socket, event]);\n\n  return items;\n}\n\n/**\n * Two-way state sync across browser tabs.\n * Uses useEffectEvent for stable sync callback.\n *\n * @example\n * const [cart, setCart] = useSocketSync<Cart>('cart', { items: [] });\n * // setCart in one tab → updates all tabs instantly\n */\nexport function useSocketSync<T>(\n  key: string,\n  initialValue: T,\n): [T, (value: T) => void] {\n  const socket = useSharedWebSocket();\n  const [value, setValue] = useState<T>(() => {\n    return socket.getSync<T>(key) ?? initialValue;\n  });\n\n  const onSync = useEffectEvent((synced: T) => {\n    setValue(synced);\n  });\n\n  useEffect(() => {\n    const unsub = socket.onSync<T>(key, onSync);\n    return unsub;\n  }, [socket, key]);\n\n  const setAndSync = useEffectEvent((newValue: T) => {\n    setValue(newValue);\n    socket.sync(key, newValue);\n  });\n\n  return [value, setAndSync];\n}\n\n/**\n * Reactive connection status.\n * Uses useEffectEvent to avoid re-creating interval on state change.\n *\n * @example\n * const { connected, tabRole } = useSocketStatus();\n */\nexport function useSocketStatus(): {\n  connected: boolean;\n  tabRole: TabRole;\n} {\n  const socket = useSharedWebSocket();\n  const [connected, setConnected] = useState(socket.connected);\n  const [tabRole, setTabRole] = useState<TabRole>(socket.tabRole);\n\n  const tick = useEffectEvent(() => {\n    setConnected(socket.connected);\n    setTabRole(socket.tabRole);\n  });\n\n  useEffect(() => {\n    const interval = setInterval(tick, 1000);\n    return () => clearInterval(interval);\n  }, [socket]);\n\n  return { connected, tabRole };\n}\n"],"mappings":";;;;;AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEA;AAAA,OACK;AAMP,IAAM,kBAAkB,cAAsC,IAAI;AAkC3D,SAAS,wBAAwB,EAAE,KAAK,SAAS,SAAS,GAAiC;AAChG,QAAM,CAAC,MAAM,IAAI,SAAS,MAAM;AAC9B,UAAM,KAAK,IAAI,gBAAgB,KAAK,OAAO;AAC3C,OAAG,QAAQ;AACX,WAAO;AAAA,EACT,CAAC;AAED,YAAU,MAAM;AACd,WAAO,MAAM;AACX,aAAO,OAAO,OAAO,EAAE;AAAA,IACzB;AAAA,EACF,GAAG,CAAC,MAAM,CAAC;AAEX,SAAO,cAAc,gBAAgB,UAAU,EAAE,OAAO,OAAO,GAAG,QAAQ;AAC5E;AASO,SAAS,qBAAsC;AACpD,QAAM,MAAM,WAAW,eAAe;AACtC,MAAI,CAAC,KAAK;AACR,UAAM,IAAI,MAAM,kEAAkE;AAAA,EACpF;AACA,SAAO;AACT;AAWO,SAAS,eAAkB,OAA8B;AAC9D,QAAM,SAAS,mBAAmB;AAClC,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAwB,MAAS;AAE3D,QAAM,UAAU,eAAe,CAAC,SAAY;AAC1C,aAAS,IAAI;AAAA,EACf,CAAC;AAED,YAAU,MAAM;AACd,UAAM,QAAQ,OAAO,GAAG,OAAO,OAAO;AACtC,WAAO;AAAA,EACT,GAAG,CAAC,QAAQ,KAAK,CAAC;AAElB,SAAO;AACT;AASO,SAAS,gBAAmB,OAAoB;AACrD,QAAM,SAAS,mBAAmB;AAClC,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAc,CAAC,CAAC;AAE1C,QAAM,UAAU,eAAe,CAAC,SAAY;AAC1C,aAAS,CAAC,SAAS,CAAC,GAAG,MAAM,IAAI,CAAC;AAAA,EACpC,CAAC;AAED,YAAU,MAAM;AACd,aAAS,CAAC,CAAC;AACX,UAAM,QAAQ,OAAO,GAAG,OAAO,OAAO;AACtC,WAAO;AAAA,EACT,GAAG,CAAC,QAAQ,KAAK,CAAC;AAElB,SAAO;AACT;AAUO,SAAS,cACd,KACA,cACyB;AACzB,QAAM,SAAS,mBAAmB;AAClC,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAY,MAAM;AAC1C,WAAO,OAAO,QAAW,GAAG,KAAK;AAAA,EACnC,CAAC;AAED,QAAM,SAAS,eAAe,CAAC,WAAc;AAC3C,aAAS,MAAM;AAAA,EACjB,CAAC;AAED,YAAU,MAAM;AACd,UAAM,QAAQ,OAAO,OAAU,KAAK,MAAM;AAC1C,WAAO;AAAA,EACT,GAAG,CAAC,QAAQ,GAAG,CAAC;AAEhB,QAAM,aAAa,eAAe,CAAC,aAAgB;AACjD,aAAS,QAAQ;AACjB,WAAO,KAAK,KAAK,QAAQ;AAAA,EAC3B,CAAC;AAED,SAAO,CAAC,OAAO,UAAU;AAC3B;AASO,SAAS,kBAGd;AACA,QAAM,SAAS,mBAAmB;AAClC,QAAM,CAAC,WAAW,YAAY,IAAI,SAAS,OAAO,SAAS;AAC3D,QAAM,CAAC,SAAS,UAAU,IAAI,SAAkB,OAAO,OAAO;AAE9D,QAAM,OAAO,eAAe,MAAM;AAChC,iBAAa,OAAO,SAAS;AAC7B,eAAW,OAAO,OAAO;AAAA,EAC3B,CAAC;AAED,YAAU,MAAM;AACd,UAAM,WAAW,YAAY,MAAM,GAAI;AACvC,WAAO,MAAM,cAAc,QAAQ;AAAA,EACrC,GAAG,CAAC,MAAM,CAAC;AAEX,SAAO,EAAE,WAAW,QAAQ;AAC9B;","names":[]}
+{"version":3,"sources":["../src/adapters/react.ts"],"sourcesContent":["import {\n  createContext,\n  useContext,\n  useEffect,\n  useState,\n  useEffectEvent,\n  type ReactNode,\n  createElement,\n} from 'react';\nimport { SharedWebSocket } from '../SharedWebSocket';\nimport type { SharedWebSocketOptions, TabRole } from '../types';\n\n// ─── Context ─────────────────────────────────────────────\n\nconst SharedWSContext = createContext<SharedWebSocket | null>(null);\n\n/**\n * Provider props — pass URL and options as props for flexibility.\n *\n * @example\n * <SharedWebSocketProvider url=\"wss://api.example.com/ws\" options={{ auth: getToken }}>\n *   <App />\n * </SharedWebSocketProvider>\n */\nexport interface SharedWebSocketProviderProps {\n  url: string;\n  options?: SharedWebSocketOptions;\n  children: ReactNode;\n}\n\n/**\n * Provider component — creates SharedWebSocket from props, auto-disposes on unmount.\n *\n * @example\n * function App() {\n *   return (\n *     <SharedWebSocketProvider\n *       url=\"wss://api.example.com/ws\"\n *       options={{\n *         auth: () => localStorage.getItem('token')!,\n *         useWorker: true,\n *       }}\n *     >\n *       <Dashboard />\n *     </SharedWebSocketProvider>\n *   );\n * }\n */\nexport function SharedWebSocketProvider({ url, options, children }: SharedWebSocketProviderProps) {\n  const [socket] = useState(() => {\n    const ws = new SharedWebSocket(url, options);\n    ws.connect();\n    return ws;\n  });\n\n  useEffect(() => {\n    return () => {\n      socket[Symbol.dispose]();\n    };\n  }, [socket]);\n\n  return createElement(SharedWSContext.Provider, { value: socket }, children);\n}\n\n/**\n * Access the SharedWebSocket instance from context.\n *\n * @example\n * const ws = useSharedWebSocket();\n * ws.send('chat.message', { text: 'Hello' });\n */\nexport function useSharedWebSocket(): SharedWebSocket {\n  const ctx = useContext(SharedWSContext);\n  if (!ctx) {\n    throw new Error('useSharedWebSocket must be used within <SharedWebSocketProvider>');\n  }\n  return ctx;\n}\n\n// ─── Hooks ───────────────────────────────────────────────\n\n/**\n * Subscribe to a WebSocket event.\n * - Without callback: returns the latest received value (reactive state).\n * - With callback: calls your handler on each event (stable ref via useEffectEvent).\n *\n * @example\n * // Reactive state — returns latest value\n * const order = useSocketEvent<Order>('order.created');\n *\n * @example\n * // Custom callback — full control, no state\n * useSocketEvent<Order>('order.created', (order) => {\n *   playSound('new-order');\n *   analytics.track('order_received', order);\n * });\n *\n * @example\n * // Custom callback with transform — store in your own state\n * const [orders, setOrders] = useState<Order[]>([]);\n * useSocketEvent<Order>('order.created', (order) => {\n *   setOrders(prev => [order, ...prev].slice(0, 50)); // keep last 50\n * });\n */\nexport function useSocketEvent<T>(event: string, callback?: (data: T) => void): T | undefined {\n  const socket = useSharedWebSocket();\n  const [value, setValue] = useState<T | undefined>(undefined);\n\n  const onEvent = useEffectEvent((data: T) => {\n    if (callback) {\n      callback(data);\n    } else {\n      setValue(data);\n    }\n  });\n\n  useEffect(() => {\n    const unsub = socket.on(event, onEvent);\n    return unsub;\n  }, [socket, event]);\n\n  return callback ? undefined : value;\n}\n\n/**\n * Accumulate WebSocket events into an array.\n * - Without callback: returns accumulated array (reactive state).\n * - With callback: calls your handler on each event, you manage your own state.\n *\n * @example\n * // Default — accumulates all events\n * const messages = useSocketStream<ChatMessage>('chat.message');\n *\n * @example\n * // Custom callback — keep only last 50, transform, filter, etc.\n * const [messages, setMessages] = useState<ChatMessage[]>([]);\n * useSocketStream<ChatMessage>('chat.message', (msg) => {\n *   setMessages(prev => [msg, ...prev].slice(0, 50));\n * });\n *\n * @example\n * // Custom callback — filter by type\n * const [errors, setErrors] = useState<LogEntry[]>([]);\n * useSocketStream<LogEntry>('log.entry', (entry) => {\n *   if (entry.level === 'error') setErrors(prev => [...prev, entry]);\n * });\n */\nexport function useSocketStream<T>(event: string, callback?: (data: T) => void): T[] {\n  const socket = useSharedWebSocket();\n  const [items, setItems] = useState<T[]>([]);\n\n  const onEvent = useEffectEvent((data: T) => {\n    if (callback) {\n      callback(data);\n    } else {\n      setItems((prev) => [...prev, data]);\n    }\n  });\n\n  useEffect(() => {\n    if (!callback) setItems([]);\n    const unsub = socket.on(event, onEvent);\n    return unsub;\n  }, [socket, event]);\n\n  return callback ? [] : items;\n}\n\n/**\n * Two-way state sync across browser tabs.\n * - Without callback: returns [value, setter] (like useState but synced).\n * - With callback: calls your handler when any tab updates this key.\n *\n * @example\n * // Default — reactive synced state\n * const [cart, setCart] = useSocketSync<Cart>('cart', { items: [] });\n *\n * @example\n * // Custom callback — side effects on sync\n * const [cart, setCart] = useSocketSync<Cart>('cart', { items: [] }, (cart) => {\n *   document.title = `Cart (${cart.items.length})`;\n *   analytics.track('cart_updated', { count: cart.items.length });\n * });\n */\nexport function useSocketSync<T>(\n  key: string,\n  initialValue: T,\n  callback?: (value: T) => void,\n): [T, (value: T) => void] {\n  const socket = useSharedWebSocket();\n  const [value, setValue] = useState<T>(() => {\n    return socket.getSync<T>(key) ?? initialValue;\n  });\n\n  const onSync = useEffectEvent((synced: T) => {\n    setValue(synced);\n    callback?.(synced);\n  });\n\n  useEffect(() => {\n    const unsub = socket.onSync<T>(key, onSync);\n    return unsub;\n  }, [socket, key]);\n\n  const setAndSync = useEffectEvent((newValue: T) => {\n    setValue(newValue);\n    socket.sync(key, newValue);\n  });\n\n  return [value, setAndSync];\n}\n\n/**\n * Subscribe to a WebSocket event with just a callback — no state, no return value.\n * Fire-and-forget: side effects, logging, analytics, sounds, browser notifications.\n * Stable ref via useEffectEvent — callback always sees latest closure values.\n *\n * @example\n * useSocketCallback<Order>('order.created', (order) => {\n *   playSound('new-order');\n *   analytics.track('order_received', { id: order.id });\n * });\n *\n * @example\n * // Browser notification only from leader tab\n * useSocketCallback<Notification>('notification', (notif) => {\n *   if (ws.tabRole === 'leader' && document.hidden) {\n *     new Notification(notif.title, { body: notif.body });\n *   }\n * });\n */\nexport function useSocketCallback<T>(event: string, callback: (data: T) => void): void {\n  const socket = useSharedWebSocket();\n\n  const handler = useEffectEvent((data: T) => {\n    callback(data);\n  });\n\n  useEffect(() => {\n    const unsub = socket.on(event, handler);\n    return unsub;\n  }, [socket, event]);\n}\n\n/**\n * Reactive connection status.\n * Uses useEffectEvent to avoid re-creating interval on state change.\n *\n * @example\n * const { connected, tabRole } = useSocketStatus();\n */\nexport function useSocketStatus(): {\n  connected: boolean;\n  tabRole: TabRole;\n} {\n  const socket = useSharedWebSocket();\n  const [connected, setConnected] = useState(socket.connected);\n  const [tabRole, setTabRole] = useState<TabRole>(socket.tabRole);\n\n  const tick = useEffectEvent(() => {\n    setConnected(socket.connected);\n    setTabRole(socket.tabRole);\n  });\n\n  useEffect(() => {\n    const interval = setInterval(tick, 1000);\n    return () => clearInterval(interval);\n  }, [socket]);\n\n  return { connected, tabRole };\n}\n"],"mappings":"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","names":[]}

package/dist/vue.cjs

@@ -1,4 +1,4 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
 
 var _chunkSMH3X34Ncjs = require('./chunk-SMH3X34N.cjs');
 
@@ -32,29 +32,38 @@ function useSharedWebSocket() {
   }
   return socket;
 }
-function useSocketEvent(event) {
+function useSocketEvent(event, callback) {
   const socket = useSharedWebSocket();
   const value = _vue.ref.call(void 0, void 0);
   const unsub = socket.on(event, (data) => {
-    value.value = data;
+    if (callback) {
+      callback(data);
+    } else {
+      value.value = data;
+    }
   });
   _vue.onUnmounted.call(void 0, unsub);
   return _vue.readonly.call(void 0, value);
 }
-function useSocketStream(event) {
+function useSocketStream(event, callback) {
   const socket = useSharedWebSocket();
   const items = _vue.ref.call(void 0, []);
   const unsub = socket.on(event, (data) => {
-    items.value = [...items.value, data];
+    if (callback) {
+      callback(data);
+    } else {
+      items.value = [...items.value, data];
+    }
   });
   _vue.onUnmounted.call(void 0, unsub);
   return _vue.readonly.call(void 0, items);
 }
-function useSocketSync(key, initialValue) {
+function useSocketSync(key, initialValue, callback) {
   const socket = useSharedWebSocket();
   const value = _vue.ref.call(void 0, _nullishCoalesce(socket.getSync(key), () => ( initialValue)));
   const unsub = socket.onSync(key, (v) => {
     value.value = v;
+    _optionalChain([callback, 'optionalCall', _ => _(v)]);
   });
   _vue.watch.call(void 0, 
     value,
@@ -66,12 +75,18 @@ function useSocketSync(key, initialValue) {
   _vue.onUnmounted.call(void 0, unsub);
   return value;
 }
+function useSocketCallback(event, callback) {
+  const socket = useSharedWebSocket();
+  const unsub = socket.on(event, (data) => {
+    callback(data);
+  });
+  _vue.onUnmounted.call(void 0, unsub);
+}
 function useSocketStatus() {
   const socket = useSharedWebSocket();
   const connected = _vue.ref.call(void 0, socket.connected);
   const tabRole = _vue.ref.call(void 0, socket.tabRole);
-  let timer;
-  timer = setInterval(() => {
+  const timer = setInterval(() => {
     connected.value = socket.connected;
     tabRole.value = socket.tabRole;
   }, 1e3);
@@ -89,5 +104,6 @@ function useSocketStatus() {
 
 
 
-exports.SharedWebSocketKey = SharedWebSocketKey; exports.createSharedWebSocketPlugin = createSharedWebSocketPlugin; exports.useSharedWebSocket = useSharedWebSocket; exports.useSocketEvent = useSocketEvent; exports.useSocketStatus = useSocketStatus; exports.useSocketStream = useSocketStream; exports.useSocketSync = useSocketSync;
+
+exports.SharedWebSocketKey = SharedWebSocketKey; exports.createSharedWebSocketPlugin = createSharedWebSocketPlugin; exports.useSharedWebSocket = useSharedWebSocket; exports.useSocketCallback = useSocketCallback; exports.useSocketEvent = useSocketEvent; exports.useSocketStatus = useSocketStatus; exports.useSocketStream = useSocketStream; exports.useSocketSync = useSocketSync;
 //# sourceMappingURL=vue.cjs.map

package/dist/vue.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/gwakko/Projects/shared-websocket/dist/vue.cjs","../src/adapters/vue.ts"],"names":[],"mappings":"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","file":"/Users/gwakko/Projects/shared-websocket/dist/vue.cjs","sourcesContent":[null,"import {\n  ref,\n  onUnmounted,\n  inject,\n  readonly,\n  watch,\n  type Ref,\n  type InjectionKey,\n  type App,\n} from 'vue';\nimport { SharedWebSocket } from '../SharedWebSocket';\nimport type { SharedWebSocketOptions, TabRole } from '../types';\n\n// ─── Plugin ──────────────────────────────────────────────\n\nexport const SharedWebSocketKey: InjectionKey<SharedWebSocket> = Symbol('SharedWebSocket');\n\n/**\n * Vue 3 plugin for SharedWebSocket.\n *\n * @example\n * const app = createApp(App);\n * app.use(createSharedWebSocketPlugin('wss://api.example.com/ws'));\n */\nexport function createSharedWebSocketPlugin(url: string, options?: SharedWebSocketOptions) {\n  return {\n    install(app: App) {\n      const socket = new SharedWebSocket(url, options);\n      socket.connect();\n      app.provide(SharedWebSocketKey, socket);\n\n      // Cleanup on app unmount\n      const originalUnmount = app.unmount.bind(app);\n      app.unmount = () => {\n        socket[Symbol.dispose]();\n        originalUnmount();\n      };\n    },\n  };\n}\n\n/**\n * Access the SharedWebSocket instance from provided context.\n *\n * @example\n * const ws = useSharedWebSocket();\n */\nexport function useSharedWebSocket(): SharedWebSocket {\n  const socket = inject(SharedWebSocketKey);\n  if (!socket) {\n    throw new Error('useSharedWebSocket: SharedWebSocket not provided. Did you install the plugin?');\n  }\n  return socket;\n}\n\n// ─── Composables ─────────────────────────────────────────\n\n/**\n * Subscribe to a WebSocket event. Returns reactive ref with latest value.\n *\n * @example\n * const order = useSocketEvent<Order>('order.created');\n */\nexport function useSocketEvent<T>(event: string): Ref<T | undefined> {\n  const socket = useSharedWebSocket();\n  const value = ref<T | undefined>(undefined) as Ref<T | undefined>;\n\n  const unsub = socket.on(event, (data: T) => {\n    value.value = data;\n  });\n\n  onUnmounted(unsub);\n  return readonly(value) as Ref<T | undefined>;\n}\n\n/**\n * Accumulate WebSocket events into reactive array.\n *\n * @example\n * const messages = useSocketStream<ChatMessage>('chat.message');\n */\nexport function useSocketStream<T>(event: string): Ref<T[]> {\n  const socket = useSharedWebSocket();\n  const items = ref<T[]>([]) as Ref<T[]>;\n\n  const unsub = socket.on(event, (data: T) => {\n    items.value = [...items.value, data];\n  });\n\n  onUnmounted(unsub);\n  return readonly(items) as Ref<T[]>;\n}\n\n/**\n * Two-way state sync across browser tabs via reactive ref.\n *\n * @example\n * const cart = useSocketSync<Cart>('cart', { items: [] });\n * cart.value = { items: [1, 2, 3] }; // syncs to all tabs\n */\nexport function useSocketSync<T>(key: string, initialValue: T): Ref<T> {\n  const socket = useSharedWebSocket();\n  const value = ref<T>(socket.getSync<T>(key) ?? initialValue) as Ref<T>;\n\n  const unsub = socket.onSync<T>(key, (v) => {\n    value.value = v;\n  });\n\n  // Watch for local changes → sync to other tabs\n  watch(\n    value,\n    (newVal) => {\n      socket.sync(key, newVal);\n    },\n    { deep: true },\n  );\n\n  onUnmounted(unsub);\n  return value;\n}\n\n/**\n * Reactive connection status.\n *\n * @example\n * const { connected, tabRole } = useSocketStatus();\n */\nexport function useSocketStatus(): {\n  connected: Ref<boolean>;\n  tabRole: Ref<TabRole>;\n} {\n  const socket = useSharedWebSocket();\n  const connected = ref(socket.connected);\n  const tabRole = ref<TabRole>(socket.tabRole);\n\n  let timer: ReturnType<typeof setInterval>;\n\n  timer = setInterval(() => {\n    connected.value = socket.connected;\n    tabRole.value = socket.tabRole;\n  }, 1000);\n\n  onUnmounted(() => clearInterval(timer));\n\n  return {\n    connected: readonly(connected) as Ref<boolean>,\n    tabRole: readonly(tabRole) as Ref<TabRole>,\n  };\n}\n"]}
+{"version":3,"sources":["/Users/gwakko/Projects/shared-websocket/dist/vue.cjs","../src/adapters/vue.ts"],"names":[],"mappings":"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","file":"/Users/gwakko/Projects/shared-websocket/dist/vue.cjs","sourcesContent":[null,"import {\n  ref,\n  onUnmounted,\n  inject,\n  readonly,\n  watch,\n  type Ref,\n  type InjectionKey,\n  type App,\n} from 'vue';\nimport { SharedWebSocket } from '../SharedWebSocket';\nimport type { SharedWebSocketOptions, TabRole } from '../types';\n\n// ─── Plugin ──────────────────────────────────────────────\n\nexport const SharedWebSocketKey: InjectionKey<SharedWebSocket> = Symbol('SharedWebSocket');\n\n/**\n * Vue 3 plugin for SharedWebSocket.\n *\n * @example\n * const app = createApp(App);\n * app.use(createSharedWebSocketPlugin('wss://api.example.com/ws', {\n *   auth: () => localStorage.getItem('token')!,\n *   useWorker: true,\n * }));\n */\nexport function createSharedWebSocketPlugin(url: string, options?: SharedWebSocketOptions) {\n  return {\n    install(app: App) {\n      const socket = new SharedWebSocket(url, options);\n      socket.connect();\n      app.provide(SharedWebSocketKey, socket);\n\n      const originalUnmount = app.unmount.bind(app);\n      app.unmount = () => {\n        socket[Symbol.dispose]();\n        originalUnmount();\n      };\n    },\n  };\n}\n\n/**\n * Access the SharedWebSocket instance from provided context.\n *\n * @example\n * const ws = useSharedWebSocket();\n * ws.send('chat.message', { text: 'Hello' });\n */\nexport function useSharedWebSocket(): SharedWebSocket {\n  const socket = inject(SharedWebSocketKey);\n  if (!socket) {\n    throw new Error('useSharedWebSocket: SharedWebSocket not provided. Did you install the plugin?');\n  }\n  return socket;\n}\n\n// ─── Composables ─────────────────────────────────────────\n\n/**\n * Subscribe to a WebSocket event.\n * - Without callback: returns reactive ref with latest value.\n * - With callback: calls your handler on each event.\n *\n * @example\n * // Reactive state\n * const order = useSocketEvent<Order>('order.created');\n *\n * @example\n * // Custom callback\n * useSocketEvent<Order>('order.created', (order) => {\n *   playSound('new-order');\n *   analytics.track('order_received', order);\n * });\n */\nexport function useSocketEvent<T>(event: string, callback?: (data: T) => void): Ref<T | undefined> {\n  const socket = useSharedWebSocket();\n  const value = ref<T | undefined>(undefined) as Ref<T | undefined>;\n\n  const unsub = socket.on(event, (data: T) => {\n    if (callback) {\n      callback(data);\n    } else {\n      value.value = data;\n    }\n  });\n\n  onUnmounted(unsub);\n  return readonly(value) as Ref<T | undefined>;\n}\n\n/**\n * Accumulate WebSocket events.\n * - Without callback: returns reactive array.\n * - With callback: calls your handler — manage your own state.\n *\n * @example\n * // Default accumulation\n * const messages = useSocketStream<ChatMessage>('chat.message');\n *\n * @example\n * // Custom — keep last 50\n * const messages = ref<ChatMessage[]>([]);\n * useSocketStream<ChatMessage>('chat.message', (msg) => {\n *   messages.value = [msg, ...messages.value].slice(0, 50);\n * });\n *\n * @example\n * // Custom — filter by type\n * const errors = ref<LogEntry[]>([]);\n * useSocketStream<LogEntry>('log.entry', (entry) => {\n *   if (entry.level === 'error') errors.value = [...errors.value, entry];\n * });\n */\nexport function useSocketStream<T>(event: string, callback?: (data: T) => void): Ref<T[]> {\n  const socket = useSharedWebSocket();\n  const items = ref<T[]>([]) as Ref<T[]>;\n\n  const unsub = socket.on(event, (data: T) => {\n    if (callback) {\n      callback(data);\n    } else {\n      items.value = [...items.value, data];\n    }\n  });\n\n  onUnmounted(unsub);\n  return readonly(items) as Ref<T[]>;\n}\n\n/**\n * Two-way state sync across browser tabs.\n * - Without callback: reactive ref synced across tabs.\n * - With callback: called when any tab updates this key — side effects.\n *\n * @example\n * // Reactive two-way sync\n * const cart = useSocketSync<Cart>('cart', { items: [] });\n * cart.value = { items: [1, 2, 3] }; // syncs to all tabs\n *\n * @example\n * // With side effect callback\n * const cart = useSocketSync<Cart>('cart', { items: [] }, (cart) => {\n *   document.title = `Cart (${cart.items.length})`;\n *   analytics.track('cart_updated');\n * });\n */\nexport function useSocketSync<T>(key: string, initialValue: T, callback?: (value: T) => void): Ref<T> {\n  const socket = useSharedWebSocket();\n  const value = ref<T>(socket.getSync<T>(key) ?? initialValue) as Ref<T>;\n\n  const unsub = socket.onSync<T>(key, (v) => {\n    value.value = v;\n    callback?.(v);\n  });\n\n  watch(\n    value,\n    (newVal) => {\n      socket.sync(key, newVal);\n    },\n    { deep: true },\n  );\n\n  onUnmounted(unsub);\n  return value;\n}\n\n/**\n * Fire-and-forget event handler — no state, no ref.\n *\n * @example\n * useSocketCallback<Notification>('notification', (n) => {\n *   showToast(n.title);\n * });\n */\nexport function useSocketCallback<T>(event: string, callback: (data: T) => void): void {\n  const socket = useSharedWebSocket();\n\n  const unsub = socket.on(event, (data: T) => {\n    callback(data);\n  });\n\n  onUnmounted(unsub);\n}\n\n/**\n * Reactive connection status.\n *\n * @example\n * const { connected, tabRole } = useSocketStatus();\n */\nexport function useSocketStatus(): {\n  connected: Ref<boolean>;\n  tabRole: Ref<TabRole>;\n} {\n  const socket = useSharedWebSocket();\n  const connected = ref(socket.connected);\n  const tabRole = ref<TabRole>(socket.tabRole);\n\n  const timer = setInterval(() => {\n    connected.value = socket.connected;\n    tabRole.value = socket.tabRole;\n  }, 1000);\n\n  onUnmounted(() => clearInterval(timer));\n\n  return {\n    connected: readonly(connected) as Ref<boolean>,\n    tabRole: readonly(tabRole) as Ref<TabRole>,\n  };\n}\n"]}

package/dist/vue.js

@@ -32,29 +32,38 @@ function useSharedWebSocket() {
   }
   return socket;
 }
-function useSocketEvent(event) {
+function useSocketEvent(event, callback) {
   const socket = useSharedWebSocket();
   const value = ref(void 0);
   const unsub = socket.on(event, (data) => {
-    value.value = data;
+    if (callback) {
+      callback(data);
+    } else {
+      value.value = data;
+    }
   });
   onUnmounted(unsub);
   return readonly(value);
 }
-function useSocketStream(event) {
+function useSocketStream(event, callback) {
   const socket = useSharedWebSocket();
   const items = ref([]);
   const unsub = socket.on(event, (data) => {
-    items.value = [...items.value, data];
+    if (callback) {
+      callback(data);
+    } else {
+      items.value = [...items.value, data];
+    }
   });
   onUnmounted(unsub);
   return readonly(items);
 }
-function useSocketSync(key, initialValue) {
+function useSocketSync(key, initialValue, callback) {
   const socket = useSharedWebSocket();
   const value = ref(socket.getSync(key) ?? initialValue);
   const unsub = socket.onSync(key, (v) => {
     value.value = v;
+    callback?.(v);
   });
   watch(
     value,
@@ -66,12 +75,18 @@ function useSocketSync(key, initialValue) {
   onUnmounted(unsub);
   return value;
 }
+function useSocketCallback(event, callback) {
+  const socket = useSharedWebSocket();
+  const unsub = socket.on(event, (data) => {
+    callback(data);
+  });
+  onUnmounted(unsub);
+}
 function useSocketStatus() {
   const socket = useSharedWebSocket();
   const connected = ref(socket.connected);
   const tabRole = ref(socket.tabRole);
-  let timer;
-  timer = setInterval(() => {
+  const timer = setInterval(() => {
     connected.value = socket.connected;
     tabRole.value = socket.tabRole;
   }, 1e3);
@@ -85,6 +100,7 @@ export {
   SharedWebSocketKey,
   createSharedWebSocketPlugin,
   useSharedWebSocket,
+  useSocketCallback,
   useSocketEvent,
   useSocketStatus,
   useSocketStream,

package/dist/vue.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/adapters/vue.ts"],"sourcesContent":["import {\n  ref,\n  onUnmounted,\n  inject,\n  readonly,\n  watch,\n  type Ref,\n  type InjectionKey,\n  type App,\n} from 'vue';\nimport { SharedWebSocket } from '../SharedWebSocket';\nimport type { SharedWebSocketOptions, TabRole } from '../types';\n\n// ─── Plugin ──────────────────────────────────────────────\n\nexport const SharedWebSocketKey: InjectionKey<SharedWebSocket> = Symbol('SharedWebSocket');\n\n/**\n * Vue 3 plugin for SharedWebSocket.\n *\n * @example\n * const app = createApp(App);\n * app.use(createSharedWebSocketPlugin('wss://api.example.com/ws'));\n */\nexport function createSharedWebSocketPlugin(url: string, options?: SharedWebSocketOptions) {\n  return {\n    install(app: App) {\n      const socket = new SharedWebSocket(url, options);\n      socket.connect();\n      app.provide(SharedWebSocketKey, socket);\n\n      // Cleanup on app unmount\n      const originalUnmount = app.unmount.bind(app);\n      app.unmount = () => {\n        socket[Symbol.dispose]();\n        originalUnmount();\n      };\n    },\n  };\n}\n\n/**\n * Access the SharedWebSocket instance from provided context.\n *\n * @example\n * const ws = useSharedWebSocket();\n */\nexport function useSharedWebSocket(): SharedWebSocket {\n  const socket = inject(SharedWebSocketKey);\n  if (!socket) {\n    throw new Error('useSharedWebSocket: SharedWebSocket not provided. Did you install the plugin?');\n  }\n  return socket;\n}\n\n// ─── Composables ─────────────────────────────────────────\n\n/**\n * Subscribe to a WebSocket event. Returns reactive ref with latest value.\n *\n * @example\n * const order = useSocketEvent<Order>('order.created');\n */\nexport function useSocketEvent<T>(event: string): Ref<T | undefined> {\n  const socket = useSharedWebSocket();\n  const value = ref<T | undefined>(undefined) as Ref<T | undefined>;\n\n  const unsub = socket.on(event, (data: T) => {\n    value.value = data;\n  });\n\n  onUnmounted(unsub);\n  return readonly(value) as Ref<T | undefined>;\n}\n\n/**\n * Accumulate WebSocket events into reactive array.\n *\n * @example\n * const messages = useSocketStream<ChatMessage>('chat.message');\n */\nexport function useSocketStream<T>(event: string): Ref<T[]> {\n  const socket = useSharedWebSocket();\n  const items = ref<T[]>([]) as Ref<T[]>;\n\n  const unsub = socket.on(event, (data: T) => {\n    items.value = [...items.value, data];\n  });\n\n  onUnmounted(unsub);\n  return readonly(items) as Ref<T[]>;\n}\n\n/**\n * Two-way state sync across browser tabs via reactive ref.\n *\n * @example\n * const cart = useSocketSync<Cart>('cart', { items: [] });\n * cart.value = { items: [1, 2, 3] }; // syncs to all tabs\n */\nexport function useSocketSync<T>(key: string, initialValue: T): Ref<T> {\n  const socket = useSharedWebSocket();\n  const value = ref<T>(socket.getSync<T>(key) ?? initialValue) as Ref<T>;\n\n  const unsub = socket.onSync<T>(key, (v) => {\n    value.value = v;\n  });\n\n  // Watch for local changes → sync to other tabs\n  watch(\n    value,\n    (newVal) => {\n      socket.sync(key, newVal);\n    },\n    { deep: true },\n  );\n\n  onUnmounted(unsub);\n  return value;\n}\n\n/**\n * Reactive connection status.\n *\n * @example\n * const { connected, tabRole } = useSocketStatus();\n */\nexport function useSocketStatus(): {\n  connected: Ref<boolean>;\n  tabRole: Ref<TabRole>;\n} {\n  const socket = useSharedWebSocket();\n  const connected = ref(socket.connected);\n  const tabRole = ref<TabRole>(socket.tabRole);\n\n  let timer: ReturnType<typeof setInterval>;\n\n  timer = setInterval(() => {\n    connected.value = socket.connected;\n    tabRole.value = socket.tabRole;\n  }, 1000);\n\n  onUnmounted(() => clearInterval(timer));\n\n  return {\n    connected: readonly(connected) as Ref<boolean>,\n    tabRole: readonly(tabRole) as Ref<TabRole>,\n  };\n}\n"],"mappings":";;;;;AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAIK;AAMA,IAAM,qBAAoD,uBAAO,iBAAiB;AASlF,SAAS,4BAA4B,KAAa,SAAkC;AACzF,SAAO;AAAA,IACL,QAAQ,KAAU;AAChB,YAAM,SAAS,IAAI,gBAAgB,KAAK,OAAO;AAC/C,aAAO,QAAQ;AACf,UAAI,QAAQ,oBAAoB,MAAM;AAGtC,YAAM,kBAAkB,IAAI,QAAQ,KAAK,GAAG;AAC5C,UAAI,UAAU,MAAM;AAClB,eAAO,OAAO,OAAO,EAAE;AACvB,wBAAgB;AAAA,MAClB;AAAA,IACF;AAAA,EACF;AACF;AAQO,SAAS,qBAAsC;AACpD,QAAM,SAAS,OAAO,kBAAkB;AACxC,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI,MAAM,+EAA+E;AAAA,EACjG;AACA,SAAO;AACT;AAUO,SAAS,eAAkB,OAAmC;AACnE,QAAM,SAAS,mBAAmB;AAClC,QAAM,QAAQ,IAAmB,MAAS;AAE1C,QAAM,QAAQ,OAAO,GAAG,OAAO,CAAC,SAAY;AAC1C,UAAM,QAAQ;AAAA,EAChB,CAAC;AAED,cAAY,KAAK;AACjB,SAAO,SAAS,KAAK;AACvB;AAQO,SAAS,gBAAmB,OAAyB;AAC1D,QAAM,SAAS,mBAAmB;AAClC,QAAM,QAAQ,IAAS,CAAC,CAAC;AAEzB,QAAM,QAAQ,OAAO,GAAG,OAAO,CAAC,SAAY;AAC1C,UAAM,QAAQ,CAAC,GAAG,MAAM,OAAO,IAAI;AAAA,EACrC,CAAC;AAED,cAAY,KAAK;AACjB,SAAO,SAAS,KAAK;AACvB;AASO,SAAS,cAAiB,KAAa,cAAyB;AACrE,QAAM,SAAS,mBAAmB;AAClC,QAAM,QAAQ,IAAO,OAAO,QAAW,GAAG,KAAK,YAAY;AAE3D,QAAM,QAAQ,OAAO,OAAU,KAAK,CAAC,MAAM;AACzC,UAAM,QAAQ;AAAA,EAChB,CAAC;AAGD;AAAA,IACE;AAAA,IACA,CAAC,WAAW;AACV,aAAO,KAAK,KAAK,MAAM;AAAA,IACzB;AAAA,IACA,EAAE,MAAM,KAAK;AAAA,EACf;AAEA,cAAY,KAAK;AACjB,SAAO;AACT;AAQO,SAAS,kBAGd;AACA,QAAM,SAAS,mBAAmB;AAClC,QAAM,YAAY,IAAI,OAAO,SAAS;AACtC,QAAM,UAAU,IAAa,OAAO,OAAO;AAE3C,MAAI;AAEJ,UAAQ,YAAY,MAAM;AACxB,cAAU,QAAQ,OAAO;AACzB,YAAQ,QAAQ,OAAO;AAAA,EACzB,GAAG,GAAI;AAEP,cAAY,MAAM,cAAc,KAAK,CAAC;AAEtC,SAAO;AAAA,IACL,WAAW,SAAS,SAAS;AAAA,IAC7B,SAAS,SAAS,OAAO;AAAA,EAC3B;AACF;","names":[]}
+{"version":3,"sources":["../src/adapters/vue.ts"],"sourcesContent":["import {\n  ref,\n  onUnmounted,\n  inject,\n  readonly,\n  watch,\n  type Ref,\n  type InjectionKey,\n  type App,\n} from 'vue';\nimport { SharedWebSocket } from '../SharedWebSocket';\nimport type { SharedWebSocketOptions, TabRole } from '../types';\n\n// ─── Plugin ──────────────────────────────────────────────\n\nexport const SharedWebSocketKey: InjectionKey<SharedWebSocket> = Symbol('SharedWebSocket');\n\n/**\n * Vue 3 plugin for SharedWebSocket.\n *\n * @example\n * const app = createApp(App);\n * app.use(createSharedWebSocketPlugin('wss://api.example.com/ws', {\n *   auth: () => localStorage.getItem('token')!,\n *   useWorker: true,\n * }));\n */\nexport function createSharedWebSocketPlugin(url: string, options?: SharedWebSocketOptions) {\n  return {\n    install(app: App) {\n      const socket = new SharedWebSocket(url, options);\n      socket.connect();\n      app.provide(SharedWebSocketKey, socket);\n\n      const originalUnmount = app.unmount.bind(app);\n      app.unmount = () => {\n        socket[Symbol.dispose]();\n        originalUnmount();\n      };\n    },\n  };\n}\n\n/**\n * Access the SharedWebSocket instance from provided context.\n *\n * @example\n * const ws = useSharedWebSocket();\n * ws.send('chat.message', { text: 'Hello' });\n */\nexport function useSharedWebSocket(): SharedWebSocket {\n  const socket = inject(SharedWebSocketKey);\n  if (!socket) {\n    throw new Error('useSharedWebSocket: SharedWebSocket not provided. Did you install the plugin?');\n  }\n  return socket;\n}\n\n// ─── Composables ─────────────────────────────────────────\n\n/**\n * Subscribe to a WebSocket event.\n * - Without callback: returns reactive ref with latest value.\n * - With callback: calls your handler on each event.\n *\n * @example\n * // Reactive state\n * const order = useSocketEvent<Order>('order.created');\n *\n * @example\n * // Custom callback\n * useSocketEvent<Order>('order.created', (order) => {\n *   playSound('new-order');\n *   analytics.track('order_received', order);\n * });\n */\nexport function useSocketEvent<T>(event: string, callback?: (data: T) => void): Ref<T | undefined> {\n  const socket = useSharedWebSocket();\n  const value = ref<T | undefined>(undefined) as Ref<T | undefined>;\n\n  const unsub = socket.on(event, (data: T) => {\n    if (callback) {\n      callback(data);\n    } else {\n      value.value = data;\n    }\n  });\n\n  onUnmounted(unsub);\n  return readonly(value) as Ref<T | undefined>;\n}\n\n/**\n * Accumulate WebSocket events.\n * - Without callback: returns reactive array.\n * - With callback: calls your handler — manage your own state.\n *\n * @example\n * // Default accumulation\n * const messages = useSocketStream<ChatMessage>('chat.message');\n *\n * @example\n * // Custom — keep last 50\n * const messages = ref<ChatMessage[]>([]);\n * useSocketStream<ChatMessage>('chat.message', (msg) => {\n *   messages.value = [msg, ...messages.value].slice(0, 50);\n * });\n *\n * @example\n * // Custom — filter by type\n * const errors = ref<LogEntry[]>([]);\n * useSocketStream<LogEntry>('log.entry', (entry) => {\n *   if (entry.level === 'error') errors.value = [...errors.value, entry];\n * });\n */\nexport function useSocketStream<T>(event: string, callback?: (data: T) => void): Ref<T[]> {\n  const socket = useSharedWebSocket();\n  const items = ref<T[]>([]) as Ref<T[]>;\n\n  const unsub = socket.on(event, (data: T) => {\n    if (callback) {\n      callback(data);\n    } else {\n      items.value = [...items.value, data];\n    }\n  });\n\n  onUnmounted(unsub);\n  return readonly(items) as Ref<T[]>;\n}\n\n/**\n * Two-way state sync across browser tabs.\n * - Without callback: reactive ref synced across tabs.\n * - With callback: called when any tab updates this key — side effects.\n *\n * @example\n * // Reactive two-way sync\n * const cart = useSocketSync<Cart>('cart', { items: [] });\n * cart.value = { items: [1, 2, 3] }; // syncs to all tabs\n *\n * @example\n * // With side effect callback\n * const cart = useSocketSync<Cart>('cart', { items: [] }, (cart) => {\n *   document.title = `Cart (${cart.items.length})`;\n *   analytics.track('cart_updated');\n * });\n */\nexport function useSocketSync<T>(key: string, initialValue: T, callback?: (value: T) => void): Ref<T> {\n  const socket = useSharedWebSocket();\n  const value = ref<T>(socket.getSync<T>(key) ?? initialValue) as Ref<T>;\n\n  const unsub = socket.onSync<T>(key, (v) => {\n    value.value = v;\n    callback?.(v);\n  });\n\n  watch(\n    value,\n    (newVal) => {\n      socket.sync(key, newVal);\n    },\n    { deep: true },\n  );\n\n  onUnmounted(unsub);\n  return value;\n}\n\n/**\n * Fire-and-forget event handler — no state, no ref.\n *\n * @example\n * useSocketCallback<Notification>('notification', (n) => {\n *   showToast(n.title);\n * });\n */\nexport function useSocketCallback<T>(event: string, callback: (data: T) => void): void {\n  const socket = useSharedWebSocket();\n\n  const unsub = socket.on(event, (data: T) => {\n    callback(data);\n  });\n\n  onUnmounted(unsub);\n}\n\n/**\n * Reactive connection status.\n *\n * @example\n * const { connected, tabRole } = useSocketStatus();\n */\nexport function useSocketStatus(): {\n  connected: Ref<boolean>;\n  tabRole: Ref<TabRole>;\n} {\n  const socket = useSharedWebSocket();\n  const connected = ref(socket.connected);\n  const tabRole = ref<TabRole>(socket.tabRole);\n\n  const timer = setInterval(() => {\n    connected.value = socket.connected;\n    tabRole.value = socket.tabRole;\n  }, 1000);\n\n  onUnmounted(() => clearInterval(timer));\n\n  return {\n    connected: readonly(connected) as Ref<boolean>,\n    tabRole: readonly(tabRole) as Ref<TabRole>,\n  };\n}\n"],"mappings":";;;;;AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAIK;AAMA,IAAM,qBAAoD,uBAAO,iBAAiB;AAYlF,SAAS,4BAA4B,KAAa,SAAkC;AACzF,SAAO;AAAA,IACL,QAAQ,KAAU;AAChB,YAAM,SAAS,IAAI,gBAAgB,KAAK,OAAO;AAC/C,aAAO,QAAQ;AACf,UAAI,QAAQ,oBAAoB,MAAM;AAEtC,YAAM,kBAAkB,IAAI,QAAQ,KAAK,GAAG;AAC5C,UAAI,UAAU,MAAM;AAClB,eAAO,OAAO,OAAO,EAAE;AACvB,wBAAgB;AAAA,MAClB;AAAA,IACF;AAAA,EACF;AACF;AASO,SAAS,qBAAsC;AACpD,QAAM,SAAS,OAAO,kBAAkB;AACxC,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI,MAAM,+EAA+E;AAAA,EACjG;AACA,SAAO;AACT;AAoBO,SAAS,eAAkB,OAAe,UAAkD;AACjG,QAAM,SAAS,mBAAmB;AAClC,QAAM,QAAQ,IAAmB,MAAS;AAE1C,QAAM,QAAQ,OAAO,GAAG,OAAO,CAAC,SAAY;AAC1C,QAAI,UAAU;AACZ,eAAS,IAAI;AAAA,IACf,OAAO;AACL,YAAM,QAAQ;AAAA,IAChB;AAAA,EACF,CAAC;AAED,cAAY,KAAK;AACjB,SAAO,SAAS,KAAK;AACvB;AAyBO,SAAS,gBAAmB,OAAe,UAAwC;AACxF,QAAM,SAAS,mBAAmB;AAClC,QAAM,QAAQ,IAAS,CAAC,CAAC;AAEzB,QAAM,QAAQ,OAAO,GAAG,OAAO,CAAC,SAAY;AAC1C,QAAI,UAAU;AACZ,eAAS,IAAI;AAAA,IACf,OAAO;AACL,YAAM,QAAQ,CAAC,GAAG,MAAM,OAAO,IAAI;AAAA,IACrC;AAAA,EACF,CAAC;AAED,cAAY,KAAK;AACjB,SAAO,SAAS,KAAK;AACvB;AAmBO,SAAS,cAAiB,KAAa,cAAiB,UAAuC;AACpG,QAAM,SAAS,mBAAmB;AAClC,QAAM,QAAQ,IAAO,OAAO,QAAW,GAAG,KAAK,YAAY;AAE3D,QAAM,QAAQ,OAAO,OAAU,KAAK,CAAC,MAAM;AACzC,UAAM,QAAQ;AACd,eAAW,CAAC;AAAA,EACd,CAAC;AAED;AAAA,IACE;AAAA,IACA,CAAC,WAAW;AACV,aAAO,KAAK,KAAK,MAAM;AAAA,IACzB;AAAA,IACA,EAAE,MAAM,KAAK;AAAA,EACf;AAEA,cAAY,KAAK;AACjB,SAAO;AACT;AAUO,SAAS,kBAAqB,OAAe,UAAmC;AACrF,QAAM,SAAS,mBAAmB;AAElC,QAAM,QAAQ,OAAO,GAAG,OAAO,CAAC,SAAY;AAC1C,aAAS,IAAI;AAAA,EACf,CAAC;AAED,cAAY,KAAK;AACnB;AAQO,SAAS,kBAGd;AACA,QAAM,SAAS,mBAAmB;AAClC,QAAM,YAAY,IAAI,OAAO,SAAS;AACtC,QAAM,UAAU,IAAa,OAAO,OAAO;AAE3C,QAAM,QAAQ,YAAY,MAAM;AAC9B,cAAU,QAAQ,OAAO;AACzB,YAAQ,QAAQ,OAAO;AAAA,EACzB,GAAG,GAAI;AAEP,cAAY,MAAM,cAAc,KAAK,CAAC;AAEtC,SAAO;AAAA,IACL,WAAW,SAAS,SAAS;AAAA,IAC7B,SAAS,SAAS,OAAO;AAAA,EAC3B;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gwakko/shared-websocket",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Share ONE WebSocket connection across browser tabs — leader election, BroadcastChannel sync, optional Web Worker",
   "type": "module",
   "main": "./dist/index.cjs",

package/src/adapters/react.ts

@@ -80,18 +80,38 @@ export function useSharedWebSocket(): SharedWebSocket {
 // ─── Hooks ───────────────────────────────────────────────
 
 /**
- * Subscribe to a WebSocket event. Returns the latest received value.
- * Uses useEffectEvent for a stable callback ref — no stale closures.
+ * Subscribe to a WebSocket event.
+ * - Without callback: returns the latest received value (reactive state).
+ * - With callback: calls your handler on each event (stable ref via useEffectEvent).
  *
  * @example
+ * // Reactive state — returns latest value
  * const order = useSocketEvent<Order>('order.created');
+ *
+ * @example
+ * // Custom callback — full control, no state
+ * useSocketEvent<Order>('order.created', (order) => {
+ *   playSound('new-order');
+ *   analytics.track('order_received', order);
+ * });
+ *
+ * @example
+ * // Custom callback with transform — store in your own state
+ * const [orders, setOrders] = useState<Order[]>([]);
+ * useSocketEvent<Order>('order.created', (order) => {
+ *   setOrders(prev => [order, ...prev].slice(0, 50)); // keep last 50
+ * });
  */
-export function useSocketEvent<T>(event: string): T | undefined {
+export function useSocketEvent<T>(event: string, callback?: (data: T) => void): T | undefined {
   const socket = useSharedWebSocket();
   const [value, setValue] = useState<T | undefined>(undefined);
 
   const onEvent = useEffectEvent((data: T) => {
-    setValue(data);
+    if (callback) {
+      callback(data);
+    } else {
+      setValue(data);
+    }
   });
 
   useEffect(() => {
@@ -99,44 +119,73 @@ export function useSocketEvent<T>(event: string): T | undefined {
     return unsub;
   }, [socket, event]);
 
-  return value;
+  return callback ? undefined : value;
 }
 
 /**
  * Accumulate WebSocket events into an array.
- * Uses useEffectEvent — handler always sees latest state without re-subscribing.
+ * - Without callback: returns accumulated array (reactive state).
+ * - With callback: calls your handler on each event, you manage your own state.
  *
  * @example
+ * // Default — accumulates all events
  * const messages = useSocketStream<ChatMessage>('chat.message');
+ *
+ * @example
+ * // Custom callback — keep only last 50, transform, filter, etc.
+ * const [messages, setMessages] = useState<ChatMessage[]>([]);
+ * useSocketStream<ChatMessage>('chat.message', (msg) => {
+ *   setMessages(prev => [msg, ...prev].slice(0, 50));
+ * });
+ *
+ * @example
+ * // Custom callback — filter by type
+ * const [errors, setErrors] = useState<LogEntry[]>([]);
+ * useSocketStream<LogEntry>('log.entry', (entry) => {
+ *   if (entry.level === 'error') setErrors(prev => [...prev, entry]);
+ * });
  */
-export function useSocketStream<T>(event: string): T[] {
+export function useSocketStream<T>(event: string, callback?: (data: T) => void): T[] {
   const socket = useSharedWebSocket();
   const [items, setItems] = useState<T[]>([]);
 
   const onEvent = useEffectEvent((data: T) => {
-    setItems((prev) => [...prev, data]);
+    if (callback) {
+      callback(data);
+    } else {
+      setItems((prev) => [...prev, data]);
+    }
   });
 
   useEffect(() => {
-    setItems([]);
+    if (!callback) setItems([]);
     const unsub = socket.on(event, onEvent);
     return unsub;
   }, [socket, event]);
 
-  return items;
+  return callback ? [] : items;
 }
 
 /**
  * Two-way state sync across browser tabs.
- * Uses useEffectEvent for stable sync callback.
+ * - Without callback: returns [value, setter] (like useState but synced).
+ * - With callback: calls your handler when any tab updates this key.
  *
  * @example
+ * // Default — reactive synced state
  * const [cart, setCart] = useSocketSync<Cart>('cart', { items: [] });
- * // setCart in one tab → updates all tabs instantly
+ *
+ * @example
+ * // Custom callback — side effects on sync
+ * const [cart, setCart] = useSocketSync<Cart>('cart', { items: [] }, (cart) => {
+ *   document.title = `Cart (${cart.items.length})`;
+ *   analytics.track('cart_updated', { count: cart.items.length });
+ * });
  */
 export function useSocketSync<T>(
   key: string,
   initialValue: T,
+  callback?: (value: T) => void,
 ): [T, (value: T) => void] {
   const socket = useSharedWebSocket();
   const [value, setValue] = useState<T>(() => {
@@ -145,6 +194,7 @@ export function useSocketSync<T>(
 
   const onSync = useEffectEvent((synced: T) => {
     setValue(synced);
+    callback?.(synced);
   });
 
   useEffect(() => {
@@ -160,6 +210,38 @@ export function useSocketSync<T>(
   return [value, setAndSync];
 }
 
+/**
+ * Subscribe to a WebSocket event with just a callback — no state, no return value.
+ * Fire-and-forget: side effects, logging, analytics, sounds, browser notifications.
+ * Stable ref via useEffectEvent — callback always sees latest closure values.
+ *
+ * @example
+ * useSocketCallback<Order>('order.created', (order) => {
+ *   playSound('new-order');
+ *   analytics.track('order_received', { id: order.id });
+ * });
+ *
+ * @example
+ * // Browser notification only from leader tab
+ * useSocketCallback<Notification>('notification', (notif) => {
+ *   if (ws.tabRole === 'leader' && document.hidden) {
+ *     new Notification(notif.title, { body: notif.body });
+ *   }
+ * });
+ */
+export function useSocketCallback<T>(event: string, callback: (data: T) => void): void {
+  const socket = useSharedWebSocket();
+
+  const handler = useEffectEvent((data: T) => {
+    callback(data);
+  });
+
+  useEffect(() => {
+    const unsub = socket.on(event, handler);
+    return unsub;
+  }, [socket, event]);
+}
+
 /**
  * Reactive connection status.
  * Uses useEffectEvent to avoid re-creating interval on state change.

package/src/adapters/vue.ts

@@ -20,7 +20,10 @@ export const SharedWebSocketKey: InjectionKey<SharedWebSocket> = Symbol('SharedW
  *
  * @example
  * const app = createApp(App);
- * app.use(createSharedWebSocketPlugin('wss://api.example.com/ws'));
+ * app.use(createSharedWebSocketPlugin('wss://api.example.com/ws', {
+ *   auth: () => localStorage.getItem('token')!,
+ *   useWorker: true,
+ * }));
  */
 export function createSharedWebSocketPlugin(url: string, options?: SharedWebSocketOptions) {
   return {
@@ -29,7 +32,6 @@ export function createSharedWebSocketPlugin(url: string, options?: SharedWebSock
       socket.connect();
       app.provide(SharedWebSocketKey, socket);
 
-      // Cleanup on app unmount
       const originalUnmount = app.unmount.bind(app);
       app.unmount = () => {
         socket[Symbol.dispose]();
@@ -44,6 +46,7 @@ export function createSharedWebSocketPlugin(url: string, options?: SharedWebSock
  *
  * @example
  * const ws = useSharedWebSocket();
+ * ws.send('chat.message', { text: 'Hello' });
  */
 export function useSharedWebSocket(): SharedWebSocket {
   const socket = inject(SharedWebSocketKey);
@@ -56,17 +59,31 @@ export function useSharedWebSocket(): SharedWebSocket {
 // ─── Composables ─────────────────────────────────────────
 
 /**
- * Subscribe to a WebSocket event. Returns reactive ref with latest value.
+ * Subscribe to a WebSocket event.
+ * - Without callback: returns reactive ref with latest value.
+ * - With callback: calls your handler on each event.
  *
  * @example
+ * // Reactive state
  * const order = useSocketEvent<Order>('order.created');
+ *
+ * @example
+ * // Custom callback
+ * useSocketEvent<Order>('order.created', (order) => {
+ *   playSound('new-order');
+ *   analytics.track('order_received', order);
+ * });
  */
-export function useSocketEvent<T>(event: string): Ref<T | undefined> {
+export function useSocketEvent<T>(event: string, callback?: (data: T) => void): 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;
+    if (callback) {
+      callback(data);
+    } else {
+      value.value = data;
+    }
   });
 
   onUnmounted(unsub);
@@ -74,17 +91,38 @@ export function useSocketEvent<T>(event: string): Ref<T | undefined> {
 }
 
 /**
- * Accumulate WebSocket events into reactive array.
+ * Accumulate WebSocket events.
+ * - Without callback: returns reactive array.
+ * - With callback: calls your handler — manage your own state.
  *
  * @example
+ * // Default accumulation
  * const messages = useSocketStream<ChatMessage>('chat.message');
+ *
+ * @example
+ * // Custom — keep last 50
+ * const messages = ref<ChatMessage[]>([]);
+ * useSocketStream<ChatMessage>('chat.message', (msg) => {
+ *   messages.value = [msg, ...messages.value].slice(0, 50);
+ * });
+ *
+ * @example
+ * // Custom — filter by type
+ * const errors = ref<LogEntry[]>([]);
+ * useSocketStream<LogEntry>('log.entry', (entry) => {
+ *   if (entry.level === 'error') errors.value = [...errors.value, entry];
+ * });
  */
-export function useSocketStream<T>(event: string): Ref<T[]> {
+export function useSocketStream<T>(event: string, callback?: (data: T) => void): Ref<T[]> {
   const socket = useSharedWebSocket();
   const items = ref<T[]>([]) as Ref<T[]>;
 
   const unsub = socket.on(event, (data: T) => {
-    items.value = [...items.value, data];
+    if (callback) {
+      callback(data);
+    } else {
+      items.value = [...items.value, data];
+    }
   });
 
   onUnmounted(unsub);
@@ -92,21 +130,31 @@ export function useSocketStream<T>(event: string): Ref<T[]> {
 }
 
 /**
- * Two-way state sync across browser tabs via reactive ref.
+ * Two-way state sync across browser tabs.
+ * - Without callback: reactive ref synced across tabs.
+ * - With callback: called when any tab updates this key — side effects.
  *
  * @example
+ * // Reactive two-way sync
  * const cart = useSocketSync<Cart>('cart', { items: [] });
  * cart.value = { items: [1, 2, 3] }; // syncs to all tabs
+ *
+ * @example
+ * // With side effect callback
+ * const cart = useSocketSync<Cart>('cart', { items: [] }, (cart) => {
+ *   document.title = `Cart (${cart.items.length})`;
+ *   analytics.track('cart_updated');
+ * });
  */
-export function useSocketSync<T>(key: string, initialValue: T): Ref<T> {
+export function useSocketSync<T>(key: string, initialValue: T, callback?: (value: T) => void): 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;
+    callback?.(v);
   });
 
-  // Watch for local changes → sync to other tabs
   watch(
     value,
     (newVal) => {
@@ -119,6 +167,24 @@ export function useSocketSync<T>(key: string, initialValue: T): Ref<T> {
   return value;
 }
 
+/**
+ * Fire-and-forget event handler — no state, no ref.
+ *
+ * @example
+ * useSocketCallback<Notification>('notification', (n) => {
+ *   showToast(n.title);
+ * });
+ */
+export function useSocketCallback<T>(event: string, callback: (data: T) => void): void {
+  const socket = useSharedWebSocket();
+
+  const unsub = socket.on(event, (data: T) => {
+    callback(data);
+  });
+
+  onUnmounted(unsub);
+}
+
 /**
  * Reactive connection status.
  *
@@ -133,9 +199,7 @@ export function useSocketStatus(): {
   const connected = ref(socket.connected);
   const tabRole = ref<TabRole>(socket.tabRole);
 
-  let timer: ReturnType<typeof setInterval>;
-
-  timer = setInterval(() => {
+  const timer = setInterval(() => {
     connected.value = socket.connected;
     tabRole.value = socket.tabRole;
   }, 1000);