Registry / devops / ioredis-ratelimit

ioredis-ratelimit

library3.1.1jsnpmunverified

A generic Redis-backed rate limiting tool built on top of ioredis. Current stable version is 3.1.1. Provides three limiting modes (binary, n-ary, uniform), batch operations, dynamic key generation, and minimum interval control. Fully tested with 100% coverage. Designed for Node.js environments with ioredis v5.8.2+. Differentiators include flexible modes, batch operations, and a simple API that can be used as Express middleware or standalone.

devops

npm install ioredis-ratelimit

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · IOREDIS-RATELIMIT

ioredis-ratelimit

devopsjavascriptv3.1.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.

RateLimiter

✓ import RateLimiter from 'ioredis-ratelimit'

✗ const RateLimiter = require('ioredis-ratelimit')

Package is ESM-only; CommonJS require will fail.

RateLimiter (default export)

✓ import RateLimiter from 'ioredis-ratelimit' // default export

✗ import { RateLimiter } from 'ioredis-ratelimit' // Named import does not exist

The package exports a single default function.

RateLimiter (TypeScript type)

✓ import RateLimiter from 'ioredis-ratelimit' // types are included

✗ import { RateLimiterOptions } from 'ioredis-ratelimit'

Types are bundled with the package; no separate type import is needed.

Creates a rate limiter allowing 10 requests per second and demonstrates consuming and checking quota.

import Redis from 'ioredis' import RateLimiter from 'ioredis-ratelimit' const ratelimiter = RateLimiter({ client: new Redis(), key: 'my-rate-limiter', limit: 10, duration: 1000 }) // Check rate limit await ratelimiter() // { total: 1, acknowledged: 1, remaining: 9 } // Get current status without consuming await ratelimiter.get() // { total: 1, remaining: 9, retryAfterMS: 0 }

Debug

Known issues

breakingPackage is ESM-only. Requires Node.js >= 12.22.0 or newer with "type": "module" in package.json.

fix

Use ES module syntax (import/export) and ensure "type": "module" in package.json.

affects: >=3.0.0

deprecatedIn mode 'nary', the acknowledged count may not equal requested count if the limit is exceeded in a partial way.

fix

Review documentation for mode behavior; consider using 'uniform' mode for smoother limiting.

affects: >=2.0.0

gotchaThe key option must be a string or a function returning a string. If using a function, it receives the id argument passed to ratelimiter().

fix

When using key as function, pass id to ratelimiter(id) to generate per-user keys.

affects: >=1.0.0

gotchaThe error option is thrown when limit exceeded, but it is not an HTTP-specific error; you must handle HTTP 429 yourself.

fix

Wrap ratelimiter calls in try-catch and return 429 response in Express/other middleware.

affects: >=1.0.0

gotchaThe TTL option defaults to duration. If you set a longer TTL, the key persists beyond the window, which may cause stale data.

fix

Set TTL to duration or do not set it unless you have specific persistence needs.

affects: >=1.0.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Package is ESM-only, but project uses CommonJS (require) or missing 'type':'module'.

fix

Add 'type': 'module' to package.json, or use dynamic import().

TypeError: RateLimiter is not a function

Using named import { RateLimiter } instead of default import.

fix

Use: import RateLimiter from 'ioredis-ratelimit'

Error: Too Many Requests

Rate limit exceeded; default error thrown.

fix

Catch the error and respond with appropriate status (e.g., 429 HTTP status). Customize via error option.

RateLimiter is not a constructor

Using new RateLimiter() instead of calling as a function.

fix

Call RateLimiter({...}) without new since it's a factory function.

Upgrade

Version history

3.1.1latest on npm

Audit

Dependencies

ioredisrequiredPeer dependency: ioredis client instance is required to connect to Redis

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/nswbmw/ioredis-ratelimit ↗

packageioredis-ratelimit ↗

homepagehttps://github.com/nswbmw/ioredis-ratelimit#readme ↗