throttle function

VoidCallback throttle(
  1. VoidCallback fn,
  2. Duration interval
)

Throttle (time) — max one call per interval. Roadmap #177.

The returned closure cannot be cancelled: a pending trailing invocation still fires after interval even if the owner is disposed. Use throttleCancelable when you need to drop a pending call on teardown. Audited: 2026-06-12 11:26 EDT

Implementation

VoidCallback throttle(VoidCallback fn, Duration interval) {
  DateTime? lastCall;
  Timer? timer;
  return () {
    final DateTime now = DateTime.now();
    final last = lastCall;
    if (last == null || now.difference(last) >= interval) {
      lastCall = now; // ignore: avoid_unused_assignment - used on next invocation
      fn();
      return;
    }
    if (timer?.isActive ?? false) return;
    final newTimer = Timer(
      interval,
      () {
        lastCall = DateTime.now();
        fn();
      },
    );
    timer = newTimer;
  };
}