[whatwg/dom] Proposal: rate limiting event listeners (debounce / throttle) (Issue #1298)

### What problem are you trying to solve?

Developers often need to limit the frequency with which event handlers are being executed, both to improve **performance** and for **behavioral reasons**. Typically there are two distinct purposes, particularly when dealing with browser events fired in rapid succession: **Debouncing** delays the respective action until a steady state has been reached while **throttling** limits execution to once per time frame. (For details, see [Debouncing and Throttling Explained Through Examples](https://css-tricks.com/debouncing-throttling-explained-examples/), perhaps also consult [another visualization](http://web.archive.org/web/20180220130059/demo.nimius.net/debounce_throttle/).)

Examples include avoiding excessive GUI updates, either for performance reasons (e.g. in response to resizing or scrolling) or to prevent flickering (e.g. when visualizing pointer coordinates or network-connection states), as well as reducing the frequency of network requests (e.g. auto-completion for keyboard inputs). A [proposal from 2017](https://discourse.wicg.io/t/add-event-throttling-and-debouncing-to-addeventlisteneroptions/2436/) by @simevidas discusses additional use cases and considerations.

Providing a standardized approach for this common operation would enhance the web platform by reducing the need for custom implementations or third-party dependencies (in fact, it's not uncommon for an application to include multiple such implementations). In addition to browsers offering a **reliable and efficient implementation**, adding this capability to the platform would likely provide **educational benefits** by raising general awareness of debouncing and throttling.

### What solutions exist today?

There are myriad JavaScript implementations for both debouncing and throttling, going back to at least 2009 with [John Hann](http://unscriptable.com/2009/03/20/debouncing-javascript-methods/) and [Ben Alman](https://benalman.com/projects/jquery-throttle-debounce-plugin/). The concepts are also widely used in reactive programming; there might be parallel efforts within the context of the recent [JavaScript signals proposal](https://github.com/tc39/proposal-signals).

### How would you solve it?

Here we're primarily trying to address the issue of controlling browser events fired in rapid succession. Thus the obvious solution seems extending `addEventListener` with two new [options](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options): `debounce` and `throttle` (complementing `once`).

```javascript
document.body.addEventListener("input", console.log, {
    debounce: 200
});
document.body.addEventListener("pointermove", console.log, {
    throttle: true
});
```

Note that a general-purpose solution for debouncing and throttling in JavaScript would exceed the scope of this particular proposal. (Though it's conceivable that might happen naturally in the future, if perhaps more through convention than via shared implementations.)

That leaves the question which values those options should assume:

* boolean: `debounce: true` and `throttle: true` would [leave it up to browsers](https://adactio.com/journal/18982) to decide a suitable delay, which might have performance and other contextual benefits (cf. [`requestAnimationFrame`](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame)). While such a default will often be just fine, sometimes developers will need more control.
* number: `debounce: 200` and `throttle: 200` could specify a delay in milliseconds, much like with [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout), most likely addressing 90+ % of all use cases.
* Complex configuration options (e.g. lead time) exceed the scope of this proposal; see above. Such things could be implemented in userland while still benefiting from standardized rate limiting.
* Activating both debouncing and throttling at the same time might result in confusion, so we might need to guard against that? (I'm not sure using both ever makes sense.)

My inclination is that supporting both boolean and numbers would be nice, but I'm not sure there's a precedent for that. It might also complicate documentation and education.

### Anything else?

_No response_

-- 
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/dom/issues/1298
You are receiving this because you are subscribed to this thread.

Message ID: <whatwg/dom/issues/1298@github.com>