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:

dart

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:

dart

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:

dart

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:

•CheckInternet
•NoDialog
•AbortWhenNoInternet
•NonReentrant
•Fresh
•Throttle

Debounce cannot be combined with:

•Retry
•UnlimitedRetries
•UnlimitedRetryCheckInternet
•OptimisticCommand
•OptimisticSync
•OptimisticSyncWithPush
•ServerPush

References

URLs from the documentation: