rate_limiter

Description:

rate limiter

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
Strategies

Debounce

Throttle
BackOff




Pending
Flush
Cancellation

Installation #
Add the following to your pubspec.yaml and replace [version] with the latest version:
dependencies:
rate_limiter: ^[version]
copied to clipboard
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));
copied to clipboard

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),
);
copied to clipboard
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]);
},
);
copied to clipboard
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));
copied to clipboard

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),
);
copied to clipboard
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')
);
copied to clipboard
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,
);
copied to clipboard

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,
);
copied to clipboard
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,
);
copied to clipboard
Pending #
Used to check if the there are functions still remaining to get invoked.
final pending = debouncedFunction.isPending;
final pending = throttledFunction.isPending;
copied to clipboard
Flush #
Used to immediately invoke all the remaining delayed functions.
final result = debouncedFunction.flush();
final result = throttledFunction.flush();
copied to clipboard
Cancellation #
Used to cancel all the remaining delayed functions.
debouncedFunction.cancel();
throttledFunction.cancel();
copied to clipboard