Skip to main content

debounce

debounce creates a read-only observable that publishes the latest source value after a quiet period controlled by a scheduler.

Import​

import { debounce } from '@bedrock-core/observable';
import type { Debounced, DebounceScheduler } from '@bedrock-core/observable';

Signature​

debounce<T>(source: ReadonlyObservable<T>, schedule: DebounceScheduler, options?: ObservableOptions<T>): Debounced<T>

Parameters​

ParameterTypeDefaultDescription
source *ReadonlyObservable<T>—Provides the initial value and subsequent changes
schedule *DebounceScheduler—Defers one callback for the quiet period and returns its cancellation function
options.equalsEquals<T>Object.isCompares the incoming value with the last published value
options.labelstring—Named in the log when a listener throws

Returns​

type DebounceScheduler = (callback: () => void) => Unsubscribe;

interface Debounced<T> extends ReadonlyObservable<T> {
dispose(): void;
}

The returned value starts at source.get(). Each source notification cancels the pending callback and schedules another. get() retains the last published value while waiting. Listeners receive the settled value and the previously published value as (next, prev).

dispose() releases the source subscription and cancels pending delivery. The last published value remains readable.

Usage​

import { debounce, observable } from '@bedrock-core/observable';
import { afterTicks } from '@bedrock-core/observable/minecraft';

const query = observable('');
const settledQuery = debounce(query, afterTicks(5));

settledQuery.subscribe(next => console.warn(next));
query.set('stone');
query.set('stone bricks'); // publishes only this value after five quiet ticks

Call settledQuery.dispose() when its owner ends. afterTicks provides Minecraft tick scheduling and cancellation through the /minecraft entry. The main entry remains independent of Minecraft.

Examples​

A computed value after settling​

import { computed } from '@bedrock-core/observable';

const length = computed(() => settledQuery.get().length, [settledQuery]);

The computed reads the last published value and recomputes on a debounced notification.

Notes​

  • The scheduler owns the delay and its units. It must defer the callback and return a cancellation function that does not throw.
  • The source subscription is eager, so the value settles even when it has no downstream listeners.
  • A source change that returns to the last published value produces no notification under the default equality check.
  • A batch produces one source notification with its final value, so it schedules one delivery.
  • Disposing twice is safe. Each downstream subscription still has its own unsubscribe function.
  • Listeners are isolated using the same error reporting as observable.