debounced<T> static method

PostFrameTask<T> debounced<T>(FutureOr<T> action(), { Object? debounceKey, List<ScrollController> scrollControllers = const [], int maxWaitFrames = 5, bool waitForEndOfFrame = true, int endOfFramePasses = 2, Duration? timeout, PostFramePredicate? predicate, void onError(Object error, StackTrace stackTrace)?, })

Schedule action to run after the current frame, canceling any previous pending action with the same debounceKey.

This is useful when multiple calls might occur in quick succession (e.g., during rapid rebuilds) and you only want the latest to execute.

The debounceKey can be any object (typically a String or enum value). If omitted, the action itself is used as the key.

Implementation

static PostFrameTask<T> debounced<T>(
  FutureOr<T> Function() action, {
  Object? debounceKey,
  List<ScrollController> scrollControllers = const [],
  int maxWaitFrames = 5,
  bool waitForEndOfFrame = true,
  int endOfFramePasses = 2,
  Duration? timeout,
  PostFramePredicate? predicate,
  void Function(Object error, StackTrace stackTrace)? onError,
}) {
  final key = debounceKey ?? action;

  // Cancel any existing task with this key.
  final existing = _debouncedTasks[key];
  if (existing != null && !existing.isCanceled) {
    existing.cancel();
  }

  // Schedule new task.
  final task = run<T>(
    action,
    scrollControllers: scrollControllers,
    maxWaitFrames: maxWaitFrames,
    waitForEndOfFrame: waitForEndOfFrame,
    endOfFramePasses: endOfFramePasses,
    timeout: timeout,
    predicate: predicate,
    onError: onError,
  );

  _debouncedTasks[key] = task;

  // Clean up from map when done.
  task.future.whenComplete(() => _debouncedTasks.remove(key));

  return task;
}