flow.debounce()

Introduce a debounce on the flow's callback pipeline, limiting the amount of triggers coming through.

Debouncing limits triggers by ignoring all triggers until a certain amount of time passes that no triggers were received. More intuitively, it waits for a certain duration of inactivity before letting a trigger through.

Note: Throttling lets through a trigger as often as possible, but no more than once every duration. A debounce may not let any triggers through for as long as it is receiving triggers more often than once every duration. For throttling, see .throttle().

Syntax

flow.debounce(duration);

Parameters

duration: A number of milliseconds to use for the debounce.

Return value

The same Flow object the method was called on, allowing for method chaining.

Details

While the .debounce() method only receives a number, it does internally add a callback to the flow's pipeline, and a non-linear one at that. Some triggers it receives are swallowed, if another trigger reaches the callback before the duration runs out.

Specifically, the triggers that make it through are those which were not followed by another for the entirety of the duration. This may be relevant for pipelines that wish to use the trigger arguments.

Examples

When writing a search box with suggestions, we generally want to prevent sending a request every single keystroke; that would bombard the server with multiple requests per second per user searching. Instead, we can use a debounce to wait until the user is done typing, or otherwise inactive. Using when() in combination with .debounce() is perfect for this use case:

const input = document.querySelector('#search-input'); when(input).inputs().debounce(500).then(() => { // fetch and display suggestions });

Note that .throttle() would probably be less appropriate here because .throttle() would fire every duration milliseconds given the user is typing faster than the duration. This results in the requests being somewhat arbitrary when it comes to the search terms, because the user is still in the middle of typing. Using .debounce() gives us a more natural point to do the search requests, because most of the time, the user stops typing when the search term is (semi-)complete.

Usage notes

If the debounce queues up a trigger, but the flow is stopped (e.g. through .stop() or through a monitored context's undo) then the queued-up trigger is cleaned up as well and does not fire. More generally, stopped Flow objects can no longer fire triggers, and this also applies to debounced triggers.