# p-throttle

> Throttle promise-returning & async functions

Latest version **8.1.0** (published 2025-11-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install p-throttle
pnpm add p-throttle
yarn add p-throttle
bun add p-throttle
```

## Health

**Score 48/100 (D)** — status: stable.

Positive: has types package; no vulnerabilities.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 8.1.0 |
| Published | 2025-11-08 |
| First published | 2016-10-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/p-throttle) |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 520 |
| Author | Sindre Sorhus |
| Maintainers | sindresorhus |
| Keywords | promise, throttle, throat, limit, limited, interval, rate, batch, ratelimit, queue, discard, async, await, promises, time, out, cancel, bluebird |

## Links

- npm: https://www.npmjs.com/package/p-throttle
- Repository: https://github.com/sindresorhus/p-throttle
- Homepage: https://github.com/sindresorhus/p-throttle#readme
- Issues: https://github.com/sindresorhus/p-throttle/issues
- Funding: https://github.com/sponsors/sindresorhus
- npm.io page: https://npm.io/package/p-throttle

## Alternatives

- [@commercetools/sync-actions](https://npm.io/package/@commercetools/sync-actions.md) — 25.1K weekly downloads
- [cwait](https://npm.io/package/cwait.md) — 21.4K weekly downloads
- [@ledgerhq/hw-app-cosmos](https://npm.io/package/@ledgerhq/hw-app-cosmos.md) — 4.2K weekly downloads
- [@financial-times/o-loading](https://npm.io/package/@financial-times/o-loading.md) — 2.8K weekly downloads
- [fa](https://npm.io/package/fa.md) — 185 weekly downloads

## Recent versions

- 8.1.0 (latest) — 2025-11-08
- 8.0.0 — 2025-08-21
- 7.0.0 — 2024-11-30
- 6.2.0 — 2024-08-14
- 6.1.0 — 2023-12-07
- 6.0.0 — 2023-11-17
- 5.1.0 — 2023-05-12
- 5.0.0 — 2021-10-04
- 4.1.1 — 2021-02-26
- 4.1.0 — 2021-02-21
- 4.0.0 — 2021-01-19
- 3.1.0 — 2019-04-06
- 3.0.0 — 2019-02-20
- 2.1.1 — 2019-02-18
- 2.1.0 — 2018-12-15
- … 3 more at https://npm.io/package/p-throttle/versions

## README

# 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. All calls are queued and executed—the last call is guaranteed to run with its original context and arguments preserved.

## Install

```sh
npm install p-throttle
```

## Browser

This package works in the browser with modern browsers that support `WeakRef` and `FinalizationRegistry` (Chrome 84+, Firefox 79+, Safari 14.1+, Edge 84+).

## Usage

This calls the function at most twice per second:

```js
import pThrottle from 'p-throttle';

const now = Date.now();

const throttle = pThrottle({
	limit: 2,
	interval: 1000
});

const throttled = throttle(async index => {
	const secDiff = ((Date.now() - now) / 1000).toFixed();
	return `${index}: ${secDiff}s`;
});

for (let index = 1; index <= 6; index++) {
	(async () => {
		console.log(await throttled(index));
	})();
}
//=> 1: 0s
//=> 2: 0s
//=> 3: 1s
//=> 4: 1s
//=> 5: 2s
//=> 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`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)

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

```js
import pThrottle from 'p-throttle';

const controller = new AbortController();

const throttle = pThrottle({
	limit: 2,
	interval: 1000,
	signal: controller.signal
});

const throttled = throttle(() => {
	console.log('Executing...');
});

await throttled();
await throttled();
controller.abort('aborted');
await throttled();
//=> Executing...
//=> Executing...
//=> 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:

```js
import pThrottle from 'p-throttle';

const throttle = pThrottle({
	limit: 2,
	interval: 1000,
	onDelay: (a, b) => {
		console.log(`Reached interval limit, call is delayed for ${a} ${b}`);
	},
});

const throttled = throttle((a, b) => {
	console.log(`Executing with ${a} ${b}...`);
});

await throttled(1, 2);
await throttled(3, 4);
await throttled(5, 6);
//=> Executing with 1 2...
//=> Executing with 3 4...
//=> Reached interval limit, call is delayed for 5 6
//=> Executing with 5 6...
```

##### weight

Type: `Function`

Calculate the weight/cost of each function call based on its arguments.

The weight determines how much of the `limit` is consumed by each call. This is useful for rate limiting APIs that use point-based or cost-based limits, where different operations consume different amounts of the quota.

By default, each call has a weight of `1`.

In the following example, queries with different numbers of tables consume different amounts of the rate limit:

```js
import pThrottle from 'p-throttle';

// Storyblok GraphQL API: 100 points per second
// Each query costs 1 point for the connection plus 1 point per table
const throttle = pThrottle({
	limit: 100,
	interval: 1000,
	weight: numberOfTables => 1 + numberOfTables
});

const fetchData = throttle(numberOfTables => {
	// Fetch GraphQL data
	return fetch('...');
});

await fetchData(1); // Costs 2 points
await fetchData(3); // Costs 4 points
```

### 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.

This can be useful for implementing queue management strategies, such as using a fallback when the queue is too full.

```js
import pThrottle from 'p-throttle';

const throttle = pThrottle({limit: 1, interval: 1000});

const accurateData = throttle(() => fetch('https://accurate-api.example.com'));
const roughData = () => fetch('https://rough-api.example.com');

async function getData() {
	if (accurateData.queueSize >= 3) {
		return roughData(); // Queue full, use fallback
	}

	return accurateData();
}
```

## Related

- [p-debounce](https://github.com/sindresorhus/p-debounce) - Debounce promise-returning & async functions
- [p-limit](https://github.com/sindresorhus/p-limit) - Run multiple promise-returning & async functions with limited concurrency
- [p-memoize](https://github.com/sindresorhus/p-memoize) - Memoize promise-returning & async functions
- [More…](https://github.com/sindresorhus/promise-fun)

---
_Source: https://npm.io/package/p-throttle · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._