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';
 
@@ -52,6 +53,30 @@ class GraphQLClient implements GraphQLDataProxy {
 
   late final QueryManager queryManager;
 
+  /// Stream of [SocketConnectionState] changes for the underlying WebSocket connection.
+  ///
+  /// Returns `null` if the [link] is not a [WebSocketLink] 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
+  /// client.connectionState?.listen((state) {
+  ///   if (state == SocketConnectionState.notConnected) {
+  ///     // connection lost — refetch queries to get fresh data
+  ///   }
+  /// });
+  /// ```
+  Stream<SocketConnectionState>? get 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,

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,88 @@ 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 WebSocketLink',
+        () async {
+      final wsLink = WebSocketLink(
+        wsUrl,
+        config: SocketClientConfig(
+          delayBetweenReconnectionAttempts: const Duration(milliseconds: 1),
+          initialPayload: {'protocol': GraphQLProtocol.graphqlWs},
+        ),
+      );
+
+      final client = GraphQLClient(
+        link: 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;