Rate Limiter
[ Built with ♥ at Stream ]
Introduction
Rate limiting is a strategy for limiting an action. It puts a cap on how often someone can repeat an action within a certain timeframe. Using rate_limiter we made it easier than ever to apply these strategies on regular dart functions.
( Inspired from lodash )
Index
Installation
Add the following to your pubspec.yaml and replace [version] with the latest version:
dependencies:
rate_limiter: ^[version]
Strategies
Debounce
A debounced function will ignore all calls to it until the calls have stopped for a specified time period. Only then it will call the original function. For instance, if we specify the time as two seconds, and the debounced function is called 10 times with an interval of one second between each call, the function will not call the original function until two seconds after the last (tenth) call.
Usage
It's fairly simple to create debounced function with rate_limiter
- Creating from scratch
final debouncedFunction = debounce((String value) {
print('Got value : $value');
return value;
}, const Duration(seconds: 2));
- Converting an existing function into debounced function
String regularFunction(String value) {
print('Got value : $value');
return value;
}
final debouncedFunction = regularFunction.debounced(
const Duration(seconds: 2),
);
Example
Often times, search boxes offer dropdowns that provide autocomplete options for the user’s current input. Sometimes the items suggested are fetched from the backend via API (for instance, on Google Maps). The autocomplete API gets called whenever the search query changes. Without debounce, an API call would be made for every letter you type, even if you’re typing very fast. Debouncing by one second will ensure that the autocomplete function does nothing until one second after the user is done typing.
final debouncedAutocompleteSearch = debounce(
(String searchQuery) async {
// fetches results from the api
final results = await searchApi.get(searchQuery);
// updates suggestion list
updateSearchSuggestions(results);
},
const Duration(seconds: 1),
);
TextField(
onChanged: (query) {
debouncedAutocompleteSearch([query]);
},
);
Throttle
To throttle a function means to ensure that the function is called at most once in a specified time period (for instance, once every 10 seconds). This means throttling will prevent a function from running if it has run “recently”. Throttling also ensures a function is run regularly at a fixed rate.
Usage
Creating throttled function is similar to debounce function
- Creating from scratch
final throttledFunction = throttle((String value) {
print('Got value : $value');
return value;
}, const Duration(seconds: 2));
- Converting an existing function into throttled function
String regularFunction(String value) {
print('Got value : $value');
return value;
}
final throttledFunction = regularFunction.throttled(
const Duration(seconds: 2),
);
Example
In action games, the user often performs a key action by pushing a button (example: shooting, punching). But, as any gamer knows, users often press the buttons much more than is necessary, probably due to the excitement and intensity of the action. So the user might hit “Punch” 10 times in 5 seconds, but the game character can only throw one punch in one second. In such a situation, it makes sense to throttle the action. In this case, throttling the “Punch” action to one second would ignore the second button press each second.
final throttledPerformPunch = throttle(
() {
print('Performed one punch to the opponent');
},
const Duration(seconds: 1),
);
RaisedButton(
onPressed: (){
throttledPerformPunch();
}
child: Text('Punch')
);
BackOff
BackOff is a strategy that allows you to retry a function call multiple times with a delay between each call. It is useful when you want to retry a function call multiple times in case of failure.
Usage
Creating backoff function is similar to debounce and throttle function.
- Creating from scratch
final response = backOff(
// Make a GET request
() => http.get('https://google.com').timeout(Duration(seconds: 5)),
maxAttempts: 5,
maxDelay: Duration(seconds: 5),
// Retry on SocketException or TimeoutException
retryIf: (e, _) => e is SocketException || e is TimeoutException,
);
- Converting an existing function into backoff function
Future<String> regularFunction() async {
// Make a GET request
final response = await http.get('https://google.com').timeout(Duration(seconds: 5));
return response.body;
}
final response = regularFunction.backOff(
maxAttempts: 5,
maxDelay: Duration(seconds: 5),
// Retry on SocketException or TimeoutException
retryIf: (e, _) => e is SocketException || e is TimeoutException,
);
Example
While making a network request, it is possible that the request fails due to network issues. In such cases, it is useful to retry the request multiple times with a delay between each call. This is where backoff strategy comes in handy.
final response = backOff(
// Make a GET request
() => http.get('https://google.com').timeout(Duration(seconds: 5)),
maxAttempts: 5,
maxDelay: Duration(seconds: 5),
// Retry on SocketException or TimeoutException
retryIf: (e, _) => e is SocketException || e is TimeoutException,
);
Pending
Used to check if the there are functions still remaining to get invoked.
final pending = debouncedFunction.isPending;
final pending = throttledFunction.isPending;
Flush
Used to immediately invoke all the remaining delayed functions.
final result = debouncedFunction.flush();
final result = throttledFunction.flush();
Cancellation
Used to cancel all the remaining delayed functions.
debouncedFunction.cancel();
throttledFunction.cancel();