use-realtime 1.0.0 → 1.0.2

package/README.md

@@ -1,222 +1,454 @@
-use-realtime 🚀
-<div align="center">
+markdown
 
-https://img.shields.io/npm/v/use-realtime
-https://img.shields.io/npm/l/use-realtime
-https://img.shields.io/badge/TypeScript-Ready-blue
+# use-realtime 🚀
+
+[![npm version](https://img.shields.io/npm/v/use-realtime.svg)](https://www.npmjs.com/package/use-realtime)
+[![npm downloads](https://img.shields.io/npm/dm/use-realtime.svg)](https://www.npmjs.com/package/use-realtime)
+[![license](https://img.shields.io/npm/l/use-realtime.svg)](https://github.com/yaredabebe/use-realtime/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+
+**Stop rewriting WebSocket boilerplate in every React project.** A production-ready React hook for building real-time features with auto-reconnect, message queuing, and event subscriptions.
+
+---
+
+  
+
+## ✨ Features
+
+  
+
+-  **🔌 Auto-reconnect** - Automatically reconnects with configurable retry limits
+
+-  **📦 Message queue** - Never lose messages when offline (queues messages automatically)
+
+-  **📡 Event-based API** - Simple subscribe/unsubscribe pattern for events
+
+-  **💓 Heartbeat support** - Optional ping-pong to keep connections alive
+
+-  **🧹 Automatic cleanup** - Proper cleanup on component unmount
+
+-  **🧠 TypeScript first** - Full type safety and IntelliSense support
+
+-  **⚡ Zero dependencies** - Lightweight and tree-shakable
+
+  
+
+---
+
+  
+
+## 📦 Installation
+
+  ### npm
+```bash
+npm  install  use-realtime
+```
+### yarn
+  ```bash
+yarn  add  use-realtime
+```
+  ### pnpm 
+```bash
+pnpm  add  use-realtime
+```
+  
+
+## 🚀  Quick  Start
+
+```jsx
+import  React,  {  useEffect  }  from  'react';
+
+import  {  useRealtime  }  from  'use-realtime';
+
+  
+
+function  ChatComponent() {
+
+const  {  emit,  subscribe,  isConnected  }  =  useRealtime({
+
+url:  'wss://your-server.com/ws',
+
+autoReconnect:  true,
+
+});
+
+  
+
+useEffect(() => {
+
+const  unsubscribe  =  subscribe('message', (data) => {
+
+console.log('New message:',  data);
+
+});
+
+return  unsubscribe; //  Cleanup  on  unmount
+
+}, [subscribe]);
+
+  
+
+const  sendMessage  = () => {
+
+emit('chat',  {  text:  'Hello World!',  user:  'You'  });
+
+};
+
+  
+
+return (
+
+<div>
+
+<p>Status:  {isConnected  ?  '✅ Connected'  :  '❌ Disconnected'}</p>
+
+<button  onClick={sendMessage}  disabled={!isConnected}>
+
+Send  Message
+
+</button>
 
-Stop rewriting WebSocket boilerplate in every React project
 </div>
 
-✨ Why use-realtime?
+);
+
+}
+
+  ```
+
+## 📖  Documentation
+
+### Configuration  Options
+
+typescript
+
+  ```jsx
+
+interface  RealtimeOptions  {
+
+//  Required
+
+url:  string;
+
+//  Optional (with defaults)
 
-Building real-time features in React usually means:
+autoConnect?:  boolean; //  Default:  true
 
-    🔄 Rewriting WebSocket logic again and again
+autoReconnect?:  boolean; //  Default:  true
 
-    🔌 Handling reconnects manually (and often incorrectly)
+reconnectAttempts?:  number; //  Default:  10
 
-    📨 Losing messages when the connection drops
+reconnectInterval?:  number; //  Default:  3000 (ms)
 
-    🧹 Managing event listeners and cleanup yourself
+//  Heartbeat  configuration
 
-use-realtime solves these problems for you.
+heartbeat?:  {
 
+enabled?:  boolean; //  Default:  false
 
+interval?:  number; //  Default:  30000 (ms)
 
-🚀 Features
+message?:  any; //  Default:  'ping'
 
-✅ WebSocket connection management
-🔄 Auto-reconnect with retry limits
-📦 Message queue (no lost messages)
-📡 Event-based subscribe/unsubscribe API
-💓 Optional heartbeat (keep connection alive)
-🧹 Automatic cleanup on unmount
-🧠 React-safe & TypeScript-first
-🌍 Works with any WebSocket backend
+};
 
+//  Message  queue  for  offline  mode
 
-📦 Installation
+messageQueue?:  {
 
-npm install use-realtime
-# or
-yarn add use-realtime
-# or
-pnpm add use-realtime
+enabled?:  boolean; //  Default:  true
 
-⚡ Quick Start
-import { useRealtime } from 'use-realtime';
+maxSize?:  number; //  Default:  100
 
-function Chat() {
-  const { emit, subscribe, isConnected } = useRealtime({
-    url: 'wss://example.com/ws',
-    autoReconnect: true,
-  });
+};
 
-  // Subscribe to events
-  useEffect(() => {
-    const unsubscribe = subscribe('chat', (message) => {
-      console.log('New message:', message);
-    });
-    return unsubscribe;
-  }, [subscribe]);
+debug?:  boolean; //  Default:  false
 
-  return (
-    <button onClick={() => emit('chat', { text: 'Hello!' })}>
-      Send Message
-    </button>
-  );
 }
 
-🧠 Core API
-useRealtime(options)
-
-const realtime = useRealtime({
-  url: string,                    // WebSocket server URL (required)
-  autoConnect?: boolean,          // Auto connect on mount (default: true)
-  autoReconnect?: boolean,        // Auto reconnect on disconnect (default: true)
-  reconnectAttempts?: number,     // Max reconnect attempts (default: 10)
-  reconnectInterval?: number,     // Reconnect delay in ms (default: 3000)
-  heartbeat?: {                   // Heartbeat configuration
-    enabled?: boolean,           // Enable heartbeat (default: false)
-    interval?: number,           // Heartbeat interval in ms (default: 30000)
-    message?: any,               // Heartbeat message (default: 'ping')
-  },
-  messageQueue?: {               // Offline message queue
-    enabled?: boolean,           // Enable message queue (default: true)
-    maxSize?: number,            // Max queue size (default: 100)
-  },
-  debug?: boolean,               // Enable debug logging (default: false)
+  ```
+
+### Hook  Return  Values
+
+### Method  Description
+
+subscribe(event,  callback) Subscribe to events, returns unsubscribe function
+
+unsubscribe(event,  callback) Unsubscribe from specific event
+
+emit(event,  data) Send event with data
+
+send(data) Send raw data (auto-wrapped  as  'message'  event)
+
+connect() Manually connect
+
+disconnect() Manually disconnect
+
+reconnect() Force reconnection
+
+getQueueSize() Get number of queued messages
+
+flushQueue() Clear all queued messages
+
+clearSubscriptions() Remove all event listeners
+
+State  Property  Type  Description
+
+isConnected  boolean  Connection  is  active
+
+isConnecting  boolean  Connection  in  progress
+
+isReconnecting  boolean  Reconnection  in  progress
+
+connection  ConnectionState  Full  connection  details
+
+### Connection  State  Object
+
+typescript
+
+  ```jsx
+
+interface  ConnectionState  {
+
+connected:  boolean;
+
+connecting:  boolean;
+
+reconnecting:  boolean;
+
+error:  Error | null;
+
+lastMessageAt:  Date | null;
+
+connectionId:  string | null;
+
+}
+
+  ```
+
+## 💡  Real-World  Examples
+
+### 1.  Live  Chat  Application
+
+```jsx
+
+function  ChatRoom() {
+
+const [messages, setMessages]  =  useState([]);
+
+const  {  subscribe,  emit,  isConnected  }  =  useRealtime({
+
+url:  'wss://chat-server.com/ws',
+
+autoReconnect:  true,
+
+reconnectAttempts:  5,
+
+});
+
+  
+
+useEffect(() => {
+
+const  unsubscribe  =  subscribe('chat-message', (msg) => {
+
+setMessages(prev => [...prev, msg]);
+
 });
 
+return  unsubscribe;
+
+}, [subscribe]);
+
+  
+
+const  sendMessage  = (text) => {
 
-📡 Sending Messages
-emit(event, data)
+emit('chat-message',  {  text,  timestamp:  Date.now() });
 
-Send a named event. If the socket is not connected, the message is queued automatically.
-emit('notification', { title: 'New order' });
+};
 
+  
 
-send(data)
+//  ...  render  messages  and  input
 
-Send a raw message (no event name).
+}
 
-send({ ping: true });
+  ```
 
+### 2.  Live  Dashboard
 
-🔔 Subscribing to Events
-subscribe(event, callback)
 jsx
+```jsx
+  
+
+function  LiveDashboard() {
+
+const [stats, setStats]  =  useState({});
+
+const  {  subscribe  }  =  useRealtime({
+
+url:  'wss://api.example.com/live',
+
+heartbeat:  {  enabled:  true,  interval:  15000  },
 
-const unsubscribe = subscribe('order:update', (data) => {
-  console.log(data);
 });
 
-// Always unsubscribe on cleanup
+  
+
 useEffect(() => {
-  const unsubscribe = subscribe('event', handler);
-  return unsubscribe;
+
+const  unsubscribe  =  subscribe('stats-update', (data) => {
+
+setStats(data);
+
+});
+
+return  unsubscribe;
+
 }, [subscribe]);
 
-🔌 Connection State
-jsx
+  
 
-const {
-  isConnected,      // boolean - Connection is active
-  isConnecting,     // boolean - Connection in progress
-  isReconnecting,   // boolean - Reconnection in progress
-  connection,       // Full connection object
-} = useRealtime(...);
+//  ...  render  dashboard  with  stats
 
-connection includes:
+}
 
-    connected - Connection is active
+ ``` 
 
-    connecting - Connection in progress
+### 🔧  Advanced  Usage
 
-    reconnecting - Reconnection in progress
+### Manual  Connection  Control
 
-    error - Last error that occurred
+``` jsx
+const  {  connect,  disconnect,  reconnect,  isConnected  }  =  useRealtime({
 
-    lastMessageAt - Timestamp of last message
+url:  'wss://example.com',
 
-    connectionId - Unique connection identifier
+autoConnect:  false,  //  Disable  auto-connect
 
-🔄 Manual Control
-jsx
+});
 
-const { connect, disconnect, reconnect } = useRealtime(...);
+  
 
-connect();     // Manually connect
-disconnect();  // Close connection safely
-reconnect();   // Force reconnect
+//  Connect  manually
 
-📦 Message Queue Utilities
-jsx
+useEffect(() => {
 
-const { getQueueSize, flushQueue } = useRealtime(...);
+connect();
 
-getQueueSize();   // Number of queued messages
-flushQueue();     // Clear queued messages
+}, [connect]);
 
-🧹 Cleanup & Safety
+  
 
-✅ Automatically closes WebSocket on unmount
-✅ Prevents duplicate connections
-✅ Prevents reconnect loops
-✅ Prevents memory leaks
+//  Disconnect  after  30  seconds
 
-Safe to use in:
+useEffect(() => {
 
-    React
+const  timer  =  setTimeout(() => {
 
-    Next.js
+if (isConnected) disconnect();
 
-    Vite
+},  30000);
 
-    CRA
+return () => clearTimeout(timer);
 
-    Any React 16.8+ environment
+}, [disconnect, isConnected]);
 
-🧩 TypeScript Support
+  ```
 
-Fully typed and tree-shakable:
-typescript
+### Message  Queue (Offline Mode)
+
+```jsx
+
+  
+
+const  {  emit,  getQueueSize,  flushQueue  }  =  useRealtime({
+
+url:  'wss://example.com',
+
+messageQueue:  {
+
+enabled:  true,
+
+maxSize:  50,  //  Queue  up  to  50  messages
 
-import { useRealtime } from 'use-realtime';
-import type {
-  RealtimeOptions,
-  ConnectionState,
-  UseRealtimeReturn
-} from 'use-realtime';
+},
 
-🧑‍💻 When should I use this?
+});
+
+  
+
+//  Messages  are  automatically  queued  when  offline
+
+//  and  sent  when  connection  is  restored
+
+emit('important-event',  {  data:  'will not be lost'  });
+
+  
+
+//  Check  queue  size
+
+console.log('Queued messages:',  getQueueSize());
+
+  
+
+//  Clear  queue  if  needed
 
-Perfect for:
+flushQueue();
+```
+  
 
-    💬 Chat applications
+### 🐛  Troubleshooting
 
-    🔔 Live notifications
+Common  Issues
 
-    📊 Dashboards
+  
 
-    🎮 Multiplayer features
+CORS Errors with Local Development
 
-    📡 Real-time feeds
+javascript
+```jsx 
 
-    🏢 Admin panels
+//  Ensure  your  WebSocket  server  allows  connections  from  your  origin
 
-    🔧 IoT dashboards
+//  For  testing,  use  a  public  echo  server:
 
-    📈 Live analytics
+url:  'wss://echo.websocket.org'
+
+  
+
+Connection  Drops  Frequently
+
+javascript
+
+  
+
+//  Enable  heartbeat  to  keep  connection  alive
+
+heartbeat:  {
+
+enabled:  true,
+
+interval: 15000, // Send ping every 15 seconds
+
+}
+```
+  
 
-📄 License
+### Too  Many  Reconnect  Attempts
 
-MIT — free for personal and commercial use. See LICENSE for details.
-<div align="center">
+javascript
+```jsx 
+//  Limit  reconnect  attempts
 
+reconnectAttempts:  5,
 
+reconnectInterval:  5000,  //  Wait  5  seconds  between  attempts
+```
+  
 
 
+  
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-realtime",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A powerful React hook for real-time WebSocket connections with auto-reconnect, message queuing, and event management",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",