philiprehberger_debounce

Debounce and throttle utilities with Stream transformers and cancellation

Requirements

• Dart >= 3.6

Installation

Add to your pubspec.yaml:

dependencies:
  philiprehberger_debounce: ^0.5.0

Then run:

dart pub get

Usage

import 'package:philiprehberger_debounce/debounce.dart';

final debouncer = Debouncer(delay: Duration(milliseconds: 300));
debouncer.call(() => print('Search executed'));
debouncer.call(() => print('Only this one runs'));

Immediate Mode

import 'package:philiprehberger_debounce/philiprehberger_debounce.dart';

final debouncer = Debouncer(delay: Duration(milliseconds: 300), immediate: true);
debouncer.call(() => print('Fires immediately, then ignores for 300ms'));

Flush Pending Action

final debouncer = Debouncer(delay: Duration(milliseconds: 300));
debouncer.call(() => saveData());

// On dispose, ensure the pending save executes immediately
debouncer.flush();

Max Wait

final debouncer = Debouncer(
  delay: Duration(milliseconds: 300),
  maxWait: Duration(milliseconds: 1000),
);

// Even with continuous calls, the action fires at least every 1000ms
for (var i = 0; i < 100; i++) {
  debouncer.call(() => print('Autosave'));
  await Future.delayed(Duration(milliseconds: 50));
}

Throttler

final throttler = Throttler(interval: Duration(seconds: 1));
throttler.call(() => print('Scroll handler'));
throttler.call(() => print('Skipped - too soon'));

Throttler Flush

final throttler = Throttler(
  interval: Duration(seconds: 1),
  trailing: true,
);
throttler.call(() => save()); // leading fires
throttler.call(() => save()); // queued as trailing

// On dispose, fire the queued trailing immediately
throttler.flush();

Stream Transformers

// Debounce a stream
textFieldStream
    .debounce(Duration(milliseconds: 300))
    .listen((query) => search(query));

// Throttle a stream (leading edge only)
scrollStream
    .throttle(Duration(milliseconds: 100))
    .listen((offset) => updateUI(offset));

// Throttle with guaranteed trailing value (great for sliders)
sliderStream
    .throttleLatest(Duration(milliseconds: 100))
    .listen((value) => saveValue(value));

API

Method	Description
Debouncer(delay:, {immediate, maxWait})	Create a debouncer with delay, optional immediate mode, and optional max wait
Debouncer.call(action)	Schedule action after delay, resetting on repeated calls
Debouncer.flush()	Immediately execute any pending action and cancel the timer
Debouncer.cancel()	Cancel any pending debounced call
Debouncer.isActive	Whether a debounced call is pending
Throttler(interval:, leading:, trailing:)	Create a throttler with interval and edge options
Throttler.call(action)	Execute action respecting the throttle interval
Throttler.flush()	Immediately execute pending trailing action and reset
Throttler.cancel()	Cancel any pending throttled call
Throttler.isActive	Whether the throttler is in its cooldown period
Stream.debounce(delay)	Emit only the last value after a pause of delay
Stream.throttle(interval)	Emit at most one value per interval (leading edge)
Stream.throttleLatest(interval)	Emit leading + guaranteed trailing latest per interval

Development

dart pub get
dart analyze --fatal-infos
dart test

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT