bucket-queue

library1.0.1jsnpmunverified

bucket-queue v1.0.1 is a minimal Node.js promise queue implementing leaky bucket throttling. It is ideal for rate-limiting API calls to services like Shopify or GitHub. The package is stable but low maintenance (last release 2016, repository archived). It enforces max calls per time window, concurrency limits, and tick-based state updates. Only 10 JavaScript (no types) and CommonJS. Alternatives: p-limit, bottleneck, p-queue (more features and active maintenance).

devops

npm install bucket-queue

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BUCKET-QUEUE

bucket-queue

devopsjavascriptv1.0.1

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.

BucketQueue

✓ import BucketQueue from 'bucket-queue'

✗ const BucketQueue = require('bucket-queue'); // CommonJS require works, but import is recommended for ESM

Package is CommonJS, ESM import works in bundlers. Only default export.

default export (no named exports)

✓ const q = BucketQueue(options);

✗ const { BucketQueue } = require('bucket-queue'); // Named destructure fails

Only default export; no named export.

Queue instance (add, getState, start, stop)

✓ q.add(fn, args); q.getState(); q.start(); q.stop();

✗ BucketQueue.add(fn, args); // add is an instance method, not static

Methods exist only on instance returned by BucketQueue(options).

Shows creating a leaky bucket queue, adding promise-returning tasks (fetch), and inspecting state.

import BucketQueue from 'bucket-queue'; const q = BucketQueue({ calls: 6, perInterval: 60 * 1000, maxConcurrent: 4, tickFrequency: 100 }).start(); const userIds = [1, 2, 3, 4, 5]; const users = userIds.map((id) => { return q.add(fetch, `/user/${id}`) .then(res => res.json()) .then(user => console.log(user.name)); }); console.log(q.getState()); // { concurrent: 4, bucketCount: 4, queueCount: 1, waiting: false } q.stop();

Debug

Known issues

deprecatedRepository last updated in 2016 and no further releases or activity. Use actively maintained alternatives.

fix

Replace with p-limit, bottleneck, or p-queue.

affects: <=1.0.1

gotchaThe `calls` option specifies maximum calls per interval, but the bucket starts full. Initial burst may exceed limits momentarily.

fix

Set calls slightly lower than actual limit to account for burst, or use a different library with better initial bucket state.

affects: <=1.0.1

gotcha`tickFrequency` defaults to 10 ms; setting too high may cause lag, too low may cause high CPU usage.

fix

Keep default or adjust based on your interval length (e.g., 100 ms for 60s windows).

affects: <=1.0.1

gotchaThe `add` method expects a function that returns a promise; using async functions is fine, but passing a promise directly will break.

fix

Always pass a function: q.add(() => fetch(url)) rather than q.add(fetch(url)).

affects: <=1.0.1

gotcha`q.getState('waiting')` returns boolean only if key is 'waiting'; other keys return the whole state object.

fix

Use q.getState().waiting to avoid confusion.

affects: <=1.0.1

Errors

Common errors & fixes

TypeError: BucketQueue is not a constructor

Using default import without calling function (it's a factory, not a class).

fix

Use: const q = BucketQueue(options); (call the function)

TypeError: Cannot destructure property 'BucketQueue' of ... undefined

Trying to named import `BucketQueue` which doesn't exist.

fix

Use default import: import BucketQueue from 'bucket-queue';

Error: Cannot find module 'bucket-queue'

Package not installed or Node.js version too old (<4.0.0).

fix

Run `npm install bucket-queue` or upgrade Node.

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubgit://github.com/willhoag/bucket-queue ↗

packagebucket-queue ↗

homepagegit://github.com/willhoag/bucket-queue.git ↗