react-ws-kit 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 react-websocket-kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,193 @@
+# react-ws-kit
+
+A production-quality, typed WebSocket hook for React with intelligent connection sharing, message queuing, and comprehensive reconnection handling.
+
+## Features
+
+- **TypeScript First**: Full generic type support for send/receive messages
+- **Connection Sharing**: Automatically shares WebSocket instances across components with matching configurations
+- **Per-Hook State**: Each hook maintains its own `allData` history and UI state
+- **Message Queuing**: Optional FIFO queue for offline message buffering
+- **Auto-Reconnect**: Configurable linear backoff strategy
+- **Kill Switch**: Programmatically close connections for all subscribers
+- **Zero Dependencies**: Only peer dependency is React 18+
+
+## Installation
+
+```bash
+npm install react-ws-kit
+```
+
+## Basic Usage
+
+```typescript
+import { useSocket } from 'react-ws-kit'
+
+function ChatComponent() {
+  const { connect, disconnect, send, status, lastReturnedData, allData } = 
+    useSocket('ws://localhost:3001/chat')
+
+  return (
+    <div>
+      <button onClick={connect}>Connect</button>
+      <button onClick={disconnect}>Disconnect</button>
+      <button onClick={() => send({ message: 'Hello!' })}>Send</button>
+      <p>Status: {status}</p>
+    </div>
+  )
+}
+```
+
+## Typed Usage
+
+```typescript
+type MessageIn = {
+  type: 'chat'
+  user: string
+  message: string
+  timestamp: number
+}
+
+type MessageOut = {
+  message: string
+}
+
+function TypedChat() {
+  const { send, lastReturnedData, allData } = useSocket<MessageIn, MessageOut>(
+    'ws://localhost:3001/chat',
+    {
+      autoConnect: true,
+      autoReconnect: true,
+      reconnectAttempts: 5,
+      reconnectDelay: 1000,
+      queueMessages: true,
+      maxQueueSize: 100
+    }
+  )
+
+  // lastReturnedData is typed as MessageIn | undefined
+  // send accepts MessageOut
+  
+  return <div>{lastReturnedData?.message}</div>
+}
+```
+
+## API
+
+### `useSocket<TIn, TOut>(url, options?)`
+
+#### Parameters
+
+- `url: string` - WebSocket URL
+- `options?: Options<TIn, TOut>` - Configuration object
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `autoConnect` | `boolean` | `false` | Connect automatically on mount |
+| `protocols` | `string \| string[]` | `undefined` | WebSocket sub-protocols |
+| `autoReconnect` | `boolean` | `false` | Enable automatic reconnection |
+| `reconnectAttempts` | `number` | `Infinity` | Max reconnection attempts |
+| `reconnectDelay` | `number` | `1000` | Base delay in ms (linear backoff) |
+| `queueMessages` | `boolean` | `false` | Queue messages when disconnected |
+| `maxQueueSize` | `number` | `50` | Maximum queue size |
+| `parse` | `(event: MessageEvent) => TIn` | `JSON.parse` | Custom message parser |
+| `serialize` | `(data: TOut) => string` | `JSON.stringify` | Custom message serializer |
+| `key` | `string` | `undefined` | Deterministic key for function identity |
+
+#### Return Value
+
+```typescript
+{
+  connect: () => void
+  disconnect: () => void
+  send: (data: TOut) => void
+  status: "disconnected" | "connecting" | "connected" | "error" | "reconnecting"
+  lastReturnedData?: TIn
+  allData: TIn[]
+  killSocketForAllSubscribers: () => void
+}
+```
+
+## Connection Sharing
+
+Hooks automatically share a WebSocket if all of the following match:
+
+- URL
+- Protocols
+- Auto-reconnect settings
+- Queue settings
+- Parse/serialize functions (by reference or via `key` option)
+
+```typescript
+// These two hooks share the same WebSocket
+function ComponentA() {
+  const ws = useSocket('ws://localhost:3001/chat', { queueMessages: true })
+  // ...
+}
+
+function ComponentB() {
+  const ws = useSocket('ws://localhost:3001/chat', { queueMessages: true })
+  // ...
+}
+```
+
+## Reconnection Strategy
+
+Linear backoff: `delay = reconnectDelay * attemptNumber`
+
+```typescript
+useSocket(url, {
+  autoReconnect: true,
+  reconnectAttempts: 5,
+  reconnectDelay: 1000
+})
+
+// Attempt 1: 1000ms delay
+// Attempt 2: 2000ms delay
+// Attempt 3: 3000ms delay
+// ...
+```
+
+## Kill Switch
+
+The kill switch closes the socket for **all** subscribers and prevents auto-reconnect:
+
+```typescript
+const { killSocketForAllSubscribers } = useSocket(url, { autoReconnect: true })
+
+// Disconnects all components using this socket
+// Auto-reconnect is disabled until manual connect()
+killSocketForAllSubscribers()
+```
+
+## Message Queuing
+
+When `queueMessages: true`, messages sent while disconnected are queued and flushed on reconnection:
+
+```typescript
+const { send } = useSocket(url, {
+  queueMessages: true,
+  maxQueueSize: 100
+})
+
+// Even if disconnected, messages are queued
+send({ message: 'Hello' })
+send({ message: 'World' })
+
+// On reconnect, both messages are sent in order
+```
+
+## Testing
+
+The package includes comprehensive unit tests:
+
+```bash
+npm test
+```
+
+## License
+
+MIT
+

