Future.wait: Run Concurrent Dart Operations

WHY IT EXISTS Many apps need to perform multiple independent tasks, like fetching data from different network endpoints. Awaiting them one by one is slow because each task waits for the previous one to finish. Future.wait solves this by allowing you to run all tasks concurrently, reducing the total wait time to that of the single longest task.

THE MENTAL MODEL Think of Future.wait as a project manager for your async tasks. You give it a list of jobs (Futures). It dispatches them all at once. It then waits until every single job is finished, collects their reports (results) into an ordered list, and hands you the complete dossier.

HOW IT WORKS You pass an iterable of Future objects to the static method Future.wait. It immediately returns a new Future that will eventually contain a List of the results. This new future completes only after every future you provided has completed. The resulting list contains the values from the completed futures, in the same order as the input iterable. If any input future fails with an error, the entire Future.wait operation fails with that same error, and the successful results are discarded.

WHEN TO USE IT Use Future.wait when you have several independent async operations and you need all of their results to proceed. A classic example is a dashboard screen that needs to fetch user profile data, notifications, and recent activity from three different API endpoints. You can fire all three requests at once and build the UI only after all data has arrived.

WHEN NOT TO USE IT Do not use Future.wait for tasks that depend on each other. If Future B needs the result of Future A, you must await A first, then start B. Also, if you only care about the first future to complete (e.g., pinging multiple servers to find the fastest one), use Future.any instead.

ONE CANONICAL EXAMPLE Imagine fetching a user's data and their friends list from two separate API endpoints. Instead of waiting for one then the other, run them in parallel:

Future<User> fetchUser() async { /* API call */ } Future<List<Friend>> fetchFriends() async { /* API call */ }

// Both futures start concurrently. var results = await Future.wait([ fetchUser(), fetchFriends(), ]);

// results is a List<dynamic>. User user = results[0]; List<Friend> friends = results[1];

This is much faster than awaiting each call sequentially. The main footgun is that if fetchUser() fails, the entire Future.wait throws an error, and you won't get the friends list unless you use the optional cleanUp parameter to handle partial successes.