use-realtime 1.0.0 → 1.0.1

package/README.md

@@ -1,222 +1,282 @@
-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 🚀
 
-Stop rewriting WebSocket boilerplate in every React project
-</div>
+[![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/)
 
-✨ Why use-realtime?
+**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.
 
-Building real-time features in React usually means:
+---
 
-    🔄 Rewriting WebSocket logic again and again
+## ✨ Features
 
-    🔌 Handling reconnects manually (and often incorrectly)
+- **🔌 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
 
-    📨 Losing messages when the connection drops
+---
 
-    🧹 Managing event listeners and cleanup yourself
+## 📦 Installation
 
-use-realtime solves these problems for you.
-
-
-
-🚀 Features
+```bash
+npm install use-realtime
 
-✅ 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
+or
+bash
 
+yarn add use-realtime
 
-📦 Installation
+or
+bash
 
-npm install use-realtime
-# or
-yarn add use-realtime
-# or
 pnpm add use-realtime
 
-⚡ Quick Start
+🚀 Quick Start
+jsx
+
+import React, { useEffect } from 'react';
 import { useRealtime } from 'use-realtime';
 
-function Chat() {
+function ChatComponent() {
   const { emit, subscribe, isConnected } = useRealtime({
-    url: 'wss://example.com/ws',
+    url: 'wss://your-server.com/ws',
     autoReconnect: true,
   });
 
-  // Subscribe to events
   useEffect(() => {
-    const unsubscribe = subscribe('chat', (message) => {
-      console.log('New message:', message);
+    const unsubscribe = subscribe('message', (data) => {
+      console.log('New message:', data);
     });
-    return unsubscribe;
+    
+    return unsubscribe; // Cleanup on unmount
   }, [subscribe]);
 
+  const sendMessage = () => {
+    emit('chat', { text: 'Hello World!', user: 'You' });
+  };
+
   return (
-    <button onClick={() => emit('chat', { text: 'Hello!' })}>
-      Send Message
-    </button>
+    <div>
+      <p>Status: {isConnected ? '✅ Connected' : '❌ Disconnected'}</p>
+      <button onClick={sendMessage} disabled={!isConnected}>
+        Send Message
+      </button>
+    </div>
   );
 }
 
-🧠 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)
-});
-
-
-📡 Sending Messages
-emit(event, data)
-
-Send a named event. If the socket is not connected, the message is queued automatically.
-emit('notification', { title: 'New order' });
-
-
-send(data)
-
-Send a raw message (no event name).
-
-send({ ping: true });
-
+📖 Documentation
+Configuration Options
+typescript
 
-🔔 Subscribing to Events
-subscribe(event, callback)
-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
+}
 
-const unsubscribe = subscribe('order:update', (data) => {
-  console.log(data);
-});
+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
 
-// Always unsubscribe on cleanup
-useEffect(() => {
-  const unsubscribe = subscribe('event', handler);
-  return unsubscribe;
-}, [subscribe]);
+interface ConnectionState {
+  connected: boolean;
+  connecting: boolean;
+  reconnecting: boolean;
+  error: Error | null;
+  lastMessageAt: Date | null;
+  connectionId: string | null;
+}
 
-🔌 Connection State
+💡 Real-World Examples
+1. Live Chat Application
 jsx
 
-const {
-  isConnected,      // boolean - Connection is active
-  isConnecting,     // boolean - Connection in progress
-  isReconnecting,   // boolean - Reconnection in progress
-  connection,       // Full connection object
-} = useRealtime(...);
+function ChatRoom() {
+  const [messages, setMessages] = useState([]);
+  const { subscribe, emit, isConnected } = useRealtime({
+    url: 'wss://chat-server.com/ws',
+    autoReconnect: true,
+    reconnectAttempts: 5,
+  });
 
-connection includes:
+  useEffect(() => {
+    const unsubscribe = subscribe('chat-message', (msg) => {
+      setMessages(prev => [...prev, msg]);
+    });
+    return unsubscribe;
+  }, [subscribe]);
 
-    connected - Connection is active
+  const sendMessage = (text) => {
+    emit('chat-message', { text, timestamp: Date.now() });
+  };
 
-    connecting - Connection in progress
+  // ... render messages and input
+}
 
-    reconnecting - Reconnection in progress
+2. Live Dashboard
+jsx
 
-    error - Last error that occurred
+function LiveDashboard() {
+  const [stats, setStats] = useState({});
+  const { subscribe } = useRealtime({
+    url: 'wss://api.example.com/live',
+    heartbeat: { enabled: true, interval: 15000 },
+  });
 
-    lastMessageAt - Timestamp of last message
+  useEffect(() => {
+    const unsubscribe = subscribe('stats-update', (data) => {
+      setStats(data);
+    });
+    return unsubscribe;
+  }, [subscribe]);
 
-    connectionId - Unique connection identifier
+  // ... render dashboard with stats
+}
 
-🔄 Manual Control
+🔧 Advanced Usage
+Manual Connection Control
 jsx
 
-const { connect, disconnect, reconnect } = useRealtime(...);
-
-connect();     // Manually connect
-disconnect();  // Close connection safely
-reconnect();   // Force reconnect
-
-📦 Message Queue Utilities
-jsx
+const { connect, disconnect, reconnect, isConnected } = useRealtime({
+  url: 'wss://example.com',
+  autoConnect: false, // Disable auto-connect
+});
 
-const { getQueueSize, flushQueue } = useRealtime(...);
+// Connect manually
+useEffect(() => {
+  connect();
+}, [connect]);
 
-getQueueSize();   // Number of queued messages
-flushQueue();     // Clear queued messages
+// Disconnect after 30 seconds
+useEffect(() => {
+  const timer = setTimeout(() => {
+    if (isConnected) disconnect();
+  }, 30000);
+  return () => clearTimeout(timer);
+}, [disconnect, isConnected]);
 
-🧹 Cleanup & Safety
+Message Queue (Offline Mode)
+jsx
 
-✅ Automatically closes WebSocket on unmount
-✅ Prevents duplicate connections
-✅ Prevents reconnect loops
-✅ Prevents memory leaks
+const { emit, getQueueSize, flushQueue } = useRealtime({
+  url: 'wss://example.com',
+  messageQueue: {
+    enabled: true,
+    maxSize: 50, // Queue up to 50 messages
+  },
+});
 
-Safe to use in:
+// Messages are automatically queued when offline
+// and sent when connection is restored
+emit('important-event', { data: 'will not be lost' });
 
-    React
+// Check queue size
+console.log('Queued messages:', getQueueSize());
 
-    Next.js
+// Clear queue if needed
+flushQueue();
 
-    Vite
+🐛 Troubleshooting
+Common Issues
 
-    CRA
+    CORS Errors with Local Development
+    javascript
 
-    Any React 16.8+ environment
+// Ensure your WebSocket server allows connections from your origin
+// For testing, use a public echo server:
+url: 'wss://echo.websocket.org'
 
-🧩 TypeScript Support
+Connection Drops Frequently
+javascript
 
-Fully typed and tree-shakable:
-typescript
+// Enable heartbeat to keep connection alive
+heartbeat: {
+  enabled: true,
+  interval: 15000, // Send ping every 15 seconds
+}
 
-import { useRealtime } from 'use-realtime';
-import type {
-  RealtimeOptions,
-  ConnectionState,
-  UseRealtimeReturn
-} from 'use-realtime';
+Too Many Reconnect Attempts
+javascript
 
-🧑‍💻 When should I use this?
+// Limit reconnect attempts
+reconnectAttempts: 5,
+reconnectInterval: 5000, // Wait 5 seconds between attempts
 
-Perfect for:
+🤝 Contributing
 
-    💬 Chat applications
+Contributions are welcome! Please feel free to submit a Pull Request.
 
-    🔔 Live notifications
+    Fork the repository
 
-    📊 Dashboards
+    Create your feature branch (git checkout -b feature/AmazingFeature)
 
-    🎮 Multiplayer features
+    Commit your changes (git commit -m 'Add some AmazingFeature')
 
-    📡 Real-time feeds
+    Push to the branch (git push origin feature/AmazingFeature)
 
-    🏢 Admin panels
+    Open a Pull Request
 
-    🔧 IoT dashboards
+📄 License
 
-    📈 Live analytics
+This project is licensed under the MIT License - see the LICENSE file for details.
+⭐ Support
 
-📄 License
+If you find this package useful, please consider:
 
-MIT — free for personal and commercial use. See LICENSE for details.
-<div align="center">
+    Giving it a star on GitHub
 
+    Sharing it with your colleagues
 
+    Reporting bugs or suggesting features
 
+🔗 Links
 
+    GitHub Repository
 
+    npm Package
 
+    Issue Tracker

package/package.json

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