| name | asyncredux-debounce-mixin |
| description | Add the Debounce mixin to wait for user input pauses before acting. Covers setting the `debounce` duration, implementing search-as-you-type, and avoiding excessive API calls during rapid input. |
Debounce Mixin
The Debounce mixin delays action execution until after a period of inactivity. Each new dispatch resets the timer, so the action only runs once dispatching stops for the specified duration. This is ideal for search-as-you-type functionality and avoiding excessive API calls during rapid user input.
Basic Usage
Add the Debounce mixin to your action class:
class SearchText extends AppAction with Debounce {
final String searchTerm;
SearchText(this.searchTerm);
Future<AppState?> reduce() async {
var response = await http.get(
Uri.parse('https://example.com/?q=${Uri.encodeComponent(searchTerm)}')
);
return state.copy(searchResult: response.body);
}
}
When the user types quickly, each keystroke dispatches SearchText. The mixin delays execution, and each new dispatch resets the timer. The API call only happens once the user stops typing for the debounce period.
Setting the Debounce Duration
The default debounce period is 333 milliseconds. Override the debounce getter to customize:
class SearchText extends AppAction with Debounce {
final String searchTerm;
SearchText(this.searchTerm);
// Wait 1 second of inactivity before executing
int get debounce => 1000;
Future<AppState?> reduce() async {
var response = await http.get(
Uri.parse('https://example.com/?q=${Uri.encodeComponent(searchTerm)}')
);
return state.copy(searchResult: response.body);
}
}
Custom Lock Builder
By default, all instances of a debounced action share the same lock. Override lockBuilder() to create independent debounce periods for different action instances:
class SearchField extends AppAction with Debounce {
final String fieldId;
final String searchTerm;
SearchField(this.fieldId, this.searchTerm);
// Each fieldId gets its own independent debounce timer
Object? lockBuilder() => fieldId;
Future<AppState?> reduce() async {
// Search logic here
}
}
This enables multiple search fields to operate independently, each with their own debounce timer.
Debounce vs Throttle
These two mixins serve different purposes:
| Mixin | Behavior | Best For |
|---|
| Throttle | Runs immediately on first dispatch, then blocks subsequent dispatches for the period | Rate-limiting actions that should execute right away (e.g., refresh button) |
| Debounce | Waits for quiet time, only runs after dispatches stop | Waiting for user to finish input (e.g., search-as-you-type) |
Throttle: "Execute now, then wait before allowing again"
Debounce: "Wait until activity stops, then execute"
Mixin Compatibility
Debounce can be combined with:
CheckInternetNoDialogAbortWhenNoInternetNonReentrantFreshThrottle
Debounce cannot be combined with:
RetryUnlimitedRetriesUnlimitedRetryCheckInternetOptimisticCommandOptimisticSyncOptimisticSyncWithPushServerPush
References
URLs from the documentation:
