feat: expose connectionState stream on WebSocketLink and GraphQLClient

Expose the underlying SocketClient's connectionState stream at the
WebSocketLink and GraphQLClient level, allowing users to detect when
a subscription connection is lost or restored. This enables refetching
stale data after reconnection.

Fixes #1188

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: vincenzopalazzo

packages/graphql/lib/src/graphql_client.dart

@@ -3,6 +3,7 @@ import 'dart:async';
 
 import 'package:graphql/src/core/core.dart';
 import 'package:graphql/src/cache/cache.dart';
+import 'package:graphql/src/links/websocket_link/websocket_link.dart';
 
 import 'package:graphql/src/core/fetch_more.dart';
 
@@ -23,6 +24,7 @@ class GraphQLClient implements GraphQLDataProxy {
   /// Constructs a [GraphQLClient] given a [Link] and a [Cache].
   GraphQLClient({
     required this.link,
+    this.websocketLink,
     required this.cache,
     DefaultPolicies? defaultPolicies,
     bool alwaysRebroadcast = false,
@@ -47,14 +49,55 @@ class GraphQLClient implements GraphQLDataProxy {
   /// The [Link] over which GraphQL documents will be resolved into a [Response].
   final Link link;
 
+  /// Optional [WebSocketLink] for subscription-aware clients that compose [link]
+  /// with helpers like `Link.split(...)`.
+  final WebSocketLink? websocketLink;
+
   /// The initial [Cache] to use in the data store.
   final GraphQLCache cache;
 
   late final QueryManager queryManager;
 
+  /// Stream of [SocketConnectionState] changes for the underlying WebSocket connection.
+  ///
+  /// Returns `null` if no [WebSocketLink] is configured or if the socket client
+  /// has not been initialized yet.
+  ///
+  /// This is useful for detecting when a subscription connection is lost or restored,
+  /// so that data can be refetched to ensure freshness.
+  ///
+  /// Example usage:
+  /// ```dart
+  /// final wsLink = WebSocketLink('ws://example.com/graphql');
+  /// final client = GraphQLClient(
+  ///   link: Link.split((request) => request.isSubscription, wsLink, httpLink),
+  ///   cache: GraphQLCache(),
+  ///   websocketLink: wsLink,
+  /// );
+  ///
+  /// client.connectionState?.listen((state) {
+  ///   if (state == SocketConnectionState.notConnected) {
+  ///     // connection lost — refetch queries to get fresh data
+  ///   }
+  /// });
+  /// ```
+  Stream<SocketConnectionState>? get connectionState {
+    final configuredLink = websocketLink;
+    if (configuredLink != null) {
+      return configuredLink.connectionState;
+    }
+
+    final l = link;
+    if (l is WebSocketLink) {
+      return l.connectionState;
+    }
+    return null;
+  }
+
   /// Create a copy of the client with the provided information.
   GraphQLClient copyWith({
     Link? link,
+    WebSocketLink? websocketLink,
     GraphQLCache? cache,
     DefaultPolicies? defaultPolicies,
     bool? alwaysRebroadcast,
@@ -65,6 +108,7 @@ class GraphQLClient implements GraphQLDataProxy {
   }) {
     return GraphQLClient(
       link: link ?? this.link,
+      websocketLink: websocketLink ?? this.websocketLink,
       cache: cache ?? this.cache,
       defaultPolicies: defaultPolicies ?? this.defaultPolicies,
       alwaysRebroadcast: alwaysRebroadcast ?? queryManager.alwaysRebroadcast,

packages/graphql/lib/src/links/websocket_link/websocket_link.dart

@@ -47,6 +47,23 @@ class WebSocketLink extends Link {
 
   SocketClient? get getSocketClient => _socketClient;
 
+  /// Stream of [SocketConnectionState] changes for the underlying WebSocket connection.
+  ///
+  /// Useful for detecting when a subscription connection is lost or restored.
+  /// Returns `null` if the socket client has not been initialized yet.
+  ///
+  /// Example usage:
+  /// ```dart
+  /// final wsLink = WebSocketLink('ws://example.com/graphql');
+  /// wsLink.connectionState?.listen((state) {
+  ///   if (state == SocketConnectionState.notConnected) {
+  ///     // connection lost, refetch data
+  ///   }
+  /// });
+  /// ```
+  Stream<SocketConnectionState>? get connectionState =>
+      _socketClient?.connectionState;
+
   /// Disposes the underlying socket client explicitly. Only use this, if you want to disconnect from
   /// the current server in favour of another one. If that's the case, create a new [WebSocketLink] instance.
   Future<void> dispose() async {

packages/graphql/test/websocket_test.dart

@@ -917,6 +917,95 @@ Future<void> main() async {
     */
   });
 
+  group('WebSocketLink connectionState', () {
+    test('exposes connectionState from underlying SocketClient', () async {
+      final wsLink = WebSocketLink(
+        wsUrl,
+        config: SocketClientConfig(
+          delayBetweenReconnectionAttempts: const Duration(milliseconds: 1),
+          initialPayload: {'protocol': GraphQLProtocol.graphqlWs},
+        ),
+      );
+
+      // Before connecting, connectionState is null
+      expect(wsLink.connectionState, isNull);
+
+      // Trigger connection by calling connectOrReconnect
+      wsLink.connectOrReconnect();
+
+      // Now connectionState should be available
+      expect(wsLink.connectionState, isNotNull);
+
+      // BehaviorSubject emits current state first (notConnected),
+      // then transitions through connecting -> connected
+      await expectLater(
+        wsLink.connectionState!,
+        emitsInOrder([
+          SocketConnectionState.notConnected,
+          SocketConnectionState.connecting,
+          SocketConnectionState.connected,
+        ]),
+      );
+
+      await wsLink.dispose();
+    });
+
+    test(
+        'GraphQLClient exposes connectionState when using Link.split with a WebSocketLink',
+        () async {
+      final wsLink = WebSocketLink(
+        wsUrl,
+        config: SocketClientConfig(
+          delayBetweenReconnectionAttempts: const Duration(milliseconds: 1),
+          initialPayload: {'protocol': GraphQLProtocol.graphqlWs},
+        ),
+      );
+      final mockLink = MockLink();
+
+      final client = GraphQLClient(
+        link: Link.split(
+          (request) => request.isSubscription,
+          wsLink,
+          mockLink,
+        ),
+        websocketLink: wsLink,
+        cache: GraphQLCache(),
+      );
+
+      // Before connecting, connectionState is null
+      expect(client.connectionState, isNull);
+
+      // Trigger connection
+      wsLink.connectOrReconnect();
+
+      // Now connectionState should be available
+      expect(client.connectionState, isNotNull);
+
+      // BehaviorSubject emits current state first (notConnected),
+      // then transitions through connecting -> connected
+      await expectLater(
+        client.connectionState!,
+        emitsInOrder([
+          SocketConnectionState.notConnected,
+          SocketConnectionState.connecting,
+          SocketConnectionState.connected,
+        ]),
+      );
+
+      await wsLink.dispose();
+    });
+
+    test('GraphQLClient connectionState is null for non-WebSocket links', () {
+      final mockLink = MockLink();
+      final client = GraphQLClient(
+        link: mockLink,
+        cache: GraphQLCache(),
+      );
+
+      expect(client.connectionState, isNull);
+    });
+  });
+
   group('SocketClient with dynamic payload', () {
     late SocketClient socketClient;