debounce / throttle

Rate-limiting utilities for functions and callbacks.

import { debounce, throttle } from 'mates';

// debounce: fires only after activity stops for `wait` ms
const search = debounce((query: string) => {
  fetchResults(query);
}, 300);
search('h');     // cancelled (new call arrives within 300ms)
search('hello'); // fires after 300ms idle

// throttle: fires at most once per `limit` ms
const onScroll = throttle(() => {
  updatePosition(window.scrollY);
}, 100);
window.addEventListener('scroll', onScroll);

search.cancel(); // discard any pending debounced call
search.flush();  // execute immediately if a call is pending

Overview

debounce(fn, wait) delays calling fn until wait ms have passed without another call — ideal for search inputs and resize handlers. throttle(fn, limit) ensures fn fires at most once per limit ms — ideal for scroll and mousemove handlers.

Both return the wrapped function with two extra methods: .cancel() discards any pending call, and .flush() executes it immediately. They are plain utilities — not component-specific — so you can create them at module level or in a component's outer function.

debounce vs throttle

Utility	Fires when…	Best for
`debounce`	After activity stops for `wait` ms	Search fields, resize handlers, save-on-type — wait until the user pauses.
`throttle`	At most once per `limit` ms	Scroll position, mousemove, analytics — sample continuous events periodically.

debounce + throttle, plus cancel() / flush()

Move the mouse: debounce waits for idle, throttle samples. Type in the search field then hit search.cancel() to drop the pending call, or search.flush() to run it immediately.

import { html, atom, renderApp } from 'mates';

import { debounce, throttle } from 'mates';

const App = () => {

const rawCount = atom(0);

const debounceCount = atom(0);

const throttleCount = atom(0);

const lastEvent = atom('—');

const query = atom('');

const flushedQuery = atom('—');

const onDebounced = debounce(() => {

debounceCount.set(n => n + 1);

}, 400);

const onThrottled = throttle(() => {

throttleCount.set(n => n + 1);

}, 400);

// debounce returns .cancel() / .flush() on the same function

const search = debounce((q) => {

flushedQuery.set(q);

}, 500);

const handleMove = (e) => {

rawCount.set(n => n + 1);

lastEvent.set(`(${Math.round(e.clientX)}, ${Math.round(e.clientY)})`);

onDebounced();

onThrottled();

};

return () => html`

<div

class="card card-body p-20"

@mousemove=${handleMove}

API — debounce & throttle

import { debounce, throttle } from 'mates'

Prop / Option	Type	Default	Description
`debounce(fn, wait)`*	`DebouncedFn`	—	Returns a debounced version of fn. fn is called only after wait milliseconds have elapsed since the last invocation. All arguments are forwarded to fn.
`throttle(fn, limit)`*	`ThrottledFn`	—	Returns a throttled version of fn. fn is called at most once per limit milliseconds; excess calls within the window are dropped. All arguments are forwarded to fn.

Methods on the returned function

Prop / Option	Type	Default	Description
`.cancel()`	`void`	—	Discard any pending invocation immediately. Available on both debounced and throttled functions.
`.flush()`	`void`	—	Execute the pending call immediately (if one is waiting), then clear the timer. Useful when you need to force a final update on blur or unmount.

When to use which

Prop / Option	Type	Default	Description
`debounce`	`—`	—	Best for inputs where you want to wait until the user has stopped — search fields, resize handlers, save-on-type.
`throttle`	`—`	—	Best for continuous events where you want periodic sampling — scroll position, mousemove, window resize analytics.
`debouncedAtom / throttledAtom`	`—`	—	Prefer these when the source is a reactive atom inside a component — they auto-clean up and re-derive without manual .cancel().