use-realtime 1.0.1 → 1.0.2

package/README.md

@@ -11,272 +11,444 @@ markdown
 
 ---
 
+  
+
 ## ✨ 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
+  
+
+-  **🔌 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
-npm install use-realtime
+pnpm  add  use-realtime
+```
+  
 
-or
-bash
+## 🚀  Quick  Start
 
-yarn add use-realtime
+```jsx
+import  React,  {  useEffect  }  from  'react';
 
-or
-bash
+import  {  useRealtime  }  from  'use-realtime';
 
-pnpm add use-realtime
+  
 
-🚀 Quick Start
-jsx
+function  ChatComponent() {
 
-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>
-    </div>
-  );
-}
+const  {  emit,  subscribe,  isConnected  }  =  useRealtime({
 
-📖 Documentation
-Configuration Options
-typescript
+url:  'wss://your-server.com/ws',
+
+autoReconnect:  true,
+
+});
 
-interface RealtimeOptions {
-  // Required
-  url: string;
-  
-  // Optional (with defaults)
-  autoConnect?: boolean;          // Default: true
-  autoReconnect?: boolean;        // Default: true
-  reconnectAttempts?: number;     // Default: 10
-  reconnectInterval?: number;     // Default: 3000 (ms)
   
-  // Heartbeat configuration
-  heartbeat?: {
-    enabled?: boolean;           // Default: false
-    interval?: number;           // Default: 30000 (ms)
-    message?: any;               // Default: 'ping'
-  };
+
+useEffect(() => {
+
+const  unsubscribe  =  subscribe('message', (data) => {
+
+console.log('New message:',  data);
+
+});
+
+return  unsubscribe; //  Cleanup  on  unmount
+
+}, [subscribe]);
+
   
-  // Message queue for offline mode
-  messageQueue?: {
-    enabled?: boolean;           // Default: true
-    maxSize?: number;            // Default: 100
-  };
+
+const  sendMessage  = () => {
+
+emit('chat',  {  text:  'Hello World!',  user:  'You'  });
+
+};
+
   
-  debug?: boolean;               // Default: false
+
+return (
+
+<div>
+
+<p>Status:  {isConnected  ?  '✅ Connected'  :  '❌ Disconnected'}</p>
+
+<button  onClick={sendMessage}  disabled={!isConnected}>
+
+Send  Message
+
+</button>
+
+</div>
+
+);
+
 }
 
-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
+  ```
+
+## 📖  Documentation
+
+### Configuration  Options
+
 typescript
 
-interface ConnectionState {
-  connected: boolean;
-  connecting: boolean;
-  reconnecting: boolean;
-  error: Error | null;
-  lastMessageAt: Date | null;
-  connectionId: string | null;
+  ```jsx
+
+interface  RealtimeOptions  {
+
+//  Required
+
+url:  string;
+
+//  Optional (with defaults)
+
+autoConnect?:  boolean; //  Default:  true
+
+autoReconnect?:  boolean; //  Default:  true
+
+reconnectAttempts?:  number; //  Default:  10
+
+reconnectInterval?:  number; //  Default:  3000 (ms)
+
+//  Heartbeat  configuration
+
+heartbeat?:  {
+
+enabled?:  boolean; //  Default:  false
+
+interval?:  number; //  Default:  30000 (ms)
+
+message?:  any; //  Default:  'ping'
+
+};
+
+//  Message  queue  for  offline  mode
+
+messageQueue?:  {
+
+enabled?:  boolean; //  Default:  true
+
+maxSize?:  number; //  Default:  100
+
+};
+
+debug?:  boolean; //  Default:  false
+
 }
 
-💡 Real-World Examples
-1. Live Chat Application
-jsx
+  ```
+
+### 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;
 
-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) => {
-    emit('chat-message', { text, timestamp: Date.now() });
-  };
-
-  // ... render messages and input
 }
 
-2. Live Dashboard
-jsx
+  ```
+
+## 💡  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) => {
+
+emit('chat-message',  {  text,  timestamp:  Date.now() });
+
+};
+
+  
+
+//  ...  render  messages  and  input
 
-function LiveDashboard() {
-  const [stats, setStats] = useState({});
-  const { subscribe } = useRealtime({
-    url: 'wss://api.example.com/live',
-    heartbeat: { enabled: true, interval: 15000 },
-  });
-
-  useEffect(() => {
-    const unsubscribe = subscribe('stats-update', (data) => {
-      setStats(data);
-    });
-    return unsubscribe;
-  }, [subscribe]);
-
-  // ... render dashboard with stats
 }
 