package/dist/index.d.mts

@@ -0,0 +1,119 @@
+/**
+ * WebSocket connection status
+ */
+type Status = "disconnected" | "connecting" | "connected" | "error" | "reconnecting";
+/**
+ * Options for configuring the WebSocket hook
+ */
+interface Options<TIn = unknown, TOut = unknown> {
+    /**
+     * Automatically connect when the hook mounts
+     * @default false
+     */
+    autoConnect?: boolean;
+    /**
+     * WebSocket sub-protocols
+     */
+    protocols?: string | string[];
+    /**
+     * Automatically reconnect on disconnect
+     * @default false
+     */
+    autoReconnect?: boolean;
+    /**
+     * Maximum number of reconnection attempts (Infinity = unlimited)
+     * @default Infinity
+     */
+    reconnectAttempts?: number;
+    /**
+     * Base delay in milliseconds for reconnection
+     * Actual delay = reconnectDelay * attemptNumber (linear backoff)
+     * @default 1000
+     */
+    reconnectDelay?: number;
+    /**
+     * Queue outgoing messages when disconnected
+     * @default false
+     */
+    queueMessages?: boolean;
+    /**
+     * Maximum size of the message queue
+     * @default 50
+     */
+    maxQueueSize?: number;
+    /**
+     * Custom parser for incoming messages
+     * @default (event) => JSON.parse(event.data)
+     */
+    parse?: (event: MessageEvent) => TIn;
+    /**
+     * Custom serializer for outgoing messages
+     * @default (data) => JSON.stringify(data)
+     */
+    serialize?: (data: TOut) => string;
+    /**
+     * Optional deterministic key for function identity
+     * Use when parse/serialize functions are not referentially stable
+     */
+    key?: string;
+}
+/**
+ * Return value of the useSocket hook
+ */
+interface UseSocketReturn<TIn = unknown, TOut = unknown> {
+    /**
+     * Manually connect to the WebSocket
+     */
+    connect: () => void;
+    /**
+     * Manually disconnect from the WebSocket
+     */
+    disconnect: () => void;
+    /**
+     * Send a typed message through the WebSocket
+     */
+    send: (data: TOut) => void;
+    /**
+     * Current connection status
+     */
+    status: Status;
+    /**
+     * Most recently received message
+     */
+    lastReturnedData?: TIn;
+    /**
+     * All messages received by this hook instance
+     */
+    allData: TIn[];
+    /**
+     * Close the socket for all subscribers and disable auto-reconnect
+     */
+    killSocketForAllSubscribers: () => void;
+}
+/**
+ * Read-only socket information for debugging/dashboard
+ */
+interface SocketInfo {
+    key: string;
+    url: string;
+    status: Status;
+    refCount: number;
+    queueLength: number;
+    reconnectAttemptsMade: number;
+    killed: boolean;
+}
+
+/**
+ * Typed WebSocket hook with sharing, queuing, and kill switch
+ */
+declare function useSocket<TIn = unknown, TOut = unknown>(url: string, options?: Options<TIn, TOut>): UseSocketReturn<TIn, TOut>;
+
+/**
+ * Export for debugging/dashboard use
+ */
+declare function getSocketStore(): {
+    getAllSocketInfo: () => SocketInfo[];
+    clearQueue: (key: string) => void;
+};
+
+export { type Options, type SocketInfo, type Status, type UseSocketReturn, getSocketStore, useSocket };

package/dist/index.d.ts

