| name | asyncredux-throttle-mixin |
| description | Add the Throttle mixin to prevent actions from running too frequently. Covers setting the throttle duration in milliseconds, use cases like price refresh, and how freshness/staleness works. |
Throttle Mixin
The Throttle mixin limits action execution to at most once per throttle period. When an action is dispatched multiple times within the defined window, only the first execution runs while subsequent calls abort silently. After the period expires, the next dispatch is permitted.
Basic Usage
class LoadPrices extends AppAction with Throttle {
// Throttle period in milliseconds (default is 1000ms)
int get throttle => 5000; // 5 seconds
Future<AppState?> reduce() async {
var prices = await fetchCurrentPrices();
return state.copy(prices: prices);
}
}
The default throttle duration is 1000 milliseconds (1 second). Override the throttle getter to set a custom duration.
How Throttle Works (Freshness/Staleness)
Throttle uses a "freshness window" concept:
- First dispatch: Action runs immediately, data becomes "fresh"
- During throttle period: Data is considered fresh, subsequent dispatches are aborted
- After throttle period expires: Data becomes "stale", next dispatch is allowed to run
This ensures that frequently triggered actions (like a "Refresh Prices" button) don't overwhelm your server while still allowing updates after a reasonable interval.
// User taps "Refresh" rapidly 5 times in 2 seconds
// With a 5-second throttle:
// - 1st tap: Action runs, prices update
// - 2nd-5th taps: Silently aborted (data still "fresh")
// - Tap after 5 seconds: Action runs again (data now "stale")
Throttle vs Debounce
| Aspect | Throttle | Debounce |
|---|
| When it runs | Immediately on first dispatch | After dispatches stop |
| Blocking | Blocks for the period after running | Resets timer on each dispatch |
| Use case | Price refresh, rate-limited APIs | Search-as-you-type |
Bypassing Throttle
Override ignoreThrottle to conditionally skip rate limiting:
class LoadPrices extends AppAction with Throttle {
final bool forceRefresh;
LoadPrices({this.forceRefresh = false});
int get throttle => 5000;
// Bypass throttle when force refresh is requested
bool get ignoreThrottle => forceRefresh;
Future<AppState?> reduce() async {
var prices = await fetchCurrentPrices();
return state.copy(prices: prices);
}
}
// Normal dispatch - respects throttle
dispatch(LoadPrices());
// Force refresh - ignores throttle
dispatch(LoadPrices(forceRefresh: true));
Failure Handling
By default, the throttle lock persists even after errors, preventing immediate retry:
class LoadPrices extends AppAction with Throttle {
int get throttle => 5000;
// Allow immediate retry if the action fails
bool get removeLockOnError => true;
Future<AppState?> reduce() async {
var prices = await fetchCurrentPrices();
return state.copy(prices: prices);
}
}
Manual Lock Control
For more control, use these methods:
// Remove the lock for this specific action type
removeLock();
// Remove locks for all throttled actions
removeAllLocks();
Custom Locking Strategies
Override lockBuilder() to implement different locking behaviors:
class LoadPricesForSymbol extends AppAction with Throttle {
final String symbol;
LoadPricesForSymbol(this.symbol);
int get throttle => 5000;
// Use the symbol as part of the lock key
// This allows throttling per symbol instead of per action type
Object lockBuilder() => 'LoadPrices_$symbol';
Future<AppState?> reduce() async {
var price = await fetchPrice(symbol);
return state.copy(prices: state.prices.add(symbol, price));
}
}
// These can run in parallel (different lock keys):
dispatch(LoadPricesForSymbol('AAPL'));
dispatch(LoadPricesForSymbol('GOOGL'));
// But this will be throttled (same lock key as first):
dispatch(LoadPricesForSymbol('AAPL')); // Aborted if within 5 seconds
Common Use Cases
Price/Data Refresh
class RefreshStockPrices extends AppAction with Throttle {
int get throttle => 10000; // At most once every 10 seconds
Future<AppState?> reduce() async {
var prices = await stockApi.getAllPrices();
return state.copy(stockPrices: prices);
}
}
Rate-Limited API Calls
class SyncWithServer extends AppAction with Throttle {
int get throttle => 30000; // At most once every 30 seconds
Future<AppState?> reduce() async {
var data = await api.sync();
return state.copy(lastSync: DateTime.now(), data: data);
}
}
Preventing Button Spam
class SubmitFeedback extends AppAction with Throttle {
final String feedback;
SubmitFeedback(this.feedback);
int get throttle => 60000; // At most once per minute
Future<AppState?> reduce() async {
await api.submitFeedback(feedback);
return state.copy(feedbackSubmitted: true);
}
}
Mixin Compatibility
Compatible with:
CheckInternetNoDialogAbortWhenNoInternetRetryUnlimitedRetriesDebounce
Incompatible with:
NonReentrant (use one or the other, not both)OptimisticUpdateOptimisticSyncOptimisticSyncWithPush
Combining Multiple Mixins
class LoadPrices extends AppAction
with CheckInternet, Throttle, Retry {
int get throttle => 5000;
Future<AppState?> reduce() async {
// CheckInternet ensures connectivity
// Throttle prevents excessive calls
// Retry handles transient failures
var prices = await fetchCurrentPrices();
return state.copy(prices: prices);
}
}
References
URLs from the documentation:
