rate_limiter 1.0.0

A pure dart package to apply useful rate limiting strategies on regular functions.

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]

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

1. Creating from scratch

final debouncedFunction = debounce((String value) {  
  print('Got value : $value');  
  return value;  
}, const Duration(seconds: 2));

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

1. Creating from scratch

final throttledFunction = throttle((String value) {  
  print('Got value : $value');  
  return value;  
}, const Duration(seconds: 2));

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.

1. 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,
);

2. 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();