oss-ratelimit

library2.6.0jsnpmunverified

A production-ready, open-source rate limiting library for Node.js and Next.js, built with TypeScript. v2.6.0 supports multiple algorithms (fixed window, sliding window, token bucket) via efficient Redis and Lua scripts. Features an optional registry system for managing multiple limiter configurations, ephemeral in-memory cache for resilience, configurable fail-open/closed strategies, analytics, and blocking support. Distributed under MIT license, actively maintained with regular releases.

devops security

npm install oss-ratelimit

package ↗

INSTALL

IMPORT

SIG · OSS-RATELIMIT

oss-ratelimit

devopsjavascriptv2.6.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

✓ import { Ratelimit } from 'oss-ratelimit'

✗ var Ratelimit = require('oss-ratelimit').default

Named export; the library is ESM-only. Correct import via named export, not default.

slidingWindow

✓ import { slidingWindow } from 'oss-ratelimit'

✗ import slidingWindow from 'oss-ratelimit'

Function algorithm export; must import as named export.

getRedisClient

✓ import { getRedisClient } from 'oss-ratelimit'

✗ const { getRedisClient } = require('oss-ratelimit')

Helper function to create a Redis client; ESM only.

RateLimitConfig

✓ import type { RateLimitConfig } from 'oss-ratelimit'

TypeScript type export; use type import. Not available at runtime.

initRateLimit

✓ import { initRateLimit } from 'oss-ratelimit'

✗ import { initRateLimit } from 'oss-ratelimit/registry'

Registry initialization function; exported from main entry point. No subpath needed.

Basic usage creating a sliding window rate limiter with one Redis client, then calling limit() on an identifier.

import { createClient } from 'redis'; import { Ratelimit, slidingWindow, getRedisClient } from 'oss-ratelimit'; async function run() { const redis = await getRedisClient({ url: process.env.REDIS_URL ?? 'redis://localhost:6379' }); const limiter = new Ratelimit({ redis, limiter: slidingWindow(10, '10 s'), prefix: 'quickstart', ephemeralCache: false, }); const result = await limiter.limit('user:123'); console.log(result); if (!result.success) { console.warn(`Rate limit exceeded. Retry after ${result.retryAfter}s`); } await redis.quit(); } run().catch(console.error);

Debug

Known issues

gotchaThe library is ESM-only; using require() in a CommonJS project will throw an error.

fix

Use dynamic import: const { Ratelimit } = await import('oss-ratelimit'); or switch your project to ESM.

affects: >=2.0.0

deprecatedThe 'Regions' concept from Upstash vercel/kv style is not supported; use 'getRedisClient' helper instead.

fix

Replace 'regions' config with a single Redis client using 'getRedisClient'.

affects: >=2.0.0

breakingIn v2.6.0, the registry function 'initRateLimit' returns a new API object; previous v1 API with 'createRateLimit' is removed.

fix

Update imports: use 'initRateLimit' from 'oss-ratelimit' and adjust usage per registry documentation.

affects: >=2.0.0

gotchaThe 'redis' peer dependency requires v4.0.0 or higher; using older versions may cause incompatibility.

fix

Install redis@^4.0.0: npm install redis@^4.0.0

affects: >=2.0.0

gotchaEphemeral cache is only available for Sliding Window algorithm; other algorithms ignore it.

fix

If using ephemeral cache, ensure limiter is slidingWindow(); otherwise set ephemeralCache: false.

affects: >=2.0.0

gotchaThe limit() method returns null for unsupported identifiers (e.g., empty string).

fix

Always use a non-empty string as the identifier.

affects: >=2.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported

Using require() to load the library in a CommonJS file.

fix

Use dynamic import: const { Ratelimit } = await import('oss-ratelimit'); or convert project to ESM.

TypeError: Cannot read properties of undefined (reading 'limit')

Registry not initialized properly or limiter not returned from initRateLimit.

fix

Ensure initRateLimit is called and returns the Registry object with .limiter method.

MISCONF Redis is configured to save RDB snapshots, but it is currently not able to persist on disk.

Redis server in read-only mode or disk full.

fix

Check Redis configuration; set 'stop-writes-on-bgsave-error no' in development or free disk space.

Error: getaddrinfo ENOTFOUND localhost

Redis server not running or incorrect host/port.

fix

Start Redis server: redis-server, or set REDIS_URL env variable to a valid endpoint.

Upgrade

Version history

2.6.0latest on npm

Audit

Dependencies

redisrequiredRequired as a peer dependency for Redis-backed rate limiting

Agent activity

14 hits · last 30 days

node

Resources

packageoss-ratelimit ↗