watch-debounced

Watch sources like Vue's watch, but run the callback only after the sources stayed quiet for debounce milliseconds.


Package	`@vizejs/composable/watch-debounced`
Own the source	`vize lib pull composable:watch-debounced`
Runtime exports	`watchDebounced`
Gzip budget	1536 B

Usage

import { watchDebounced } from "@vizejs/composable/watch-debounced";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`watchDebounced`	timing	experimental	deterministic-fallback	not-applicable	caller, reactive-scope	web, server, worker, native, desktop, terminal	`globalThis`, `window`	`tryOnScopeDispose`

API

`watchDebounced`

Watch sources like Vue's watch, but run the callback only after the sources stayed quiet for debounce milliseconds. The callback receives the newest value together with the old value from before the first change of the burst, so it always describes the whole settled transition. onCleanup registered by a callback runs before the next call, as with watch. maxWait bounds starvation under continuous changes. Source typing mirrors watch, including tuples and the immediate flag (an immediate first call is debounced too). Without a browser window (and without runOnServer) the callback runs synchronously, so server-side effects are not silently dropped. Timers are cleared when the watcher stops or the owning scope is disposed.

function watchDebounced< const Sources extends WatchSources, Immediate extends Readonly<boolean> = false, >( source: Sources, callback: WatchHelperCallback<Sources, Immediate>, options?: WatchDebouncedOptions<Immediate>, ): TimedWatchHandle

watchDebounced(query, (value) => search(value), { debounce: 300, maxWait: 1_000 });

`watchDebounced`

function watchDebounced( source: WatchSources, callback: WatchCallback<unknown, unknown>, options: WatchDebouncedOptions<boolean> = {}, ): TimedWatchHandle

Types

`WatchDebouncedOptions`

Options for watchDebounced.

Member	Type	Description
`debounce`?	`MaybeRefOrGetter<number>`	Quiet period in milliseconds after the last change before the callback runs. Reactive; read whenever a call is scheduled.
`maxWait`?	`MaybeRefOrGetter<number \| undefined>`	Longest time a call may be postponed by continuous changes. When it elapses, the newest pending call runs even if changes keep coming.
`runOnServer`?	`boolean`	Applies the timing policy when no browser `window` is available. When disabled, the callback runs synchronously on the server.
`scheduler`?	`TimeoutScheduler`	Owns the single-shot timers.

`TimedWatchHandle`

Stop handle plus timing controls returned by the debounced/throttled watchers.

Member	Type	Description
`stop`	`() => void`	Stop watching and discard any pending call.
`flush`	`() => boolean`	Run the pending call now instead of waiting.
`cancel`	`() => boolean`	Discard the pending call; later changes schedule again.