js/page/debounce.html

54 lines
1.8 KiB
HTML

<link rel="stylesheet" href="style.css">
<script type="module" src="codeblock.js"></script>
<script type="module" src="filesize.js"></script>
<h1 class="js module">debounce.js</h1>
<code-block>import debounce from 'debounce.js'</code-block>
<section>
<h2>Description</h2>
<p>
Utility module for debouncing user-interactions (or any other events).
</p>
<p>
Its main application are cases where expensive operations like updating or querying data are performed in response to some event like a user typing into a search box.
</p>
<dl>
<code>
<dt>debounce</dt>
<dd>target &xrarr; wrapper</dd>
<dd>target, timeout &xrarr; wrapper</dd>
</code>
<dd>
A decorator function that takes a target function and returns a wrapper that will only call the target after a set timeout expires.
Repeatedly calling the wrapper while the timeout is running will reset the timeout without calling the target function.
</dd>
</dl>
<h2>Example</h2>
<code-block>
const update = value =&gt; expensive_operation(value)
input.addEventListener("change", debounce(event =&gt; update(input.value)))
</code-block>
This code will debounce the update event handler of an input element, calling the <code>update</code>
function only after no changes have been made for at least one second.
<h2>Methods</h2>
<p>
The returned wrapper function has the following methods and properties:
<dl>
<dt><code>cancel()</code></dt>
<dd>Cancels the running timeout without calling the target function.</dd>
<dt><code>now(...)</code></dt>
<dd>Cancels the running timeout and calls the target function immediately.</dd>
<dt><code>running</code></dt>
<dd><code>true</code> if there is a timeout currently running, <code>false</code> otherwise.</dd>
</dl>
</p>
</section>