Framework
Version
Debouncer API Reference
Throttler API Reference
Rate Limiter API Reference
Queue API Reference
Batcher API Reference

asyncThrottle

Function: asyncThrottle()

ts
function asyncThrottle<TFn>(fn, initialOptions): (...args) => Promise<undefined | ReturnType<TFn>>
function asyncThrottle<TFn>(fn, initialOptions): (...args) => Promise<undefined | ReturnType<TFn>>

Defined in: async-throttler.ts:457

Creates an async throttled function that limits how often the function can execute. The throttled function will execute at most once per wait period, even if called multiple times. If called while executing, it will wait until execution completes before scheduling the next call.

Unlike the non-async Throttler, this async version supports returning values from the throttled function, making it ideal for API calls and other async operations where you want the result of the maybeExecute call instead of setting the result on a state variable from within the throttled function.

Error Handling:

  • If an onError handler is provided, it will be called with the error and throttler instance
  • If throwOnError is true (default when no onError handler is provided), the error will be thrown
  • If throwOnError is false (default when onError handler is provided), the error will be swallowed
  • Both onError and throwOnError can be used together - the handler will be called before any error is thrown
  • The error state can be checked using the underlying AsyncThrottler instance

State Management:

  • Uses TanStack Store for reactive state management
  • Use initialState to provide initial state values when creating the async throttler
  • Use onSuccess callback to react to successful function execution and implement custom logic
  • Use onError callback to react to function execution errors and implement custom error handling
  • Use onSettled callback to react to function execution completion (success or error) and implement custom logic
  • The state includes error count, execution status, last execution time, and success/settle counts
  • State can be accessed via the underlying AsyncThrottler instance's store.state property
  • When using framework adapters (React/Solid), state is accessed from the hook's state property

Type Parameters

TFn extends AnyAsyncFunction

Parameters

fn

TFn

initialOptions

AsyncThrottlerOptions<TFn>

Returns

Function

Attempts to execute the throttled function. The execution behavior depends on the throttler options:

  • If enough time has passed since the last execution (>= wait period):

    • With leading=true: Executes immediately
    • With leading=false: Waits for the next trailing execution
  • If within the wait period:

    • With trailing=true: Schedules execution for end of wait period
    • With trailing=false: Drops the execution

Parameters

args

...Parameters<TFn>

Returns

Promise<undefined | ReturnType<TFn>>

Example

ts
const throttled = new AsyncThrottler(fn, { wait: 1000 });

// First call executes immediately
await throttled.maybeExecute('a', 'b');

// Call during wait period - gets throttled
await throttled.maybeExecute('c', 'd');
const throttled = new AsyncThrottler(fn, { wait: 1000 });

// First call executes immediately
await throttled.maybeExecute('a', 'b');

// Call during wait period - gets throttled
await throttled.maybeExecute('c', 'd');

Example

ts
const throttled = asyncThrottle(async (value: string) => {
  const result = await saveToAPI(value);
  return result; // Return value is preserved
}, {
  wait: 1000,
  onError: (error) => {
    console.error('API call failed:', error);
  }
});

// This will execute at most once per second
// Returns the API response directly
const result = await throttled(inputElement.value);
const throttled = asyncThrottle(async (value: string) => {
  const result = await saveToAPI(value);
  return result; // Return value is preserved
}, {
  wait: 1000,
  onError: (error) => {
    console.error('API call failed:', error);
  }
});

// This will execute at most once per second
// Returns the API response directly
const result = await throttled(inputElement.value);
Subscribe to Bytes

Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.

Bytes

No spam. Unsubscribe at any time.