Registry / security / ratelimit.js

ratelimit.js

JSON →
library1.8.0jsnpmunverified

A Node.js rate-limiting library using sliding windows stored in Redis. Version 1.8.0 (latest as of 2025) is stable with infrequent updates. It supports multiple rules per instance, whitelisting/blacklisting, and includes Express middleware. Compared to alternatives like express-rate-limit, it relies on Redis for distributed rate limiting and uses a sliding window algorithm for more accurate throttling.

securitydevops
npm install ratelimit.js
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · RATELIMIT.JS
R
ratelimit.js
securityjavascriptv1.8.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.

RateLimit
✓ const { RateLimit } = require('ratelimit.js');
✗ const RateLimit = require('ratelimit.js');
CommonJS only; ESM is not supported. The package exports RateLimit and ExpressMiddleware as named exports.
ExpressMiddleware
✓ const { ExpressMiddleware } = require('ratelimit.js');
✗ const ExpressMiddleware = require('ratelimit.js').ExpressMiddleware;
Named export; accessing via property on default export works but standard is destructuring.
RateLimit with ioredis
✓ const RateLimit = require('ratelimit.js').RateLimit; const limiter = new RateLimit(ioRedisClient, rules, { prefix: ioRedisClient.keyPrefix, clientPrefix: true });
✗ new RateLimit(ioRedisClient, rules, { prefix: 'myPrefix' });
When using ioredis with key prefixing, set clientPrefix: true and pass the ioRedisClient.keyPrefix as prefix to avoid double prefixing.

Demonstrates creating a RateLimit instance with two rules (per-second and per-hour) and checking if a key is rate limited.

const redis = require('redis'); const { RateLimit } = require('ratelimit.js'); const client = redis.createClient({ url: process.env.REDIS_URL ?? 'redis://localhost:6379' }); const rules = [ { interval: 1, limit: 5 }, { interval: 3600, limit: 1000, precision: 100 } ]; const limiter = new RateLimit(client, rules); const key = 'user:123'; limiter.incr(key, (err, isRateLimited) => { if (err) return console.error(err); console.log('Is rate limited?', isRateLimited); });
Debug
Known issues
gotchaThe precision option in rules can significantly increase Redis memory usage. High precision leads to more keys per interval.
fix
Use precision defaults (interval in seconds) or set precision to a lower value (e.g., precision: 100 for 100ms slots).
affects: >=1.0.0
gotchaWhitelist/blacklist keys are stored indefinitely; they must be explicitly removed or they will persist across application restarts.
fix
Use unwhitelist() or unblacklist() to remove entries, or implement TTL via external key expiration.
affects: >=1.0.0
gotchaThe library does not handle Redis connection errors gracefully; if Redis is down, incr() calls will return errors that must be handled.
fix
Wrap incr() calls with error handling and consider implementing a circuit breaker.
affects: >=1.0.0
breakingVersion 0.x used a different API (e.g., RateLimit.create). Upgrade path requires rewriting code to use constructor and incr().
fix
Migrate to 1.x by using new RateLimit(client, rules) and calling limiter.incr(key, callback).
affects: <1.0.0
Errors
Common errors & fixes
TypeError: RateLimit is not a constructor
Importing the package incorrectly; returns an object with named exports.
fix
Use const { RateLimit } = require('ratelimit.js'); then new RateLimit(...)
Error: Redis connection failed - connect ECONNREFUSED
Redis server is not running or URL is incorrect.
fix
Ensure Redis is running on localhost:6379 or set REDIS_URL environment variable properly.
Upgrade
Version history
1.8.0latest on npm
Audit
Dependencies
redisrequiredRequired for connecting to Redis to store rate limit state.
Agent activity
7 hits · last 30 days
node
6
OpenAI (training)
1
Resources
githubhttps://github.com/dudleycarr/ratelimit.js ↗
packageratelimit.js ↗
homepagehttp://ratelimit.io ↗
ratelimit.js — npm install ratelimit.js · libregistry