-🔧 Advanced Usage
-Manual Connection Control
+  ```
+
+### 2.  Live  Dashboard
+
 jsx
+```jsx
+  
+
+function  LiveDashboard() {
+
+const [stats, setStats]  =  useState({});
+
+const  {  subscribe  }  =  useRealtime({
+
+url:  'wss://api.example.com/live',
+
+heartbeat:  {  enabled:  true,  interval:  15000  },
 
-const { connect, disconnect, reconnect, isConnected } = useRealtime({
-  url: 'wss://example.com',
-  autoConnect: false, // Disable auto-connect
 });
 
-// Connect manually
+  
+
 useEffect(() => {
-  connect();
+
+const  unsubscribe  =  subscribe('stats-update', (data) => {
+
+setStats(data);
+
+});
+
+return  unsubscribe;
+
+}, [subscribe]);
+
+  
+
+//  ...  render  dashboard  with  stats
+
+}
+
+ ``` 
+
+### 🔧  Advanced  Usage
+
+### Manual  Connection  Control
+
+``` jsx
+const  {  connect,  disconnect,  reconnect,  isConnected  }  =  useRealtime({
+
+url:  'wss://example.com',
+
+autoConnect:  false,  //  Disable  auto-connect
+
+});
+
+  
+
+//  Connect  manually
+
+useEffect(() => {
+
+connect();
+
 }, [connect]);
 
-// Disconnect after 30 seconds
+  
+
+//  Disconnect  after  30  seconds
+
 useEffect(() => {
-  const timer = setTimeout(() => {
-    if (isConnected) disconnect();
-  }, 30000);
-  return () => clearTimeout(timer);
+
+const  timer  =  setTimeout(() => {
+
+if (isConnected) disconnect();
+
+},  30000);
+
+return () => clearTimeout(timer);
+
 }, [disconnect, isConnected]);
 
-Message Queue (Offline Mode)
-jsx
+  ```
+
+### Message  Queue (Offline Mode)
+
+```jsx
+
+  
+
+const  {  emit,  getQueueSize,  flushQueue  }  =  useRealtime({
+
+url:  'wss://example.com',
+
+messageQueue:  {
+
+enabled:  true,
+
+maxSize:  50,  //  Queue  up  to  50  messages
+
+},
 
-const { emit, getQueueSize, flushQueue } = useRealtime({
-  url: 'wss://example.com',
-  messageQueue: {
-    enabled: true,
-    maxSize: 50, // Queue up to 50 messages
-  },
 });
 
-// Messages are automatically queued when offline
-// and sent when connection is restored
-emit('important-event', { data: 'will not be lost' });
+  
+
+//  Messages  are  automatically  queued  when  offline
 
-// Check queue size
-console.log('Queued messages:', getQueueSize());
+//  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
 
-// Clear queue if needed
 flushQueue();
+```
+  
 
-🐛 Troubleshooting
-Common Issues
+### 🐛  Troubleshooting
 
-    CORS Errors with Local Development
-    javascript
+Common  Issues
 
-// Ensure your WebSocket server allows connections from your origin
-// For testing, use a public echo server:
-url: 'wss://echo.websocket.org'
+  
+
+CORS Errors with Local Development
 
-Connection Drops Frequently
 javascript
+```jsx 
 
-// Enable heartbeat to keep connection alive
-heartbeat: {
-  enabled: true,
-  interval: 15000, // Send ping every 15 seconds
-}
+//  Ensure  your  WebSocket  server  allows  connections  from  your  origin
 
-Too Many Reconnect Attempts
-javascript
+//  For  testing,  use  a  public  echo  server:
 
-// Limit reconnect attempts
-reconnectAttempts: 5,
-reconnectInterval: 5000, // Wait 5 seconds between attempts
+url:  'wss://echo.websocket.org'
 
-🤝 Contributing
+  
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Connection  Drops  Frequently
 
-    Fork the repository
+javascript
 
-    Create your feature branch (git checkout -b feature/AmazingFeature)
+  
 
-    Commit your changes (git commit -m 'Add some AmazingFeature')
+//  Enable  heartbeat  to  keep  connection  alive
 
-    Push to the branch (git push origin feature/AmazingFeature)
+heartbeat:  {
 
-    Open a Pull Request
+enabled:  true,
 
-📄 License
+interval: 15000, // Send ping every 15 seconds
 
-This project is licensed under the MIT License - see the LICENSE file for details.
-⭐ Support
+}
+```
+  
 
-If you find this package useful, please consider:
+### Too  Many  Reconnect  Attempts
 
-    Giving it a star on GitHub
+javascript
+```jsx 
+//  Limit  reconnect  attempts
 
-    Sharing it with your colleagues
+reconnectAttempts:  5,
 
-    Reporting bugs or suggesting features
+reconnectInterval:  5000,  //  Wait  5  seconds  between  attempts
+```
+  
 
-🔗 Links
 
-    GitHub Repository
+  
 
-    npm Package
 
-    Issue Tracker

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-realtime",
-  "version": "1.0.1",
+  "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",