Registry / testing / redis-token-bucket-ratelimiter

redis-token-bucket-ratelimiter

JSON →
library0.5.1jsnpmunverified

A rolling token bucket rate limiter implemented via a Lua script in Redis for atomic operations. v0.5.1 is the latest stable version. It supports ioredis (including Redis Cluster) and node-redis clients. Key differentiator: uses a Lua script to prevent blocked actions from subtracting from the bucket and ensures consistency, even with concurrent requests. Ideal for Node.js applications needing precise rate limiting with Redis.

testing
npm install redis-token-bucket-ratelimiter
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · REDIS-TOKEN-BUCKET
R
redis-token-bucket-ratelimiter
testingjavascriptv0.5.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.

RollingLimit
✓ const RollingLimit = require('redis-token-bucket-ratelimiter')
✗ import RollingLimit from 'redis-token-bucket-ratelimiter'
Package does not ship ESM; CommonJS require is required.
RollingLimit
✓ const { RollingLimit } = require('redis-token-bucket-ratelimiter')
✗ import { RollingLimit } from 'redis-token-bucket-ratelimiter'
Only default export exists; named import fails with ESM.
stubLimit
✓ const { RollingLimit } = require('redis-token-bucket-ratelimiter'); RollingLimit.stubLimit(5)
✗ require('redis-token-bucket-ratelimiter').stubLimit(5)
stubLimit is a static method on RollingLimit.

Creates a RollingLimit with a 60-second interval, 10 maximum uses, then checks rate limit for a user ID, logging remaining tokens and retry time.

const RollingLimit = require('redis-token-bucket-ratelimiter'); const Redis = require('ioredis'); const redis = new Redis({ host: 'localhost', port: 6379 }); const limiter = new RollingLimit({ interval: 60000, limit: 10, redis: redis, prefix: 'myapp:', }); async function checkRateLimit(userId) { const result = await limiter.use(userId); console.log(`Remaining: ${result.remaining}`); if (result.rejected) { console.log(`Rate limited, retry in ${result.retryDelta}ms`); } return result; } checkRateLimit('user123').catch(console.error);
Debug
Known issues
gotcha`interval` and `limit` are required but not validated; passing invalid values may cause runtime errors.
fix
Ensure interval > 0 and limit >= 0.
affects: >=0.0.1
gotchaThe `redis` client must be connected before using the limiter, or calls will hang.
fix
Call `await redis.connect()` before creating the limiter.
affects: >=0.0.1
gotchaThe `prefix` option does not automatically append a colon; if you want a separator, include it manually.
fix
Use `prefix: 'myapp:'` instead of `prefix: 'myapp'`.
affects: >=0.4.0
deprecatedThe `force` option is deprecated; it allows the bucket to go negative, which may lead to inconsistent behavior.
fix
Avoid using `force`; instead design logic to handle rejection.
affects: >=0.5.0
gotchaUsing `amount: 0` with `limiter.use(id, 0)` still deducts tokens? No, it only returns current count; but this behavior is not documented and may be confusing.
fix
Refer to source code to confirm behavior with amount=0.
affects: >=0.5.0
Errors
Common errors & fixes
RollingLimit is not a constructor
ESM import or destructuring incorrect
fix
Use `const RollingLimit = require('redis-token-bucket-ratelimiter')`.
Error: The client is closed
Redis client not connected before limiter usage
fix
Add `await redis.connect()` or ensure connection is established.
TypeError: limiter.use is not a function
Incorrect import or no default export
fix
Verify correct import: `const RollingLimit = require('redis-token-bucket-ratelimiter')` and then `const limiter = new RollingLimit(...)`.
Upgrade
Version history
0.5.1latest on npm
Audit
Dependencies
ioredisoptionalPrimary Redis client used in examples
redisoptionalAlternative Redis client supported
Agent activity
4 hits · last 30 days
node
4
Resources
githubssh://git@github.com/BitMEX/node-redis-token-bucket-ratelimiter ↗
packageredis-token-bucket-ratelimiter ↗
homepagehttps://github.com/BitMEX/node-redis-token-bucket-ratelimiter#readme ↗
redis-token-bucket-ratelimiter — npm install redis-token-bucket-ratelimiter · libregistry