use-stream-peers

(no submodules)

Purpose

useStreamPeers returns the live remote-peer roster as a stable readonly Peer[]. Each peer entry carries the participant id, display name, transport connection state, and the latest measured round-trip time in milliseconds. The hook is the canonical source of peer data for any UI that renders a participant list, a per-peer mixer strip, or a per-peer level meter, and it re-evaluates whenever the provider's render-bump version ticks.

The hook is intentionally a thin projection — it does not own selection, sorting, or filtering. Consumers compose their own derived state on top with useMemo.

Features

Stable array identity across renders when peers have not changed.
Re-renders on peers-changed, state-changed, and every other session event channel via the provider's render-bump counter.
Throws REACT_AUDIO_STREAM.NO_PROVIDER when used without a <StreamProvider>.

Usage: Basic

const peers = useStreamPeers();
return (
    <ul>
        {peers.map((p) => (
            <li key={p.id}>{p.displayName} ({p.rttMs} ms)</li>
        ))}
    </ul>
);

Usage: Advanced

const peers = useStreamPeers();
const sorted = useMemo(
    () => [...peers].sort((a, b) => a.displayName.localeCompare(b.displayName)),
    [peers]
);
const slow = sorted.filter((p) => p.rttMs > 150);

API Reference

useStreamPeers(): readonly Peer[] — see Peer in session/session-shape/session-shape.types.ts.

Implementation Notes

The implementation memoises against the provider's version counter, which is the only legitimate invalidation signal — components must not depend on the peer array's internal identity for invalidation because the session is free to reuse the same array across mutations (for example when only RTT changed). The version-counter approach is intentionally over-eager: re-deriving an array reference is O(1) and matches the package-wide pattern.

2.0 KiB Raw Permalink Blame History