`debounceOn`, `delayOn` & `throttleOn`

Selector-driven time: each value names the stream that decides when it is due — debounce, delay, and throttle without a Duration.

FxEvents<T> FxEvents<T>.debounceOn(Stream<void> Function(T value) selector) // chain (events) FxEvents<T> FxEvents<T>.delayOn(Stream<void> Function(T value) selector) FxEvents<T> FxEvents<T>.throttleOn(Stream<void> Function(T value) selector, {bool leading = true, bool trailing = false})

Lecture

The Duration forms already live on debounce, throttle, and delay — a fixed clock, the same wait for every value. The xOn family hands that clock to a selector: each value produces a stream, and the first event on that stream is the moment the value is due. Wait for a blur instead of 300ms; debounce longer queries longer; release a held value when a button fires rather than when a timer does.

debounceOn(selector) is trailing-edge debounce with that stream as the quiet window. A newer value aborts the previous inner and starts a fresh one; the inner's first next emits the pending value; an inner that completes without a next drops it. A value still pending when the source closes is flushed, matching Duration debounce.

delayOn(selector) holds every value until its own inner fires — nothing is aborted, so two in-flight values can pass each other if their selectors do, matching Rx's delayWhen. The close waits for outstanding inners; errors are forwarded immediately, since only data is worth holding.

throttleOn(selector) emits at most one event per inner window: leading (on by default, like the stream form of throttle) keeps the first of the window; trailing keeps the newest seen when the inner fires, or when the source closes mid-window. fxdart events layer, after Rx's selector forms of debounce, delayWhen, and throttle.

Demo 1 · A burst, released when its selector fires

Demo 2 · Held until a notifier says go

import 'dart:async';

import 'package:fxdart/fxdart.dart';

Future<void> main() async {
  // delayOn holds every value until ITS selector fires once. Here the
  // selector is a shared notifier, so nothing moves until we say go.
  final source = StreamController<String>();
  final release = StreamController<void>.broadcast();
  final seen = <String>[];
  final done = Completer<void>();

fxEvents(source.stream)
      .delayOn((_) => release.stream)
      .listen(seen.add, onDone: done.complete);

source
    ..add('held a')
    ..add('held b');
  await Future<void>.delayed(const Duration(milliseconds: 20));
  print(seen); // [] — both values are waiting on the notifier

release.add(null);
  await Future<void>.delayed(const Duration(milliseconds: 20));
  print(seen); // [held a, held b]

await source.close();
  await done.future;
  await release.close();
  // Inners run independently, so if two selectors fired out of order
  // the values would too — matching Rx's delayWhen. Inner completion
  // without a next drops that value; the close waits for outstanding
  // inners.
}

Try it yourself

Exercise: one scroll offset per inner window, leading edge.

import 'dart:async';

import 'package:fxdart/fxdart.dart';

/// Emits each (offsetMs, value) pair at its offset, closing at [closeMs].
Stream<T> timed<T>(List<(int, T)> events, int closeMs) {
  final c = StreamController<T>();
  for (final (ms, v) in events) {
    Timer(Duration(milliseconds: ms), () => c.add(v));
  }
  Timer(Duration(milliseconds: closeMs), c.close);
  return c.stream;
}

Future<void> main() async {
  // Exercise: a scroll offset firing constantly. throttleOn leading
  // (the default) keeps the first event of each inner window.
  final offsets = timed([(0, 0), (20, 40), (40, 90), (150, 160)], 200);

final leading = await fxEvents(offsets)
      .throttleOn((_) => Stream<void>.fromFuture(
            Future<void>.delayed(const Duration(milliseconds: 80)),
          ))
      .toList();

print(leading); // [0, 160]
  // The 80ms inner opened on 0 and swallowed 40 and 90; the next event
  // after that window (160) opened a new one. trailing: true would also
  // emit the newest value seen during each window.
}

Related: debounce — the Duration form, and the callback wrapper · throttle — the Duration form, leading and trailing · delay — shift a whole stream by a fixed clock

debounceOn, delayOn & throttleOn

Lecture

Demo 1 · A burst, released when its selector fires

Demo 2 · Held until a notifier says go

Try it yourself

`debounceOn`, `delayOn` & `throttleOn`