@diiiazote/redis-rate-limit

v1.0.3

A simple rate limiter for Redis using ioredis

---

@diiiazote/redis-rate-limit is an easy-to-use rate limiting library built for Node.js applications that rely on Redis for managing rate limits across distributed systems or single server setups. It utilizes ioredis for seamless integration with Redis and provides an developer friendly implemenation to manage request rates per identifier (e.g., user IP).

---

Import

Installation

You can install @diiiazote/redis-rate-limit using npm:

npm install @diiiazote/redis-rate-limit

Importing + initialization

To use @diiiazote/redis-rate-limit, import the RateLimit class from the package and initialize it with a Redis client instance, and configuration parameters:

import Redis from 'ioredis';
import { RateLimit } from '@diiiazote/redis-rate-limit';

const redisClient = new Redis(process.env.REDIS_URL_HERE);

// minimum configuration needed
const rateLimiter = new RateLimit({
  redis: redisClient,
  prefix: 'api-rate-limit'
});

RateLimit props

Here is a table of properties you can configure for the RateLimit class:

Name	Type	Description	Default
redis	Redis	An instance of ioredis client.	N.A
prefix	string	A prefix for Redis keys to namespace different rate limits.	N.A
window	number	The duration in which requests are counted.	1000 or ms("1s")
limit	number	The maximum number of requests allowed within the window.	1
difference	number	Minimum time interval between requests. Acts as a cooldown.	0 or ms("0s")
ephemeralCache	boolean	Whether to use an in-memory cache to store rate limit data.	true
logger	Function	Custom function for logging errors.	console.error

RateLimit limit method response

Here is a table of the response object for the .limit method:

Name	Type	Description
key	string	Key used for rate limiting.
success	boolean	Whether the request is allowed.
remaining	number	Number of requests remaining before hitting the rate limit.
limit	number	Maximum number of requests allowed within the rate limit window.
reset	() => Promise<void>	Function to reset the rate limit.
ttl	number	Time to live in milliseconds until the rate limit resets.
error	string	Optional error message when the request fails.
statusCode	number	Status code indicating the type of response or error.

---

Usage

Express

Here's how to use the @diiiazote/redis-rate-limit in an express application to limit API requests:

import express from 'express';
import Redis from "ioredis";
import { RateLimit } from '@diiiazote/redis-rate-limit';

const app = express();
const rateLimiter = new RateLimit({
  redis: new Redis(),
  prefix: "MyAPI",
  window: "1m",
  limit: 100
});

app.use(async (req, res, next) => {
  const ip = req.ip;
  const response = await rateLimiter.limit(ip);
  if (!response.success) {
    return res.status(429).json({ message: "Too many requests" });
  }
  next();
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

Next.js (self-hosted)

Here's how to use the @diiiazote/redis-rate-limit in Next.js.

Define the rate limit instance outside of router function or server action.

// /lib/rate-limit.ts
import Redis from "ioredis";
import { RateLimit, RateLimitResponse, ms } from "@diiiazote/redis-rate-limit";

// define redis
export const redis = new Redis(env.RATE_LIMIT_REDIS_HOST)

// define the api rate limit - here max 100 requests per minute
export const apiRateLimit = new RateLimit({
  redis,
  prefix: "MyApp/api", // or anything else
  window: ms("1m"),
  limit: 100,
})

Then import and use it with let's say the user's ip.

// /api/myRoute/route.ts
import { NextRequest } from "next/server";
import { headers } from "next/headers";
import { apiRateLimit } from "/lib/rate-limit"; // defined above

export async function POST(
  request: NextRequest,
) {
  const ip = headers().get("x-forwarded-for") ?? "Anonymous";
  const limit = await apiRateLimit.limit(ip);
  if(!limit?.success) {
    // rate limited, return too many request response
  }
  // ... do something not rate limited here
}

The nice thing about this approach is you can define multiple rate limiters for each route/action as need be. Make sure to change the prefix prop so there is no conflicts between your rate limiters. I like to use the app name and limiter name (what I'm limiting): `${app_name}/${limiter_name}`

---

Features

• Flexible Rate Limiting: Configurable windows and limits to accommodate various use cases.
• Cooldown Support: Ensures a minimum interval between requests with the difference option.
• In-memory Caching: Optional local caching to reduce Redis calls.
• Easy Integration: Simple setup with ioredis and minimal configuration.

---

Extras

The package also exports utility functions for managing and converting durations:

• ms: Convert a readable duration to milliseconds.
• msPrecise: Sum multiple durations.
• msToFriendly: Convert milliseconds to a human-readable format.
• formatDuration: Convert milliseconds to a formatted string based on specified units.

---

Limitations

While redis-rate-limit is designed to be robust and efficient, it's recommended to perform your own performance testing to ensure it meets the specific demands and traffic patterns of your application.

---

Dependencies

redis-rate-limit depends only on ioredis.

License

redis-rate-limit is ISC licensed.