Honeydrop 🍯

The Developer-Friendly Socket.IO Helper

Simplify your real-time applications. Effortless connection management, automatic reconnection, and powerful utilities for Socket.IO.

Installation • Quick Start • Features • API Reference • Contributing

💡 Motivation

Building robust Socket.IO applications often involves repetitive boilerplate: managing room joins, handling reconnections gracefully, queuing events when the network drops, and implementing retry logic.

Honeydrop handles this complexity for you. It wraps the standard socket.io-client with a powerful, developer-friendly API that makes your real-time code cleaner, more reliable, and easier to maintain.

✨ Features

• 🔌 Effortless Connection Management: Simple API to connect, disconnect, and monitor health.
• 🎯 Smart Event Handling: Auto-cleanup of listeners on disconnect.
• 🔄 Robust Reconnection: Configurable strategies (linear/exponential backoff) with hooks.
• 📛 Namespacing Made Easy: Organize your events into logical channels (chat:message, game:score).
• ⚡ Powerful Utilities: Multi-emit, multi-listen, throttle, debounce, and specific event waiting.
• 📦 Offline Queue: Automatically queue events when disconnected and flush them on reconnect.
• 🔗 Middleware System: Intercept and transform events before emit or after receive.
• ⌨️ Typing Indicators: Built-in utility for chat "user is typing..." with auto-debounce.
• ⚛️ React Hooks: First-class React support with useSocketEvent, useSocketEmit, useRoom, and more.
• 🐛 Dev-Friendly: Built-in debug logging and full TypeScript support.

📦 Installation

[!IMPORTANT] Run the following command to install the package:

npm install honeydrop

Note: socket.io-client is a peer dependency and will be installed if not present.

🚀 Quick Start

Here's how easy it is to get started:

import Honeydrop from 'honeydrop';

// 1. Initialize the client
const client = new Honeydrop('http://localhost:3000', {
  autoConnect: true,
  debug: true
});

// 2. Listen for events
client.on('message', (data) => {
  console.log('Received:', data);
});

// 3. Emit events (even if currently disconnected!)
client.emit('chat:message', { text: 'Hello, World!' });

// 4. Cleanup when done
// client.disconnect();

📖 API Reference

Client Configuration

new Honeydrop(url, {
  debug: false,               // Enable debug logs
  autoConnect: true,          // Connect immediately
  reconnection: {             // Reconnection strategy
    enabled: true,
    maxAttempts: 10,
    strategy: 'exponential'   // 'linear' | 'exponential'
  },
  offlineQueue: {             // Offline behavior
    enabled: true,
    maxSize: 100
  }
})

Core Methods

| Method | Description | |--------|-------------| | connect() | Manually connect to the server. | | disconnect() | Disconnect and clean up all listeners. | | reconnect() | Force a manual reconnection attempt. | | setDebug(bool) | Toggle debug logging at runtime. |

Event Handling

Honeydrop provides a rich API for event management:

// Standard listener
client.on('user:login', (user) => console.log(user));

// One-time listener
client.once('init', () => console.log('Initialized'));

// Remove listeners
client.off('user:login');

// Listen to MULTIPLE events with one handler
client.onMultiple(['connect', 'reconnect'], () => updateStatus('online'));

// Wait for a specific event (Promise-based)
const data = await client.waitFor('ready', 5000);

Emitting Events

Send data with confidence using advanced emit patterns:

// Standard emit
client.emit('update', data);

// Emit with Acknowledgment (Async/Await)
try {
  const response = await client.emitWithAck('createUser', userData, 5000);
} catch (err) {
  console.error('Server did not acknowledge in time');
}

// Emit with Automatic Retry
// Great for critical actions that must reach the server
await client.emitWithRetry('saveData', payload, {
  maxRetries: 3,
  retryDelay: 1000
});

// Throttled Emit (e.g., for mouse movement or window resize)
const updatePosition = client.throttle('cursor:move', 100);
updatePosition({ x: 10, y: 20 });

Namespaces

Organize your events into logical groups without creating multiple socket connections.

const chat = client.namespace('chat'); // prefixes events with 'chat:'

chat.emit('msg', 'hello');       // Emits 'chat:msg'
chat.on('typing', showTyping);   // Listens for 'chat:typing'

Room Management

Helper methods for room-based logic (requires server-side support for room events).

client.join('room-123');
client.toRoom('room-123').emit('announcement', 'Welcome!');
const inRoom = client.isInRoom('room-123'); // true

