@kaelyx/ts-kit

Appearance

@kaelyx/ts-kit / function / debounceWithAbort

Function: debounceWithAbort() ​

debounceWithAbort<A, R>(fn, options?): DebounceWithAbortHandler<A, R>

Defined in: function/debounce-with-abort/debounce-with-abort.ts:126

Wraps an async function so that only the latest call matters. Each new call cancels the previous one: it clears a waiting timer, aborts an in-flight call through its AbortSignal, and resolves the superseded promise to undefined.

Type Parameters ​

A ​

A extends unknown[]

R ​

R

Parameters ​

fn ​

DebounceWithAbortAbortableFunction<A, R>

The async function. It gets an AbortSignal first, then the call's arguments.

options? ​

DebounceWithAbortOptions<A, R>

The debounce delay, callbacks and an optional parent signal. With no options, each call runs immediately and only aborts the previous call.

Returns ​

DebounceWithAbortHandler<A, R>

A handler with cancel, flush and pending. Each call resolves with the result, or undefined if the call was skipped, superseded, cancelled or handled by onError. It rejects with a real error from fn when onError is not set.

Example ​

ts
const search = debounceWithAbort(
  (signal, query: string) => fetch(`/search?q=${query}`, { signal }).then((r) => r.json()),
  { debounceMs: 300, shouldRun: (query) => query.length > 2 },
)
input.addEventListener('input', () => search(input.value))

Types ​

DebounceWithAbortAbortableFunction<A, R> type ​

DebounceWithAbortAbortableFunction<A, R> = (signal, ...args) => Promise<R>

Defined in: function/debounce-with-abort/debounce-with-abort.types.ts:8

An async function that debounceWithAbort can cancel. It gets an AbortSignal as its first argument, then the arguments that the caller passed.

Type Parameters ​

A ​

A extends unknown[]

R ​

R

Parameters ​

signal ​

AbortSignal

args ​

...A

Returns ​

Promise<R>

DebounceWithAbortHandler()<A, R> interface ​

Defined in: function/debounce-with-abort/debounce-with-abort.types.ts:35

The function that debounceWithAbort returns, with methods to control it.

Type Parameters ​

A ​

A extends unknown[]

R ​

R

DebounceWithAbortHandler(...args): Promise<R | undefined>

Defined in: function/debounce-with-abort/debounce-with-abort.types.ts:37

Resolves with the result, or undefined if the call was skipped, superseded, cancelled or handled by onError.

Parameters ​

args ​

...A

Returns ​

Promise<R | undefined>

Properties ​

cancel ​

cancel: () => void

Defined in: function/debounce-with-abort/debounce-with-abort.types.ts:40

Clears a waiting timer, aborts an in-flight call and resolves its promise to undefined.

Returns ​

void

flush ​

flush: () => Promise<R | undefined>

Defined in: function/debounce-with-abort/debounce-with-abort.types.ts:43

Runs a waiting call immediately, for example on blur or submit. Resolves to undefined if no call is waiting.

Returns ​

Promise<R | undefined>

pending ​

readonly pending: boolean

Defined in: function/debounce-with-abort/debounce-with-abort.types.ts:46

True while a call waits on its timer or is in flight.

DebounceWithAbortOptions<A, R> interface ​

Defined in: function/debounce-with-abort/debounce-with-abort.types.ts:14

Options for debounceWithAbort.

Type Parameters ​

A ​

A extends unknown[]

R ​

R

Properties ​

debounceMs? ​

optional debounceMs?: number

Defined in: function/debounce-with-abort/debounce-with-abort.types.ts:16

Delay in milliseconds before a call runs. 0 or less runs each call immediately (abort-only behaviour).

Default ​
ts
0.
onError? ​

optional onError?: (error, ...args) => void

Defined in: function/debounce-with-abort/debounce-with-abort.types.ts:28

Called for a real (non-abort) error. When set, the returned promise resolves to undefined instead of rejecting, so the handler is safe to use fire-and-forget as an event listener.

Parameters ​
error ​

unknown

args ​

...A

Returns ​

void

onSuccess? ​

optional onSuccess?: (result, ...args) => void

Defined in: function/debounce-with-abort/debounce-with-abort.types.ts:22

Called with the result of the latest call. Never called for a superseded or cancelled call.

Parameters ​
result ​

R

args ​

...A

Returns ​

void

shouldRun? ​

optional shouldRun?: (...args) => boolean

Defined in: function/debounce-with-abort/debounce-with-abort.types.ts:19

Return false to skip a call, for example below a minimum query length. A skipped call still cancels earlier calls.

Parameters ​
args ​

...A

Returns ​

boolean

signal? ​

optional signal?: AbortSignal

Defined in: function/debounce-with-abort/debounce-with-abort.types.ts:31

Parent signal, for example tied to a component's lifetime. Aborting it cancels and disables the handler.