EventFlux is a Dart package designed for efficient handling of server-sent event streams. It provides easy-to-use connectivity, data management, and robust error handling for real-time data applications. đ
Supported Platforms
Android | iOS | Web | MacOS | Windows | Linux |
---|---|---|---|---|---|
â | â | đī¸ | â | â | â |
Pssst... see those question marks? That's your cue, tech adventurers! Dive in, test, and tell me all about it. đđ ī¸
Inspiration đĄ
EventFlux was born from the inspiration I found in the flutter_client_sse
package by Pratik Baid. His work laid a great foundation, and I aimed to build upon it, adding my own twist to enhance SSE stream management with better features. đ ī¸
Why EventFlux? đ
- Streamlined Connection Handling: Easy setup for connecting to event streams with support for both GET and POST requests. đ
- Auto-Reconnect Capability: Seamlessly maintains your connection, automatically reconnecting in case of any server interruptions or network changes. Devs can choose to do linear or exponential backoff đ
- Real-Time Data Management: Efficient processing and handling of real-time data streams. đ
- Error Handling: Robust mechanisms to manage connection interruptions and stream errors. đĄī¸
- Versatile Instance Creation: Offers both singleton and factory patterns for tailored SSE connections. đ
- Customizable: Extendable to fit various use cases and custom implementations. â¨
EventFlux for Every Scenario đ
Get Started in a Snap đĻ
Add EventFlux to your Dart project's dependencies, and you're golden:
dependencies:
eventflux: ^2.2.1
How to Use (Spoiler: It's Super Easy) đ§
Here's a quick example to get you started:
The Simple Streamer â¨
Need just one SSE connection? It's a breeze with EventFlux! Perfect for when your app is dancing solo with a single SSE.
import 'package:eventflux/eventflux.dart';
void main() {
// Connect and start the magic!
EventFlux.instance.connect(
EventFluxConnectionType.get,
'https://example.com/events',
files: [
/// Optional, If you want to send multipart files with the request
],
multipartRequest: true, // Optional, By default, it will be considered as normal request, but if the files are provided or this flag is true, it will be considered as multipart request
onSuccessCallback: (EventFluxResponse? response) {
response.stream?.listen((data) {
// Your data is now in the spotlight!
});
},
onError: (oops) {
// Oops! Time to handle those little hiccups.
// You can also choose to disconnect here
},
autoReconnect: true // Keep the party going, automatically!
reconnectConfig: ReconnectConfig(
mode: ReconnectMode.linear, // or exponential,
interval: Duration(seconds: 5),
reconnectHeader: () async {
/// If you want to send custom headers during reconnect which are different from the initial connection
/// If you don't want to send any headers, you can skip this, initial headers will be used
// Your async code to refresh or fetch headers
// For example, fetching a new access token:
String newAccessToken = await fetchNewAccessToken();
return {
'Authorization': 'Bearer $newAccessToken',
'Accept': 'text/event-stream',
};
},
maxAttempts: 5, // or -1 for infinite,
onReconnect: () {
// Things to execute when reconnect happens
// FYI: for network changes, the `onReconnect` will not be called.
// It will only be called when the connection is interupted by the server and eventflux is trying to reconnect.
}
),
);
}
Supercharged đ
When your app just need a multiple parallel SSE connections, use this.
import 'package:eventflux/eventflux.dart';
void main() {
// Create separate EventFlux instances for each SSE connection
EventFlux e1 = EventFlux.spawn();
EventFlux e2 = EventFlux.spawn();
// First connection - firing up!
e1.connect(EventFluxConnectionType.get,
'https://example1.com/events',
tag: "SSE Connection 1", // Optional tag for debugging, you'll see this in logs
onSuccessCallback: (EventFluxResponse? data) {
data.stream?.listen((data) {
// Your 1st Stream's data is being fetched!
});
},
onError: (oops) {
// Oops! Time to handle those little hiccups.
// You can also choose to disconnect here
},
);
// Second connection - firing up!
e2.connect(EventFluxConnectionType.get,
'https://example2.com/events',
tag: "SSE Connection 2", // Optional tag for debugging, you'll see this in logs
onSuccessCallback: (EventFluxResponse? data) {
data.stream?.listen((data) {
// Your 2nd Stream's data is also being fetched!
});
},
onError: (oops) {
// Oops! Time to handle those little hiccups.
// You can also choose to disconnect here
},
autoReconnect: true // Keep the party going, automatically!
reconnectConfig: ReconnectConfig(
mode: ReconnectMode.exponential, // or linear,
interval: Duration(seconds: 5),
maxAttempts: 5, // or -1 for infinite,
reconnectHeader: () async {
/// If you want to send custom headers during reconnect which are different from the initial connection
/// If you don't want to send any headers, you can skip this, initial headers will be used
// Your async code to refresh or fetch headers
// For example, fetching a new access token:
String newAccessToken = await fetchNewAccessToken();
return {
'Authorization': 'Bearer $newAccessToken',
'Accept': 'text/event-stream',
};
},
onReconnect: () {
// Things to execute when reconnect happens
// FYI: for network changes, the `onReconnect` will not be called.
// It will only be called when the connection is interupted by the server and eventflux is trying to re-establish the connection.
}
),
);
}
âšī¸ Remember to disconnect all instances when you are done with it to avoid memory leaks.
Need More Info? đ
- EventFlux: Main class for managing event streams.
- ReconnectConfig: Configuration for auto-reconnect.
- EventFluxData: Data model for events received from the stream.
- EventFluxException: Custom exception handling for EventFlux operations.
- EventFluxResponse: Encapsulates the response from EventFlux operations.
- Enums:
EventFluxConnectionType
for specifying connection types andEventFluxStatus
for connection status.
For detailed documentation, please see the respective Dart files in the lib
folder.
EventFlux Class Documentation đ
EventFlux
is a Dart class for managing server-sent event streams. It provides methods for connecting to, disconnecting from, and managing SSE streams.
Connect
Connects to a server-sent event stream.
Parameter | Type | Description | Default |
---|---|---|---|
type |
EventFluxConnectionType |
The type of HTTP request (GET or POST). | - |
url |
String |
The URL of the SSE stream to connect to. | - |
header |
Map<String, String> |
HTTP headers for the request. | {'Accept': 'text/event-stream'} |
onConnectionClose |
Function()? |
Callback function triggered when the connection is closed. | - |
autoReconnect |
bool |
Whether to automatically reconnect on disconnection. | false |
reconnectConfig |
ReconnectConfig? |
Configuration for auto-reconnect. If auto-reconnect is true, this is required |
- |
onSuccessCallback |
Function(EventFluxResponse?) |
Callback invoked upon successful connection. | - |
onError |
Function(EventFluxException)? |
Callback for handling errors. | - |
body |
Map<String, dynamic>? |
Optional body for POST request types. | - |
files |
List<File>? |
Optional list of files to send with the request. | - |
multipartRequest |
bool |
Whether the request is a multipart request. | false |
tag |
String |
Optional tag for debugging. | - |
logReceivedData |
bool |
Whether to log received data. | false |
httpClient |
HttpClientAdapter? |
Optional Http Client Adapter to allow usage of different http clients. | - |
Disconnect
Disconnects from the SSE stream.
Parameter | Type | Description |
---|---|---|
- | - | This method has no parameters. |
Returns a Future<EventFluxStatus>
indicating the disconnection status.
Spawn
Parameter | Type | Description |
---|---|---|
- | - | This method has no parameters. |
Returns a new instance of EventFlux
, this is used for having multiple SSE connections.
Be a Part of the Adventure đ¤
Got ideas? Want to contribute? Jump aboard! Open an issue or send a pull request. Let's make EventFlux even more awesome together!
The Boring (but Important) Stuff đ
Licensed under MIT - use it freely, but let's play nice and give credit where it's due!