View Categories

What is a StreamTransformer in Dart, and how do you use it?

Parthiban Kannan
Updated on December 6, 2025

2 min read

StreamTransformer is a very powerful feature in Dart’s asynchronous programming model. It allows you to modify, filter, or transform data events as they pass through a Stream, before the listener receives them.

Think of it like a middleware for streams — data comes in, you process or change it, and then send the transformed data out. This is very useful when you want to apply custom logic between a data source and its consumers without modifying the original stream.

For example, let’s say I have a stream of integers, but I want to only pass even numbers to the listener. I can create a StreamTransformer to filter out the odd ones:

📄
filename.dart 
import 'dart:async';

final evenNumberTransformer =
    StreamTransformer.fromHandlers(handleData: (number, sink) {
  if (number % 2 == 0) {
    sink.add(number); // pass even numbers
  } else {
    sink.addError('Odd number skipped: $number'); // optional error handling
  }
});

void main() {
  final controller = StreamController();
  controller.stream
      .transform(evenNumberTransformer)
      .listen((data) => print('Even number: $data'),
          onError: (err) => print(err));

  // Add some numbers
  controller.add(1);
  controller.add(2);
  controller.add(3);
  controller.add(4);

  controller.close();
}

Output

📄
filename.dart 
Odd number skipped: 1
Even number: 2
Odd number skipped: 3
Even number: 4

Here, the transformer intercepts the data flowing through the stream and decides what to do with it — either forward it using sink.add() or handle it differently using sink.addError().

In a real-world project, I used a StreamTransformer in a Flutter chat app where I had a message stream from the backend. Some messages came in raw JSON format, so I used a transformer to decode the JSON before passing it to the UI layer:

📄
filename.dart 
final messageTransformer = StreamTransformer<String, Map>.fromHandlers(
  handleData: (jsonString, sink) {
    sink.add(jsonDecode(jsonString));
  },
);

This kept the UI layer clean, since it didn’t need to worry about JSON parsing — the stream was already providing decoded message objects.

A common challenge I’ve faced is error handling inside transformers. If exceptions aren’t handled properly within handleData, they can cause the stream to close unexpectedly. So, I always wrap transformations in try-catch blocks or use sink.addError() to keep the stream stable.

One limitation of StreamTransformer is that it’s synchronous by default — if you need asynchronous transformations (like calling an API or database inside the transform), you’ll need to use an async generator (async*) with yield or chain multiple streams using asyncMap().

As an alternative, Dart also provides RxDart — a reactive programming library that extends the Stream API with operators like map(), filter(), debounce(), and flatMap(). So instead of manually building a transformer, I could easily write:

📄
filename.dart 
stream.where((n) => n.isEven).listen(print);

In summary, StreamTransformer is ideal when you need custom reusable stream logic — such as filtering, mapping, throttling, or parsing data — in a structured, declarative way. It keeps your stream pipelines clean and modular, especially when working with real-time data in Flutter apps.

Scroll to Top