function useRateLimiter<TFn, TArgs>(fn, options): object
function useRateLimiter<TFn, TArgs>(fn, options): object
Defined in: react-pacer/src/rate-limiter/useRateLimiter.ts:53
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.
For smoother execution patterns:
The hook returns an object containing:
• TFn extends (...args) => any
• TArgs extends any[]
TFn
RateLimiterOptions
object
readonly getExecutionCount: () => number;
readonly getExecutionCount: () => number;
Returns the number of times the function has been executed
number
readonly getRejectionCount: () => number;
readonly getRejectionCount: () => number;
Returns the number of times the function has been rejected
number
readonly getRemainingInWindow: () => number;
readonly getRemainingInWindow: () => number;
Returns the number of remaining executions allowed in the current window
number
readonly maybeExecute: (...args) => boolean;
readonly maybeExecute: (...args) => boolean;
Attempts to execute the rate-limited function if within the configured limits. Will reject execution if the number of calls in the current window exceeds the limit.
...TArgs
boolean
const rateLimiter = new RateLimiter(fn, { limit: 5, window: 1000 });
// First 5 calls will return true
rateLimiter.maybeExecute('arg1', 'arg2'); // true
// Additional calls within the window will return false
rateLimiter.maybeExecute('arg1', 'arg2'); // false
const rateLimiter = new RateLimiter(fn, { limit: 5, window: 1000 });
// First 5 calls will return true
rateLimiter.maybeExecute('arg1', 'arg2'); // true
// Additional calls within the window will return false
rateLimiter.maybeExecute('arg1', 'arg2'); // false
readonly reset: () => void;
readonly reset: () => void;
Resets the rate limiter state
void
// Basic rate limiting - max 5 calls per minute
const { maybeExecute } = useRateLimiter(apiCall, {
maxExecutions: 5,
windowMs: 60000
});
// With Redux
const dispatch = useDispatch();
const { maybeExecute, getRemainingInWindow } = useRateLimiter(
(value) => dispatch(updateAction(value)),
{ maxExecutions: 10, windowMs: 30000 }
);
// Monitor rate limit status
const handleClick = () => {
const remaining = getRemainingInWindow();
if (remaining > 0) {
maybeExecute(data);
} else {
showRateLimitWarning();
}
};
// Basic rate limiting - max 5 calls per minute
const { maybeExecute } = useRateLimiter(apiCall, {
maxExecutions: 5,
windowMs: 60000
});
// With Redux
const dispatch = useDispatch();
const { maybeExecute, getRemainingInWindow } = useRateLimiter(
(value) => dispatch(updateAction(value)),
{ maxExecutions: 10, windowMs: 30000 }
);
// Monitor rate limit status
const handleClick = () => {
const remaining = getRemainingInWindow();
if (remaining > 0) {
maybeExecute(data);
} else {
showRateLimitWarning();
}
};
Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.