steady-socket

Overview

steady-socket is a robust WebSocket client library designed to maintain a persistent connection for web applications and React Native environments. It addresses common issues encountered with WebSocket connections, such as disruptions caused by network changes and server restarts, by implementing intelligent reconnection strategies and subscription management.

Key Features

• Connection Resilience: steady-socket detects dead connections through heartbeats and automatically manages reconnections. It uses incrementing delays to prevent server overload during reconnection attempts.
• Subscription Management: The library ensures that client subscriptions to topics are reestablished automatically after reconnections, thus maintaining continuity of updates without manual intervention.
• Platform Agnostic: Functionality remains consistent across both web applications and React Native, simplifying code maintenance for developers working in hybrid environments.
• Lightweight and Dependency-Free: Core functionality is about 1.7 kB when minified and gzipped, and operates without external dependencies. It features strict TypeScript support and is published as both ESM and CommonJS.
• Flexible Lifecycle Management: It provides lifecycle hooks specifically for React Native’s AppState and browser events, efficiently managing the connection state based on the app’s status.

Usage Example

Here is a basic setup example to demonstrate how to create and manage a WebSocket connection using steady-socket:

import { createSocket } from 'steady-socket';

type Incoming = { type: 'pong' } | { type: 'event'; topic: string; payload: unknown };
type Outgoing = { type: 'ping' } | { type: 'subscribe' | 'unsubscribe'; topic: string };

const socket = createSocket<Incoming, Outgoing>({
  url: async () => `wss://api.example.com/ws?token=${await getToken()}`,
  heartbeat: {
    interval: 15000, // ping every 15 seconds
    timeout: 5000,   // close if no pong in 5 seconds
    ping: () => ({ type: 'ping' }),
    isPong: (msg) => msg.type === 'pong',
  },
  reconnect: {
    minDelay: 500,
    maxDelay: 30000,
    factor: 2,
    jitter: 'full',
  },
});

socket.connect();

Advanced Features

• State Management: Connection states are clearly defined (idle, connecting, open, reconnecting, closed), allowing developers to manage user interfaces based on connection status.
• Error Handling: Provides hooks for error tracking without disrupting connection flow, ensuring that malformed messages do not crash applications.
• Substantial Testing: Comes with tests that cover various scenarios, ensuring stability and performance even during edge cases such as silent connections or expired logins.

Live Demo

Explore a live demo at steady-socket web demo, where various connection scenarios can be tested interactively.

Conclusion

steady-socket provides a powerful, lightweight solution for applications relying on real-time data, ensuring reliability and easier development in both web and mobile platforms. Its thoughtful design allows developers to focus on building features rather than managing WebSocket complexities.