use-throttled-stream
v1.0.0
Published
React hook that batches high-frequency streams (WebSocket, SSE, any subscribe function) into throttled state updates — append window, latest value or custom reducer. Keeps UIs smooth at thousands of messages per second.
Maintainers
Readme
use-throttled-stream
Render fast WebSocket / SSE streams without freezing React.
Calling setState for every message (hundreds per second) makes React re-render hundreds of times per second. This hook buffers messages and flushes them as one batched update per interval, with a sliding window, a "latest value" mode, or your own reducer.
import { useThrottledStream } from 'use-throttled-stream';
function LiveTrades({ socket }: { socket: WebSocket }) {
const { data: trades, stats } = useThrottledStream<Trade>(socket, { interval: 100, maxItems: 200 });
return (
<>
<small>{stats.received} messages, {stats.flushes} renders</small>
<TradeTable rows={trades} />
</>
);
}Install
npm install use-throttled-streamSources
WebSocket,EventSource,BroadcastChannel,Worker— anything withaddEventListener('message'). String payloads areJSON.parsed (falls back to the raw string); override withparse.- A subscribe function —
(emit) => unsubscribe, e.g. Socket.IO, Firebase, MQTT:
useThrottledStream<Order>((emit) => {
socket.on('order', emit);
return () => socket.off('order', emit);
});null— and callpush()yourself.
Modes
// append (default): sliding window of the newest `maxItems`
const { data } = useThrottledStream<LogLine>(ws, { maxItems: 1000 }); // LogLine[]
// latest: only the newest message
const { data } = useThrottledStream<Price>(ws, { mode: 'latest' }); // Price | undefined
// reduce: fold each batch into state
const { data } = useThrottledStream<Tick, Record<string, Tick>>(ws, {
mode: 'reduce',
initialState: {},
reducer: (state, batch) => ({ ...state, ...Object.fromEntries(batch.map((t) => [t.symbol, t])) }),
});Options
| Option | Default | Description |
| --- | --- | --- |
| interval | 100 | Max one flush per N ms. 0 = once per animation frame |
| mode | 'append' | 'append' \| 'latest' \| 'reduce' |
| maxItems | 1000 | Window size (append) |
| reducer, initialState | – | Required for reduce |
| parse | JSON with fallback | Convert event.data |
| filter | – | Drop messages |
| enabled | true | Pause listening |
Returns { data, push(...messages), flush(), clear(), stats: { received, flushes, lastBatch } }.
The first message after a quiet period is shown immediately (leading edge); bursts are grouped.
License
MIT
