GuardX 🚀

A lightweight, modular, and production-ready rate limiting middleware for Express.

GuardX provides a clean and stable API with built-in Memory and Redis stores. The Redis implementation uses atomic Lua scripting to ensure race-condition-free request counting under concurrent traffic.

📚 Documentation: https://guardx-official.vercel.app/

Installation

npm install guardx-rate-limit

For Redis support:

npm install redis

Quick Start

import express from "express";
import guardx from "guardx-rate-limit";

const app = express();

// Apply the rate limiter to all incoming requests
app.use(
    guardx({
        // Maximum number of requests allowed per window
        limit: 100,

        // Time window in milliseconds
        windowMs: 60 * 1000
    })
);

app.get("/", (req, res) => {
    res.json({
        success: true
    });
});

app.listen(3000);

Redis

import express from "express";
import { createClient } from "redis";
import guardx, { RedisStore } from "guardx-rate-limit";

const app = express();

// Create a Redis client
const client = createClient();

// Connect to Redis before using the limiter
await client.connect();

// Use Redis as the storage backend
app.use(
    guardx({
        // Maximum requests per time window
        limit: 100,

        // Window duration (1 minute)
        windowMs: 60 * 1000,

        // Use Redis instead of the default in-memory store
        store: new RedisStore(client)
    })
);

app.listen(3000);

The Redis store executes the Fixed Window algorithm using an atomic Lua script, combining Redis commands into a single operation for safe concurrent request counting.

Features

• Fixed Window algorithm
• Built-in Memory store
• Redis store
• Atomic Redis Lua implementation
• Standard RateLimit-* headers
• Retry-After header
• Custom response handler
• Lightweight and production-ready

Configuration

| Option | Type | Default | | ----------------- | --------------------------- | ---------------------- | | limit | number | 100 | | windowMs | number | 60000 | | message | string | "Too many requests." | | standardHeaders | boolean | true | | handler | function | undefined | | store | MemoryStore \| RedisStore | MemoryStore |

Custom Handler

guardx({
    // Override the default 429 response
    handler(req, res, info) {

        return res.status(429).json({
            success: false,
            message: "Rate limit exceeded",

            // Seconds until the client can make requests again
            retryAfter: info.retryAfter,

            // Remaining requests in the current window
            remaining: info.remaining,

            // Configured request limit
            limit: info.limit
        });

    }
});

Documentation

📚 Looking for advanced configuration, API reference, Redis setup, algorithms, and more? Visit the official documentation:

https://guardx-official.vercel.app/

License

MIT