@@ -0,0 +1,119 @@
+/**
+ * WebSocket connection status
+ */
+type Status = "disconnected" | "connecting" | "connected" | "error" | "reconnecting";
+/**
+ * Options for configuring the WebSocket hook
+ */
+interface Options<TIn = unknown, TOut = unknown> {
+    /**
+     * Automatically connect when the hook mounts
+     * @default false
+     */
+    autoConnect?: boolean;
+    /**
+     * WebSocket sub-protocols
+     */
+    protocols?: string | string[];
+    /**
+     * Automatically reconnect on disconnect
+     * @default false
+     */
+    autoReconnect?: boolean;
+    /**
+     * Maximum number of reconnection attempts (Infinity = unlimited)
+     * @default Infinity
+     */
+    reconnectAttempts?: number;
+    /**
+     * Base delay in milliseconds for reconnection
+     * Actual delay = reconnectDelay * attemptNumber (linear backoff)
+     * @default 1000
+     */
+    reconnectDelay?: number;
+    /**
+     * Queue outgoing messages when disconnected
+     * @default false
+     */
+    queueMessages?: boolean;
+    /**
+     * Maximum size of the message queue
+     * @default 50
+     */
+    maxQueueSize?: number;
+    /**
+     * Custom parser for incoming messages
+     * @default (event) => JSON.parse(event.data)
+     */
+    parse?: (event: MessageEvent) => TIn;
+    /**
+     * Custom serializer for outgoing messages
+     * @default (data) => JSON.stringify(data)
+     */
+    serialize?: (data: TOut) => string;
+    /**
+     * Optional deterministic key for function identity
+     * Use when parse/serialize functions are not referentially stable
+     */
+    key?: string;
+}
+/**
+ * Return value of the useSocket hook
+ */
+interface UseSocketReturn<TIn = unknown, TOut = unknown> {
+    /**
+     * Manually connect to the WebSocket
+     */
+    connect: () => void;
+    /**
+     * Manually disconnect from the WebSocket
+     */
+    disconnect: () => void;
+    /**
+     * Send a typed message through the WebSocket
+     */
+    send: (data: TOut) => void;
+    /**
+     * Current connection status
+     */
+    status: Status;
+    /**
+     * Most recently received message
+     */
+    lastReturnedData?: TIn;
+    /**
+     * All messages received by this hook instance
+     */
+    allData: TIn[];
+    /**
+     * Close the socket for all subscribers and disable auto-reconnect
+     */
+    killSocketForAllSubscribers: () => void;
+}
+/**
+ * Read-only socket information for debugging/dashboard
+ */
+interface SocketInfo {
+    key: string;
+    url: string;
+    status: Status;
+    refCount: number;
+    queueLength: number;
+    reconnectAttemptsMade: number;
+    killed: boolean;
+}
+
+/**
+ * Typed WebSocket hook with sharing, queuing, and kill switch
+ */
+declare function useSocket<TIn = unknown, TOut = unknown>(url: string, options?: Options<TIn, TOut>): UseSocketReturn<TIn, TOut>;
+
+/**
+ * Export for debugging/dashboard use
+ */
+declare function getSocketStore(): {
+    getAllSocketInfo: () => SocketInfo[];
+    clearQueue: (key: string) => void;
+};
+
+export { type Options, type SocketInfo, type Status, type UseSocketReturn, getSocketStore, useSocket };

package/dist/index.js