Middleware

Intercept events before they're emitted or after they're received. Perfect for logging, validation, or transformation.

// Log all outgoing events
client.use('emit', (event, data, next) => {
    console.log(`Sending: ${event}`, data);
    next(); // Continue with emit
});

// Block certain events
client.use('emit', (event, data, next, abort) => {
    if (event === 'spam') abort();
    else next();
});

// Intercept incoming events
client.use('receive', (event, data, next) => {
    console.log(`Received: ${event}`, data);
    next();
});

Typing Indicators

Built-in utility for chat applications with automatic debouncing and timeout.

const typing = client.typing({
    startEvent: 'typing:start',
    stopEvent: 'typing:stop',
    timeout: 3000
});

// Call when user types
inputField.addEventListener('input', () => typing.send());

// Track other users typing
typing.onUserTyping((userId) => showTypingBadge(userId));
typing.onUserStopped((userId) => hideTypingBadge(userId));

// Check who's typing
const typingUsers = typing.getTypingUsers();

⚛️ Using with React

Honeydrop provides first-class support for React with powerful hooks that handle lifecycle and cleanup for you.

Setup Provider

Wrap your app in the HoneydropProvider to make the client available throughout your component tree.

import { Honeydrop, HoneydropProvider } from 'honeydrop';

const client = new Honeydrop('http://localhost:3000');

function App() {
  return (
    <HoneydropProvider client={client}>
      <Dashboard />
    </HoneydropProvider>
  );
}

Hooks API

useSocketEvent

Listens for an event and automatically removes the listener when the component unmounts. No more useEffect boilerplate!

import { useSocketEvent } from 'honeydrop';

function LiveCounter() {
  // Listen for 'count:update' event
  useSocketEvent('count:update', (count) => {
    console.log('New count:', count);
  });

  return <div>Check console for updates</div>;
}

useSocketStatus

Easily track your connection status to show loading spinners or offline badges.

import { useSocketStatus } from 'honeydrop';

function ConnectionBadge() {
  const status = useSocketStatus(); // 'connected' | 'disconnected' | 'connecting'

  if (status === 'disconnected') {
    return <span style={{ color: 'red' }}>Offline</span>;
  }
  return <span style={{ color: 'green' }}>Online</span>;
}

useSocketEmit

Emit events with loading and error state management.

import { useSocketEmit } from 'honeydrop';

function SendMessage() {
  const { emit, isLoading, error } = useSocketEmit('chat:message');

  const handleSend = async () => {
    await emit({ text: 'Hello!' });
  };

  return (
    <button onClick={handleSend} disabled={isLoading}>
      {isLoading ? 'Sending...' : 'Send'}
    </button>
  );
}

useRoom

Automatically join/leave rooms with cleanup on unmount.

import { useRoom } from 'honeydrop';

function ChatRoom({ roomId }: { roomId: string }) {
  const room = useRoom(roomId);

  const sendMessage = () => {
    room.emit('message', { text: 'Hello room!' });
  };

  return <button onClick={sendMessage}>Send to Room</button>;
}

useLatency

Track connection latency and quality.

import { useLatency } from 'honeydrop';

function LatencyIndicator() {
  const { latency, quality } = useLatency();
  // quality: 'excellent' | 'good' | 'fair' | 'poor' | 'disconnected'

  return <span>{latency}ms ({quality})</span>;
}

useTypingIndicator

Manage typing indicators in React.

import { useTypingIndicator } from 'honeydrop';

function ChatInput() {
  const { sendTyping, typingUsers } = useTypingIndicator();

  return (
    <div>
      <input onInput={() => sendTyping()} />
      {typingUsers.length > 0 && (
        <span>{typingUsers.join(', ')} typing...</span>
      )}
    </div>
  );
}

🌐 Browser Support

Honeydrop works seamlessly in both Node.js and the Browser.

Using with Bundlers (Vite, Webpack, etc.)

import Honeydrop from 'honeydrop';

Using via CDN

<script src="https://cdn.socket.io/4.7.4/socket.io.min.js"></script>
<script src="https://unpkg.com/honeydrop/dist/honeydrop.umd.js"></script>
<script>
  const client = new Honeydrop.Honeydrop('http://localhost:3000');
</script>

🤝 Contributing

We welcome contributions! Please feel free to verify the correctness of your changes by running the demo app:

cd demo
npm install
npm start

📄 License

MIT License © 2026