Add WebSocket.connect as a cross-platform connection method (#1149)

Author: brianquinlan

pkgs/web_socket/README.md

@@ -7,12 +7,11 @@ implementations.
 ## Using
 
 ```dart
-import 'package:web_socket/io_web_socket.dart';
 import 'package:web_socket/web_socket.dart';
 
 void main() async {
   final socket =
-      await IOWebSocket.connect(Uri.parse('wss://ws.postman-echo.com/raw'));
+      await WebSocket.connect(Uri.parse('wss://ws.postman-echo.com/raw'));
 
   socket.events.listen((e) async {
     switch (e) {

pkgs/web_socket/example/web_socket_example.dart

@@ -1,7 +1,6 @@
 import 'dart:convert';
 import 'dart:io';
 
-import 'package:web_socket/io_web_socket.dart';
 import 'package:web_socket/web_socket.dart';
 
 const requestId = 305;
@@ -11,7 +10,7 @@ void main() async {
   // Whitebit public WebSocket API documentation:
   // https://docs.whitebit.com/public/websocket/
   final socket =
-      await IOWebSocket.connect(Uri.parse('wss://api.whitebit.com/ws'));
+      await WebSocket.connect(Uri.parse('wss://api.whitebit.com/ws'));
 
   socket.events.listen((e) {
     switch (e) {

pkgs/web_socket/lib/src/browser_web_socket.dart

@@ -18,7 +18,8 @@ class BrowserWebSocket implements WebSocket {
   final web.WebSocket _webSocket;
   final _events = StreamController<WebSocketEvent>();
 
-  static Future<BrowserWebSocket> connect(Uri url) async {
+  static Future<BrowserWebSocket> connect(Uri url,
+      {Iterable<String>? protocols}) async {
     final webSocket = web.WebSocket(url.toString())..binaryType = 'arraybuffer';
     final browserSocket = BrowserWebSocket._(webSocket);
     final webSocketConnected = Completer<BrowserWebSocket>();
@@ -126,3 +127,5 @@ class BrowserWebSocket implements WebSocket {
   @override
   Stream<WebSocketEvent> get events => _events.stream;
 }
+
+const connect = BrowserWebSocket.connect;

pkgs/web_socket/lib/src/connect_stub.dart

@@ -0,0 +1,9 @@
+// Copyright (c) 2024, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import '../web_socket.dart';
+
+Future<WebSocket> connect(Uri url, {Iterable<String>? protocols}) {
+  throw UnsupportedError('Cannot connect without dart:js_interop or dart:io.');
+}

pkgs/web_socket/lib/src/io_web_socket.dart

@@ -16,9 +16,10 @@ class IOWebSocket implements WebSocket {
   final io.WebSocket _webSocket;
   final _events = StreamController<WebSocketEvent>();
 
-  static Future<IOWebSocket> connect(Uri uri) async {
+  static Future<IOWebSocket> connect(Uri url,
+      {Iterable<String>? protocols}) async {
     try {
-      final webSocket = await io.WebSocket.connect(uri.toString());
+      final webSocket = await io.WebSocket.connect(url.toString());
       return IOWebSocket._(webSocket);
     } on io.WebSocketException catch (e) {
       throw WebSocketException(e.message);
@@ -90,3 +91,5 @@ class IOWebSocket implements WebSocket {
   @override
   Stream<WebSocketEvent> get events => _events.stream;
 }
+
+const connect = IOWebSocket.connect;

pkgs/web_socket/lib/src/web_socket.dart

@@ -4,6 +4,10 @@
 
 import 'dart:typed_data';
 
+import 'connect_stub.dart'
+    if (dart.library.js_interop) 'browser_web_socket.dart'
+    if (dart.library.io) 'io_web_socket.dart' as connector;
+
 /// An event received from the peer through the [WebSocket].
 sealed class WebSocketEvent {}
 
@@ -90,12 +94,11 @@ class WebSocketConnectionClosed extends WebSocketException {
 /// The interface for WebSocket connections.
 ///
 /// ```dart
-/// import 'package:web_socket/io_web_socket.dart';
 /// import 'package:web_socket/src/web_socket.dart';
 ///
 /// void main() async {
 ///   final socket =
-///       await IOWebSocket.connect(Uri.parse('wss://ws.postman-echo.com/raw'));
+///       await WebSocket.connect(Uri.parse('wss://ws.postman-echo.com/raw'));
 ///
 ///   socket.events.listen((e) async {
 ///     switch (e) {
@@ -112,6 +115,9 @@ class WebSocketConnectionClosed extends WebSocketException {
 ///   socket.sendText('Hello Dart WebSockets! 🎉');
 /// }
 abstract interface class WebSocket {
+  static Future<WebSocket> connect(Uri url, {Iterable<String>? protocols}) =>
+      connector.connect(url, protocols: protocols);
+
   /// Sends text data to the connected peer.
   ///
   /// Throws [WebSocketConnectionClosed] if the [WebSocket] is

pkgs/web_socket/test/browser_web_socket_conformance_test.dart

@@ -10,5 +10,5 @@ import 'package:web_socket/browser_web_socket.dart';
 import 'package:web_socket_conformance_tests/web_socket_conformance_tests.dart';
 
 void main() {
-  testAll((uri, {protocols}) => BrowserWebSocket.connect(uri));
+  testAll(BrowserWebSocket.connect);
 }

pkgs/web_socket/test/io_web_socket_conformance_test.dart

@@ -10,5 +10,5 @@ import 'package:web_socket/io_web_socket.dart';
 import 'package:web_socket_conformance_tests/web_socket_conformance_tests.dart';
 
 void main() {
-  testAll((uri, {protocols}) => IOWebSocket.connect(uri));
+  testAll(IOWebSocket.connect);
 }

pkgs/web_socket/test/websocket_test.dart

@@ -0,0 +1,10 @@
+// Copyright (c) 2024, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:web_socket/web_socket.dart';
+import 'package:web_socket_conformance_tests/web_socket_conformance_tests.dart';
+
+void main() {
+  testAll(WebSocket.connect);
+}