throttled-queue

library3.0.0jsnpmunverified

Rate-limit arbitrary asynchronous or synchronous code with a FIFO queue that drains at a controlled interval. Version 3.0.0 is current, actively maintained, and ships TypeScript definitions. Unlike lodash throttle, throttled-queue never drops executions — every call is queued and executed at the configured rate. Supports browser and Node.js, with optional even spacing and convenience helpers (seconds, minutes, hours). Breaking changes from v2: named import required, options passed as single object.

testing

npm install throttled-queue

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · THROTTLED-QUEUE

throttled-queue

testingjavascriptv3.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

throttledQueue

✓ import { throttledQueue } from 'throttled-queue'

✗ import throttledQueue from 'throttled-queue'

Version 3 switched to a named export. Default import works only in v2 and below.

require('throttled-queue')

✓ const { throttledQueue } = require('throttled-queue')

✗ const throttledQueue = require('throttled-queue')

CommonJS require must destructure the named export.

seconds

✓ import { seconds } from 'throttled-queue'

Convenience helper for interval. Also available: minutes, hours.

ThrottledQueueOptions

✓ import type { ThrottledQueueOptions } from 'throttled-queue'

Optional TypeScript type import for the options object.

Creates a throttle that allows up to 5 executions per second, with even spacing. Queues 20 requests; logs each with timestamp.

import { throttledQueue, seconds } from 'throttled-queue'; const throttle = throttledQueue({ maxPerInterval: 5, interval: seconds(1), // or 1000ms evenlySpaced: true, }); for (let i = 0; i < 20; i++) { throttle(() => { console.log(`Request ${i} at ${Date.now()}`); }); }

Debug

Known issues

breakingVersion 3 changes import syntax from default to named export and options from positional arguments to a single object.

fix

Use `import { throttledQueue } from 'throttled-queue'` and pass options as `{ maxPerInterval, interval, evenlySpaced }`.

affects: >=3.0.0

gotchaThe `interval` option expects milliseconds. Using `seconds` etc. is recommended to avoid unit confusion.

fix

Use helpers like `seconds(1)` or pass `1000` explicitly for one second.

affects: >=3.0.0

gotchaIf `evenlySpaced` is set to `true`, the queue will space executions evenly over the interval. With small intervals or high concurrency, this can delay the first execution.

fix

Consider whether even spacing is important; omit or set to `false` for immediate queuing.

affects: >=3.0.0

gotchaThe throttle does not automatically retry or handle failures. The promise returned by `throttle(fn)` rejects if the function throws or returns a rejected promise.

fix

Wrap in try/catch or attach .catch() to each throttled call.

affects: >=1.0.0

deprecatedIn version 2, `throttledQueue(maxPerInterval, interval, evenlySpaced)` was the signature. This is deprecated and removed in v3.

fix

Upgrade to v3 with the new options object syntax.

affects: >=2.0.0 <3.0.0

Errors

Common errors & fixes

TypeError: throttledQueue is not a function

Using default import in v3 instead of named import.

fix

Change to `import { throttledQueue } from 'throttled-queue'`.

TypeError: throttledQueue is not a function

Using CommonJS require without destructuring.

fix

Use `const { throttledQueue } = require('throttled-queue')`.

Error: The "interval" option must be a positive number.

Passing NaN, string, or undefined as interval value.

fix

Ensure interval is a number in milliseconds, e.g., `interval: 1000` or `interval: seconds(1)`.

Error: The "maxPerInterval" option must be a positive integer.

Passing zero, negative number, or non-integer.

fix

Use a positive integer like `maxPerInterval: 5`.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/shaunpersad/throttled-queue ↗

packagethrottled-queue ↗

homepagehttps://github.com/shaunpersad/throttled-queue#readme ↗