function useRateLimiter<TFn>(fn, options): RateLimiter<TFn>

function useRateLimiter<TFn>(fn, options): RateLimiter<TFn>

Defined in: react-pacer/src/rate-limiter/useRateLimiter.ts:55

A low-level React hook that creates a RateLimiter instance to enforce rate limits on function execution.

This hook is designed to be flexible and state-management agnostic - it simply returns a rate limiter instance that you can integrate with any state management solution (useState, Redux, Zustand, Jotai, etc).

Rate limiting is a simple "hard limit" approach that allows executions until a maximum count is reached within a time window, then blocks all subsequent calls until the window resets. Unlike throttling or debouncing, it does not attempt to space out or collapse executions intelligently.

The rate limiter supports two types of windows:

• 'fixed': A strict window that resets after the window period. All executions within the window count towards the limit, and the window resets completely after the period.
• 'sliding': A rolling window that allows executions as old ones expire. This provides a more consistent rate of execution over time.

For smoother execution patterns:

• Use throttling when you want consistent spacing between executions (e.g. UI updates)
• Use debouncing when you want to collapse rapid-fire events (e.g. search input)
• Use rate limiting only when you need to enforce hard limits (e.g. API rate limits)

The hook returns an object containing:

• maybeExecute: The rate-limited function that respects the configured limits
• getExecutionCount: Returns the number of successful executions
• getRejectionCount: Returns the number of rejected executions due to rate limiting
• getRemainingInWindow: Returns how many more executions are allowed in the current window
• reset: Resets the execution counts and window timing

• TFn extends AnyFunction

TFn

RateLimiterOptions<TFn>

RateLimiter<TFn>

// Basic rate limiting - max 5 calls per minute with a sliding window
const { maybeExecute } = useRateLimiter(apiCall, {
  limit: 5,
  window: 60000,
  windowType: 'sliding',
});

// Monitor rate limit status
const handleClick = () => {
  const remaining = getRemainingInWindow();
  if (remaining > 0) {
    maybeExecute(data);
  } else {
    showRateLimitWarning();
  }
};

// Basic rate limiting - max 5 calls per minute with a sliding window
const { maybeExecute } = useRateLimiter(apiCall, {
  limit: 5,
  window: 60000,
  windowType: 'sliding',
});

// Monitor rate limit status
const handleClick = () => {
  const remaining = getRemainingInWindow();
  if (remaining > 0) {
    maybeExecute(data);
  } else {
    showRateLimitWarning();
  }
};