ws 0.0.6-dev

WS: A compact, highly efficient WebSocket library. Easily establish, manage, and reconnect WebSocket connections in real-time apps.

Cross-platform WebSocket client

The ws package provides a cross-platform WebSocket client for both Dart and Flutter applications. It allows you to connect to a WebSocket server, send and receive messages, and handle the connection state changes.

Installation

Add the following dependency to your pubspec.yaml file:

dependencies:
  ws: ^0.1.0

Properties

• state: A read-only property that returns the current WebSocket connection state.
• stateChanges: A read-only property that returns a stream of WebSocket connection state changes.
• stream: A read-only property that returns a stream of message events handled by the WebSocket.

Methods

• connect(String url): Connects to the WebSocket server specified by the URL argument.
• disconnect([int? code = 1000, String? reason = 'NORMAL_CLOSURE']): Closes the WebSocket connection. You can optionally pass a numeric code and a reason string to the method to send close information to the remote peer.
• add(Object data): Sends data on the WebSocket connection. The data can be either a String or a List of integers holding bytes.
• close([int? code = 1000, String? reason = 'NORMAL_CLOSURE']): Permanently stops the WebSocket connection and frees all resources. After calling this method, the WebSocket client is no longer usable.

Example

import 'package:ws/ws.dart';

void main() async {
  const url = 'wss://echo.plugfox.dev:443/connect';

  final client = WebSocketClient.connect(url)
    ..stream.listen((message) => print('< $message'))
    ..add('Hello, ').ignore()
    ..add('world!').ignore();

  Timer(const Duration(seconds: 5), client.close);
}

Reconnection

The ws package provides a cross-platform WebSocket client that supports automatic reconnection in case of connection loss. The client automatically tries to reconnect to the server when the connection is lost. To handle reconnection-related events, you can register listeners for the stateChanges stream, which notifies you about changes in the connection state. When the connection is closed, the client tries to reconnect with a delay, which increases exponentially with each unsuccessful attempt to prevent overloading the server.

---

Features and Roadmap

• Cross-platform WebSocket client for Dart and Flutter
• Support for secure WebSocket connections (wss://)
• Connection state changes
• Fake client
• Reconnection to new URL
• Concurrency
• Auto reconnection after network problems
• Handy stream of messages with automatic JSON decoding
• Metrics & counters
• TS/RX Speed
• Reusing client between isolates
• 95% test coverage

---

More resources

• RFC 6455: The WebSocket Protocol
• WebSocket API on MDN
• Dart HTML WebSocket library
• Dart IO WebSocket library

---

Coverage

---

Changelog

Refer to the Changelog to get all release notes.

---

Maintainers

Plague Fox

---

License

MIT

---

Tags

web, socket, ws, wss, WebSocket, cross, platform