liveConnection
CreateRelayEnvironment feeds it from its
graphql-ws client, so a screen can say "Connected", "Reconnecting in 4 s" or offer "Retry now" without
owning a second client. It is the connection, not the data: payloads still arrive through Relay.When to use
- a screen shows whether live updates are on, retrying or refused;
- the app needs "retry now", sign-out closing, or a socket dropped when pings stop;
- a subscription ended and the screen should say why.
- you only read data:
subscriptionLiveStatehides the socket; - the environment has no
useSubscription: the connection staysidle.
Usage
import { CreateRelayEnvironment, useLiveConnection } from '@apollion-dsi/relay';
const { Environment, connection } = new CreateRelayEnvironment({
url: 'https://api.example.com/graphql/',
socket: 'wss://api.example.com/graphql/',
useSubscription: true,
subscriptionClient: { retryAttempts: Infinity, shouldRetry: () => true },
});
const { state, retry } = useLiveConnection(connection);connection.subscribe and connection.getSnapshot also fit useSyncExternalStore as they are.
Reading
getSnapshot() returns the same object until a field changes.
Field | Meaning |
|---|---|
state | connecting, live, idle (no socket, or it stopped) or error (failed or refused) |
generation | Increases on every reconnect(). List it as a dependency to subscribe again |
recovered | Increases each time the socket is back after a drop: say "Connected" and read again |
dropped | The socket dropped and is not back yet |
refused | The protocol refused the socket (close code 4400 up). The client gives up instead of waiting |
retry | { attempt, delayMs, since } while a wait is pending, else null. delayMs is null with a custom retryWait |
Driving
Call | Does |
|---|---|
reconnect() | "Retry now": ends a pending wait, else drops the socket so the client opens a fresh one |
terminate() | Drops the socket abruptly, for a host that stopped answering pings. The client opens it again |
dispose() | Closes the client for good (sign-out, token change). The next subscription creates a new client |
The client is still disposed by itself when the last subscriber leaves, and connectionParams still sends the
Bearer token on every connect.
Client policy
subscriptionClient passes retryAttempts, shouldRetry, keepAlive, lazyCloseTimeout and on to
graphql-ws. The wait between attempts is retryDelay(retries) in ms, which the package waits and shows as
retry, or a full retryWait(retries). on handlers run after the connection is updated.
Why a subscription ended
A subscription the server refuses, or that the socket ends, reaches Relay's onError as a SubscriptionError:
message, code (the first extensions.code), errors (the GraphQL errors), and closeCode / reason for a
close. Any other Error passes through unchanged.