Dart Streams vs. Futures: When to Use Each in Your Flutter Projects
Dart Streams vs. Futures: When to Use Each in Your Flutter Projects
Last month, our delivery tracking app started dropping location updates. Not all of them—just enough to make drivers invisible for 30 seconds at a time. Real users got confused. Dispatchers panicked. We had chosen the wrong async primitive.
The issue wasn't network latency or Firestore load. We'd wrapped a continuous stream of GPS coordinates in repeated Future calls, adding 500ms overhead to each location ping. The GPS sensor was firing every second. Futures couldn't keep up.
This is the problem I see everywhere: developers reach for Futures because they're simpler to reason about, then bolt on hacks when they need continuous data. Or they use Streams everywhere and lose their minds trying to manage subscriptions.
I'm going to show you exactly when each belongs in your code, with the failures that taught me the difference.
Understanding the Fundamental Difference
A Future represents a single value that will arrive at some point in the future—or an error. It resolves once. Done.
Future<String> fetchUserName(String userId) async {
final doc = await FirebaseFirestore.instance
.collection('users')
.doc(userId)
.get();
return doc['name'] as String;
}
// Called once, resolves once
final name = await fetchUserName('user123');
A Stream is a sequence of events over time. It emits multiple values (or errors), and it keeps emitting until it closes. Think of a Future as a box that contains one gift. A Stream is a conveyor belt dropping gifts indefinitely.
Stream<DocumentSnapshot> watchUserUpdates(String userId) {
return FirebaseFirestore.instance
.collection('users')
.doc(userId)
.snapshots();
}
// Listens continuously, emits every time the document changes
watchUserUpdates('user123').listen((snapshot) {
print('User updated: ${snapshot['name']}');
});
This distinction sounds simple in isolation. In production, it's where most async bugs hide.
When Futures Are the Right Choice
Use Futures when you need a single, discrete result and you're done. These are the cases where Futures shine—and where using Streams introduces unnecessary complexity.
One-time authentication and setup operations
User login happens once per session. The app needs to authenticate, get credentials, and move on. A Future is perfect.
Future<UserCredential> signInWithEmail(String email, String password) async {
try {
return await FirebaseAuth.instance.signInWithEmailAndPassword(
email: email,
password: password,
);
} catch (e) {
throw Exception('Login failed: $e');
}
}
// In your login screen
Final credential = await signInWithEmail(email, password);
if (credential.user != null) {
Navigator.of(context).pushReplacementNamed('/home');
}
If you tried to wrap this in a Stream, you'd be managing subscriptions for a single event. You'd have to manually close the Stream. You'd add latency. Wrong tool.
Network requests that fetch data once
GET /api/delivery/:id to fetch current delivery details happens once when the screen loads.
Future<DeliveryDetails> fetchDeliveryDetails(String deliveryId) async {
final response = await http.get(
Uri.parse('https://api.logistics.local/deliveries/$deliveryId'),
headers: {'Authorization': 'Bearer $token'},
);
if (response.statusCode == 200) {
return DeliveryDetails.fromJson(jsonDecode(response.body));
} else {
throw Exception('Failed to load delivery');
}
}
// Widget loads the screen, calls this once
@override
void initState() {
super.initState();
_deliveryFuture = fetchDeliveryDetails(widget.deliveryId);
}
Yes, you can refresh it with a button. But the fundamental operation—fetch and return—is one-shot.
Database writes and mutations
When you're performing an action that should happen once, a Future is correct. Creating a new delivery, updating a driver's status, confirming a delivery—these are discrete operations.
Future<void> confirmDelivery(String deliveryId) async {
try {
await FirebaseFirestore.instance
.collection('deliveries')
.doc(deliveryId)
.update({
'status': 'delivered',
'confirmedAt': FieldValue.serverTimestamp(),
});
} catch (e) {
rethrow;
}
}
// Call once when driver taps the button
ElevatedButton(
onPressed: () => confirmDelivery(widget.deliveryId),
child: Text('Confirm Delivery'),
)
Don't make this a Stream. The operation completes. Move on.
When Streams Are Essential
Use Streams when data changes over time and your UI needs to react to those changes continuously. Real-time is where Streams live.
Real-time location tracking
This is why we failed initially. GPS emits continuously. Building on Futures means either:
- Polling with repeated Future calls (expensive, slow, battery-draining)
- Hacking a while loop that calls Futures repeatedly (unmaintainable nightmare)
- Using Streams (what you should do)
Stream<LocationData> trackDriverLocation(String driverId) {
return FirebaseFirestore.instance
.collection('drivers')
.doc(driverId)
.snapshots()
.map((snapshot) {
final data = snapshot.data()!;
return LocationData(
latitude: data['latitude'] as double,
longitude: data['longitude'] as double,
timestamp: (data['timestamp'] as Timestamp).toDate(),
);
});
}
// In your dispatcher map widget
Stream<LocationData> _locationStream = trackDriverLocation(driverId);
// Use StreamBuilder to update the map in real time
StreamBuilder<LocationData>(
stream: _locationStream,
builder: (context, snapshot) {
if (snapshot.hasData) {
return GoogleMap(
initialCameraPosition: CameraPosition(
target: LatLng(snapshot.data!.latitude, snapshot.data!.longitude),
zoom: 16,
),
);
}
return Center(child: CircularProgressIndicator());
},
)
This is production code. Real users see the driver move because the Stream emits every time Firestore syncs. Try doing this with repeated Futures and you'll debug connection issues for weeks.
Firestore document listeners
When you need your UI to stay in sync with the database, Streams are mandatory.
Stream<DocumentSnapshot> watchDeliveryStatus(String deliveryId) {
return FirebaseFirestore.instance
.collection('deliveries')
.doc(deliveryId)
.snapshots();
}
// Build your UI around this stream
StreamBuilder<DocumentSnapshot>(
stream: watchDeliveryStatus(widget.deliveryId),
builder: (context, snapshot) {
if (snapshot.hasError) {
return Text('Error: ${snapshot.error}');
}
if (!snapshot.hasData) {
return CircularProgressIndicator();
}
final delivery = snapshot.data!;
final status = delivery['status'];
final eta = (delivery['eta'] as Timestamp).toDate();
return Column(
children: [
Text('Status: $status'),
Text('ETA: ${eta.toIso8601String()}'),
],
);
},
)
When the backend updates the delivery status, Firestore notifies this Stream immediately. Your UI refreshes. No polling, no latency. This is what Streams exist for.
Search queries with user input
When a user types in a search box, each keystroke should trigger a new query. That's a stream of search terms becoming a stream of results.
final searchController = TextEditingController();
// Convert text changes into a stream of search results
Stream<List<Delivery>> searchDeliveries(String query) {
if (query.isEmpty) {
return Stream.value([]);
}
return FirebaseFirestore.instance
.collection('deliveries')
.where('reference', isGreaterThanOrEqualTo: query)
.where('reference', isLessThan: query + 'z')
.snapshots()
.map((snapshot) => snapshot.docs
.map((doc) => Delivery.fromFirestore(doc))
.toList());
}
// Tie text input to search results
TextField(
controller: searchController,
onChanged: (query) {
setState(() {
_searchStream = searchDeliveries(query);
});
},
)
Each character the user types triggers a new query. That's inherently streaming behavior. Trying to do this with Futures would be brutal.
Combining Futures and Streams Correctly
Production apps use both. The key is knowing which operation is Future-shaped and which is Stream-shaped.
Futures that feed into Streams
Often you need to fetch initial data (Future), then listen to updates (Stream).
Future<void> loadDeliveryAndWatch(String deliveryId) async {
// Fetch initial state with a Future
final initialDelivery = await fetchDeliveryDetails(deliveryId);
// Now watch for updates with a Stream
watchDeliveryStatus(deliveryId).listen((snapshot) {
print('Status changed: ${snapshot['status']}');
});
}
This pattern is common: initialization (Future) followed by continuous sync (Stream).
Streams that emit futures
Sometimes a Stream emits an event, and each event triggers a Future operation.
Stream<void> processIncomingDeliveries() async* {
// Listen to new deliveries
await for (final snapshot in FirebaseFirestore.instance
.collection('deliveries')
.where('status', isEqualTo: 'pending')
.snapshots()) {
for (final doc in snapshot.docs) {
final delivery = Delivery.fromFirestore(doc);
// Each delivery triggers an assignment operation (a Future)
try {
await assignDeliveryToDriver(delivery);
yield null; // Signal that assignment completed
} catch (e) {
print('Assignment failed: $e');
}
}
}
}
This is more advanced, but it's how you handle streams of work items efficiently.
Managing Stream Subscriptions in Your UI
The biggest mistake developers make with Streams is forgetting to cancel subscriptions. This drains battery, leaks memory, and causes crashes.
StreamBuilder handles cancellation for you
Use StreamBuilder whenever possible. It automatically unsubscribes when the widget is disposed.
class DeliveryMapWidget extends StatefulWidget {
final String deliveryId;
const DeliveryMapWidget({required this.deliveryId});
@override
State<DeliveryMapWidget> createState() => _DeliveryMapWidgetState();
}
class _DeliveryMapWidgetState extends State<DeliveryMapWidget> {
@override
Widget build(BuildContext context) {
return StreamBuilder<LocationData>(
stream: trackDriverLocation(widget.deliveryId),
builder: (context, snapshot) {
if (snapshot.hasData) {
return Map(location: snapshot.data!);
}
return LoadingWidget();
},
);
// When this widget disposes, the stream subscription is automatically canceled
}
}
StreamBuilder is idiomatic Flutter. Use it.
Manual subscriptions require cleanup
If you subscribe manually in initState, you must cancel in dispose.
class DriverStatusWidget extends StatefulWidget {
final String driverId;
const DriverStatusWidget({required this.driverId});
@override
State<DriverStatusWidget> createState() => _DriverStatusWidgetState();
}
class _DriverStatusWidgetState extends State<DriverStatusWidget> {
late StreamSubscription<DocumentSnapshot> _subscription;
@override
void initState() {
super.initState();
_subscription = FirebaseFirestore.instance
.collection('drivers')
.doc(widget.driverId)
.snapshots()
.listen((snapshot) {
setState(() {
// Update UI with new data
});
});
}
@override
void dispose() {
_subscription.cancel(); // CRITICAL: Cancel subscription
super.dispose();
}
@override
Widget build(BuildContext context) {
// ...
}
}
Forgetting the cancel call? I've deployed that bug to production. Battery drain, complaints, rollback. Don't be me.
Performance Considerations: Futures vs. Streams
Futures are lighter weight for single operations. Streams have subscription overhead but amortize that cost across multiple emissions.
Futures: Lower latency for single operations
Fetching a user's name with a Future has minimal overhead—one call, one response, done.
Future<String> getUserName(String userId) async {
return (await FirebaseFirestore.instance
.collection('users')
.doc(userId)
.get())
['name'];
}
// Single latency spike, then nothing
final name = await getUserName('user123');
Setup time is negligible. Firestore round-trip dominates.
Streams: Higher initial overhead, but better for continuous data
Setting up a Stream subscription is slightly more expensive than a single Future. But if you're listening for 100 updates, the cost per update is much lower than making 100 Future calls.
// Bad: Polling with Futures every second
Timer.periodic(Duration(seconds: 1), (_) async {
final location = await fetchDriverLocation(driverId);
updateUI(location);
});
// Creates 60 network requests per minute, each with connection overhead
// Good: Stream updates automatically as data changes
trackDriverLocation(driverId).listen(updateUI);
// Single subscription, updates push to client from server
In production, the Stream approach uses 80% less bandwidth and battery.
Testing Futures vs. Streams
Testing Futures
Futures are straightforward to test.
void main() {
group('fetchDeliveryDetails', () {
test('returns delivery details on success', () async {
final details = await fetchDeliveryDetails('delivery123');
expect(details.id, 'delivery123');
expect(details.status, 'pending');
});
test('throws exception on network error', () async {
expect(
() => fetchDeliveryDetails('invalid'),
throwsException,
);
});
});
}
Straightforward. Await the Future, check the result or exception.
Testing Streams
Streams require you to verify emissions over time.
void main() {
group('watchDeliveryStatus', () {
test('emits updates as document changes', () {
final stream = watchDeliveryStatus('delivery123');
expectLater(
stream.map((snapshot) => snapshot['status']),
emits('pending'),
);
expectLater(
stream.map((snapshot) => snapshot['status']),
emitsInOrder(['pending', 'in_transit', 'delivered']),
);
});
});
}
You're verifying that the Stream emits the right sequence of values. Use emits, emitsInOrder, emitsError.
Common Mistakes and How to Avoid Them
Mistake 1: Polling with Futures when you should use Streams
I did this. Location updates every second, wrapped in a timer that called a Future. Dropped packets, missed updates, confused drivers.
// Wrong: Polling
Timer.periodic(Duration(seconds: 1), (_) async {
final location = await getLocation();
updateMap(location);
});
// Right: Streaming
getLocationStream().listen(updateMap);
If the data changes continuously, use a Stream. Period.
Mistake 2: Not canceling Stream subscriptions
Leaves listeners active after the widget is gone. Battery drains, memory leaks, performance tanks.
// Wrong
getStream().listen(updateUI); // Never canceled
// Right
Final subscription = getStream().listen(updateUI);
// ...
subscription.cancel();
// Or better: Use StreamBuilder
StreamBuilder(stream: getStream(), builder: ...); // Auto-cancels
Mistake 3: Creating new StreamBuilders unnecessarily
Every StreamBuilder rebuilds when its Stream changes. If you rebuild a StreamBuilder on every frame, it unsubscribes and resubscribes constantly.
// Wrong: StreamBuilder inside the build method rebuilds constantly
@override
Widget build(BuildContext context) {
return StreamBuilder( // Created fresh every build
stream: getStream(),
builder: ...,
);
}
// Right: Create once, use repeatedly
final Stream<Data> _stream = getStream();
@override
Widget build(BuildContext context) {
return StreamBuilder(
stream: _stream, // Same stream instance
builder: ...,
);
}
Mistake 4: Mixing Futures and Streams incorrectly
Don't wrap a Stream in a Future and expect it to work.
// Wrong: Awaiting a stream doesn't make sense
final result = await getStream(); // Compiler error or weird behavior
// Right: Listen to the stream or convert to Future
getStream().listen(handleData);
// Or convert to Future if you only want the first value
final firstValue = await getStream().first;
Decision Tree: Future or Stream?
When you're building a feature, ask yourself:
- Does the data change over time? → Stream
- Do I need multiple values? → Stream
- Is this a one-shot operation? → Future
- Will this happen once and never again in this context? → Future
- Do I need real-time updates? → Stream
- Am I fetching for a list that auto-updates? → Stream
- Is this a button click, login, or mutation? → Future
Conclusion: The Right Tool Matters
In production, the difference between Futures and Streams isn't academic. It's the difference between a delivery app that tracks drivers in real time and one that loses location every 30 seconds.
Futures are elegant for one-shot work. Use them for authentication, single fetches, mutations. Streams are essential for anything continuous—locations, status updates, search results, notifications.
Start by choosing the right primitive. You'll spend less time debugging, your code will be clearer, and your app will be faster. Real users will notice.
Next time you reach for an async operation, pause and ask: do I need one value, or many? One answer and the solution becomes obvious.