@@ -0,0 +1,394 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  getSocketStore: () => getSocketStore,
+  useSocket: () => useSocket
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useSocket.ts
+var import_react = require("react");
+
+// src/hash.ts
+function simpleHash(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return hash.toString(36);
+}
+function isDefaultParse(fn) {
+  const fnStr = fn.toString();
+  return fnStr.includes("JSON.parse") && fnStr.includes("event.data");
+}
+function isDefaultSerialize(fn) {
+  const fnStr = fn.toString();
+  return fnStr.includes("JSON.stringify") && !fnStr.includes("event");
+}
+function createSocketKey(url, config) {
+  const parts = [url];
+  if (config.protocols) {
+    const protocols = Array.isArray(config.protocols) ? config.protocols.sort().join(",") : config.protocols;
+    parts.push(`proto:${protocols}`);
+  }
+  parts.push(`ar:${config.autoReconnect}`);
+  parts.push(`ra:${config.reconnectAttempts}`);
+  parts.push(`rd:${config.reconnectDelay}`);
+  parts.push(`qm:${config.queueMessages}`);
+  parts.push(`mqs:${config.maxQueueSize}`);
+  if (config.key) {
+    parts.push(`key:${config.key}`);
+  } else {
+    const parseHash = isDefaultParse(config.parse) ? "default-parse" : simpleHash(config.parse.toString());
+    const serializeHash = isDefaultSerialize(config.serialize) ? "default-serialize" : simpleHash(config.serialize.toString());
+    parts.push(`ph:${parseHash}`);
+    parts.push(`sh:${serializeHash}`);
+  }
+  return parts.join("|");
+}
+
+// src/store.ts
+var SocketStore = class {
+  constructor() {
+    this.sockets = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Get a socket instance by key
+   */
+  get(key) {
+    return this.sockets.get(key);
+  }
+  /**
+   * Set a socket instance
+   */
+  set(key, instance) {
+    this.sockets.set(key, instance);
+  }
+  /**
+   * Delete a socket instance
+   */
+  delete(key) {
+    this.sockets.delete(key);
+  }
+  /**
+   * Check if a socket key exists
+   */
+  has(key) {
+    return this.sockets.has(key);
+  }
+  /**
+   * Get all socket keys
+   */
+  keys() {
+    return Array.from(this.sockets.keys());
+  }
+  /**
+   * Get read-only information about all sockets (for debugging/dashboard)
+   */
+  getAllSocketInfo() {
+    return Array.from(this.sockets.entries()).map(([key, instance]) => ({
+      key,
+      url: instance.socket?.url || "N/A",
+      status: instance.status,
+      refCount: instance.refCount,
+      queueLength: instance.messageQueue.length,
+      reconnectAttemptsMade: instance.reconnectAttemptsMade,
+      killed: instance.killed
+    }));
+  }
+  /**
+   * Clear a socket's message queue (for debugging/testing)
+   */
+  clearQueue(key) {
+    const instance = this.sockets.get(key);
+    if (instance) {
+      instance.messageQueue = [];
+    }
+  }
+};
+var socketStore = new SocketStore();
+function getSocketStore() {
+  return {
+    getAllSocketInfo: () => socketStore.getAllSocketInfo(),
+    clearQueue: (key) => socketStore.clearQueue(key)
+  };
+}
+
+// src/useSocket.ts
+var defaultParse = (event) => {
+  return JSON.parse(event.data);
+};
+var defaultSerialize = (data) => {
+  return JSON.stringify(data);
+};
+function normalizeOptions(options) {
+  return {
+    autoConnect: options?.autoConnect ?? false,
+    protocols: options?.protocols,
+    autoReconnect: options?.autoReconnect ?? false,
+    reconnectAttempts: options?.reconnectAttempts ?? Infinity,
+    reconnectDelay: options?.reconnectDelay ?? 1e3,
+    queueMessages: options?.queueMessages ?? false,
+    maxQueueSize: options?.maxQueueSize ?? 50,
+    parse: options?.parse ?? defaultParse,
+    serialize: options?.serialize ?? defaultSerialize,
+    key: options?.key
+  };
+}
+var subscriberIdCounter = 0;
+function generateSubscriberId() {
+  return `sub-${++subscriberIdCounter}-${Date.now()}`;
+}
+function useSocket(url, options) {
+  const config = (0, import_react.useRef)(normalizeOptions(options)).current;
+  const socketKey = (0, import_react.useRef)(createSocketKey(url, config)).current;
+  const subscriberId = (0, import_react.useRef)(generateSubscriberId()).current;
+  const [status, setStatus] = (0, import_react.useState)("disconnected");
+  const [lastReturnedData, setLastReturnedData] = (0, import_react.useState)(void 0);
+  const [allData, setAllData] = (0, import_react.useState)([]);
+  const isConnectedRef = (0, import_react.useRef)(false);
+  const addToAllData = (0, import_react.useCallback)((data) => {
+    setAllData((prev) => [...prev, data]);
+  }, []);
+  const getOrCreateInstance = (0, import_react.useCallback)(() => {
+    let instance = socketStore.get(socketKey);
+    if (!instance) {
+      instance = {
+        socket: null,
+        key: socketKey,
+        status: "disconnected",
+        subscribers: /* @__PURE__ */ new Set(),
+        refCount: 0,
+        reconnectAttemptsMade: 0,
+        messageQueue: [],
+        config,
+        killed: false,
+        reconnectTimer: null
+      };
+      socketStore.set(socketKey, instance);
+    }
+    return instance;
+  }, [socketKey, config]);
+  const updateAllSubscribers = (0, import_react.useCallback)((instance, newStatus) => {
+    instance.status = newStatus;
+    instance.subscribers.forEach((sub) => {
+      sub.setStatus(newStatus);
+    });
+  }, []);
+  const flushQueue = (0, import_react.useCallback)((instance) => {
+    if (!instance.socket || instance.socket.readyState !== WebSocket.OPEN) {
+      return;
+    }
+    while (instance.messageQueue.length > 0) {
+      const data = instance.messageQueue.shift();
+      try {
+        const serialized = instance.config.serialize(data);
+        instance.socket.send(serialized);
+      } catch (error) {
+        console.error("[useSocket] Error flushing queued message:", error);
+      }
+    }
+  }, []);
+  const scheduleReconnect = (0, import_react.useCallback)((instance) => {
+    if (instance.reconnectTimer) {
+      clearTimeout(instance.reconnectTimer);
+      instance.reconnectTimer = null;
+    }
+    if (instance.killed || !instance.config.autoReconnect) {
+      return;
+    }
+    if (instance.reconnectAttemptsMade >= instance.config.reconnectAttempts) {
+      console.log("[useSocket] Reconnect attempts exhausted");
+      updateAllSubscribers(instance, "error");
+      return;
+    }
+    instance.reconnectAttemptsMade++;
+    const delay = instance.config.reconnectDelay * instance.reconnectAttemptsMade;
+    console.log(`[useSocket] Scheduling reconnect attempt ${instance.reconnectAttemptsMade} in ${delay}ms`);
+    updateAllSubscribers(instance, "reconnecting");
+    instance.reconnectTimer = setTimeout(() => {
+      instance.reconnectTimer = null;
+      connectSocket(instance);
+    }, delay);
+  }, [updateAllSubscribers]);
+  const connectSocket = (0, import_react.useCallback)((instance) => {
+    if (instance.socket?.readyState === WebSocket.OPEN) {
+      updateAllSubscribers(instance, "connected");
+      return;
+    }
+    if (instance.socket?.readyState === WebSocket.CONNECTING) {
+      updateAllSubscribers(instance, "connecting");
+      return;
+    }
+    if (instance.reconnectTimer) {
+      clearTimeout(instance.reconnectTimer);
+      instance.reconnectTimer = null;
+    }
+    try {
+      updateAllSubscribers(instance, "connecting");
+      const ws = new WebSocket(url, instance.config.protocols);
+      instance.socket = ws;
+      ws.onopen = () => {
+        console.log("[useSocket] Connected:", socketKey);
+        instance.reconnectAttemptsMade = 0;
+        updateAllSubscribers(instance, "connected");
+        flushQueue(instance);
+      };
+      ws.onmessage = (event) => {
+        try {
+          const data = instance.config.parse(event);
+          instance.subscribers.forEach((sub) => {
+            if (sub.isConnected) {
+              sub.setLastReturnedData(data);
+              sub.addToAllData(data);
+            }
+          });
+        } catch (error) {
+          console.error("[useSocket] Parse error:", error);
+        }
+      };
+      ws.onerror = (error) => {
+        console.error("[useSocket] WebSocket error:", error);
+        updateAllSubscribers(instance, "error");
+      };
+      ws.onclose = () => {
+        console.log("[useSocket] Disconnected:", socketKey);
+        instance.socket = null;
+        if (!instance.killed && instance.config.autoReconnect && instance.refCount > 0) {
+          scheduleReconnect(instance);
+        } else {
+          updateAllSubscribers(instance, "disconnected");
+        }
+      };
+    } catch (error) {
+      console.error("[useSocket] Connection error:", error);
+      updateAllSubscribers(instance, "error");
+      if (!instance.killed && instance.config.autoReconnect) {
+        scheduleReconnect(instance);
+      }
+    }
+  }, [url, socketKey, updateAllSubscribers, flushQueue, scheduleReconnect]);
+  const connect = (0, import_react.useCallback)(() => {
+    const instance = getOrCreateInstance();
+    if (!isConnectedRef.current) {
+      const subscriber = {
+        id: subscriberId,
+        isConnected: true,
+        setStatus,
+        setLastReturnedData,
+        addToAllData
+      };
+      instance.subscribers.add(subscriber);
+      instance.refCount++;
+      isConnectedRef.current = true;
+      setStatus(instance.status);
+    }
+    instance.killed = false;
+    connectSocket(instance);
+  }, [getOrCreateInstance, subscriberId, addToAllData, connectSocket]);
+  const disconnect = (0, import_react.useCallback)(() => {
+    const instance = socketStore.get(socketKey);
+    if (!instance || !isConnectedRef.current) return;
+    const subscriberToRemove = Array.from(instance.subscribers).find(
+      (sub) => sub.id === subscriberId
+    );
+    if (subscriberToRemove) {
+      instance.subscribers.delete(subscriberToRemove);
+      instance.refCount--;
+      isConnectedRef.current = false;
+    }
+    if (instance.refCount <= 0) {
+      if (instance.reconnectTimer) {
+        clearTimeout(instance.reconnectTimer);
+        instance.reconnectTimer = null;
+      }
+      if (instance.socket) {
+        instance.socket.close();
+        instance.socket = null;
+      }
+      socketStore.delete(socketKey);
+    }
+    setStatus("disconnected");
+  }, [socketKey, subscriberId]);
+  const send = (0, import_react.useCallback)((data) => {
+    const instance = socketStore.get(socketKey);
+    if (!instance) {
+      console.error("[useSocket] Cannot send: no instance found");
+      return;
+    }
+    if (instance.socket?.readyState === WebSocket.OPEN) {
+      try {
+        const serialized = instance.config.serialize(data);
+        instance.socket.send(serialized);
+      } catch (error) {
+        console.error("[useSocket] Send error:", error);
+      }
+    } else if (instance.config.queueMessages) {
+      instance.messageQueue.push(data);
+      while (instance.messageQueue.length > instance.config.maxQueueSize) {
+        instance.messageQueue.shift();
+      }
+      console.log(`[useSocket] Message queued (${instance.messageQueue.length}/${instance.config.maxQueueSize})`);
+    } else {
+      console.error("[useSocket] Cannot send: not connected and queueMessages is false");
+    }
+  }, [socketKey]);
+  const killSocketForAllSubscribers = (0, import_react.useCallback)(() => {
+    const instance = socketStore.get(socketKey);
+    if (!instance) return;
+    console.log("[useSocket] Kill switch activated for:", socketKey);
+    instance.killed = true;
+    if (instance.reconnectTimer) {
+      clearTimeout(instance.reconnectTimer);
+      instance.reconnectTimer = null;
+    }
+    if (instance.socket) {
+      instance.socket.close();
+      instance.socket = null;
+    }
+    updateAllSubscribers(instance, "disconnected");
+  }, [socketKey, updateAllSubscribers]);
+  (0, import_react.useEffect)(() => {
+    if (config.autoConnect) {
+      connect();
+    }
+    return () => {
+      disconnect();
+    };
+  }, []);
+  return {
+    connect,
+    disconnect,
+    send,
+    status,
+    lastReturnedData,
+    allData,
+    killSocketForAllSubscribers
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getSocketStore,
+  useSocket
+});

package/dist/index.mjs

@@ -0,0 +1,366 @@
+// src/useSocket.ts
+import { useEffect, useRef, useState, useCallback } from "react";
+
+// src/hash.ts
+function simpleHash(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return hash.toString(36);
+}
+function isDefaultParse(fn) {
+  const fnStr = fn.toString();
+  return fnStr.includes("JSON.parse") && fnStr.includes("event.data");
+}
+function isDefaultSerialize(fn) {
+  const fnStr = fn.toString();
+  return fnStr.includes("JSON.stringify") && !fnStr.includes("event");
+}
+function createSocketKey(url, config) {
+  const parts = [url];
+  if (config.protocols) {
+    const protocols = Array.isArray(config.protocols) ? config.protocols.sort().join(",") : config.protocols;
+    parts.push(`proto:${protocols}`);
+  }
+  parts.push(`ar:${config.autoReconnect}`);
+  parts.push(`ra:${config.reconnectAttempts}`);
+  parts.push(`rd:${config.reconnectDelay}`);
+  parts.push(`qm:${config.queueMessages}`);
+  parts.push(`mqs:${config.maxQueueSize}`);
+  if (config.key) {
+    parts.push(`key:${config.key}`);
+  } else {
+    const parseHash = isDefaultParse(config.parse) ? "default-parse" : simpleHash(config.parse.toString());
+    const serializeHash = isDefaultSerialize(config.serialize) ? "default-serialize" : simpleHash(config.serialize.toString());
+    parts.push(`ph:${parseHash}`);
+    parts.push(`sh:${serializeHash}`);
+  }
+  return parts.join("|");
+}
+
+// src/store.ts
+var SocketStore = class {
+  constructor() {
+    this.sockets = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Get a socket instance by key
+   */
+  get(key) {
+    return this.sockets.get(key);
+  }
+  /**
+   * Set a socket instance
+   */
+  set(key, instance) {
+    this.sockets.set(key, instance);
+  }
+  /**
+   * Delete a socket instance
+   */
+  delete(key) {
+    this.sockets.delete(key);
+  }
+  /**
+   * Check if a socket key exists
+   */
+  has(key) {
+    return this.sockets.has(key);
+  }
+  /**
+   * Get all socket keys
+   */
+  keys() {
+    return Array.from(this.sockets.keys());
+  }
+  /**
+   * Get read-only information about all sockets (for debugging/dashboard)
+   */
+  getAllSocketInfo() {
+    return Array.from(this.sockets.entries()).map(([key, instance]) => ({
+      key,
+      url: instance.socket?.url || "N/A",
+      status: instance.status,
+      refCount: instance.refCount,
+      queueLength: instance.messageQueue.length,
+      reconnectAttemptsMade: instance.reconnectAttemptsMade,
+      killed: instance.killed
+    }));
+  }
+  /**
+   * Clear a socket's message queue (for debugging/testing)
+   */
+  clearQueue(key) {
+    const instance = this.sockets.get(key);
+    if (instance) {
+      instance.messageQueue = [];
+    }
+  }
+};
+var socketStore = new SocketStore();
+function getSocketStore() {
+  return {
+    getAllSocketInfo: () => socketStore.getAllSocketInfo(),
+    clearQueue: (key) => socketStore.clearQueue(key)
+  };
+}
+
+// src/useSocket.ts
+var defaultParse = (event) => {
+  return JSON.parse(event.data);
+};
+var defaultSerialize = (data) => {
+  return JSON.stringify(data);
+};
+function normalizeOptions(options) {
+  return {
+    autoConnect: options?.autoConnect ?? false,
+    protocols: options?.protocols,
+    autoReconnect: options?.autoReconnect ?? false,
+    reconnectAttempts: options?.reconnectAttempts ?? Infinity,
+    reconnectDelay: options?.reconnectDelay ?? 1e3,
+    queueMessages: options?.queueMessages ?? false,
+    maxQueueSize: options?.maxQueueSize ?? 50,
+    parse: options?.parse ?? defaultParse,
+    serialize: options?.serialize ?? defaultSerialize,
+    key: options?.key
+  };
+}
+var subscriberIdCounter = 0;
+function generateSubscriberId() {
+  return `sub-${++subscriberIdCounter}-${Date.now()}`;
+}
+function useSocket(url, options) {
+  const config = useRef(normalizeOptions(options)).current;
+  const socketKey = useRef(createSocketKey(url, config)).current;
+  const subscriberId = useRef(generateSubscriberId()).current;
+  const [status, setStatus] = useState("disconnected");
+  const [lastReturnedData, setLastReturnedData] = useState(void 0);
+  const [allData, setAllData] = useState([]);
+  const isConnectedRef = useRef(false);
+  const addToAllData = useCallback((data) => {
+    setAllData((prev) => [...prev, data]);
+  }, []);
+  const getOrCreateInstance = useCallback(() => {
+    let instance = socketStore.get(socketKey);
+    if (!instance) {
+      instance = {
+        socket: null,
+        key: socketKey,
+        status: "disconnected",
+        subscribers: /* @__PURE__ */ new Set(),
+        refCount: 0,
+        reconnectAttemptsMade: 0,
+        messageQueue: [],
+        config,
+        killed: false,
+        reconnectTimer: null
+      };
+      socketStore.set(socketKey, instance);
+    }
+    return instance;
+  }, [socketKey, config]);
+  const updateAllSubscribers = useCallback((instance, newStatus) => {
+    instance.status = newStatus;
+    instance.subscribers.forEach((sub) => {
+      sub.setStatus(newStatus);
+    });
+  }, []);
+  const flushQueue = useCallback((instance) => {
+    if (!instance.socket || instance.socket.readyState !== WebSocket.OPEN) {
+      return;
+    }
+    while (instance.messageQueue.length > 0) {
+      const data = instance.messageQueue.shift();
+      try {
+        const serialized = instance.config.serialize(data);
+        instance.socket.send(serialized);
+      } catch (error) {
+        console.error("[useSocket] Error flushing queued message:", error);
+      }
+    }
+  }, []);
+  const scheduleReconnect = useCallback((instance) => {
+    if (instance.reconnectTimer) {
+      clearTimeout(instance.reconnectTimer);
+      instance.reconnectTimer = null;
+    }
+    if (instance.killed || !instance.config.autoReconnect) {
+      return;
+    }
+    if (instance.reconnectAttemptsMade >= instance.config.reconnectAttempts) {
+      console.log("[useSocket] Reconnect attempts exhausted");
+      updateAllSubscribers(instance, "error");
+      return;
+    }
+    instance.reconnectAttemptsMade++;
+    const delay = instance.config.reconnectDelay * instance.reconnectAttemptsMade;
+    console.log(`[useSocket] Scheduling reconnect attempt ${instance.reconnectAttemptsMade} in ${delay}ms`);
+    updateAllSubscribers(instance, "reconnecting");
+    instance.reconnectTimer = setTimeout(() => {
+      instance.reconnectTimer = null;
+      connectSocket(instance);
+    }, delay);
+  }, [updateAllSubscribers]);
+  const connectSocket = useCallback((instance) => {
+    if (instance.socket?.readyState === WebSocket.OPEN) {
+      updateAllSubscribers(instance, "connected");
+      return;
+    }
+    if (instance.socket?.readyState === WebSocket.CONNECTING) {
+      updateAllSubscribers(instance, "connecting");
+      return;
+    }
+    if (instance.reconnectTimer) {
+      clearTimeout(instance.reconnectTimer);
+      instance.reconnectTimer = null;
+    }
+    try {
+      updateAllSubscribers(instance, "connecting");
+      const ws = new WebSocket(url, instance.config.protocols);
+      instance.socket = ws;
+      ws.onopen = () => {
+        console.log("[useSocket] Connected:", socketKey);
+        instance.reconnectAttemptsMade = 0;
+        updateAllSubscribers(instance, "connected");
+        flushQueue(instance);
+      };
+      ws.onmessage = (event) => {
+        try {
+          const data = instance.config.parse(event);
+          instance.subscribers.forEach((sub) => {
+            if (sub.isConnected) {
+              sub.setLastReturnedData(data);
+              sub.addToAllData(data);
+            }
+          });
+        } catch (error) {
+          console.error("[useSocket] Parse error:", error);
+        }
+      };
+      ws.onerror = (error) => {
+        console.error("[useSocket] WebSocket error:", error);
+        updateAllSubscribers(instance, "error");
+      };
+      ws.onclose = () => {
+        console.log("[useSocket] Disconnected:", socketKey);
+        instance.socket = null;
+        if (!instance.killed && instance.config.autoReconnect && instance.refCount > 0) {
+          scheduleReconnect(instance);
+        } else {
+          updateAllSubscribers(instance, "disconnected");
+        }
+      };
+    } catch (error) {
+      console.error("[useSocket] Connection error:", error);
+      updateAllSubscribers(instance, "error");
+      if (!instance.killed && instance.config.autoReconnect) {
+        scheduleReconnect(instance);
+      }
+    }
+  }, [url, socketKey, updateAllSubscribers, flushQueue, scheduleReconnect]);
+  const connect = useCallback(() => {
+    const instance = getOrCreateInstance();
+    if (!isConnectedRef.current) {
+      const subscriber = {
+        id: subscriberId,
+        isConnected: true,
+        setStatus,
+        setLastReturnedData,
+        addToAllData
+      };
+      instance.subscribers.add(subscriber);
+      instance.refCount++;
+      isConnectedRef.current = true;
+      setStatus(instance.status);
+    }
+    instance.killed = false;
+    connectSocket(instance);
+  }, [getOrCreateInstance, subscriberId, addToAllData, connectSocket]);
+  const disconnect = useCallback(() => {
+    const instance = socketStore.get(socketKey);
+    if (!instance || !isConnectedRef.current) return;
+    const subscriberToRemove = Array.from(instance.subscribers).find(
+      (sub) => sub.id === subscriberId
+    );
+    if (subscriberToRemove) {
+      instance.subscribers.delete(subscriberToRemove);
+      instance.refCount--;
+      isConnectedRef.current = false;
+    }
+    if (instance.refCount <= 0) {
+      if (instance.reconnectTimer) {
+        clearTimeout(instance.reconnectTimer);
+        instance.reconnectTimer = null;
+      }
+      if (instance.socket) {
+        instance.socket.close();
+        instance.socket = null;
+      }
+      socketStore.delete(socketKey);
+    }
+    setStatus("disconnected");
+  }, [socketKey, subscriberId]);
+  const send = useCallback((data) => {
+    const instance = socketStore.get(socketKey);
+    if (!instance) {
+      console.error("[useSocket] Cannot send: no instance found");
+      return;
+    }
+    if (instance.socket?.readyState === WebSocket.OPEN) {
+      try {
+        const serialized = instance.config.serialize(data);
+        instance.socket.send(serialized);
+      } catch (error) {
+        console.error("[useSocket] Send error:", error);
+      }
+    } else if (instance.config.queueMessages) {
+      instance.messageQueue.push(data);
+      while (instance.messageQueue.length > instance.config.maxQueueSize) {
+        instance.messageQueue.shift();
+      }
+      console.log(`[useSocket] Message queued (${instance.messageQueue.length}/${instance.config.maxQueueSize})`);
+    } else {
+      console.error("[useSocket] Cannot send: not connected and queueMessages is false");
+    }
+  }, [socketKey]);
+  const killSocketForAllSubscribers = useCallback(() => {
+    const instance = socketStore.get(socketKey);
+    if (!instance) return;
+    console.log("[useSocket] Kill switch activated for:", socketKey);
+    instance.killed = true;
+    if (instance.reconnectTimer) {
+      clearTimeout(instance.reconnectTimer);
+      instance.reconnectTimer = null;
+    }
+    if (instance.socket) {
+      instance.socket.close();
+      instance.socket = null;
+    }
+    updateAllSubscribers(instance, "disconnected");
+  }, [socketKey, updateAllSubscribers]);
+  useEffect(() => {
+    if (config.autoConnect) {
+      connect();
+    }
+    return () => {
+      disconnect();
+    };
+  }, []);
+  return {
+    connect,
+    disconnect,
+    send,
+    status,
+    lastReturnedData,
+    allData,
+    killSocketForAllSubscribers
+  };
+}
+export {
+  getSocketStore,
+  useSocket
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "react-ws-kit",
+  "version": "1.0.0",
+  "description": "Production-quality typed WebSocket hook for React with intelligent connection sharing, auto-reconnect, and message queuing",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sameerdewan/react-ws-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sameerdewan/react-ws-kit/issues"
+  },
+  "homepage": "https://github.com/sameerdewan/react-ws-kit#readme",
+  "author": "Sameer Dewan <dewansameer@protonmail.com>",
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^14.1.2",
+    "@types/react": "^18.2.45",
+    "@vitest/ui": "^1.1.0",
+    "happy-dom": "^12.10.3",
+    "react": "^18.2.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.1.0"
+  },
+  "keywords": [
+    "react",
+    "websocket",
+    "hook",
+    "typescript",
+    "realtime",
+    "ws",
+    "connection-sharing",
+    "auto-reconnect",
+    "message-queue",
+    "typed-websocket",
+    "react-hook",
+    "websocket-client"
+  ],
+  "license": "MIT",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}
+