In Dart, a dashboard loads profile, feed and stats from three independent futures; how do you run them concurrently and collect typed results?

## The sequential trap A dashboard that shows a profile card, a feed and a stats tile usually needs three independent network calls. The naive version awaits them one by one: ```dart final profile = await loadProfile(); // ~300 ms final feed = await loadFeed(); // ~500 ms, starts only now final stats = await loadStats(); // ~200 ms, starts only now // total ~1000 ms ``` Each call is **started** only when the previous `await` has finished, so the latencies add up. Nothing is wrong with `await` itself; the calls were simply issued in sequence. ## Start first, wait once In Dart, calling an `async` function starts its work immediately and returns a future. So the fix is to **create all the futures before awaiting any of them**, then wait for the group. The total becomes roughly the slowest call (~500 ms above). This is **concurrency on one isolate**: the three requests are in flight at the same time and their I/O overlaps, but Dart code still runs one piece at a time. CPU-heavy work does not speed up this way; that needs another isolate. ## `Future.wait` `Future.wait<T>(Iterable<Future<T>> futures, {bool eagerError = false, void cleanUp(T successValue)?})` returns `Future<List<T>>`: - **Order**: results are in the order the futures were supplied, not the order they completed. - **Default error behaviour** (`eagerError: false`): it waits for **all** futures, then completes with the **first error that occurred**; later errors are silently dropped. - **`eagerError: true`**: completes with the first error immediately, without waiting for the rest (which keep running). - **`cleanUp`**: after an error, called for each non-null successful value, so resources such as open handles are not lost. - **Types**: all futures share one `T`, so a profile, a feed and a stats object collapse to `List<Object>` and need casts. ## Records and `.wait` (Dart 3.0) Dart 3.0 added `wait` getters on records of two to nine futures, and on any `Iterable<Future<T>>`: ```dart final (profile, feed, stats) = await (loadProfile(), loadFeed(), loadStats()).wait; ``` - Each field keeps its own static type: `profile` is a `Profile`, `feed` a `List<Post>`. - The returned future completes only when **all** futures have completed. - If any fail, it completes with a **`ParallelWaitError`**. Its `values` has the same shape as the input with `null` for failed slots, and its `errors` holds an `AsyncError` for each failed slot and `null` for successes. The dashboard can render the tiles that loaded and an error state for the rest. | | `Future.wait` | record `.wait` | |---|---|---| | Result type | `List<T>` | typed record | | Mixed value types | collapse to a common supertype | preserved per field | | On error | first error only | `ParallelWaitError` with every value and error | | Early failure option | `eagerError: true` | always waits for all | | Cleanup hook | `cleanUp` | inspect `values` yourself | ## A variable number of tiles When the dashboard's tiles come from configuration rather than a fixed three, the `Iterable` extension does the same job: `final tiles = await [for (final id in tileIds) loadTile(id)].wait;` returns a `List` in input order. On failure it throws a `ParallelWaitError` whose `values` is a list with `null` in failed slots and whose `errors` is a list of the same length holding an `AsyncError` for each failure, so the screen can still render every tile that loaded. ## Why not await started futures one by one? A tempting middle ground is to start all three, then `await a; await b; await c;`. It is concurrent, but it has an error-handling hole. The SDK documents that a future's error is reported as **unhandled** if it completes with an error before any handler is attached. If `stats` fails while the code is still awaiting `profile`, that error is reported as unhandled even though a later `await c` would also see it. `Future.wait` and `.wait` attach handlers to every future at once, which avoids this. ## Checklist 1. Identify which calls are truly independent. 2. Start them together and wait once, preferring the record `.wait` for mixed types. 3. Decide whether a partial failure should fail the screen or degrade a single tile, and use `ParallelWaitError` accordingly.