Enrich top merchants concurrently

FxDart wins async

Requirement

From July's per-merchant spend totals, take the top three merchants and enrich each with its category from a (simulated) merchant-directory API — but the API rate-limits, so never more than two lookups in flight at once. Results print in spend order after all lookups finish, and the fake lookup counts overlapping requests so both versions can prove the limit held. The data is in the code below; both versions must print the lines shown under Expected output.

Expected output

Green Grocer — $118.65 (Groceries)
Electric Co — $60.34 (Utilities)
Noodle Bar — $54.70 (Dining)
max lookups in flight: 2

Side by side

Native Dart

class Merchant {
  final String name;
  final double total;
  const Merchant(this.name, this.total);
}

// Per-merchant spend totals for July 2026.
const merchants = [
  Merchant('Green Grocer', 118.65),
  Merchant('Cafe Aroma', 34.80),
  Merchant('Electric Co', 60.34),
  Merchant('Noodle Bar', 54.70),
  Merchant('Metro', 21.50),
  Merchant('Cinema', 15.00),
  Merchant('StreamFlix', 9.99),
  Merchant('Taxi', 24.00),
];

const directory = {
  'Green Grocer': 'Groceries',
  'Electric Co': 'Utilities',
  'Noodle Bar': 'Dining',
  'Cafe Aroma': 'Dining',
};

int inFlight = 0;
int maxInFlight = 0;

Future<String> lookupCategory(String name) async {
  inFlight++;
  if (inFlight > maxInFlight) maxInFlight = inFlight;
  await Future.delayed(const Duration(milliseconds: 15));
  inFlight--;
  return directory[name]!;
}

/// A hand-rolled worker pool: [limit] workers pull from a shared cursor,
/// writing into pre-sized slots so the output keeps the input order.
Future<List<String>> enrichAll(List<Merchant> picked, int limit) async {
  final results = List<String?>.filled(picked.length, null);
  var next = 0;
  Future<void> worker() async {
    while (next < picked.length) {
      final i = next++;
      final m = picked[i];
      final category = await lookupCategory(m.name);
      results[i] = '${m.name} — \$${m.total.toStringAsFixed(2)} ($category)';
    }
  }

await Future.wait([for (var i = 0; i < limit; i++) worker()]);
  return results.cast<String>();
}

Future<void> main() async {
  final top = [...merchants]..sort((a, b) => b.total.compareTo(a.total));
  final enriched = await enrichAll(top.take(3).toList(), 2);
  print(enriched.join('\n'));
  print('max lookups in flight: $maxInFlight');
}

FxDart

import 'package:fxdart/fxdart.dart';

class Merchant {
  final String name;
  final double total;
  const Merchant(this.name, this.total);
}

const directory = {
  'Green Grocer': 'Groceries',
  'Electric Co': 'Utilities',
  'Noodle Bar': 'Dining',
  'Cafe Aroma': 'Dining',
};

int inFlight = 0;
int maxInFlight = 0;

Future<void> main() async {
  final enriched = await fx(merchants)
      .sortBy((m) => -m.total)
      .take(3)
      .toAsync()
      .map((m) async => '${m.name} — \$${m.total.toStringAsFixed(2)} '
          '(${await lookupCategory(m.name)})')
      .concurrent(2)
      .toList();
  print(enriched.join('\n'));
  print('max lookups in flight: $maxInFlight');
}

Why they differ

The task changes character halfway through — synchronous ranking, then rate-limited I/O — and only one version's code changes character with it. In FxDart the seam is a single chain step: sortBy + take pick the merchants, toAsync crosses into async, and map + concurrent(2) run the lookups two at a time, in order. Native Dart has no primitive for "at most two in flight": Future.wait fires everything at once, so the bounded half becomes a hand-rolled worker pool — shared cursor, pre-sized result slots, worker futures — that dwarfs the two-line ranking it serves. Changing the limit, or dropping it, is one number in the chain versus that whole scaffold.

Benchmark

Apple M1 Max, 32 GB RAM · Dart 3.12.2 (AOT-compiled) · 2026-08-24

Async case: the headline scale is N = 100,000, not 1,000,000. Every element costs an event-loop turn on both sides, so a million real awaits would measure Dart's event loop for minutes — not the pipeline. Delays are zero-length and the example's concurrency limit is kept; what the bars compare is the pipeline machinery.

N = 100

Time Tie

Native Dart 214 µs

FxDart 237 µs

Peak memory Tie

Native Dart 16.6 MB

FxDart 16.6 MB

N = 10,000

Time Native wins

Native Dart 17.7 ms

FxDart 21.5 ms

Peak memory Tie

Native Dart 49.3 MB

FxDart 50.4 MB

N = 100,000

Time Native wins

Native Dart 195.0 ms

FxDart 233.0 ms

Peak memory Tie

Native Dart 81.4 MB

FxDart 84.0 MB

Bars are medians of repeated timed iterations in fresh processes per side (small N is batched for timer resolution). Sides within 5% of each other — or within 0.6 ms, a difference no person can perceive — count as a tie; close relative races are re-measured up to 5 runs. In an app, anything under a few milliseconds is invisible to the user regardless of which bar is shorter. Memory is peak process RSS. The Dart VM and the dataset are identical on both sides, so the difference between the two bars is what the pipeline itself holds onto.