@inno-isw/sse-hooks

TanStack-like React hooks for Server-Sent Events (SSE). Makes real-time streaming as easy as REST.

Installation

npm install @inno-isw/sse-hooks
# or
pnpm add @inno-isw/sse-hooks

Quick Start

import { SSEProvider, createSSEClient, useSSE } from '@inno-isw/sse-hooks';

// 1. Create a client (like QueryClient)
const sseClient = createSSEClient({
  baseURL: 'https://api.example.com',
  headers: () => ({
    Authorization: `Bearer ${getToken()}`,
  }),
});

// 2. Wrap your app (like QueryClientProvider)
function App() {
  return (
    <SSEProvider client={sseClient}>
      <MeterStatus />
    </SSEProvider>
  );
}

// 3. Use the hook (like useQuery)
function MeterStatus() {
  const { data, isConnected, error } = useSSE<MeterData>({
    url: '/api/v1/meters/stream',
    params: { groupId: '42' },
    enabled: !!groupId,
  });

  if (error) return <div>Error: {error.message}</div>;
  if (!isConnected) return <div>Connecting...</div>;

  return <div>Meters Online: {data?.onlineCount}</div>;
}

API Reference

createSSEClient(config)

Creates a configured SSE client.

const client = createSSEClient({
  baseURL: 'https://api.example.com',    // Base URL for all requests
  headers: { 'X-API-Key': 'key' },       // Static headers
  // or dynamic headers:
  headers: () => ({ Authorization: getToken() }),
  reconnect: true,                        // Enable auto-reconnect (default: true)
  reconnectInterval: 1000,                // Base reconnect interval in ms (default: 1000)
  maxReconnectAttempts: 10,               // Max retry attempts (default: 10)
  withCredentials: false,                 // Include cookies (default: false)
});

useSSE<T>(options)

Main hook for SSE connections.

const {
  data,           // Latest data received (T | null)
  status,         // 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'error'
  error,          // Error object if status is 'error'
  isConnected,    // true when status === 'connected'
  isConnecting,   // true when status === 'connecting'
  isReconnecting, // true when status === 'reconnecting'
  isError,        // true when status === 'error'
  isIdle,         // true when status === 'idle'
  reconnectCount, // Number of reconnection attempts
  disconnect,     // Function to manually disconnect
  reconnect,      // Function to manually reconnect
} = useSSE<MeterData>({
  url: '/stream',                        // Endpoint path (required)
  params: { id: '123' },                 // Query parameters
  enabled: true,                         // Enable/disable connection (default: true)
  eventName: 'update',                   // Filter by SSE event name
  headers: { 'X-Custom': 'value' },      // Additional headers for this connection
  onMessage: (data) => {},               // Callback on each message
  onError: (error) => {},                // Callback on error
  onOpen: () => {},                      // Callback on connection open
  onClose: () => {},                     // Callback on connection close
  select: (raw) => raw.transformed,      // Transform incoming data
  reconnect: true,                       // Override client reconnect setting
  reconnectInterval: 2000,               // Override client interval
  maxReconnectAttempts: 5,               // Override client max attempts
});

SSEProvider

Context provider for SSEClient.

<SSEProvider client={sseClient}>
  {children}
</SSEProvider>

useSSEClient()

Access the SSE client from context.

const client = useSSEClient();
const url = client.buildURL('/stream', { id: '123' });

Without Provider

You can use useSSE without a provider by passing full URLs:

const { data } = useSSE({
  url: 'https://api.example.com/stream',
  headers: { Authorization: 'Bearer token' },
});

Features

• TypeScript-first: Full type safety with generics
• Auto-reconnect: Exponential backoff with jitter
• Dynamic headers: Support for auth token refresh
• Event filtering: Subscribe to specific SSE event names
• Data transformation: select function like TanStack Query
• Manual control: disconnect() and reconnect() functions
• Lightweight: ~3KB gzipped

License

MIT