Skip to the content

liveConnection

The state of the subscription socket, readable and drivable. 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.
Relay

When to use

Use when
  • 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.
Avoid when
  • you only read data: subscriptionLiveState hides the socket;
  • the environment has no useSubscription: the connection stays idle.

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
Scrolls sideways inside the table. The page does not.

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
Scrolls sideways inside the table. The page does not.

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.

See also