Ratelite

A simple, modern, and flexible Redis-based rate limiter for Express.js, designed for serverless functions, edge environments, and traditional Node.js applications.

Features

• Simple API: Get started in minutes with a clean and intuitive API.
• Upstash Redis: Built on @upstash/redis for serverless and edge compatibility.
• Flexible: Customize keys, error messages, and behavior with ease.
• TypeScript Ready: Fully written in TypeScript with type definitions included.

Installation

npm install ratelite express

Quick Start

Create a new Upstash Redis database at upstash.com and get your UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN.

import express from "express";
import { createRateLimiter } from "ratelite";

const app = express();

// Create a rate limiter that allows 10 requests per minute from an IP address.
const rateLimiter = createRateLimiter({
	redisUrl: process.env.UPSTASH_REDIS_REST_URL!,
	redisToken: process.env.UPSTASH_REDIS_REST_TOKEN!,
	maxRequests: 10,
	windowInSeconds: 60,
});

app.use(rateLimiter);

app.get("/", (req, res) => {
	res.send("Hello, World!");
});

app.listen(3000, () => {
	console.log("Server is running on port 3000");
});

Configuration

The createRateLimiter function accepts the following options:

| Option | Type | Required | Description | | ----------------- | ----------------------------------------------------- | -------- | ---------------------------------------------------------------------------- | | redisUrl | string | Yes | Your Upstash Redis REST URL. | | redisToken | string | Yes | Your Upstash Redis REST token. | | maxRequests | number | Yes | The maximum number of requests to allow per window. | | windowInSeconds | number | Yes | The duration of the time window in seconds. | | keyFn | (req: Request) => string | No | A function to generate a unique key for rate limiting. Defaults to req.ip. | | onLimitReached | (req: Request, res: Response) => void | No | A callback to execute when the rate limit is exceeded. | | onError | (err: unknown, req: Request, res: Response) => void | No | A callback to handle errors from the Redis client. | | debug | boolean | No | Set to true to log debug information. |

Custom Key Generation

By default, the ratelite uses the client's IP address (req.ip). You can provide a custom keyFn to use a different identifier, such as an API key or user ID.

const rateLimiter = createRateLimiter({
	// ... other options
	keyFn: (req) => req.headers["x-api-key"] as string,
});

Testing

To run the test suite:

npm test

License

This project is licensed under the MIT License. See the LICENSE file for details.