StreamTransformer: Building Custom Stream Operators
A StreamTransformer is a factory for custom stream operators like map or where. Use it to build reusable logic, like parsing data chunks, that can be applied to any stream.
Why it exists
Dart's Stream API provides common operators like map and where, but sometimes you need custom, reusable logic to apply to different streams. StreamTransformer was created to package that logic into a single, composable unit, making complex stream processing clean and maintainable.
The mental model
Think of a StreamTransformer as a reusable "pipe fitting" for streams. You attach it to an input stream using the transform() method, and it gives you back a new, transformed output stream. It is the fundamental building block for creating your own stream operators beyond the standard library.
How it works
A StreamTransformer's core job is to implement a bind method, which takes a source stream and returns a new one. The easiest way to create one is with the StreamTransformer.fromHandlers constructor. This provides three optional callbacks: handleData to process an incoming event and push a new event to an output sink, handleError to manage errors, and handleDone to perform cleanup and, crucially, close the sink when the input stream is finished.
When to use it
Use a StreamTransformer for complex, stateful, or reusable stream logic. Three common scenarios: first, decoding a stream of raw bytes into structured data objects (like a JSON parser); second, implementing custom operators like debounce or throttle for UI events; third, transforming events in a way that requires maintaining state between events.
When not to use it
Avoid StreamTransformer for simple, one-off transformations. If a chain of existing operators like stream.where(...).map(...) can achieve the same result clearly and concisely, prefer that. Overusing transformers for simple tasks can add unnecessary complexity and make the code harder to read.
One canonical example
A transformer that filters out duplicate consecutive values is a great example. Using StreamTransformer.fromHandlers, you would store the previously seen value in a variable. In handleData, you compare the new data with the stored value. If they are different, you update the stored value and add the new data to the sink. If they are the same, you do nothing. This stateful filtering logic is perfectly encapsulated within the transformer.
Interview question
When is a StreamTransformer the most appropriate tool for stream processing?
- a.To emit new events into a stream from an external, non-stream source.
- b.To perform a simple, one-to-one transformation on each event in a stream.
- c.To directly modify the events of an existing stream in place.
- d.To create a reusable, stateful custom operator for processing stream events.Correct
Why? this is the answer
A StreamTransformer is specifically designed for encapsulating complex, stateful, or reusable logic to create custom stream operators. Option B describes a simple transformation best handled by existing operators like 'map', which the card advises against using a transformer for.
Just read this? Test yourself on what you have been reading.
Read the original → api.dart.dev
Put your scrolling time to good use
Learn one idea, try a quiz and save useful cards for revision. Tezvyn makes it easy to learn and stay current in your tech field, a few minutes at a time.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Open roles that interview on dart — each one lists the topics its interview covers.
See open roles