`debounceOn`, `delayOn` & `throttleOn`

Tiempo impulsado por selector: cada valor nombra el stream que decide cuándo le toca — debounce, delay y throttle sin un 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})

Lección

Las formas con Duration ya viven en debounce, throttle y delay — un reloj fijo, la misma espera para cada valor. La familia xOn entrega ese reloj a un selector: cada valor produce un stream, y el primer evento de ese stream es el momento en que el valor toca. Espera un blur en vez de 300ms; debounce consultas más largas durante más tiempo; libera un valor retenido cuando dispara un botón en vez de cuando lo hace un temporizador.

debounceOn(selector) es debounce de flanco de bajada con ese stream como ventana de calma. Un valor más nuevo aborta el interior anterior y arranca uno fresco; el primer next del interior emite el valor pendiente; un interior que completa sin un next lo descarta. Un valor aún pendiente cuando la fuente se cierra se vacía, igual que el debounce con Duration.

delayOn(selector) retiene cada valor hasta que su propio interior dispara — nada se aborta, así que dos valores en vuelo pueden adelantarse si sus selectores lo hacen, igual que el delayWhen de Rx. El cierre espera a los interiores pendientes; los errores se reenvían de inmediato, ya que solo los datos merecen retenerse.

throttleOn(selector) emite como máximo un evento por ventana interior: leading (activado por defecto, como la forma stream de throttle) conserva el primero de la ventana; trailing conserva el más reciente visto cuando el interior dispara, o cuando la fuente se cierra a mitad de ventana. Capa de eventos de fxdart, según las formas con selector de debounce, delayWhen y throttle de Rx.

Demo 1 · Una ráfaga, liberada cuando dispara su selector

Demo 2 · Retenido hasta que un notificador diga adelante

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.
}

Pruébalo tú

Ejercicio: un offset de scroll por ventana interior, flanco de subida.

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.
}

Relacionado: debounce — la forma con Duration, y el wrapper de callback · throttle — la forma con Duration, leading y trailing · delay — desplazar un stream entero con un reloj fijo

debounceOn, delayOn & throttleOn

Lección

Demo 1 · Una ráfaga, liberada cuando dispara su selector

Demo 2 · Retenido hasta que un notificador diga adelante

Pruébalo tú

`debounceOn`, `delayOn` & `throttleOn`