p-throttle

Throttle promise-returning & async functions

Also works with normal functions.

It rate-limits function calls without discarding them, making it ideal for external API interactions where avoiding call loss is crucial.

Install

1npm install p-throttle

Usage

This calls the function at most twice per second:

1import pThrottle from 'p-throttle';
2
3const now = Date.now();
4
5const throttle = pThrottle({
6	limit: 2,
7	interval: 1000
8});
9
10const throttled = throttle(async index => {
11	const secDiff = ((Date.now() - now) / 1000).toFixed();
12	return `${index}: ${secDiff}s`;
13});
14
15for (let index = 1; index <= 6; index++) {
16	(async () => {
17		console.log(await throttled(index));
18	})();
19}
20//=> 1: 0s
21//=> 2: 0s
22//=> 3: 1s
23//=> 4: 1s
24//=> 5: 2s
25//=> 6: 2s

API

pThrottle(options)

Returns a throttle function.

options

Type: object

Both the limit and interval options must be specified.

limit

Type: number

The maximum number of calls within an interval.

interval

Type: number

The timespan for limit in milliseconds.

strict

Type: boolean
Default: false

Use a strict, more resource-intensive, throttling algorithm. The default algorithm uses a windowed approach that will work correctly in most cases, limiting the total number of calls at the specified limit per interval window. The strict algorithm throttles each call individually, ensuring the limit is not exceeded for any interval.

signal

Type: AbortSignal

Abort pending executions. When aborted, all unresolved promises are rejected with signal.reason.

1import pThrottle from 'p-throttle';
2
3const controller = new AbortController();
4
5const throttle = pThrottle({
6	limit: 2,
7	interval: 1000,
8	signal: controller.signal
9});
10
11const throttled = throttle(() => {
12	console.log('Executing...');
13});
14
15await throttled();
16await throttled();
17controller.abort('aborted');
18await throttled();
19//=> Executing...
20//=> Executing...
21//=> Promise rejected with reason `aborted`

onDelay

Type: Function

Get notified when function calls are delayed due to exceeding the limit of allowed calls within the given interval. The delayed call arguments are passed to the onDelay callback.

Can be useful for monitoring the throttling efficiency.

In the following example, the third call gets delayed and triggers the onDelay callback:

1import pThrottle from 'p-throttle';
2
3const throttle = pThrottle({
4	limit: 2,
5	interval: 1000,
6	onDelay: (a, b) => {
7		console.log(`Reached interval limit, call is delayed for ${a} ${b}`);
8	},
9});
10
11const throttled = throttle((a, b) => {
12	console.log(`Executing with ${a} ${b}...`);
13});
14
15await throttled(1, 2);
16await throttled(3, 4);
17await throttled(5, 6);
18//=> Executing with 1 2...
19//=> Executing with 3 4...
20//=> Reached interval limit, call is delayed for 5 6
21//=> Executing with 5 6...

throttle(function_)

Returns a throttled version of function_.

function_

Type: Function

A promise-returning/async function or a normal function.

throttledFn.isEnabled

Type: boolean
Default: true

Whether future function calls should be throttled and count towards throttling thresholds.

throttledFn.queueSize

Type: number

The number of queued items waiting to be executed.

Related

• p-debounce - Debounce promise-returning & async functions
• p-limit - Run multiple promise-returning & async functions with limited concurrency
• p-memoize - Memoize promise-returning & async functions
• More…