> ## Documentation Index > Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt > Use this file to discover all available pages before exploring further. # Dart Stream A `Stream` in Dart represents a sequence of asynchronous events. While an `Iterable` provides synchronous delivery of data, a `Stream` delivers data, errors, and a completion signal asynchronously over time. It is a core primitive of Dart's asynchronous programming model, implementing the reactive programming pattern. ## Event Types A stream communicates with its subscribers by emitting three distinct types of events: 1. **Data Events:** The actual payload of type `T`. 2. **Error Events:** Exceptions or errors that occur during stream processing. 3. **Done Event:** A terminal signal indicating no further data or error events will be emitted. ## Stream Architectures Dart categorizes streams into two architectural models based on subscription behavior: * **Single-subscription Streams:** The default stream type. It permits only one listener throughout its lifecycle. Attempting to listen a second time throws a `StateError`. The behavior of the stream before a subscription occurs depends on its instantiation: streams generated via `async*` are lazy and do not generate events until a listener attaches, whereas streams created manually via a `StreamController` will buffer emitted events internally to ensure no data is lost before the subscription occurs. * **Broadcast Streams:** Designed for multiple concurrent listeners. It does not buffer events; if an event is emitted when no listeners are attached, the event is permanently discarded. Listeners only receive events emitted after they subscribe. ## Consuming Streams Developers can consume streams using either asynchronous iteration or the subscription API. **Asynchronous Iteration (`await for`)** This syntax pauses execution of the surrounding `async` function until the stream emits a new event or completes. ```dart theme={"dark"} Future processStream(Stream numberStream) async { await for (final int number in numberStream) { print(number); // Executes sequentially as data arrives } // Execution resumes here after the Done event is emitted } ``` **Subscription API (`listen`)** The `listen` method returns a `StreamSubscription`, providing granular control over the stream state (pause, resume, cancel) and explicit handlers for different event types. ```dart theme={"dark"} import 'dart:async'; Future manageSubscription() async { // Using a periodic stream to demonstrate asynchronous event emission over time final Stream numberStream = Stream.periodic( const Duration(milliseconds: 100), (int count) => count, ); final StreamSubscription subscription = numberStream.listen( (int number) => print('Data: $number'), onError: (Object error) => print('Error: $error'), onDone: () => print('Stream closed'), cancelOnError: false, ); // Allow the stream to emit events before manipulating the subscription state await Future.delayed(const Duration(milliseconds: 250)); subscription.pause(); await Future.delayed(const Duration(milliseconds: 100)); subscription.resume(); await Future.delayed(const Duration(milliseconds: 250)); // Safely terminate the subscription before the stream naturally completes await subscription.cancel(); } ``` ## Creating Streams Streams are typically instantiated via asynchronous generator functions or manual controllers. **Asynchronous Generators (`async*`)** The `async*` keyword defines a generator function that returns a `Stream`. The `yield` keyword emits individual data events, while `yield*` delegates to another stream. ```dart theme={"dark"} Stream generateNumbers(int max) async* { for (int i = 1; i <= max; i++) { yield i; // Emits a data event } // Function termination implicitly emits the Done event } ``` **StreamController** A `StreamController` provides an imperative API to construct and manage a stream. It exposes a `sink` for event injection and a `stream` for subscription. ```dart theme={"dark"} import 'dart:async'; void demonstrateController() { // Use StreamController.broadcast() for a broadcast stream final StreamController controller = StreamController(); // Exposing the stream final Stream myStream = controller.stream; // Attaching a listener with an onError handler to catch asynchronous exceptions myStream.listen( (String event) => print('Received: $event'), onError: (Object error) => print('Caught error: $error'), ); // Injecting events controller.sink.add('Event 1'); // Data event controller.sink.addError(Exception()); // Error event (caught by onError) controller.sink.close(); // Done event } ``` ## Stream Transformations Streams support functional composition. Methods like `map`, `where`, and `expand` return new streams that intercept and mutate events from the source stream before they reach the listener. For complex transformations, the `transform` method applies a `StreamTransformer`. ```dart theme={"dark"} void transformStream() { final Stream sourceStream = Stream.fromIterable([1, 2, 3, 4, 5]); final Stream transformedStream = sourceStream .where((int x) => x % 2 == 0) // Filters events .map((int x) => x * 10); // Mutates events transformedStream.listen((int result) => print(result)); } ```

Tired of Poor Dart Skills? Fix That With Deep Grasping! Learn More