Streams

Many values over time

Some data does not arrive once; it keeps coming: the score of a cricket match, a delivery rider's location, new chat messages, the user typing in a search box. A Stream is a sequence of asynchronous events. It can deliver values, errors, and finally a "done" signal.

Streams are everywhere in apps even when you do not create them yourself: a text field's changes, a sensor's readings, a database query that updates when rows change, or messages from a WebSocket. Learning to read and write stream code makes all of these feel the same.

Like a Future, a Stream can fail. An error event does not necessarily end the stream; it depends on the source. Always provide error handling with onError in listen, or a try/catch around await for, so one bad event does not crash the screen.

Creating a stream with async*

Stream<int> countdown(int from) async* {
  for (var i = from; i >= 1; i--) {
    yield i;                                           // send a value
    await Future.delayed(const Duration(seconds: 1));
  }
}

Future<void> main() async {
  await for (final s in countdown(3)) {
    print('OTP expires in $s s');
  }
  print('OTP expired');
}

listen and subscriptions

final sub = countdown(5).listen(
  (value) => print('tick $value'),
  onError: (e) => print('error: $e'),
  onDone: () => print('done'),
);
// later, for example when the screen closes:
// sub.cancel();

StreamController

A StreamController lets you push values into a stream from ordinary code, for example when a WebSocket message arrives. By default its stream is single-subscription: only one listener, and values are buffered until someone listens. A broadcast stream allows many listeners but does not buffer for late ones.

import 'dart:async';

class ScoreBoard {
  final _controller = StreamController<String>.broadcast();
  Stream<String> get scores => _controller.stream;

  void update(String score) => _controller.add(score);
  void dispose() => _controller.close();     // always close what you create
}

void main() {
  final board = ScoreBoard();
  board.scores.listen((s) => print('App: $s'));
  board.scores.listen((s) => print('Widget: $s'));
  board.update('IND 245/3 (40)');
  board.dispose();
}

Transforming streams

final evensDoubled = Stream.fromIterable([1, 2, 3, 4])
    .where((n) => n.isEven)
    .map((n) => n * 2);
evensDoubled.listen(print);      // 4, then 8

How Flutter uses streams

Flutter's StreamBuilder widget listens to a stream and rebuilds part of the screen with the latest value. Cloud Firestore's snapshots() returns a stream, so a chat screen updates the moment a new message is written. State management libraries such as Bloc are also built on streams (module 7).

Common mistakes

• Forgetting to cancel subscriptions in a widget's dispose: memory leaks and work on screens that are gone.
• Not closing StreamControllers you create.
• Listening twice to a single-subscription stream: "Bad state: Stream has already been listened to". Use a broadcast stream or a single listener.
• Using a Stream when only one value is expected. Use a Future.