Deprecate the constructors for HtmlWebSocketChannel and IOWebSocketChannel

CHANGELOG.md

@@ -6,6 +6,10 @@
 - **BREAKING**: Make `WebSocketChannel` an `abstract interface`.
 - **BREAKING**: `IOWebSocketChannel.ready` will throw
   `WebSocketChannelException` instead of `WebSocketException`.
+- `HtmlWebSocketChannel.connect` is deprecated.
+- The `HtmlWebSocketChannel` constructor is deprecated.
+- `IOWebSocketChannel.connect` is deprecated.
+- The `IOWebSocketChannel` constructor is deprecated.
 
 ## 2.4.5
 

README.md

@@ -12,7 +12,7 @@ It provides a cross-platform
 that API that communicates over an underlying [`StreamChannel`][stream_channel],
 [an implementation][IOWebSocketChannel] that wraps `dart:io`'s `WebSocket`
 class, and [a similar implementation][HtmlWebSocketChannel] that wraps
-`dart:html`'s.
+`package:web`'s.
 
 [stream_channel]: https://pub.dev/packages/stream_channel
 [WebSocketChannel]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketChannel-class.html
@@ -27,7 +27,6 @@ import this library with the prefix `status`.
 
 ```dart
 import 'package:web_socket_channel/web_socket_channel.dart';
-import 'package:web_socket_channel/status.dart' as status;
 
 main() async {
   final wsUrl = Uri.parse('ws://example.com');
@@ -37,7 +36,7 @@ main() async {
 
   channel.stream.listen((message) {
     channel.sink.add('received!');
-    channel.sink.close(status.goingAway);
+    channel.sink.close();
   });
 }
 ```

example/example.dart

@@ -2,7 +2,6 @@
 // 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_channel/status.dart' as status;
 import 'package:web_socket_channel/web_socket_channel.dart';
 
 void main() async {
@@ -13,6 +12,6 @@ void main() async {
 
   channel.stream.listen((message) {
     channel.sink.add('received!');
-    channel.sink.close(status.goingAway);
+    channel.sink.close();
   });
 }

lib/html.dart

@@ -72,6 +72,7 @@ class HtmlWebSocketChannel extends StreamChannelMixin
   /// received by this socket. It defaults to [BinaryType.list], which causes
   /// binary messages to be delivered as [Uint8List]s. If it's
   /// [BinaryType.blob], they're delivered as [Blob]s instead.
+  @Deprecated('Use WebSocketChannel.connect() instead')
   HtmlWebSocketChannel.connect(Object url,
       {Iterable<String>? protocols, BinaryType? binaryType})
       : this(
@@ -85,6 +86,7 @@ class HtmlWebSocketChannel extends StreamChannelMixin
   ///
   /// The parameter [webSocket] should be either a dart:html `WebSocket`
   /// instance or a package:web [WebSocket] instance.
+  @Deprecated('Use WebSocketChannel.connect() instead')
   HtmlWebSocketChannel(Object /*WebSocket*/ webSocket)
       : innerWebSocket = webSocket as WebSocket {
     _readyCompleter = Completer();

lib/io.dart

@@ -33,6 +33,35 @@ class IOWebSocketChannel extends AdapterWebSocketChannel {
   ///
   /// If there's an error connecting, the channel's stream emits a
   /// [WebSocketChannelException] wrapping that error and then closes.
+  ///
+  /// **DEPRECATED**: Instead of using this method, use [IOWebSocket] with
+  /// [AdapterWebSocketChannel]. For example:
+  ///
+  /// ```dart
+  /// import 'dart:io' show WebSocket;
+  ///
+  /// import 'package:web_socket/io_web_socket.dart' show IOWebSocket;
+  /// import 'package:web_socket_channel/adapter_web_socket_channel.dart';
+  ///
+  /// void main() async {
+  ///   final ioWebSocket = await WebSocket.connect('<url>', protocols: [
+  ///     'chatV1',
+  ///     'chatV2',
+  ///   ], headers: {
+  ///     'authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV',
+  ///   }).timeout(const Duration(milliseconds: 500));
+  ///
+  ///   ioWebSocket.pingInterval = const Duration(seconds: 10);
+  ///
+  ///   final channel =
+  ///       AdapterWebSocketChannel(IOWebSocket.fromWebSocket(ioWebSocket));
+  ///
+  ///   await channel.ready;
+  ///
+  ///   // Use the `WebSocketChannel`.
+  /// }
+  /// ```
+  @Deprecated('Use IOWebSocket with AdapterWebSocketChannel')
   factory IOWebSocketChannel.connect(
     Object url, {
     Iterable<String>? protocols,
@@ -56,6 +85,36 @@ class IOWebSocketChannel extends AdapterWebSocketChannel {
   }
 
   /// Creates a channel wrapping [webSocket].
+  ///
+  /// **DEPRECATED**: Instead, use [IOWebSocket] with [AdapterWebSocketChannel].
+  ///
+  /// For example:
+  ///
+  /// ```dart
+  /// import 'dart:io' show WebSocket;
+  ///
+  /// import 'package:web_socket/io_web_socket.dart' show IOWebSocket;
+  /// import 'package:web_socket_channel/adapter_web_socket_channel.dart';
+  ///
+  /// void main() async {
+  ///   final ioWebSocket = await WebSocket.connect('<url>', protocols: [
+  ///     'chatV1',
+  ///     'chatV2',
+  ///   ], headers: {
+  ///     'authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV',
+  ///   }).timeout(const Duration(milliseconds: 500));
+  ///
+  ///   ioWebSocket.pingInterval = const Duration(seconds: 10);
+  ///
+  ///   final channel =
+  ///       AdapterWebSocketChannel(IOWebSocket.fromWebSocket(ioWebSocket));
+  ///
+  ///   await channel.ready;
+  ///
+  ///   // Use the `WebSocketChannel`.
+  /// }
+  /// ```
+  @Deprecated('Use IOWebSocket with AdapterWebSocketChannel')
   IOWebSocketChannel(FutureOr<WebSocket> webSocket)
       : super(webSocket is Future<WebSocket>
             ? webSocket.then(IOWebSocket.fromWebSocket) as FutureOr<IOWebSocket>

lib/status.dart

@@ -16,6 +16,8 @@
 ///   channel.close(status.goingAway);
 /// }
 /// ```
+@Deprecated('RFC-6455 reserves codes 1000-4999 for applications. '
+    'Some WebSocket implementations only allow those codes to be set.')
 library web_socket_channel.status;
 
 import 'dart:core';

test/html_test.dart

@@ -2,6 +2,8 @@
 // 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.
 
+// ignore_for_file: deprecated_member_use_from_same_package
+
 @TestOn('browser')
 library;
 

test/io_test.dart

@@ -2,6 +2,8 @@
 // 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.
 
+// ignore_for_file: deprecated_member_use_from_same_package
+
 @TestOn('vm')
 library;